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/src/cli-program.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command, type CommandUnknownOpts, InvalidArgumentError } from '@commander-js/extra-typings';
 import type { KtxCliDeps, KtxCliIo, KtxCliPackageInfo } from './cli-runtime.js';
+import { SLACK_HELP_FOOTER, writeErrorCommunityHint } from './community-cta.js';
 import { registerCompletionCommands } from './commands/completion-commands.js';
 import { registerConnectionCommands } from './commands/connection-commands.js';
 import { registerIngestCommands } from './commands/ingest-commands.js';
@@ -258,6 +259,7 @@ function createBaseProgram(info: KtxCliPackageInfo, io: KtxCliIo): Command {
     .helpOption('-h, --help', 'Show this help text')
     .configureHelp({ showGlobalOptions: true })
     .showHelpAfterError()
+    .addHelpText('after', `\n${SLACK_HELP_FOOTER}`)
     .exitOverride()
     .configureOutput({
       writeOut: (chunk) => io.stdout.write(chunk),
@@ -561,6 +563,7 @@ export async function runCommanderKtxCli(
           io,
         });
         io.stderr.write(`${formatCliError(error)}\n`);
+        writeErrorCommunityHint(io, 'error');
         return 1;
       }
     }
@@ -585,6 +588,7 @@ export async function runCommanderKtxCli(
       exitCode = error.exitCode === 0 ? 0 : 1;
     } else {
       io.stderr.write(`${formatCliError(error)}\n`);
+      writeErrorCommunityHint(io, 'error');
       exitCode = 1;
     }
   } finally {

packages/cli/src/cli-runtime.ts

@@ -12,6 +12,7 @@ import type { KtxSqlArgs } from './sql.js';
 import { profileMark, profileSpan } from './startup-profile.js';
 import type { KtxTextIngestArgs } from './text-ingest.js';
 import { assertCliVersion } from './release-version.js';
+import { writeErrorCommunityHint } from './community-cta.js';
 
 profileMark('module:cli-runtime');
 
@@ -144,6 +145,16 @@ export function createGlobalExceptionReporter(io: KtxCliIo, info: KtxCliPackageI
   };
 }
 
+/** @internal */
+export function writeGlobalExceptionToStderr(io: KtxCliIo, error: unknown): void {
+  if (error instanceof Error && error.stack) {
+    io.stderr.write(`${error.stack}\n`);
+  } else {
+    io.stderr.write(`${String(error)}\n`);
+  }
+  writeErrorCommunityHint(io, 'crash');
+}
+
 export function installGlobalExceptionHandlers(io: KtxCliIo, info: KtxCliPackageInfo): () => void {
   const report = createGlobalExceptionReporter(io, info);
   const handle = (source: 'uncaughtException' | 'unhandledRejection', error: unknown): void => {
@@ -153,11 +164,7 @@ export function installGlobalExceptionHandlers(io: KtxCliIo, info: KtxCliPackage
       } catch {
         // Best-effort: preserve Node's process termination behavior.
       }
-      if (error instanceof Error && error.stack) {
-        io.stderr.write(`${error.stack}\n`);
-      } else {
-        io.stderr.write(`${String(error)}\n`);
-      }
+      writeGlobalExceptionToStderr(io, error);
       process.exit(1);
     })();
   };

packages/cli/src/community-cta.ts

@@ -0,0 +1,28 @@
+import type { KtxCliIo } from './cli-runtime.js';
+import { isWritableTtyOutput } from './io/tty.js';
+import { dim } from './io/symbols.js';
+import { SLACK_URL } from './links.js';
+
+type ErrorCtaVariant = 'error' | 'crash';
+
+/** @internal */
+export const SLACK_HELP_FOOTER = `Community & support: ${SLACK_URL}`;
+
+/** @internal */
+export const SLACK_SETUP_NOTE = {
+  title: 'Community',
+  body: `Questions or feedback? Join the ktx Slack: ${SLACK_URL}`,
+} as const;
+
+export function writeErrorCommunityHint(io: KtxCliIo, variant: ErrorCtaVariant): void {
+  if (!isWritableTtyOutput(io.stderr)) {
+    return;
+  }
+
+  const line =
+    variant === 'crash'
+      ? `This may be a bug - report it or ask in the ktx community: ${SLACK_URL}`
+      : `Stuck? The ktx community can help: ${SLACK_URL}`;
+
+  io.stderr.write(`${dim(line)}\n`);
+}

packages/cli/src/io/tty.ts

@@ -0,0 +1,17 @@
+import type { Writable } from 'node:stream';
+
+import type { KtxCliIo } from '../cli-runtime.js';
+
+type KtxCliOutput = (KtxCliIo['stdout'] | KtxCliIo['stderr']) & {
+  isTTY?: boolean;
+  columns?: number;
+  on?: unknown;
+};
+
+export function isWritableTtyOutput(output: KtxCliOutput): output is KtxCliOutput & Writable {
+  return (
+    (output as { isTTY?: unknown }).isTTY === true &&
+    typeof (output as { on?: unknown }).on === 'function' &&
+    typeof (output as { columns?: unknown }).columns !== 'undefined'
+  );
+}

packages/cli/src/links.ts

@@ -0,0 +1 @@
+export const SLACK_URL = 'https://ktx.sh/slack';

packages/cli/src/setup-agents.ts

@@ -1,7 +1,6 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
-import type { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import { styleText } from 'node:util';
 import { log, outro } from '@clack/prompts';
@@ -11,6 +10,7 @@ import { serializeKtxProjectConfig } from './context/project/config.js';
 import { strToU8, zipSync } from 'fflate';
 import type { KtxCliIo } from './cli-runtime.js';
 import { errorMessage, writePrefixedLines } from './clack.js';
+import { isWritableTtyOutput } from './io/tty.js';
 import {
   createKtxSetupPromptAdapter,
   createKtxSetupUiAdapter,
@@ -84,14 +84,6 @@ interface KtxCliLauncher {
   args: string[];
 }
 
-function isWritableTtyOutput(output: KtxCliIo['stdout']): output is KtxCliIo['stdout'] & Writable {
-  return (
-    output.isTTY === true &&
-    typeof (output as { on?: unknown }).on === 'function' &&
-    typeof (output as { columns?: unknown }).columns !== 'undefined'
-  );
-}
-
 function writeSetupInfo(io: KtxCliIo, message: string): void {
   if (isWritableTtyOutput(io.stdout)) {
     log.info(message, { output: io.stdout });

packages/cli/src/setup-prompts.ts

@@ -1,4 +1,3 @@
-import type { Writable } from 'node:stream';
 import {
   autocomplete,
   autocompleteMultiselect,
@@ -13,6 +12,7 @@ import {
   text,
 } from '@clack/prompts';
 import type { KtxCliIo } from './cli-runtime.js';
+import { isWritableTtyOutput } from './io/tty.js';
 import { withMenuOptionsSpacing, withTextInputNavigation } from './prompt-navigation.js';
 import { revealPassword } from './reveal-password-prompt.js';
 import { withSetupInterruptConfirmation } from './setup-interrupt.js';
@@ -211,14 +211,6 @@ export interface KtxSetupUiAdapter {
   note(message: string, title: string, io: KtxCliIo, options?: KtxSetupNoteOptions): void;
 }
 
-function isWritableTtyOutput(output: KtxCliIo['stdout']): output is KtxCliIo['stdout'] & Writable {
-  return (
-    output.isTTY === true &&
-    typeof (output as { on?: unknown }).on === 'function' &&
-    typeof (output as { columns?: unknown }).columns !== 'undefined'
-  );
-}
-
 export function createKtxSetupUiAdapter(): KtxSetupUiAdapter {
   return {
     intro(title, io) {

packages/cli/src/setup.ts

@@ -6,6 +6,7 @@ import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject, type KtxLocalProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
 import { getKtxCliPackageInfo, type KtxCliIo } from './cli-runtime.js';
+import { SLACK_SETUP_NOTE } from './community-cta.js';
 import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
@@ -921,5 +922,6 @@ async function runKtxSetupInner(args: KtxSetupArgs, io: KtxCliIo, deps: KtxSetup
       );
     }
   }
+  setupUi.note(SLACK_SETUP_NOTE.body, SLACK_SETUP_NOTE.title, io);
   return 0;
 }