feat(cli): add Slack community CTA on errors, crashes, setup, and help (#277)

* feat(cli): show Slack CTA on help and unexpected errors

* feat(cli): show Slack CTA after crashes

* feat(setup): show Slack community note after setup

* chore: refresh Python lockfile versions

packages/cli/test/cli-program-telemetry.test.ts

@@ -13,9 +13,27 @@ vi.mock('../src/telemetry/exception.js', () => ({
   reportException: reportExceptionMock,
 }));
 
-function makeIo(stdoutIsTTY = true): { io: KtxCliIo; stdout: () => string; stderr: () => string } {
+function makeIo(
+  stdoutIsTTY = true,
+  stderrIsTTY = false,
+): { io: KtxCliIo; stdout: () => string; stderr: () => string } {
   let stdout = '';
   let stderr = '';
+  const stderrStream = stderrIsTTY
+    ? {
+        isTTY: true,
+        columns: 80,
+        on: () => undefined,
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      }
+    : {
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      };
+
   return {
     io: {
       stdout: {
@@ -24,11 +42,7 @@ function makeIo(stdoutIsTTY = true): { io: KtxCliIo; stdout: () => string; stder
           stdout += chunk;
         },
       },
-      stderr: {
-        write: (chunk) => {
-          stderr += chunk;
-        },
-      },
+      stderr: stderrStream,
     },
     stdout: () => stdout,
     stderr: () => stderr,
@@ -164,4 +178,75 @@ describe('runCommanderKtxCli telemetry', () => {
       }),
     );
   });
+
+  it('prints the Slack hint for unexpected command errors on TTY stderr only', async () => {
+    const ttyIo = makeIo(true, true);
+    const deps: KtxCliDeps = {
+      doctor: async () => {
+        throw new Error('status failed');
+      },
+    };
+
+    await expect(
+      runCommanderKtxCli(
+        ['--project-dir', tempDir, 'status', '--json'],
+        ttyIo.io,
+        deps,
+        info,
+        { runInit: async () => 0 },
+      ),
+    ).resolves.toBe(1);
+
+    expect(ttyIo.stderr()).toContain('status failed');
+    expect(ttyIo.stderr()).toContain('Stuck? The ktx community can help');
+    expect(ttyIo.stderr()).toContain('https://ktx.sh/slack');
+
+    const pipeIo = makeIo(true, false);
+    await expect(
+      runCommanderKtxCli(
+        ['--project-dir', tempDir, 'status', '--json'],
+        pipeIo.io,
+        deps,
+        info,
+        { runInit: async () => 0 },
+      ),
+    ).resolves.toBe(1);
+
+    expect(pipeIo.stderr()).toContain('status failed');
+    expect(pipeIo.stderr()).not.toContain('https://ktx.sh/slack');
+  });
+
+  it('does not print the Slack hint for Commander usage errors', async () => {
+    const io = makeIo(true, true);
+
+    await expect(
+      runCommanderKtxCli(['--not-a-real-option'], io.io, {}, info, { runInit: async () => 0 }),
+    ).resolves.toBe(1);
+
+    expect(io.stderr()).toContain("unknown option '--not-a-real-option'");
+    expect(io.stderr()).not.toContain('Stuck? The ktx community can help');
+  });
+
+  it('prints the Slack hint for bare interactive setup failures on TTY stderr', async () => {
+    const originalCwd = process.cwd();
+    const noProjectDir = await mkdtemp(join(tmpdir(), 'ktx-cli-bare-'));
+    const io = makeIo(true, true);
+    const deps: KtxCliDeps = {
+      setup: async () => {
+        throw new Error('setup failed');
+      },
+    };
+
+    try {
+      process.chdir(noProjectDir);
+      await expect(runCommanderKtxCli([], io.io, deps, info, { runInit: async () => 0 })).resolves.toBe(1);
+    } finally {
+      process.chdir(originalCwd);
+      await rm(noProjectDir, { recursive: true, force: true });
+    }
+
+    expect(io.stderr()).toContain('setup failed');
+    expect(io.stderr()).toContain('Stuck? The ktx community can help');
+    expect(io.stderr()).toContain('https://ktx.sh/slack');
+  });
 });

packages/cli/test/cli-program.test.ts

@@ -54,6 +54,32 @@ describe('buildKtxProgram', () => {
 
     expect(wrote).toBe('');
   });
+
+  it('adds the Slack community footer to root help', () => {
+    let stdout = '';
+    const io: KtxCliIo = {
+      stdout: {
+        isTTY: false,
+        columns: 80,
+        write: (chunk) => {
+          stdout += chunk;
+        },
+      },
+      stderr: {
+        write: () => undefined,
+      },
+    };
+    const program: Command = buildKtxProgram({
+      io,
+      deps: {},
+      packageInfo: stubPackageInfo(),
+      runInit: async () => 0,
+    });
+
+    program.outputHelp();
+
+    expect(stdout).toContain('Community & support: https://ktx.sh/slack');
+  });
 });
 
 describe('collectCommandFlagsPresent', () => {

packages/cli/test/cli-runtime.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+
+import type { KtxCliIo } from '../src/cli-runtime.js';
+import { writeGlobalExceptionToStderr } from '../src/cli-runtime.js';
+
+function makeIo(stderrIsTty: boolean): { io: KtxCliIo; stderr: () => string } {
+  let stderr = '';
+  const stderrStream = stderrIsTty
+    ? {
+        isTTY: true,
+        columns: 80,
+        on: () => undefined,
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      }
+    : {
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      };
+
+  return {
+    io: {
+      stdout: {
+        write: () => undefined,
+      },
+      stderr: stderrStream,
+    },
+    stderr: () => stderr,
+  };
+}
+
+describe('writeGlobalExceptionToStderr', () => {
+  it('prints the crash Slack hint after a stack on TTY stderr', () => {
+    const testIo = makeIo(true);
+
+    writeGlobalExceptionToStderr(testIo.io, new Error('global boom'));
+
+    expect(testIo.stderr()).toContain('Error: global boom');
+    expect(testIo.stderr()).toContain('This may be a bug');
+    expect(testIo.stderr()).toContain('https://ktx.sh/slack');
+  });
+
+  it('prints crash details without the Slack hint on non-TTY stderr', () => {
+    const testIo = makeIo(false);
+
+    writeGlobalExceptionToStderr(testIo.io, 'global boom');
+
+    expect(testIo.stderr()).toContain('global boom');
+    expect(testIo.stderr()).not.toContain('https://ktx.sh/slack');
+  });
+});

packages/cli/test/community-cta.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  SLACK_HELP_FOOTER,
+  SLACK_SETUP_NOTE,
+  writeErrorCommunityHint,
+} from '../src/community-cta.js';
+import type { KtxCliIo } from '../src/cli-runtime.js';
+
+function makeIo(stderrIsTty: boolean): { io: KtxCliIo; stderr: () => string } {
+  let stderr = '';
+  const stderrStream = stderrIsTty
+    ? {
+        isTTY: true,
+        columns: 80,
+        on: () => undefined,
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      }
+    : {
+        write: (chunk: string) => {
+          stderr += chunk;
+        },
+      };
+
+  return {
+    io: {
+      stdout: {
+        write: () => undefined,
+      },
+      stderr: stderrStream,
+    },
+    stderr: () => stderr,
+  };
+}
+
+describe('community CTA', () => {
+  it('writes the error hint to TTY stderr', () => {
+    const testIo = makeIo(true);
+
+    writeErrorCommunityHint(testIo.io, 'error');
+
+    expect(testIo.stderr()).toContain('Stuck? The ktx community can help');
+    expect(testIo.stderr()).toContain('https://ktx.sh/slack');
+  });
+
+  it('suppresses the error hint for non-TTY stderr', () => {
+    const testIo = makeIo(false);
+
+    writeErrorCommunityHint(testIo.io, 'error');
+
+    expect(testIo.stderr()).toBe('');
+  });
+
+  it('uses stronger crash copy for crash hints', () => {
+    const testIo = makeIo(true);
+
+    writeErrorCommunityHint(testIo.io, 'crash');
+
+    expect(testIo.stderr()).toContain('This may be a bug');
+    expect(testIo.stderr()).toContain('https://ktx.sh/slack');
+  });
+
+  it('exports setup and help copy with the stable Slack URL', () => {
+    expect(SLACK_HELP_FOOTER).toBe('Community & support: https://ktx.sh/slack');
+    expect(SLACK_SETUP_NOTE).toEqual({
+      title: 'Community',
+      body: 'Questions or feedback? Join the ktx Slack: https://ktx.sh/slack',
+    });
+  });
+});

packages/cli/test/io/tty.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { isWritableTtyOutput } from '../../src/io/tty.js';
+
+describe('isWritableTtyOutput', () => {
+  it('accepts writable TTY-like output', () => {
+    const output = {
+      isTTY: true,
+      columns: 80,
+      on: () => undefined,
+      write: () => undefined,
+    };
+
+    expect(isWritableTtyOutput(output)).toBe(true);
+  });
+
+  it('rejects non-TTY output', () => {
+    expect(isWritableTtyOutput({ write: () => undefined })).toBe(false);
+  });
+
+  it('rejects output missing stream event support', () => {
+    expect(
+      isWritableTtyOutput({
+        isTTY: true,
+        columns: 80,
+        write: () => undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it('rejects output missing column metadata', () => {
+    const output = {
+      isTTY: true,
+      on: () => undefined,
+      write: () => undefined,
+    };
+
+    expect(isWritableTtyOutput(output)).toBe(false);
+  });
+});

packages/cli/test/setup.test.ts

@@ -652,6 +652,8 @@ describe('setup status', () => {
     expect(testIo.stdout()).toContain('ktx setup');
     expect(testIo.stdout()).not.toContain('ktx agent context --json');
     expect(testIo.stdout()).not.toContain('Optional MCP:');
+    expect(testIo.stdout()).toContain('Community:');
+    expect(testIo.stdout()).toContain('Questions or feedback? Join the ktx Slack: https://ktx.sh/slack');
     expect(testIo.stderr()).toBe('');
   });