@cursor/july 0.1.15 → 0.1.17

package/src/internal/cli-slack.ts

@@ -1,15 +1,39 @@
 /**
- * `agent-serve slack …` CLI — manifests, setup, doctor (Socket Mode).
+ * `agent-serve slack …` CLI — manifests, setup, doctor (Socket Mode), and
+ * managed provisioning (`create` / `destroy`) through Cursor's
+ * "Add to Slack" API (`slack-provision-client.ts`).
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
-import { basename, join, resolve as resolvePath } from "node:path";
+import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, join, resolve as resolvePath } from "node:path";
 import {
+  buildSlackManifest,
   buildSlackManifestPair,
+  envPrefixFromName,
   formatSlackSetupGuide,
   initSlackChannel,
   runSlackDoctor,
+  type SlackDoctorResult,
+  slackEnvKeys,
 } from "../channels/slack/index.js";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { cursorExternalApiUrl } from "./cursor/credentials.js";
+import { slugFromDirectoryName } from "./deploy-client.js";
+import { describeError } from "./describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { loadAgentLocalEnv } from "./local-env.js";
+import { openBrowser } from "./open-browser.js";
+import {
+  AgentServeSlackClient,
+  type SlackAppEnv,
+  type SlackAppIconContentType,
+  type SlackAppIconInput,
+  type SlackAppProvisionResult,
+  type SlackConnectedWorkspace,
+  type SlackManagedAppInfo,
+  SlackProvisionApiError,
+  type SlackProvisionStatus,
+} from "./slack-provision-client.js";
 
 export interface SlackCliOptions {
   dir: string;
@@ -23,22 +47,69 @@ export interface SlackCliOptions {
   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: overwrite manifest edits made in Slack (skip the drift check). */
+  force?: boolean;
+  /** `slack icon <source>` positional (same URL-or-file forms as --icon). */
+  iconSource?: 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;
 }
 
 const SLACK_HELP = `agent-serve slack — Slack channel pack helpers (Socket Mode)
 
 Usage:
   agent-serve slack setup
+  agent-serve slack create    [--dir .] [--name NAME] [--slack-team T0123ABCD]
+                                [--prod] [--team <id>] [--icon URL-or-FILE]
+                                [--force] [--prefix PREFIX | --no-prefix] [--json]
+  agent-serve slack destroy   [--dir .] [--slack-team T0123ABCD] [--prod]
+                                [--team <id>] [--json]
+  agent-serve slack icon      <URL-or-FILE> [--dir .] [--slack-team T0123ABCD]
+                                [--prod] [--team <id>] [--json]
   agent-serve slack init      [--dir .] [--name NAME] [--prefix PREFIX | --no-prefix]
                                 [--channel-posts]
   agent-serve slack manifest --env dev|prod|both [--dir .] [--name NAME]
                                 [--print]
-  agent-serve slack doctor [--prefix PREFIX] [--json]
+  agent-serve slack doctor [--dir .] [--prefix PREFIX | --no-prefix] [--json]
+
+create/destroy/icon — Cursor "Add to Slack" managed provisioning:
+  create   One-command Path B setup: connects the Slack workspace (browser
+           consent) when needed, creates + installs this agent's dedicated
+           Socket Mode app from the generated manifest, writes the token
+           pair into <dir>/.env.local, then runs doctor (prose mode; --json
+           reports without the doctor pass). Requires
+           \`agent-serve login\` (or CURSOR_API_KEY) and the feature gate.
+           --prod provisions the prod app (default dev); --slack-team picks
+           the workspace when several are connected. --icon sets the app's
+           icon (best-effort: a bad icon warns, never fails the create).
+           A re-run refuses to overwrite manifest edits made by hand at
+           api.slack.com (manifest_drift); --force overwrites them.
+  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).
 
 Env tokens:
   single agent:  SLACK_BOT_TOKEN + SLACK_APP_TOKEN
   multi-agent:   <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN
-                 (init defaults PREFIX from the directory name)
+                 (init/create default PREFIX from the directory name;
+                  doctor defaults to it too when those keys are set)
 
 See also: skills/setup-slack/SKILL.md
 `;
@@ -57,6 +128,12 @@ export async function cmdSlack(
     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(options);
     case "manifest":
@@ -155,21 +232,922 @@ async function runManifest(options: SlackCliOptions): Promise<number> {
 }
 
 async function runDoctor(options: SlackCliOptions): Promise<number> {
-  const result = await runSlackDoctor(
-    options.prefix === undefined ? {} : { envPrefix: options.prefix }
-  );
+  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 result = await doctor(envPrefix === undefined ? {} : { envPrefix });
   if (options.json) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   } else {
-    process.stdout.write(
-      `env: ${result.envKeys.bot} / ${result.envKeys.app}\n`
+    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_CONNECT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_CONNECT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
+
+interface SlackProvisionContext {
+  client: AgentServeSlackClient;
+  teamId: number;
+  json: boolean;
+  out: (text: string) => void;
+  err: (text: string) => void;
+  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"
     );
-    for (const check of result.checks) {
-      process.stdout.write(
-        `${check.ok ? "ok" : "!!"}  ${check.id}: ${check.message}\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;
     }
-    process.stdout.write(result.ok ? "doctor: pass\n" : "doctor: fail\n");
+    return { kind: "url", url: raw };
   }
-  return result.ok ? 0 : 1;
+  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 };
+}
+
+/**
+ * URL icons ride the provision request; file icons post to the icon
+ * endpoint afterwards. Best-effort: failures warn, never fail the create.
+ */
+async function applySlackCreateIcon(
+  ctx: SlackProvisionContext,
+  source: SlackIconSource | undefined,
+  result: SlackAppProvisionResult
+): Promise<"set" | "failed" | undefined> {
+  if (source === undefined) {
+    return undefined;
+  }
+  let failure: string | undefined;
+  if (source.kind === "url") {
+    if (result.iconStatus !== "set") {
+      failure = "Slack did not accept the icon URL";
+    }
+  } else {
+    try {
+      await ctx.client.setAppIcon({
+        teamId: ctx.teamId,
+        slackAppId: result.appId,
+        icon: toSlackAppIconInput(source),
+      });
+    } catch (error) {
+      failure = describeError(error);
+    }
+  }
+  if (failure === undefined) {
+    return "set";
+  }
+  const retryWith = source.kind === "url" ? source.url : source.path;
+  ctx.err(
+    `warning: setting the Slack app icon failed: ${failure}\nRetry with \`${CLI} slack icon ${retryWith}\`.\n`
+  );
+  return "failed";
+}
+
+/**
+ * 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 auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+    err,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+  // Provisioning routes live on the external API host beside deploys.
+  return {
+    client: new AgentServeSlackClient({
+      backendUrl: cursorExternalApiUrl(),
+      apiKey: auth.apiKey,
+      fetchImpl: options.fetchImpl,
+    }),
+    teamId: auth.teamId,
+    json: options.json === true,
+    out,
+    err,
+    openBrowserImpl: options.openBrowserImpl ?? openBrowser,
+    pollIntervalMs:
+      options.connectPollIntervalMs ?? DEFAULT_CONNECT_POLL_INTERVAL_MS,
+    pollTimeoutMs:
+      options.connectPollTimeoutMs ?? DEFAULT_CONNECT_POLL_TIMEOUT_MS,
+  };
+}
+
+/** What the connect poll waits for in `GET /status`. */
+interface ConnectWaitTarget {
+  /** Wait for this workspace to be connected (else: any workspace). */
+  slackTeamId?: string;
+  /**
+   * Wait for connectedAt to move past this value — a fresh grant. Used
+   * whenever the workspace row already exists and only the new approval
+   * bumps its timestamp.
+   */
+  notConnectedAt?: string;
+}
+
+function matchConnectedWorkspace(
+  workspaces: SlackConnectedWorkspace[],
+  wait: ConnectWaitTarget
+): SlackConnectedWorkspace | undefined {
+  const candidates =
+    wait.slackTeamId === undefined
+      ? workspaces
+      : workspaces.filter(
+          (workspace) => workspace.slackTeamId === wait.slackTeamId
+        );
+  if (wait.notConnectedAt === undefined) {
+    return candidates[0];
+  }
+  return candidates.find(
+    (workspace) => workspace.connectedAt !== wait.notConnectedAt
+  );
+}
+
+/**
+ * Mint the browser consent URL, open it, and poll `GET /status` until the
+ * awaited workspace shows up (or the poll times out). Returns the
+ * connected workspace, or an exit code with the error already rendered.
+ */
+async function runConnectFlow(
+  ctx: SlackProvisionContext,
+  wait: ConnectWaitTarget
+): Promise<SlackConnectedWorkspace | number> {
+  let url: string;
+  try {
+    url = await ctx.client.connect(ctx.teamId);
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+  ctx.err(
+    `\nConnect your Slack workspace to Cursor — approve in the browser:\n\n  ${url}\n\n(waiting for the Slack consent to complete, up to ${Math.round(ctx.pollTimeoutMs / 60_000)} minutes)\n`
+  );
+  ctx.openBrowserImpl(url);
+  const deadline = Date.now() + ctx.pollTimeoutMs;
+  let lastPollFailure: string | undefined;
+  for (;;) {
+    let workspace: SlackConnectedWorkspace | undefined;
+    let sleepMs = ctx.pollIntervalMs;
+    try {
+      const status = await ctx.client.status(ctx.teamId);
+      workspace = matchConnectedWorkspace(status.workspaces, wait);
+      lastPollFailure = undefined;
+    } catch (error) {
+      // Transient poll failures must not abort a minted consent flow; only
+      // a still-failing poll at the deadline surfaces the error.
+      if (Date.now() >= deadline) {
+        return renderSlackApiError(error, ctx.err);
+      }
+      const failure = describeError(error);
+      if (failure !== lastPollFailure) {
+        lastPollFailure = failure;
+        ctx.err(`(status poll failed, retrying: ${failure})\n`);
+      }
+      if (
+        error instanceof SlackProvisionApiError &&
+        error.retryAfterSeconds !== undefined
+      ) {
+        // Respect backend backpressure instead of hammering at the poll rate.
+        sleepMs = Math.max(sleepMs, error.retryAfterSeconds * 1000);
+      }
+    }
+    if (workspace !== undefined) {
+      ctx.err(`Connected Slack workspace ${workspace.slackTeamId}.\n`);
+      return workspace;
+    }
+    if (Date.now() >= deadline) {
+      ctx.err(
+        `Timed out waiting for the Slack workspace connection. The consent link stays valid for ~10 minutes — approve it and re-run \`${CLI} slack create\`.\n`
+      );
+      return 1;
+    }
+    await sleep(sleepMs);
+  }
+}
+
+export async function cmdSlackCreate(
+  options: SlackCliOptions
+): Promise<number> {
+  const target = resolveSlackAppTarget(options, errStream(options));
+  if (typeof target === "number") {
+    return target;
+  }
+  // Resolved before any network I/O so a bad path/type/size fails fast.
+  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;
+  }
+
+  // Workspace: --slack-team wins; one → use it; none → connect; several → ask.
+  let status: SlackProvisionStatus;
+  try {
+    status = await ctx.client.status(ctx.teamId);
+  } catch (error) {
+    return renderSlackApiError(error, ctx.err);
+  }
+  let workspace: SlackConnectedWorkspace | undefined;
+  if (options.slackTeam !== undefined) {
+    workspace = status.workspaces.find(
+      (candidate) => candidate.slackTeamId === options.slackTeam
+    );
+  } else if (status.workspaces.length === 1) {
+    workspace = status.workspaces[0];
+  } else if (status.workspaces.length > 1) {
+    ctx.err(
+      `Multiple Slack workspaces are connected:\n` +
+        status.workspaces
+          .map(
+            (candidate) =>
+              `  - ${candidate.slackTeamId} (Slack user ${candidate.slackUserId}, connected ${candidate.connectedAt})\n`
+          )
+          .join("") +
+        `Pass --slack-team <id> to pick one.\n`
+    );
+    return 1;
+  }
+  if (workspace === undefined) {
+    const connected = await runConnectFlow(ctx, {
+      slackTeamId: options.slackTeam,
+    });
+    if (typeof connected === "number") {
+      return connected;
+    }
+    workspace = connected;
+  }
+
+  let wrote: string[];
+  try {
+    wrote = await scaffoldSlackChannelFiles(options, target);
+  } catch (error) {
+    ctx.err(`${describeError(error)}\n`);
+    return 1;
+  }
+  if (wrote.length > 0 && !ctx.json) {
+    ctx.err(`Scaffolded the Slack channel: ${wrote.join(", ")}\n`);
+  }
+  // A re-run rebuilds this manifest from flags, so backend-side
+  // customizations reset to it (documented in the skill).
+  const manifest = buildSlackManifest({
+    name: target.name,
+    env: target.env,
+    channelPosts: options.channelPosts === true,
+  });
+  const manifestJson = JSON.stringify(manifest);
+
+  // One connect-and-retry for not_connected / insufficient_scopes (both
+  // are fixed by a fresh consent grant).
+  let result: SlackAppProvisionResult;
+  let connectRetried = false;
+  for (;;) {
+    try {
+      result = await ctx.client.provisionApp({
+        teamId: ctx.teamId,
+        slackTeamId: workspace.slackTeamId,
+        slug: target.slug,
+        env: target.env,
+        manifest: manifestJson,
+        icon: iconSource?.kind === "url" ? { url: iconSource.url } : undefined,
+        force: options.force === true ? true : undefined,
+      });
+      break;
+    } catch (error) {
+      if (
+        error instanceof SlackProvisionApiError &&
+        (error.code === "not_connected" ||
+          error.code === "insufficient_scopes") &&
+        !connectRetried
+      ) {
+        connectRetried = true;
+        // Both codes arrive holding a row that GET /status already lists, so
+        // the poll waits for a fresh grant instead of re-matching that row.
+        const wait: ConnectWaitTarget = {
+          slackTeamId: workspace.slackTeamId,
+          notConnectedAt: workspace.connectedAt,
+        };
+        if (error.code === "insufficient_scopes") {
+          ctx.err(
+            `The Slack connection is missing scopes provisioning needs; approving the consent link again grants them.\n`
+          );
+        } else {
+          ctx.err(
+            `The Slack workspace is not connected to Cursor; starting the connect flow.\n`
+          );
+        }
+        const connected = await runConnectFlow(ctx, wait);
+        if (typeof connected === "number") {
+          return connected;
+        }
+        workspace = connected;
+        continue;
+      }
+      return renderCreateProvisionError(error, ctx.err);
+    }
+  }
+
+  const iconStatus = await applySlackCreateIcon(ctx, iconSource, result);
+
+  if (result.status === "pending_admin_approval") {
+    if (ctx.json) {
+      ctx.out(
+        `${JSON.stringify(
+          {
+            ok: false,
+            appId: result.appId,
+            status: result.status,
+            slackTeamId: workspace.slackTeamId,
+            envKeys: target.envKeys,
+            wrote,
+            oauthAuthorizeUrl: result.oauthAuthorizeUrl ?? null,
+            iconStatus,
+          },
+          null,
+          2
+        )}\n`
+      );
+    } else {
+      ctx.err(
+        `The Slack app was created (app ${result.appId}), but installing it needs a Slack workspace-admin approval.\n` +
+          (result.oauthAuthorizeUrl === undefined
+            ? ""
+            : `\n  Approve it (or send this to a workspace admin):\n\n    ${result.oauthAuthorizeUrl}\n\n`) +
+          `Once an admin approves the app, re-run \`${CLI} slack create\` to finish the install and mint the tokens.\n`
+      );
+    }
+    return 1;
+  }
+
+  // Tokens come back exactly once and are never printed.
+  const envEntries = [{ key: target.envKeys.bot, value: result.botToken }];
+  if (result.appToken !== undefined) {
+    envEntries.push({ key: target.envKeys.app, value: result.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 (result.appToken === undefined) {
+    ctx.err(
+      `warning: Slack did not return an app-level token, so ${target.envKeys.app} was not written (an existing value was left as-is and may belong to an older app); re-run \`${CLI} slack create\` to recover it.\n`
+    );
+  }
+
+  if (ctx.json) {
+    ctx.out(
+      `${JSON.stringify(
+        {
+          ok: true,
+          appId: result.appId,
+          status: result.status,
+          slackTeamId: workspace.slackTeamId,
+          envKeys: target.envKeys,
+          wrote,
+          iconStatus,
+        },
+        null,
+        2
+      )}\n`
+    );
+    return 0;
+  }
+
+  ctx.out(
+    `Provisioned the ${target.env} Slack app for ${target.slug} (app ${result.appId}) in workspace ${workspace.slackTeamId}.\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} dev ${options.dir}\n` +
+      `  2. In Slack, invite @${manifest.features.bot_user.display_name} to a channel and @mention it (or DM 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 channel files when the channel file is absent. Existing
+ * files are never overwritten: initSlackChannel writes with `wx`, and
+ * EEXIST means "already scaffolded" (provisioning builds its manifest in
+ * memory and does not need the on-disk copies).
+ */
+async function scaffoldSlackChannelFiles(
+  options: SlackCliOptions,
+  target: SlackAppTarget
+): Promise<string[]> {
+  const channelFile = "agent/channels/slack.ts";
+  if (await fileExists(join(target.dir, channelFile))) {
+    return [];
+  }
+  try {
+    // Pass the resolved name/prefix so the channel file and the env keys
+    // share one derivation.
+    const result = await initSlackChannel({
+      dir: target.dir,
+      name: target.name,
+      envPrefix: target.envPrefix ?? "",
+      channelPosts: options.channelPosts,
+    });
+    return result.files;
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "EEXIST") {
+      // The channel file is written first, so it exists by the time a
+      // later pre-existing file aborts the scaffold.
+      return (await fileExists(join(target.dir, channelFile)))
+        ? [channelFile]
+        : [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Append `KEY=value` lines to an env file, replacing every existing line
+ * for the same key instead of appending duplicates. Creates the file when
+ * missing.
+ */
+async function upsertEnvFile(
+  path: string,
+  entries: Array<{ key: string; value: string }>
+): Promise<void> {
+  let existing = "";
+  try {
+    existing = await readFile(path, "utf8");
+  } catch (error) {
+    if (!isErrnoException(error) || error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const lines =
+    existing === "" ? [] : existing.replace(/\r?\n$/, "").split(/\r?\n/);
+  // A stale `export KEY=…` line would shadow or duplicate the bare line
+  // under some loaders; treat both spellings as the same entry.
+  const matchesKey = (line: string, key: string): boolean =>
+    line.startsWith(`${key}=`) || line.startsWith(`export ${key}=`);
+  for (const { key, value } of entries) {
+    const next = `${key}=${value}`;
+    let replaced = false;
+    for (let i = 0; i < lines.length; ) {
+      if (!matchesKey(lines[i] ?? "", key)) {
+        i += 1;
+        continue;
+      }
+      if (replaced) {
+        lines.splice(i, 1);
+        continue;
+      }
+      lines[i] = next;
+      replaced = true;
+      i += 1;
+    }
+    if (!replaced) {
+      lines.push(next);
+    }
+  }
+  // writeFile's mode only applies on create; clamp pre-existing files too.
+  await writeFile(path, `${lines.join("\n")}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+/**
+ * Ensure the agent directory's .gitignore covers .env.local (create or
+ * append). A bare `.env` line does not count — that pattern matches only
+ * the file literally named .env.
+ */
+async function ensureEnvLocalGitignored(dir: string): Promise<boolean> {
+  const path = join(dir, ".gitignore");
+  let existing = "";
+  try {
+    existing = await readFile(path, "utf8");
+  } catch (error) {
+    if (!isErrnoException(error) || error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const covered = existing
+    .split(/\r?\n/)
+    .some((line) => /^\.env(\.local\*?|\.\*|\*)$/.test(line.trim()));
+  if (covered) {
+    return false;
+  }
+  const next =
+    existing === "" || existing.endsWith("\n")
+      ? `${existing}.env.local\n`
+      : `${existing}\n.env.local\n`;
+  await writeFile(path, next);
+  return true;
+}
+
+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";
+  return text;
+}
+
+/**
+ * Actionable rendering for `POST /apps` failures the create flow does not
+ * retry itself (the connect-and-retry codes are handled by the caller).
+ */
+function renderCreateProvisionError(
+  error: unknown,
+  err: (text: string) => void
+): number {
+  if (!(error instanceof SlackProvisionApiError)) {
+    throw error;
+  }
+  switch (error.code) {
+    case "app_conflict":
+      err(
+        `${error.message}\nA concurrent \`${CLI} slack create\` for this agent won the race; re-run create to pick up that app.\n`
+      );
+      return 1;
+    case "app_cap_reached":
+      err(
+        `${error.message}\nDelete unused apps with \`${CLI} slack destroy\`, then re-run create.\n`
+      );
+      return 1;
+    case "ratelimited":
+      err(`${error.message}\nRe-run \`${CLI} slack create\` after the wait.\n`);
+      return 1;
+    case "invalid_app_id":
+      err(
+        `${error.message}\nThe provisioned Slack app seems to have been deleted outside Cursor. Run \`${CLI} slack destroy\` to drop the stale record, then re-run \`${CLI} slack create\`.\n`
+      );
+      return 1;
+    case "manifest_drift":
+      err(
+        `${error.message}\n` +
+          (error.changedPaths ?? []).map((path) => `  - ${path}\n`).join("") +
+          `Re-run \`${CLI} slack create --force\` to overwrite those edits.\n`
+      );
+      return 1;
+    default:
+      err(`${error.message}\n`);
+      return 1;
+  }
+}
+
+function renderSlackApiError(
+  error: unknown,
+  err: (text: string) => void
+): number {
+  if (error instanceof SlackProvisionApiError) {
+    err(`${error.message}\n`);
+    return 1;
+  }
+  throw error;
+}
+
+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;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }