@cursor/bdk 0.2.1

package/src/internal/cli-slack.ts

@@ -0,0 +1,874 @@
+/**
+ * `agent-sdk slack …` CLI — doctor, destroy/icon, `create` as a
+ * dashboard-wizard launcher (`slack-provision-client.ts`), and
+ * `init --manual` for Slack CLI / paste-at-api.slack.com manifests.
+ */
+
+import { access, readFile } from "node:fs/promises";
+import { basename, extname, join, resolve as resolvePath } from "node:path";
+import {
+  envPrefixFromName,
+  formatSlackSetupGuide,
+  initSlackChannel,
+  runSlackDoctor,
+  type SlackDoctorResult,
+  slackEnvKeys,
+} from "../channels/slack/index.js";
+import type { AgentArchitecture } from "../types.js";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { cmdSlackInit, runSlackManifest, type SlackCliExec } from "./cli-slack-manual.js";
+import { cursorExternalApiUrl, resolveApiKeySync } from "./cursor/credentials.js";
+import { slugFromDirectoryName } from "./deploy-client.js";
+import { inferDeployGitSource } from "./deploy-source.js";
+import { describeError } from "./describe-error.js";
+import { DEFAULT_AGENT_ARCHITECTURE, isAgentProjectDir, loadAgentProject } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { ensureEnvLocalGitignored, upsertEnvFile } from "./env-file.js";
+import { loadAgentLocalEnv } from "./local-env.js";
+import { openBrowser } from "./open-browser.js";
+import { projectPath, resolveProjectRoot } from "./project-layout.js";
+import {
+  AgentServeSlackClient,
+  type SlackAppEnv,
+  type SlackAppIconContentType,
+  type SlackAppIconInput,
+  type SlackManagedAppInfo,
+  SlackProvisionApiError,
+  type SlackProvisionStatus,
+  type SlackWizardMintResult,
+  type SlackWizardPollResult,
+} from "./slack-provision-client.js";
+import { sleep } from "./sleep.js";
+import { stderrPalette, type TerminalPalette } from "./terminal-style.js";
+
+export interface SlackCliOptions {
+  dir: string;
+  name?: string;
+  env?: "dev" | "prod" | "both";
+  json?: boolean;
+  print?: boolean;
+  /** Per-agent env prefix for tokens (`MY_AGENT`). */
+  prefix?: string;
+  /** Use shared `SLACK_*` env vars (no per-agent prefix). */
+  noPrefix?: boolean;
+  /** Subscribe manifests to channel-post events (opt-in channel watch). */
+  channelPosts?: boolean;
+  /** create/destroy: target Slack workspace id (`T…`). */
+  slackTeam?: string;
+  /** create/destroy: target the prod app (default dev). */
+  prod?: boolean;
+  /** create/destroy: Cursor team id; resolved from the account when omitted. */
+  team?: string;
+  /** create/destroy: Cursor API key (defaults to the stored login / env). */
+  apiKey?: string;
+  /** create: app icon — an https image URL or a local png/jpg/gif ≤512KB. */
+  icon?: string;
+  /** create: accepted for compatibility; live-app updates always overwrite. */
+  force?: boolean;
+  /** `slack init --manual`: Slack CLI project + paste fallback. */
+  manual?: boolean;
+  /** `slack init --manual`: require Slack CLI install. */
+  install?: boolean;
+  /** `slack init --manual`: skip Slack CLI install. */
+  noInstall?: boolean;
+  detectSlackCli?: () => string | undefined;
+  runSlackCli?: SlackCliExec;
+  /** `slack icon <source>` positional (same URL-or-file forms as --icon). */
+  iconSource?: string;
+  /** doctor: watched channel ids (`C…`) to verify visibility/membership. */
+  channels?: string[];
+  /** Test seams. */
+  fetchImpl?: typeof fetch;
+  openBrowserImpl?: (url: string) => void;
+  connectPollIntervalMs?: number;
+  connectPollTimeoutMs?: number;
+  doctorImpl?: typeof runSlackDoctor;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+  palette?: TerminalPalette;
+}
+
+const SLACK_HELP = `${CLI} slack — Slack channel pack helpers (Socket Mode)
+
+Usage:
+  ${CLI} slack setup
+  ${CLI} slack create    [--dir .] [--name NAME] [--slack-team T0123ABCD]
+                                [--prod] [--team <id>] [--icon URL-or-FILE]
+                                [--force] [--prefix PREFIX | --no-prefix] [--json]
+  ${CLI} slack destroy   [--dir .] [--slack-team T0123ABCD] [--prod]
+                                [--team <id>] [--json]
+  ${CLI} slack icon      <URL-or-FILE> [--dir .] [--slack-team T0123ABCD]
+                                [--prod] [--team <id>] [--json]
+  ${CLI} slack init --manual [--dir .] [--name NAME]
+                                [--prefix PREFIX | --no-prefix] [--channel-posts]
+                                [--install | --no-install]
+                                [--slack-team T0123ABCD] [--prod]
+  ${CLI} slack manifest --env dev|prod|both [--dir .] [--name NAME]
+                                [--print]
+  ${CLI} slack doctor [--dir .] [--prefix PREFIX | --no-prefix] [--json]
+                                [--channel C0123ABCD]...
+
+create/destroy/icon — dedicated Socket Mode app via the Cursor dashboard:
+  create   Opens the signed-in dashboard wizard. Finish name, workspace,
+           and Slack consent there. The CLI writes the token pair into
+           <dir>/.env.local and runs doctor. Requires \`${CLI} login\`
+           (or CURSOR_API_KEY). A team service-account key cannot
+           provision Slack apps. --prod provisions the prod app (default
+           dev). --name / --icon / --channel-posts prefill the wizard.
+           All three follow the agent's \`architecture\` (agent.ts;
+           default v2): the wizard stores tokens on that deployment and
+           the app inventory lives on that control plane.
+  destroy  Delete the provisioned Slack app for this agent (+env). Tokens
+           already in .env.local are left in place (they just stop working).
+  icon     Set the provisioned app's icon: an https image URL or a local
+           png/jpg/gif file (at most 512KB).
+
+\`slack init\` without --manual is not the first-run path. Use \`slack create\`.
+\`slack init --manual\` writes the channel file, manifests, a Slack CLI
+\`.slack/\` project (get-manifest → those JSON files), env.example, and
+setup-status.json. When \`~/.slack/bin/slack\` is logged in, it installs
+the app. Otherwise \`next\` asks the user to install it. \`--install\`
+requires that install. \`--no-install\` skips it. \`--prod\` selects the
+deployed app. Paste at api.slack.com is the fallback. Do not
+\`slack deploy\`.
+
+Env tokens:
+  single agent:  SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+  multi-agent:   <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN
+                 (create / init --manual default PREFIX from the directory name;
+                  doctor defaults to it too when those keys are set)
+
+See also: skills/setup-slack/SKILL.md
+`;
+
+export async function cmdSlack(
+  subcommand: string | undefined,
+  options: SlackCliOptions,
+): Promise<number> {
+  switch (subcommand) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(SLACK_HELP);
+      return subcommand === undefined ? 1 : 0;
+    case "setup":
+      process.stdout.write(formatSlackSetupGuide());
+      return 0;
+    case "create":
+      return cmdSlackCreate(options);
+    case "destroy":
+      return cmdSlackDestroy(options);
+    case "icon":
+      return cmdSlackIcon(options);
+    case "init":
+      return cmdSlackInit({
+        dir: options.dir,
+        name: options.name,
+        prefix: options.prefix,
+        noPrefix: options.noPrefix,
+        channelPosts: options.channelPosts,
+        manual: options.manual,
+        install: options.install,
+        noInstall: options.noInstall,
+        slackTeam: options.slackTeam,
+        detectSlackCli: options.detectSlackCli,
+        runSlackCli: options.runSlackCli,
+        prod: options.prod,
+        out: options.out,
+        err: options.err,
+      });
+    case "manifest":
+      return runSlackManifest(options);
+    case "doctor":
+      return runDoctor(options);
+    default:
+      process.stderr.write(`Unknown slack subcommand: ${subcommand}\n`);
+      process.stdout.write(SLACK_HELP);
+      return 1;
+  }
+}
+
+async function runDoctor(options: SlackCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  // Tokens usually live in the agent's .env.local; real env still wins.
+  loadAgentLocalEnv(dir);
+  const envPrefix = resolveDoctorEnvPrefix(options, dir);
+  const doctor = options.doctorImpl ?? runSlackDoctor;
+  const channels = options.channels ?? [];
+  const result = await doctor({
+    envPrefix,
+    channels: channels.length > 0 ? channels : undefined,
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(renderDoctorReport(result));
+  }
+  return result.ok ? 0 : 1;
+}
+
+/**
+ * --prefix / --no-prefix win; otherwise the directory-derived prefix
+ * create/init use, but only when one of its keys is set — unprefixed
+ * setups keep the bare SLACK_* default.
+ */
+function resolveDoctorEnvPrefix(options: SlackCliOptions, dir: string): string | undefined {
+  if (options.noPrefix === true) {
+    return undefined;
+  }
+  if (options.prefix !== undefined) {
+    return options.prefix;
+  }
+  const derived = envPrefixFromName(basename(dir));
+  const keys = slackEnvKeys(derived);
+  return process.env[keys.bot] !== undefined || process.env[keys.app] !== undefined
+    ? derived
+    : undefined;
+}
+
+// ============================================================================
+// create / destroy — Cursor "Add to Slack" managed provisioning
+// ============================================================================
+
+const DEFAULT_WIZARD_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_WIZARD_POLL_TIMEOUT_MS = 60 * 60 * 1000;
+
+interface SlackProvisionContext {
+  client: AgentServeSlackClient;
+  teamId: number;
+  /** The control plane `client` is pinned to; see {@link resolveSlackAppArchitecture}. */
+  architecture: AgentArchitecture;
+  json: boolean;
+  out: (text: string) => void;
+  err: (text: string) => void;
+  dim: (s: string) => string;
+  openBrowserImpl: (url: string) => void;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+}
+
+/** Local facts about the app being provisioned, resolved before any I/O. */
+interface SlackAppTarget {
+  dir: string;
+  name: string;
+  slug: string;
+  env: SlackAppEnv;
+  envPrefix: string | undefined;
+  envKeys: { bot: string; app: string };
+}
+
+function resolveSlackAppTarget(
+  options: SlackCliOptions,
+  err: (text: string) => void,
+): SlackAppTarget | number {
+  if (options.env === "both" && options.prod !== true) {
+    err("Provisioning targets one env at a time; pass --prod for the prod app (default dev).\n");
+    return 1;
+  }
+  const env: SlackAppEnv = options.prod === true || options.env === "prod" ? "prod" : "dev";
+  const dir = resolvePath(options.dir);
+  // Backend slug rule, mirrored so the error names the real problem
+  // instead of a generic 400.
+  const slug = slugFromDirectoryName(basename(dir));
+  if (slug === undefined || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(slug)) {
+    err(
+      `Could not derive a valid app slug from the directory name ${JSON.stringify(basename(dir))} (slugs start with a letter or digit; lowercase letters, digits, '-', '_'); rename the directory or pass --dir <agent>.\n`,
+    );
+    return 1;
+  }
+  const name = options.name ?? basename(dir);
+  const envPrefix =
+    options.noPrefix === true ? undefined : (options.prefix ?? envPrefixFromName(basename(dir)));
+  return { dir, name, slug, env, envPrefix, envKeys: slackEnvKeys(envPrefix) };
+}
+
+function errStream(options: SlackCliOptions): (text: string) => void {
+  return options.err ?? ((text: string) => void process.stderr.write(text));
+}
+
+const SLACK_ICON_MAX_BYTES = 524_288;
+
+const SLACK_ICON_URL_MAX_LENGTH = 3000;
+
+const SLACK_ICON_CONTENT_TYPES: Record<string, SlackAppIconContentType> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+};
+
+type SlackIconSource =
+  | { kind: "url"; url: string }
+  | {
+      kind: "file";
+      base64: string;
+      contentType: SlackAppIconContentType;
+      path: string;
+    };
+
+async function resolveSlackIconSource(
+  raw: string,
+  err: (text: string) => void,
+): Promise<SlackIconSource | number> {
+  if (raw.startsWith("https://")) {
+    if (raw.length > SLACK_ICON_URL_MAX_LENGTH) {
+      err(
+        `Icon URLs must be at most ${SLACK_ICON_URL_MAX_LENGTH} characters (got ${raw.length}).\n`,
+      );
+      return 1;
+    }
+    return { kind: "url", url: raw };
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    err(`Icon URLs must be https (got ${JSON.stringify(raw)}).\n`);
+    return 1;
+  }
+  const path = resolvePath(raw);
+  const contentType = SLACK_ICON_CONTENT_TYPES[extname(path).toLowerCase()];
+  if (contentType === undefined) {
+    err(`Icon files must be .png, .jpg/.jpeg, or .gif (got ${JSON.stringify(basename(path))}).\n`);
+    return 1;
+  }
+  let data: Buffer;
+  try {
+    data = await readFile(path);
+  } catch (error) {
+    err(`Could not read the icon file ${path}: ${describeError(error)}\n`);
+    return 1;
+  }
+  if (data.length > SLACK_ICON_MAX_BYTES) {
+    err(`Icon files must be at most ${SLACK_ICON_MAX_BYTES} bytes (${path} is ${data.length}).\n`);
+    return 1;
+  }
+  return { kind: "file", base64: data.toString("base64"), contentType, path };
+}
+
+function toSlackAppIconInput(source: SlackIconSource): SlackAppIconInput {
+  return source.kind === "url"
+    ? { url: source.url }
+    : { base64: source.base64, contentType: source.contentType };
+}
+
+/**
+ * File icons post after the wizard finishes. URL icons ride the mint
+ * payload. Best-effort: failures warn, never fail the create.
+ */
+async function applySlackCreateFileIcon(
+  ctx: SlackProvisionContext,
+  source: SlackIconSource | undefined,
+  appId: string,
+): Promise<"set" | "failed" | undefined> {
+  if (source === undefined || source.kind === "url") {
+    return undefined;
+  }
+  try {
+    await ctx.client.setAppIcon({
+      teamId: ctx.teamId,
+      slackAppId: appId,
+      icon: toSlackAppIconInput(source),
+    });
+    return "set";
+  } catch (error) {
+    ctx.err(
+      `warning: setting the Slack app icon failed: ${describeError(error)}\nRetry with \`${CLI} slack icon ${source.path}\`.\n`,
+    );
+    return "failed";
+  }
+}
+
+/**
+ * The Slack control plane follows the agent's hosted architecture
+ * (`defineAgent({ architecture })`, `"v2"` when omitted): the dashboard
+ * wizard stores the minted tokens on that architecture's deployment, and
+ * the app inventory `destroy` / `icon` read lives there too. A directory
+ * that is not an agent project yet has nothing to read and takes the
+ * framework default, same as an `agent.ts` that omits the field.
+ */
+async function resolveSlackAppArchitecture(dir: string): Promise<AgentArchitecture> {
+  if (!(await isAgentProjectDir(dir))) {
+    return DEFAULT_AGENT_ARCHITECTURE;
+  }
+  const project = await loadAgentProject(dir);
+  return project.agent.architecture ?? DEFAULT_AGENT_ARCHITECTURE;
+}
+
+/**
+ * Credentials → provisioning client → team id, sharing the deploy CLI's
+ * resolution (stored login / CURSOR_API_KEY, `--team` override, GetMe
+ * default-team fallback). Returns an exit code (error already rendered)
+ * on failure.
+ */
+async function prepareProvision(options: SlackCliOptions): Promise<SlackProvisionContext | number> {
+  const out = options.out ?? ((text: string) => void process.stdout.write(text));
+  const err = errStream(options);
+  const credential = resolveApiKeySync(
+    options.apiKey === undefined ? undefined : { apiKey: options.apiKey },
+  );
+  if (credential?.source === "service-account") {
+    err(
+      `A team service-account key cannot provision Slack apps. Sign in with \`${CLI} login\` or set CURSOR_API_KEY.\n`,
+    );
+    return 1;
+  }
+  const auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+    err,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+  // Loading the project imports its authored modules; do it only once the
+  // credentials are known good.
+  const architecture = await resolveSlackAppArchitecture(resolvePath(options.dir));
+  // Provisioning routes live on the external API host beside deploys.
+  return {
+    client: new AgentServeSlackClient({
+      backendUrl: cursorExternalApiUrl(),
+      apiKey: auth.apiKey,
+      architecture,
+      fetchImpl: options.fetchImpl,
+    }),
+    teamId: auth.teamId,
+    architecture,
+    json: options.json === true,
+    out,
+    err,
+    dim: (options.palette ?? stderrPalette()).dim,
+    openBrowserImpl: options.openBrowserImpl ?? openBrowser,
+    pollIntervalMs: options.connectPollIntervalMs ?? DEFAULT_WIZARD_POLL_INTERVAL_MS,
+    pollTimeoutMs: options.connectPollTimeoutMs ?? DEFAULT_WIZARD_POLL_TIMEOUT_MS,
+  };
+}
+
+function writePendingAdminWait(ctx: SlackProvisionContext, poll: SlackWizardPollResult): void {
+  const appSuffix = poll.appId === undefined ? "" : ` (${poll.appId})`;
+  const requestUrl =
+    poll.oauthAuthorizeUrl !== undefined && poll.oauthAuthorizeUrl.length > 0
+      ? poll.oauthAuthorizeUrl
+      : undefined;
+  ctx.err(`Waiting for a Slack admin to approve the app${appSuffix}.\n\n`);
+  if (poll.approvalRequest === "pending") {
+    // Already in the admin queue: nothing to file, so no browser hop.
+    ctx.err(ctx.dim(`  Approval request sent; workspace owners were notified.\n\n`));
+    if (requestUrl !== undefined) {
+      ctx.err(ctx.dim(`  Send a reminder from:\n\n`));
+      ctx.err(`  ${requestUrl}\n\n`);
+    }
+  } else if (requestUrl !== undefined) {
+    ctx.err(
+      ctx.dim(
+        `  Slack will notify workspace owners once the request is in their queue.\n` +
+          `  Open this page to file it or send a reminder:\n\n`,
+      ),
+    );
+    ctx.err(`  ${requestUrl}\n\n`);
+    ctx.openBrowserImpl(requestUrl);
+  } else {
+    ctx.err(
+      ctx.dim(`  Slack will notify workspace owners once the request is in their queue.\n\n`),
+    );
+  }
+  ctx.err(
+    ctx.dim(
+      `  Keep this command running.\n` +
+        `  After an admin approves, click Retry in the dashboard.\n`,
+    ),
+  );
+}
+
+export async function cmdSlackCreate(options: SlackCliOptions): Promise<number> {
+  const target = resolveSlackAppTarget(options, errStream(options));
+  if (typeof target === "number") {
+    return target;
+  }
+  let iconSource: SlackIconSource | undefined;
+  if (options.icon !== undefined) {
+    const resolved = await resolveSlackIconSource(options.icon, errStream(options));
+    if (typeof resolved === "number") {
+      return resolved;
+    }
+    iconSource = resolved;
+  }
+  const ctx = await prepareProvision(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+
+  let wrote: string[];
+  try {
+    wrote = await scaffoldSlackChannelFiles(target);
+  } catch (error) {
+    ctx.err(`${describeError(error)}\n`);
+    return 1;
+  }
+  if (wrote.length > 0 && !ctx.json) {
+    ctx.err(`${ctx.dim(`Scaffolded the Slack channel: ${wrote.join(", ")}`)}\n`);
+  }
+
+  const source = await inferDeployGitSource(target.dir);
+  let minted: SlackWizardMintResult;
+  try {
+    minted = await ctx.client.mintWizard({
+      teamId: ctx.teamId,
+      slug: target.slug,
+      env: target.env,
+      envPrefix: target.envPrefix,
+      name: options.name ?? target.name,
+      gitRepoUrl: source.gitRepoUrl,
+      gitRef: source.gitRef,
+      agentPath: source.agentPath,
+      channelPosts: options.channelPosts === true ? true : undefined,
+      slackTeamId: options.slackTeam,
+      iconUrl: iconSource?.kind === "url" ? iconSource.url : undefined,
+      force: options.force === true ? true : undefined,
+    });
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+
+  const waitMinutes = Math.round(ctx.pollTimeoutMs / 60_000);
+  ctx.err(`Finish Slack setup in the browser:\n\n  ${minted.url}\n\n`);
+  ctx.err(
+    ctx.dim(
+      `  Sign in as the same Cursor account that ran this command.\n` +
+        `  The CLI waits here (up to ${waitMinutes} minutes).\n`,
+    ),
+  );
+  ctx.openBrowserImpl(minted.url);
+
+  const deadline = Date.now() + ctx.pollTimeoutMs;
+  let sawPendingAdmin = false;
+  let poll: SlackWizardPollResult | undefined;
+  for (;;) {
+    try {
+      poll = await ctx.client.pollWizard(minted.wizardId);
+    } catch (error) {
+      if (Date.now() >= deadline) {
+        return renderSlackApiError(error, ctx.err);
+      }
+      await sleep(ctx.pollIntervalMs);
+      continue;
+    }
+    if (poll.status === "complete") {
+      break;
+    }
+    if (poll.status === "failed") {
+      ctx.err(`${poll.error ?? "Slack setup failed"}\n`);
+      return 1;
+    }
+    if (poll.status === "pending_admin_approval" && !sawPendingAdmin) {
+      sawPendingAdmin = true;
+      writePendingAdminWait(ctx, poll);
+    }
+    if (Date.now() >= deadline) {
+      ctx.err(`Timed out waiting for Slack setup.\n\n`);
+      ctx.err(ctx.dim(`  Finish it in the browser, then re-run \`${CLI} slack create\`.\n\n`));
+      ctx.err(`  ${minted.url}\n`);
+      return 1;
+    }
+    await sleep(ctx.pollIntervalMs);
+  }
+
+  if (poll === undefined || poll.localEnv === undefined) {
+    ctx.err(
+      poll.localEnvClaimed === true
+        ? "Tokens were already claimed by another poll; re-run create to rotate them.\n"
+        : "Slack setup finished but no tokens were returned; re-run create.\n",
+    );
+    return 1;
+  }
+
+  const envEntries = [{ key: target.envKeys.bot, value: poll.localEnv.botToken }];
+  if (poll.localEnv.appToken !== undefined) {
+    envEntries.push({ key: target.envKeys.app, value: poll.localEnv.appToken });
+  }
+  const envFile = join(target.dir, ".env.local");
+  try {
+    await upsertEnvFile(envFile, envEntries);
+    if (await ensureEnvLocalGitignored(target.dir)) {
+      wrote.push(".gitignore (+.env.local)");
+    }
+  } catch (error) {
+    ctx.err(`Could not write ${envFile}: ${describeError(error)}\n`);
+    return 1;
+  }
+  wrote.push(".env.local");
+  for (const { key, value } of envEntries) {
+    process.env[key] = value;
+  }
+  if (poll.localEnv.appToken === undefined) {
+    ctx.err(
+      ctx.dim(
+        `warning: Slack did not return an app-level token, so ${target.envKeys.app} was not written.\n` +
+          `  Re-run \`${CLI} slack create\` to recover it.\n`,
+      ),
+    );
+  }
+
+  let iconStatus: "set" | "failed" | undefined;
+  if (poll.appId !== undefined) {
+    iconStatus = await applySlackCreateFileIcon(ctx, iconSource, poll.appId);
+  }
+
+  if (ctx.json) {
+    ctx.out(
+      `${JSON.stringify(
+        {
+          ok: true,
+          appId: poll.appId,
+          status: poll.status,
+          architecture: ctx.architecture,
+          envKeys: target.envKeys,
+          wrote,
+          iconStatus,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return 0;
+  }
+
+  ctx.out(
+    `Slack is connected for ${target.slug}` +
+      (poll.appId === undefined ? "" : ` (app ${poll.appId})`) +
+      `.\n  wrote ${envEntries.map(entry => entry.key).join(" + ")} to ${envFile}\n\n`,
+  );
+
+  const doctor = options.doctorImpl ?? runSlackDoctor;
+  const doctorResult = await doctor(
+    target.envPrefix === undefined ? {} : { envPrefix: target.envPrefix },
+  );
+  ctx.out(renderDoctorReport(doctorResult));
+  ctx.out(
+    `\nNext steps:\n` +
+      `  1. ${CLI} serve --dir ${options.dir} --dev\n` +
+      `  2. Invite the bot in Slack and @mention it.\n`,
+  );
+  return 0;
+}
+
+/**
+ * Resolve the one provisioned app for (slug, env[, --slack-team]) from
+ * `GET /status`. Returns an exit code with the error already rendered
+ * when zero or several apps match.
+ */
+async function resolveProvisionedApp(
+  ctx: SlackProvisionContext,
+  target: SlackAppTarget,
+  options: SlackCliOptions,
+): Promise<SlackManagedAppInfo | number> {
+  let status: SlackProvisionStatus;
+  try {
+    status = await ctx.client.status(ctx.teamId);
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+  const sameSlug = status.apps.filter(app => app.slug === target.slug);
+  let candidates = sameSlug.filter(app => app.env === target.env);
+  if (options.slackTeam !== undefined) {
+    candidates = candidates.filter(app => app.slackTeamId === options.slackTeam);
+  }
+  if (candidates.length === 0) {
+    ctx.err(
+      `No provisioned ${target.env} Slack app for "${target.slug}"${
+        options.slackTeam === undefined ? "" : ` in workspace ${options.slackTeam}`
+      } (team ${ctx.teamId}).\n` +
+        (sameSlug.length === 0
+          ? ""
+          : `Provisioned apps for this agent:\n${formatAppList(sameSlug)}`),
+    );
+    return 1;
+  }
+  if (candidates.length > 1) {
+    ctx.err(
+      `Multiple provisioned Slack apps match "${target.slug}" (${target.env}):\n` +
+        formatAppList(candidates) +
+        `Pass --slack-team <id> to pick one.\n`,
+    );
+    return 1;
+  }
+  return candidates[0]!;
+}
+
+export async function cmdSlackDestroy(options: SlackCliOptions): Promise<number> {
+  const target = resolveSlackAppTarget(options, errStream(options));
+  if (typeof target === "number") {
+    return target;
+  }
+  const ctx = await prepareProvision(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+
+  const app = await resolveProvisionedApp(ctx, target, options);
+  if (typeof app === "number") {
+    return app;
+  }
+  try {
+    await ctx.client.deleteApp({
+      teamId: ctx.teamId,
+      slackAppId: app.slackAppId,
+    });
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(
+      `${JSON.stringify(
+        {
+          ok: true,
+          deleted: true,
+          appId: app.slackAppId,
+          slackTeamId: app.slackTeamId,
+          slug: target.slug,
+          env: target.env,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return 0;
+  }
+  ctx.out(
+    `Deleted the ${target.env} Slack app for ${target.slug} (app ${app.slackAppId}) from workspace ${app.slackTeamId}.\n` +
+      `Tokens in .env.local were left in place — ${target.envKeys.bot} / ${target.envKeys.app} are now inert; remove them whenever you like.\n`,
+  );
+  return 0;
+}
+
+export async function cmdSlackIcon(options: SlackCliOptions): Promise<number> {
+  const err = errStream(options);
+  if (options.iconSource === undefined) {
+    err(
+      `Usage: ${CLI} slack icon <https-url-or-file> [--dir .] [--slack-team T0123ABCD] [--prod] [--team <id>] [--json]\n`,
+    );
+    return 1;
+  }
+  const source = await resolveSlackIconSource(options.iconSource, err);
+  if (typeof source === "number") {
+    return source;
+  }
+  const target = resolveSlackAppTarget(options, err);
+  if (typeof target === "number") {
+    return target;
+  }
+  const ctx = await prepareProvision(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  const app = await resolveProvisionedApp(ctx, target, options);
+  if (typeof app === "number") {
+    return app;
+  }
+  try {
+    await ctx.client.setAppIcon({
+      teamId: ctx.teamId,
+      slackAppId: app.slackAppId,
+      icon: toSlackAppIconInput(source),
+    });
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(
+      `${JSON.stringify(
+        {
+          ok: true,
+          appId: app.slackAppId,
+          slackTeamId: app.slackTeamId,
+          slug: target.slug,
+          env: target.env,
+          iconStatus: "set",
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return 0;
+  }
+  ctx.out(
+    `Set the icon for the ${target.env} Slack app for ${target.slug} (app ${app.slackAppId}).\n`,
+  );
+  return 0;
+}
+
+function formatAppList(
+  apps: ReadonlyArray<{
+    slackAppId: string;
+    slackTeamId: string;
+    env: string;
+    installStatus: string;
+  }>,
+): string {
+  return apps
+    .map(
+      app =>
+        `  - ${app.slackAppId} (${app.env}) in workspace ${app.slackTeamId} — ${app.installStatus}\n`,
+    )
+    .join("");
+}
+
+/**
+ * Scaffold the authored Slack channel when absent. Existing files are never
+ * overwritten: initSlackChannel writes with `wx`.
+ */
+async function scaffoldSlackChannelFiles(target: SlackAppTarget): Promise<string[]> {
+  const channelFile = projectPath(resolveProjectRoot(target.dir), "channels/slack.ts");
+  if (await fileExists(join(target.dir, channelFile))) {
+    return [];
+  }
+  try {
+    const result = await initSlackChannel({
+      dir: target.dir,
+      name: target.name,
+      envPrefix: target.envPrefix ?? "",
+    });
+    return result.files;
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "EEXIST") {
+      return [];
+    }
+    throw error;
+  }
+}
+
+function renderDoctorReport(result: SlackDoctorResult): string {
+  let text = `env: ${result.envKeys.bot} / ${result.envKeys.app}\n`;
+  for (const check of result.checks) {
+    text += `${check.ok ? "ok" : "!!"}  ${check.id}: ${check.message}\n`;
+  }
+  text += result.ok ? "doctor: pass\n" : "doctor: fail\n";
+  for (const note of result.notes ?? []) {
+    text += `\nnote: ${note}\n`;
+  }
+  return text;
+}
+
+function renderSlackApiError(error: unknown, err: (text: string) => void): number {
+  if (!(error instanceof SlackProvisionApiError)) {
+    throw error;
+  }
+  err(
+    error.code === "manager_reauth_required"
+      ? `${error.message}\nRe-run \`${CLI} slack create\` and finish Slack consent in the dashboard.\n`
+      : `${error.message}\n`,
+  );
+  return 1;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}