@sprid/cli 0.1.2

package/src/commands/connect.mjs

@@ -0,0 +1,586 @@
+// connect: the one command that crosses from "a key on this machine" to "a
+// sensor on the server". Three shapes:
+//
+//   sprid connect                          the wizard: what is missing, and the line that fixes each
+//   sprid connect instagram --account x    OAuth in the browser, polled here until the tick
+//   sprid connect asc --key … --key-id …   read the file, PATCH the profile's secrets. Never printed.
+//   sprid connect --from-local             every key ~/.sprid/secrets/<slug>.json points at
+//
+// Nothing here prints a key's contents, in any mode. `--json` reports which
+// secret keys are now set, never their values.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { UsageError } from "../args.mjs";
+import { secretsPath } from "../creds.mjs";
+import { ApiError } from "../http.mjs";
+import { pendingGrant } from "../pending.mjs";
+import { C, BAD, EXPIRING, NONE, OK, table, wrap } from "../format.mjs";
+import { connectionRows } from "./status.mjs";
+import { confirm } from "./reviews.mjs";
+import { expandHome, listProfiles, patchProfile, readKeyFile, readLocalApp, resolveProfile } from "../profiles.mjs";
+
+export const CHANNEL_PLATFORMS = ["instagram", "tiktok", "youtube", "linkedin", "facebook", "pinterest", "x"];
+export const SENSOR_SERVICES = [
+  "asc",
+  "play",
+  "gsc",
+  "posthog",
+  // The revenue rails. RevenueCat reads store sales; the other four read web
+  // ones, and a customer may legitimately have two of them.
+  "revenuecat",
+  "stripe",
+  "polar",
+  "lemonsqueezy",
+  "paddle",
+  "cloudflare",
+];
+/** Model / generation keys held per WORKSPACE (BYOK), not per App Profile. */
+export const PROVIDERS = ["anthropic", "openai", "fal", "google", "replicate"];
+
+/** Every secret key a service owns on the App Profile; `--clear` nulls all of them. */
+export const SENSOR_KEYS = {
+  asc: ["ascPrivateKey", "ascKeyId", "ascIssuerId"],
+  play: ["playServiceAccountJson"],
+  gsc: ["gscServiceAccountJson"],
+  posthog: ["posthogApiKey"],
+  revenuecat: ["revenuecatApiKey"],
+  stripe: ["stripeApiKey"],
+  polar: ["polarApiKey"],
+  lemonsqueezy: ["lemonSqueezyApiKey"],
+  paddle: ["paddleApiKey"],
+  cloudflare: ["cloudflareApiToken"],
+};
+
+const SENSOR_LABEL = {
+  asc: "App Store Connect",
+  play: "Google Play",
+  gsc: "Search Console",
+  posthog: "PostHog",
+  revenuecat: "RevenueCat",
+  stripe: "Stripe",
+  polar: "Polar",
+  lemonsqueezy: "Lemon Squeezy",
+  paddle: "Paddle",
+  cloudflare: "Cloudflare",
+};
+
+const PENDING_POLL_MS = 3000;
+const PENDING_TIMEOUT_MS = 10 * 60 * 1000;
+
+export async function connect(ctx) {
+  const [what] = ctx.positionals;
+  if (ctx.flags["from-local"]) return fromLocal(ctx);
+  if (!what) return wizard(ctx);
+  if (CHANNEL_PLATFORMS.includes(what)) return connectChannel(ctx, what);
+  if (SENSOR_SERVICES.includes(what)) return connectSensor(ctx, what);
+  if (PROVIDERS.includes(what)) return connectProvider(ctx, what);
+  throw new UsageError(
+    `Unknown target "${what}". Channels: ${CHANNEL_PLATFORMS.join(", ")}. Keys: ${SENSOR_SERVICES.join(", ")}. Model keys: ${PROVIDERS.join(", ")}.`,
+  );
+}
+
+// ─── the wizard ──────────────────────────────────────────────────────────────
+
+async function wizard(ctx) {
+  const wid = await ctx.workspaceId();
+  const { connections = [] } = await ctx.api().get(`/api/connections?workspaceId=${wid}`);
+
+  // Channels that do not exist at all are not rows in /connections, so ask
+  // for the accounts and mark the core platforms that have no channel.
+  let accounts = [];
+  try {
+    const rows = await ctx.api().get("/api/accounts");
+    accounts = (Array.isArray(rows) ? rows : rows?.accounts ?? []).filter((a) => a.workspaceId === wid);
+  } catch {
+    accounts = [];
+  }
+  // Sensors whose id is not even set are optional; list them per profile.
+  let profiles = [];
+  try {
+    profiles = await listProfiles(ctx, wid);
+  } catch {
+    profiles = [];
+  }
+
+  const { next = [] } = await ctx.api().get(`/api/status?workspaceId=${wid}`);
+  const setup = next.filter((a) => a.kind === "first-app" || a.ref?.setup === "account");
+
+  const missingKeys = connections.filter((c) => c.kind === "sensor" && c.health === "missing");
+  // A key that is set but whose last pull failed: the store's own error text
+  // is the useful part, so it gets its own group and the detail in full.
+  const failing = connections.filter((c) => c.health === "error");
+  // Only revoked is a reconnect. Expiring usually refreshes itself hourly.
+  const brokenChannels = connections.filter((c) => c.kind === "channel" && c.health === "revoked");
+  const expiring = connections.filter((c) => c.health === "expiring");
+  const notConnected = [];
+  for (const a of accounts) {
+    for (const p of ["instagram", "tiktok", "youtube", "linkedin", "pinterest", "x"]) {
+      if (!connections.some((c) => c.kind === "channel" && c.scope === a.slug && c.service === p)) {
+        notConnected.push({ account: a.slug, platform: p, cli: `sprid connect ${p} --account ${a.slug}` });
+      }
+    }
+  }
+  const optional = [];
+  for (const p of profiles) {
+    const opts = [];
+    if (!p.posthogProjectId) opts.push("PostHog");
+    if (!p.revenuecatProjectId) opts.push("RevenueCat");
+    if (!p.gscProperty) opts.push("Search Console");
+    if (!p.cloudflareZoneId) opts.push("Cloudflare");
+    if (!p.appStoreId) opts.push("App Store Connect");
+    if (!p.playPackageName) opts.push("Google Play");
+    if (opts.length) optional.push({ app: p.slug, services: opts });
+  }
+  const ok = connections.filter((c) => c.health === "ok");
+
+  if (ctx.json) {
+    ctx.out({ workspaceId: wid, setup, missingKeys, failing, brokenChannels, expiring, notConnected, optional, ok });
+    return 0;
+  }
+
+  const lines = setup.map((a) => `  ${a.title} → ${a.cli}\n    ${a.why}`);
+  if (missingKeys.length) {
+    lines.push(C.bold("  Missing keys"));
+    lines.push(table(missingKeys.map((c) => [`${NONE} ${c.label}`, C.dim("→"), c.cli]), { indent: "    " }));
+  }
+  if (failing.length) {
+    lines.push(C.bold("  Failing"));
+    for (const c of failing) {
+      lines.push(`    ${BAD} ${c.label}`);
+      lines.push(...failureLines(c, "      "));
+    }
+  }
+  if (brokenChannels.length) {
+    lines.push(C.bold("  Channels to reconnect"));
+    lines.push(table(brokenChannels.map((c) => [`${BAD} ${c.label}`, C.dim(c.detail ?? c.health), c.cli]), { indent: "    " }));
+  }
+  if (expiring.length) {
+    lines.push(C.bold("  Expiring soon, usually refreshes itself"));
+    lines.push(table(expiring.map((c) => [`${EXPIRING} ${c.label}`, C.dim(c.detail ?? "")]), { indent: "    " }));
+  }
+  if (notConnected.length) {
+    lines.push(C.bold("  Channels not connected"));
+    lines.push(table(notConnected.map((c) => [`${NONE} ${c.platform} @${c.account}`, C.dim("→"), c.cli]), { indent: "    " }));
+  }
+  if (optional.length) {
+    lines.push(C.bold("  Optional (no id on the profile yet)"));
+    for (const o of optional) lines.push(`    ${o.app}: ${o.services.join(", ")}  ${C.dim("→ sprid init, or add the id in Settings → App Profiles")}`);
+  }
+  if (ok.length) {
+    lines.push(C.bold("  Connected"));
+    const rows = connectionRows(ok);
+    const byok = ok.filter((c) => PROVIDERS.includes(c.service));
+    if (byok.length) rows.push(["BYOK", byok.map((c) => `${c.service} ${OK}`).join("  ")]);
+    lines.push(table(rows, { indent: "    " }));
+  }
+  if (!lines.length) lines.push("  Everything that has an id is connected. Nothing to do.");
+  ctx.print(lines.join("\n"));
+  return 0;
+}
+
+/**
+ * A failing row, as the server now describes it: `detail` is a plain sentence,
+ * `fix` is the imperative, `url` is where to do it. Printed in that order, then
+ * the command. Nothing raw from the store is printed any more.
+ */
+export function failureLines(c, indent = "") {
+  const out = [];
+  for (const l of wrap(c.detail ?? "The last pull failed.", 100)) out.push(C.dim(`${indent}${l}`));
+  if (c.fix) for (const l of wrap(`Fix: ${c.fix}`, 100)) out.push(`${indent}${l}`);
+  if (c.url) out.push(`${indent}${c.url}`);
+  if (c.cli) out.push(`${indent}${c.cli}`);
+  return out;
+}
+
+// ─── channels (OAuth) ────────────────────────────────────────────────────────
+
+async function connectChannel(ctx, platform) {
+  const account = ctx.flags.account;
+  if (!account) throw new UsageError(`sprid connect ${platform} --account <slug>`);
+  const returnUrl = `${ctx.appUrl()}/connected`;
+  const auth = ctx.auth();
+  const pageId = ctx.flags.page;
+  if (pageId && platform !== "facebook") throw new UsageError("--page is only supported for Facebook connections.");
+  const pending = pendingGrant(ctx, `channel:${auth.apiUrl}:${auth.token}:${account}:${platform}:${pageId ?? ""}`);
+  const previous = pending.read();
+  const { url, pendingId } = previous ?? await ctx.api().post(`/api/channels/connect/${platform}`, { accountSlug: account, returnUrl, ...(pageId ? { pageId } : {}) });
+  if (!url) throw new ApiError(500, "The server returned no authorize URL.");
+  if (!previous && pendingId) pending.write({ url, pendingId, expiresAt: Date.now() + PENDING_TIMEOUT_MS });
+
+  if (ctx.json) ctx.warn(JSON.stringify({ url, pendingId }));
+  else ctx.print(`  Open ${C.bold(url)}`);
+  const opened = previous ? false : await ctx.openBrowser(url);
+  if (!ctx.json) ctx.print(C.dim(`  ${opened ? "Opening the browser… " : ""}waiting for ${label(platform)}`));
+
+  if (!pendingId) {
+    // Older server: nothing to poll. Say so instead of pretending.
+    if (ctx.json) ctx.out({ ok: true, polled: false, url });
+    else ctx.print(`  Finish in the browser, then check with \`sprid status\`.`);
+    return 0;
+  }
+
+  const deadline = Date.now() + PENDING_TIMEOUT_MS;
+  let last = null;
+  while (Date.now() < deadline) {
+    await ctx.sleep(PENDING_POLL_MS);
+    last = await ctx.api().get(`/api/channels/pending/${pendingId}`);
+    if (last.status && last.status !== "pending") break;
+  }
+  const s = last?.status ?? "pending";
+  if (s === "connected") {
+    pending.clear();
+    const handle = last.channel?.displayName ? `@${last.channel.displayName}` : label(platform);
+    if (ctx.json) ctx.out({ ok: true, status: s, channel: last.channel, account });
+    else ctx.print(`  ${C.ok(OK)} ${handle} connected to ${account}`);
+    return 0;
+  }
+  const message =
+    s === "conflict"
+      ? `${last.error || "That login is already connected to another account."} Move it in Settings → Accounts, or connect a different login.`
+      : s === "expired" || s === "pending"
+        ? "Timed out waiting for the browser (10 minutes). Run the command again."
+      : last?.error || `Connect ${s}.`;
+  if (s !== "pending") pending.clear();
+  if (ctx.json) {
+    ctx.out({ ok: false, status: s, error: message, channel: last?.channel ?? null });
+    return 1;
+  }
+  throw new ApiError(0, message);
+}
+
+function label(platform) {
+  return { instagram: "Instagram", tiktok: "TikTok", youtube: "YouTube", linkedin: "LinkedIn", facebook: "Facebook", pinterest: "Pinterest", x: "X" }[platform] ?? platform;
+}
+
+// ─── sensors (keys) ──────────────────────────────────────────────────────────
+
+/**
+ * A token flag takes a file path or the value itself. The guides say file, so
+ * the secret never sits in shell history; the bare value still works for a
+ * one-off. Contents are trimmed (a trailing newline is not part of a key).
+ */
+export function fileOrValue(arg, cwd) {
+  const p = resolve(cwd, expandHome(String(arg)));
+  if (existsSync(p) && statSync(p).isFile()) {
+    const text = readFileSync(p, "utf8").trim();
+    if (!text) throw new UsageError(`Key file is empty: ${p}`);
+    return text;
+  }
+  return String(arg);
+}
+
+/** Flags → the PATCH body for one service. Reads files; never echoes them. */
+export function sensorPatch(service, flags, cwd) {
+  const need = (name) => {
+    const v = flags[name];
+    if (!v || v === true) throw new UsageError(`sprid connect ${service} needs --${name}`);
+    return String(v);
+  };
+  switch (service) {
+    case "asc":
+      return {
+        secrets: {
+          ascPrivateKey: readKeyFile(need("key"), cwd),
+          ascKeyId: need("key-id"),
+          ascIssuerId: need("issuer"),
+        },
+      };
+    case "play":
+      return { secrets: { playServiceAccountJson: readKeyFile(need("key"), cwd) } };
+    case "gsc":
+      return {
+        gscProperty: need("property"),
+        secrets: { gscServiceAccountJson: readKeyFile(need("key"), cwd) },
+      };
+    case "posthog": {
+      const body = { posthogProjectId: need("project"), secrets: { posthogApiKey: fileOrValue(need("key"), cwd) } };
+      if (flags.host && flags.host !== true) {
+        const host = String(flags.host);
+        body.posthogHost = host === "eu" || host === "us" ? `https://${host}.posthog.com` : host;
+      }
+      return body;
+    }
+    case "revenuecat":
+      return { revenuecatProjectId: need("project"), secrets: { revenuecatApiKey: fileOrValue(need("key"), cwd) } };
+    // Stripe and Paddle need no id: the key names the account. Polar takes an
+    // optional organization id (an org token already implies one), Lemon
+    // Squeezy needs its store id.
+    case "stripe":
+      return { secrets: { stripeApiKey: fileOrValue(need("key"), cwd) } };
+    case "polar": {
+      const body = { secrets: { polarApiKey: fileOrValue(need("key"), cwd) } };
+      if (flags.org && flags.org !== true) body.polarOrganizationId = String(flags.org);
+      return body;
+    }
+    case "lemonsqueezy":
+      return {
+        lemonSqueezyStoreId: String(need("store")),
+        secrets: { lemonSqueezyApiKey: fileOrValue(need("key"), cwd) },
+      };
+    case "paddle": {
+      const body = { secrets: { paddleApiKey: fileOrValue(need("key"), cwd) } };
+      if (flags.env && flags.env !== true) body.paddleEnvironment = String(flags.env) === "sandbox" ? "sandbox" : "live";
+      return body;
+    }
+    case "cloudflare":
+      return { cloudflareZoneId: need("zone"), secrets: { cloudflareApiToken: fileOrValue(need("token"), cwd) } };
+    default:
+      throw new UsageError(`Unknown key type "${service}"`);
+  }
+}
+
+async function connectSensor(ctx, service) {
+  if (ctx.flags.clear) return clearSensor(ctx, service);
+  const body = sensorPatch(service, ctx.flags, ctx.cwd);
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  const updated = await patchProfile(ctx, wid, profile.id, body);
+  report(ctx, updated, Object.keys(body.secrets), `${SENSOR_LABEL[service]} key`, wid, service);
+  return 0;
+}
+
+/** `--clear`: PATCH every key of the service to null. The id stays; only the key goes. */
+async function clearSensor(ctx, service) {
+  const keys = SENSOR_KEYS[service];
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  const updated = await patchProfile(ctx, wid, profile.id, { secrets: Object.fromEntries(keys.map((k) => [k, null])) });
+  if (ctx.json) {
+    ctx.out({ ok: true, cleared: keys, profile: { id: updated.id, slug: updated.slug, name: updated.name }, secretsSet: updated.secretsSet, sensors: updated.sensors });
+  } else {
+    ctx.print(`  ${C.ok(OK)} ${SENSOR_LABEL[service]} key removed from ${updated.slug}  ${C.dim(keys.join(", "))}`);
+  }
+  return 0;
+}
+
+function report(ctx, profile, keys, what, workspaceId, service) {
+  const app = "'" + profile.slug.replace(/'/g, "'\\''") + "'";
+  const verifyCommand = `sprid marketing-review --workspace ${workspaceId} --app ${app} --days 7 --json`;
+  const guideUrl = service ? `https://sprid.studio/docs/connect/${({ asc: "app-store-connect", play: "google-play", gsc: "search-console" })[service] ?? service}` : undefined;
+  if (ctx.json) {
+    ctx.out({ ok: true, verified: false, verifyCommand, guideUrl, profile: { id: profile.id, slug: profile.slug, name: profile.name }, set: keys, secretsSet: profile.secretsSet, sensors: profile.sensors });
+    return;
+  }
+  ctx.print(`  ${C.ok(OK)} ${what} set on ${profile.slug}  ${C.dim(keys.join(", "))}`);
+  const s = profile.sensors ?? {};
+  const running = Object.entries(s)
+    .filter(([, v]) => v)
+    .map(([k]) => k);
+  if (running.length) ctx.print(C.dim(`  Sensors configured: ${running.join(", ")}`));
+  ctx.print(`  Key saved; provider access has not been checked. Verify: ${verifyCommand}`);
+  if (guideUrl) ctx.print(C.dim(`  Setup and required permissions: ${guideUrl}`));
+}
+
+// ─── provider keys (BYOK, per workspace) ─────────────────────────────────────
+
+/**
+ * `sprid connect anthropic --key <file or sk-ant-…>`. The server validates the
+ * key live and stores it encrypted; what comes back is a display hint
+ * ("sk-ant...ab12"), which is all this ever prints.
+ */
+async function connectProvider(ctx, provider) {
+  if (ctx.flags.clear) return clearProvider(ctx, provider);
+  const raw = ctx.flags.key;
+  if (!raw || raw === true) throw new UsageError(`sprid connect ${provider} --key <file or key>`);
+  const apiKey = fileOrValue(raw, ctx.cwd);
+  if (apiKey.length < 8) throw new UsageError("That key is too short to be one.");
+  const wid = await ctx.workspaceId();
+  let created;
+  try {
+    created = await ctx.api().post("/api/provider-keys", { workspaceId: wid, provider, apiKey });
+  } catch (e) {
+    // "anthropic key validation failed" is the server's own verdict; pass it on as is.
+    if (e instanceof ApiError && e.status === 400) throw new ApiError(400, e.message);
+    throw e;
+  }
+  const hint = created?.keyDisplayHint ?? null;
+  if (ctx.json) {
+    ctx.out({ ok: true, provider, id: created?.id ?? null, keyDisplayHint: hint, status: created?.status ?? "active", workspaceId: wid });
+  } else {
+    ctx.print(`  ${C.ok(OK)} ${provider} key set on the workspace${hint ? `  ${C.dim(hint)}` : ""}`);
+    if (provider === "anthropic" || provider === "openai") ctx.print(C.dim("  Review replies and other drafting now run on your own key."));
+  }
+  return 0;
+}
+
+/** `--clear`: revoke the workspace's active key for the provider (id from the list). */
+async function clearProvider(ctx, provider) {
+  const wid = await ctx.workspaceId();
+  const rows = await ctx.api().get(`/api/provider-keys?workspaceId=${wid}`);
+  const list = Array.isArray(rows) ? rows : rows?.keys ?? [];
+  const hits = list.filter((r) => r.provider === provider && (r.status ?? "active") === "active");
+  if (hits.length === 0) {
+    if (ctx.json) ctx.out({ ok: true, cleared: [], provider, note: "no active key" });
+    else ctx.print(`  No ${provider} key on this workspace. Nothing to remove.`);
+    return 0;
+  }
+  for (const r of hits) await ctx.api().del(`/api/provider-keys/${r.id}`);
+  if (ctx.json) ctx.out({ ok: true, cleared: hits.map((r) => r.id), provider, workspaceId: wid });
+  else ctx.print(`  ${C.ok(OK)} ${provider} key removed from the workspace${hits[0].keyDisplayHint ? `  ${C.dim(hits[0].keyDisplayHint)}` : ""}`);
+  return 0;
+}
+
+// ─── --from-local ────────────────────────────────────────────────────────────
+
+/**
+ * ~/.sprid/secrets/<slug>.json, the shape the plugin's pull scripts read:
+ *   { gscServiceAccountPath, cloudflareApiToken,
+ *     asc: { keyId, issuerId, keyPath },
+ *     playServiceAccounts: { "<packageName>": "<sa json path>" } }
+ * Extras accepted when present: posthogApiKey, revenuecatApiKey.
+ */
+export function localSecretsPatch(local, profile, cwd) {
+  const secrets = {};
+  const skipped = [];
+  const file = (p) => readFileSync(expandHome(p), "utf8");
+  const exists = (p) => existsSync(expandHome(p));
+
+  if (local.asc?.keyPath && local.asc.keyId && local.asc.issuerId) {
+    if (exists(local.asc.keyPath)) {
+      secrets.ascPrivateKey = file(local.asc.keyPath);
+      secrets.ascKeyId = String(local.asc.keyId);
+      secrets.ascIssuerId = String(local.asc.issuerId);
+    } else skipped.push(`asc: ${local.asc.keyPath} not found`);
+  }
+  if (local.playServiceAccounts && typeof local.playServiceAccounts === "object") {
+    const entries = Object.entries(local.playServiceAccounts);
+    const pick = profile?.playPackageName ? entries.find(([pkg]) => pkg === profile.playPackageName) : entries.length === 1 ? entries[0] : null;
+    if (pick) {
+      if (exists(pick[1])) secrets.playServiceAccountJson = file(pick[1]);
+      else skipped.push(`play: ${pick[1]} not found`);
+    } else if (entries.length) {
+      skipped.push(`play: no entry for ${profile?.playPackageName ?? "(profile has no playPackageName)"}; have ${entries.map(([k]) => k).join(", ")}`);
+    }
+  }
+  if (local.gscServiceAccountPath) {
+    if (exists(local.gscServiceAccountPath)) secrets.gscServiceAccountJson = file(local.gscServiceAccountPath);
+    else skipped.push(`gsc: ${local.gscServiceAccountPath} not found`);
+  }
+  if (local.cloudflareApiToken) secrets.cloudflareApiToken = String(local.cloudflareApiToken);
+  if (local.posthogApiKey) secrets.posthogApiKey = String(local.posthogApiKey);
+  if (local.revenuecatApiKey) secrets.revenuecatApiKey = String(local.revenuecatApiKey);
+
+  return { body: { secrets }, keys: Object.keys(secrets), skipped };
+}
+
+async function fromLocal(ctx) {
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  const slug = ctx.flags.app || readLocalApp(ctx.cwd)?.data?.slug || profile.slug;
+  const path = secretsPath(slug, ctx.env);
+  if (!existsSync(path)) throw new UsageError(`No local secrets at ${path}.`);
+  let local;
+  try {
+    local = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    throw new UsageError(`${path} is not valid JSON: ${e.message}`);
+  }
+  const { body, keys, skipped } = localSecretsPatch(local, profile, ctx.cwd);
+  if (keys.length === 0) {
+    if (ctx.json) ctx.out({ ok: false, set: [], skipped, error: `Nothing usable in ${path}` });
+    else {
+      ctx.print(`  Nothing usable in ${path}.`);
+      for (const s of skipped) ctx.print(C.dim(`  ${NONE} ${s}`));
+    }
+    return 1;
+  }
+  const updated = await patchProfile(ctx, wid, profile.id, body);
+  report(ctx, updated, keys, `${keys.length} key${keys.length === 1 ? "" : "s"} from ${path}`, wid);
+  if (!ctx.json) for (const s of skipped) ctx.print(C.dim(`  ${NONE} skipped ${s}`));
+  return 0;
+}
+
+// ─── disconnect ──────────────────────────────────────────────────────────────
+
+/**
+ * sprid disconnect <platform> --account <slug> [--forget] [--id <channelId>]
+ *
+ * Two different things, and the difference matters:
+ *   plain      the grant is dropped, the row stays. Reconnecting the same
+ *              login revives it with its publish history intact.
+ *   --forget   the row goes. This is the only way to clear a channel that
+ *              was connected to the wrong account — a plain disconnect
+ *              leaves a dead row that keeps showing in Connections. The
+ *              server refuses to forget a channel that has published.
+ */
+export async function disconnect(ctx) {
+  const [platform] = ctx.positionals;
+  const account = ctx.flags.account;
+  const forget = !!ctx.flags.forget;
+  if (!platform || !CHANNEL_PLATFORMS.includes(platform)) {
+    throw new UsageError(
+      `sprid disconnect <${CHANNEL_PLATFORMS.join("|")}> --account <slug> [--forget]`,
+    );
+  }
+  if (!account) throw new UsageError(`sprid disconnect ${platform} --account <slug>`);
+
+  const rows = await ctx.api().get(`/api/channels?account=${encodeURIComponent(account)}`);
+  let hits = (rows ?? []).filter((r) => r.platform === platform);
+  if (ctx.flags.id) hits = hits.filter((r) => String(r.id) === String(ctx.flags.id));
+  // Without --id, a plain disconnect means the live one and --forget means
+  // the dead ones: that is what each word is for, and it is unambiguous
+  // whenever an account holds both.
+  else hits = forget
+    ? (hits.some((r) => r.status !== "active") ? hits.filter((r) => r.status !== "active") : hits)
+    : hits.filter((r) => r.status === "active");
+
+  if (hits.length === 0) {
+    const msg = `No ${label(platform)} channel on ${account}${forget ? " to forget" : " is connected"}.`;
+    if (ctx.json) ctx.out({ ok: true, changed: [], note: msg });
+    else ctx.print(`  ${NONE} ${msg}`);
+    return 0;
+  }
+  if (hits.length > 1 && !ctx.flags.id) {
+    const list = hits.map((r) => `    --id ${r.id}  ${r.displayName ?? r.platformUserId} (${r.status})`);
+    if (ctx.json) {
+      ctx.out({ ok: false, error: "Several channels match; pass --id.", channels: hits });
+      return 1;
+    }
+    ctx.print(`  ${BAD} Several ${label(platform)} channels on ${account}. Pass one:`);
+    for (const l of list) ctx.print(C.dim(l));
+    return 1;
+  }
+
+  // A disconnect stops a live channel publishing, and it is one word away
+  // from the harmless --forget. Ask, the way `reviews reply` asks.
+  const what = hits
+    .map((r) => `${label(platform)} ${r.displayName ?? r.platformUserId} (${r.status})`)
+    .join(", ");
+  if (!ctx.flags.yes) {
+    const interactive = Boolean(ctx.stdin?.isTTY);
+    const verb = forget ? "Removing" : "Disconnecting";
+    if (ctx.json || !interactive) {
+      const msg = `${verb} ${what} on ${account}. Re-run with --yes to do it without the prompt.`;
+      if (ctx.json) ctx.out({ ok: false, error: msg, channels: hits });
+      else ctx.warn(`  ${BAD} ${msg}`);
+      return 2;
+    }
+    ctx.print(`  ${verb} ${what} on ${account}.`);
+    ctx.print(
+      C.dim(
+        forget
+          ? "  The row goes. Nothing that was published is affected."
+          : "  Scheduled posts on it will fail until you connect again.",
+      ),
+    );
+    const ok = await confirm(ctx, forget ? "  Remove it? [y/N] " : "  Disconnect it? [y/N] ");
+    if (!ok) {
+      ctx.print("  Nothing changed.");
+      return 1;
+    }
+  }
+
+  const done = [];
+  for (const r of hits) {
+    await ctx.api().del(`/api/channels/${r.id}${forget ? "?purge=1" : ""}`);
+    done.push({ id: r.id, handle: r.displayName ?? r.platformUserId, forgotten: forget });
+  }
+  if (ctx.json) ctx.out({ ok: true, changed: done, account, platform });
+  else
+    for (const d of done)
+      ctx.print(
+        `  ${C.ok(OK)} ${d.handle} ${forget ? "removed from" : "disconnected from"} ${account}`,
+      );
+  return 0;
+}

package/src/commands/docs.mjs

@@ -0,0 +1,53 @@
+import { getDocumentation, searchDocumentation } from '../docs/index.mjs';
+import { DEFAULT_API_URL } from '../creds.mjs';
+import { UsageError } from '../args.mjs';
+
+export async function docs(ctx) {
+  const [topic] = ctx.positionals;
+  if (topic === 'search') {
+    const query = ctx.positionals.slice(1).join(' ').trim();
+    if (!query) throw new UsageError('Supply search words, for example: sprid docs search posthog permissions');
+    const limit = Number(ctx.flags.limit ?? 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new UsageError('--limit must be an integer from 1 to 100.');
+    const matches = searchDocumentation(query);
+    const results = matches.slice(0, limit);
+    if (ctx.json) ctx.out({ topic: 'search', query, source: 'bundled', total: matches.length, results });
+    else ctx.print(results.length
+      ? `Bundled documentation · ${matches.length} matches · showing ${results.length}\n\n${results.map(result => `${result.title}\n  ${result.read}\n  ${result.excerpt}`).join('\n\n')}`
+      : `No bundled documentation matches "${query}". Run sprid docs to list guides.`);
+    return 0;
+  }
+  if (ctx.positionals.length > 1) throw new UsageError('Use sprid docs <topic>, or sprid docs search <words>.');
+  if (topic && !/^[a-z0-9-]+$/.test(topic)) throw new UsageError('Use a guide name or cli. Run sprid docs to list guides.');
+  let document;
+  try { document = getDocumentation(topic); }
+  catch (error) { if (ctx.flags.offline) throw new UsageError(error.message); }
+  let source = 'bundled';
+  let note;
+  // CLI syntax must describe this executable, even when the server is newer.
+  if (!ctx.flags.offline && topic !== 'cli') {
+    try {
+      const base = ctx.env.SPRID_URL || DEFAULT_API_URL;
+      const response = await ctx.fetch(`${base.replace(/\/$/, '')}/api/docs${topic ? '/' + encodeURIComponent(topic) : ''}`, { signal: AbortSignal.timeout(3000) });
+      if (!response.ok) throw new Error('Guide request failed');
+      const live = await response.json();
+      const expectedTopic = document?.topic ?? live.topic;
+      if ((!document && !['connect', 'content'].includes(live.topic)) || live.topic !== expectedTopic ||
+        (['connect', 'content'].includes(expectedTopic) && live.id !== (document?.id ?? topic)) ||
+        (expectedTopic !== 'index' && typeof live.markdown !== 'string') ||
+        (expectedTopic === 'index' && !Array.isArray(live.guides))) throw new Error('Invalid guide response');
+      document = live;
+      source = 'live';
+    } catch {
+      note = 'Could not read the current guide. This is the copy shipped with your CLI; the website may have newer steps.';
+    }
+  }
+  if (!document) throw new UsageError(`Guide "${topic}" is unavailable. Run sprid docs to list services.`);
+  if (ctx.json) ctx.out({ ...document, source, ...(note ? { note } : {}) });
+  else {
+    if (note) ctx.print(note + '\n');
+    if (document.markdown) ctx.print(document.markdown);
+    else ctx.print(document.guides.map(guide => `${guide.title}\n  sprid docs ${guide.id}\n  ${guide.summary}`).join('\n\n'));
+  }
+  return 0;
+}