@sprid/cli 0.1.2

package/src/cli.mjs

@@ -0,0 +1,257 @@
+// sprid — the terminal face of one contract (REST = MCP = CLI), and the one
+// trusted local process that reads key files so a secret never has to pass
+// through an agent's conversation.
+//
+// Every command takes `--json`. Human output is short and aligned; the only
+// symbols are ✓ ✗ –. `run(argv, io)` is the whole program: `io` exists so the
+// tests can hand in a fake server, a fake browser and a clock that does not
+// wait.
+
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { parseArgs, UsageError } from "./args.mjs";
+import { readLocalApp } from "./profiles.mjs";
+import { DEFAULT_API_URL, appUrlFor, resolveAuth } from "./creds.mjs";
+import { makeClient, ApiError } from "./http.mjs";
+import { openBrowser as realOpenBrowser } from "./browser.mjs";
+import { C } from "./format.mjs";
+
+import * as auth from "./commands/auth.mjs";
+import * as status from "./commands/status.mjs";
+import * as connect from "./commands/connect.mjs";
+import * as init from "./commands/init.mjs";
+import { setup } from "./commands/setup.mjs";
+import * as misc from "./commands/misc.mjs";
+import * as mcp from "./commands/mcp.mjs";
+import * as reviews from "./commands/reviews.mjs";
+import { marketingReview } from "./commands/marketing-review.mjs";
+import { plan, research } from './commands/plan.mjs';
+import { apps, family, insights, account } from "./commands/family.mjs";
+import * as post from "./commands/post.mjs";
+import { docs } from "./commands/docs.mjs";
+import { screenshots, release } from './commands/local-tools.mjs';
+import { pinterest } from './commands/pinterest.mjs';
+import { media, capabilities } from './commands/studio.mjs';
+import { getHelp, renderHelp, suggest } from "./docs/help.mjs";
+import { completion } from "./commands/completion.mjs";
+
+import { doctor, update, notifyUpdate } from './commands/update.mjs';
+
+export const VERSION = readVersion();
+
+function readVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export const COMMANDS = {
+  plan, research,
+  media, capabilities, completion,
+  screenshots, release, doctor, update,
+  apps, family, insights, account,
+  docs,
+  login: auth.login,
+  logout: auth.logout,
+  whoami: auth.whoami,
+  use: auth.use,
+  status: status.status,
+  next: status.next,
+  queue: status.queue,
+  connect: connect.connect,
+  disconnect: connect.disconnect,
+  init: init.init,
+  setup,
+  open: misc.open,
+  invite: misc.invite,
+  upgrade: misc.upgrade,
+  mcp: mcp.mcp,
+  reviews: reviews.reviews,
+  "marketing-review": marketingReview,
+  post: post.post,
+  pinterest,
+  help: help,
+};
+
+export const HELP = renderHelp(getHelp(), VERSION);
+
+/** See ctx.workspace(). Exported for `sprid use`. */
+export async function pickWorkspace(ctx, ref) {
+  const list = await ctx.workspaces();
+  const hit = list.find((w) => w.slug === String(ref) || String(w.id) === String(ref));
+  if (!hit) {
+    throw new UsageError(
+      list.length
+        ? `No workspace "${ref}" for this token. It sees: ${list.map((w) => w.slug).join(", ")}.`
+        : `No workspace "${ref}": this token sees no workspaces.`,
+    );
+  }
+  return { id: hit.id, slug: hit.slug, name: hit.name, tier: hit.tier };
+}
+
+async function resolveWorkspace(ctx) {
+  if (ctx.flags.workspace && ctx.flags.workspace !== true) return pickWorkspace(ctx, ctx.flags.workspace);
+  const pinned = readLocalApp(ctx.cwd)?.data?.workspaceId;
+  if (pinned) return pickWorkspace(ctx, pinned);
+  const a = ctx.auth();
+  if (a.workspace?.id) return a.workspace;
+  const list = await ctx.workspaces();
+  if (list.length === 1) return { id: list[0].id, slug: list[0].slug, name: list[0].name, tier: list[0].tier };
+  if (list.length === 0) throw new ApiError(400, "This token belongs to no workspace.");
+  const local = readLocalApp(ctx.cwd)?.data?.workspace;
+  if (local) return pickWorkspace(ctx, local);
+  const rows = list.map((w) => `    ${w.slug.padEnd(Math.max(...list.map((x) => x.slug.length)) + 2)}${w.name}  (id ${w.id})`).join("\n");
+  throw new UsageError(`This token sees ${list.length} workspaces and none is chosen:\n${rows}\n  Pick one: sprid use <slug>   (or -w <slug> for one command)`);
+}
+
+async function help(ctx) {
+  const reference = getHelp(ctx.helpPath ?? ctx.positionals);
+  ctx.json ? ctx.out({ version: VERSION, ...reference }) : ctx.print(renderHelp(reference, VERSION));
+  return 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} io  overrides for tests: env, cwd, stdout, stderr, openBrowser, sleep, fetch, stdin
+ * @returns {Promise<number>} exit code
+ */
+export async function run(argv, io = {}) {
+  const env = io.env ?? process.env;
+  const write = io.stdout ?? ((s) => process.stdout.write(s));
+  const writeErr = io.stderr ?? ((s) => process.stderr.write(s));
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    const options = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length);
+    if (options.includes('--json') || options.includes('--json=true')) write(JSON.stringify({ ok: false, error: e.message, status: null }) + '\n');
+    else writeErr(`  ✗ ${e.message}\n`);
+    return 2;
+  }
+  const { flags, positionals } = parsed;
+  const json = Boolean(flags.json);
+  let command = parsed.command;
+  const passthrough = ['post', 'media', 'screenshots', 'release'].includes(command);
+  if (flags.version && !passthrough) command = "version";
+  const nativeHelp = ['screenshots', 'release'].includes(command);
+  const helpPath = flags.help && !nativeHelp && command !== 'help' && command
+    ? [command, ...positionals.slice(0, 1)] : undefined;
+  if ((flags.help && !nativeHelp) || !command) command = "help";
+
+  const ctx = {
+    env,
+    cwd: io.cwd ?? process.cwd(),
+    flags,
+    positionals,
+    helpPath,
+    commandArgv: parsed.commandArgv,
+    json,
+    version: VERSION,
+    updateOptions: io.updateOptions,
+    hostname: io.hostname ?? hostname(),
+    openBrowser: flags["no-browser"] ? async () => false : io.openBrowser ?? realOpenBrowser,
+    sleep: io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+    fetch: io.fetch ?? globalThis.fetch,
+    stdin: io.stdin ?? process.stdin,
+    /** Raw stdout, for the MCP adapter (no newline handling). */
+    rawWrite: write,
+    /** One line to the person. */
+    print: (s) => write(s.endsWith("\n") ? s : s + "\n"),
+    /** The JSON document, when --json. */
+    out: (obj) => write(JSON.stringify(obj, null, 2) + "\n"),
+    warn: (s) => writeErr(s.endsWith("\n") ? s : s + "\n"),
+    _auth: null,
+    auth() {
+      if (!this._auth) this._auth = resolveAuth(env, flags);
+      return this._auth;
+    },
+    _noticed: new Set(),
+    /** Server notices (the CLI version floor) are worth saying once, never once per request. */
+    notice(text) {
+      if (this._noticed.has(text)) return;
+      this._noticed.add(text);
+      this.warn(`  ! ${text}`);
+    },
+    api() {
+      const a = this.auth();
+      return makeClient({ apiUrl: a.apiUrl, token: a.token, fetchImpl: this.fetch, userAgent: `sprid/${VERSION}`, version: VERSION, onNotice: text => this.notice(text) });
+    },
+    /** A client for a given base + token (null token for the public device-flow routes). */
+    clientFor(apiUrl, token) {
+      return makeClient({ apiUrl, token, fetchImpl: this.fetch, userAgent: `sprid/${VERSION}`, version: VERSION, onNotice: text => this.notice(text) });
+    },
+    appUrl() {
+      return appUrlFor(this.auth().apiUrl, env);
+    },
+    /** The app URL even when nobody is logged in (for help text). */
+    appUrlSafe() {
+      try {
+        return this.appUrl();
+      } catch {
+        return appUrlFor(env.SPRID_URL || DEFAULT_API_URL, env);
+      }
+    },
+    _me: null,
+    /** GET /api/me, once. */
+    async me() {
+      if (!this._me) this._me = await this.api().get("/api/me");
+      return this._me;
+    },
+    /** The workspaces this token can see: [{id, slug, name, tier}]. */
+    async workspaces() {
+      return (await this.me())?.user?.workspaces ?? [];
+    },
+    _workspace: undefined,
+    /**
+     * The workspace every request is about, as {id, slug, name}. Order:
+     * --workspace/-w (slug or id) > pinned workspaceId in .sprid/app.json >
+     * the one stored by login / `sprid use` >
+     * the only one the token sees > `workspace` in ./.sprid/app.json > a list
+     * and exit 2. The server's own 400 ("Pass ?workspaceId=") never reaches
+     * the person.
+     */
+    async workspace() {
+      if (this._workspace !== undefined) return this._workspace;
+      this._workspace = await resolveWorkspace(this);
+      return this._workspace;
+    },
+    async workspaceId() {
+      return (await this.workspace()).id;
+    },
+  };
+
+  if (command === "version") {
+    json ? ctx.out({ version: VERSION }) : ctx.print(VERSION);
+    return 0;
+  }
+
+  const fn = COMMANDS[command];
+  if (!fn) {
+    const match = suggest(command, Object.keys(COMMANDS));
+    const message = `Unknown command "${command}".${match ? ` Did you mean "${match}"?` : ''} Try sprid help.`;
+    if (json) ctx.out({ ok: false, error: message, status: null });
+    else ctx.warn(`  ✗ ${message}`);
+    return 2;
+  }
+
+  try {
+    if (io.notifyUpdates && !flags.offline && ["status", "next"].includes(command)) await notifyUpdate(ctx).catch(() => {});
+    const code = await fn(ctx);
+    return code ?? 0;
+  } catch (e) {
+    const code = e && e.exitCode ? e.exitCode : 1;
+    const message = e && e.message ? e.message : String(e);
+    if (json) {
+      write(JSON.stringify({ ok: false, error: message, status: e?.status ?? null }) + "\n");
+    } else {
+      writeErr(`  ${C.bad("✗")} ${message}\n`);
+    }
+    return code;
+  }
+}

package/src/commands/auth.mjs

@@ -0,0 +1,192 @@
+// login / logout / whoami. The device authorization grant: this process holds
+// a long secret, the person types a short code into a signed-in browser, and
+// the server hands over a personal access token exactly once.
+
+import { DEFAULT_API_URL, deleteCredentials, credentialsPath, readCredentials, stripSlash, writeCredentials } from "../creds.mjs";
+import { ApiError } from "../http.mjs";
+import { C, OK } from "../format.mjs";
+import { pickWorkspace } from "../cli.mjs";
+import { pendingGrant } from "../pending.mjs";
+import { assertCredentialDestination } from '../endpoint.mjs';
+
+export async function login(ctx) {
+  const apiUrl = stripSlash(ctx.env.SPRID_URL || ctx.flags.api || DEFAULT_API_URL);
+  const api = ctx.clientFor(apiUrl, null);
+  const clientName = `sprid ${ctx.version} on ${ctx.hostname}`.slice(0, 80);
+
+  const pending = pendingGrant(ctx, `login:${apiUrl}:${ctx.cwd}`);
+  const previous = pending.read();
+  const start = previous ?? await api.post("/api/auth/device", { clientName });
+  const { deviceCode, userCode, verificationUrlComplete, verificationUrl, interval = 5, expiresIn = 900 } = start;
+  const openUrl = verificationUrlComplete || verificationUrl;
+  const expiresAt = previous?.expiresAt ?? Date.now() + expiresIn * 1000;
+  if (!previous) pending.write({ ...start, expiresAt });
+
+  if (ctx.json) {
+    // An agent driving this sees the code once, on stderr, so stdout stays one document.
+    ctx.warn(JSON.stringify({ userCode, verificationUrl: openUrl }));
+  } else {
+    ctx.print(`  Open ${C.bold(openUrl)} and enter  ${C.bold(userCode)}`);
+  }
+  const opened = previous ? false : await ctx.openBrowser(openUrl);
+  if (!ctx.json && opened) ctx.print(C.dim("  (opening browser…)"));
+
+  const deadline = expiresAt;
+  let waitMs = Math.max(1, Number(interval) || 5) * 1000;
+  let result = null;
+  while (Date.now() < deadline) {
+    await ctx.sleep(waitMs);
+    const { status, data } = await api.raw("POST", "/api/auth/device/token", { deviceCode });
+    if (status === 200 && data?.token) {
+      result = data;
+      break;
+    }
+    if (status === 428) {
+      if (data?.interval) waitMs = Math.max(1, Number(data.interval)) * 1000;
+      continue;
+    }
+    if (status === 429) {
+      waitMs += 5000;
+      continue;
+    }
+    const code = data?.error;
+    if (["access_denied", "expired_token", "invalid_grant"].includes(code)) pending.clear();
+    if (code === "access_denied") throw new ApiError(status, "Denied in the browser. Nothing was stored.");
+    if (code === "expired_token") throw new ApiError(status, "The code expired before it was approved. Run `sprid login` again.");
+    if (code === "invalid_grant") throw new ApiError(status, data?.message || "The device code was not accepted. Run `sprid login` again.");
+    throw new ApiError(status, data?.message || `Unexpected ${status} while waiting for approval.`);
+  }
+  if (!result) throw new ApiError(408, "The code expired before it was approved. Run `sprid login` again.");
+
+  const finalApi = stripSlash(result.apiUrl || apiUrl);
+  assertCredentialDestination(finalApi, apiUrl);
+  // Ask who we are so the file carries the email. Best effort: a failure here
+  // must not lose the token that was just minted.
+  let email = null;
+  try {
+    const me = await ctx.clientFor(finalApi, result.token).get("/api/me");
+    email = me?.user?.email ?? null;
+  } catch {
+    email = null;
+  }
+
+  const creds = {
+    apiUrl: finalApi,
+    token: result.token,
+    tokenId: result.tokenId ?? null,
+    workspace: result.workspace ?? null,
+    email,
+    createdAt: new Date().toISOString(),
+  };
+  const path = writeCredentials(creds, ctx.env);
+  pending.clear();
+
+  if (ctx.json) {
+    ctx.out({ ok: true, apiUrl: creds.apiUrl, tokenId: creds.tokenId, workspace: creds.workspace, email, credentials: path });
+  } else {
+    const ws = creds.workspace ? `workspace ${creds.workspace.slug}` : "no workspace";
+    const tier = creds.workspace?.tier ? ` · ${tierName(creds.workspace.tier)}` : "";
+    ctx.print(`  ${C.ok(OK)} ${email ?? "signed in"} · ${ws}${tier}`);
+    ctx.print(C.dim(`  Token stored at ${path} (0600). Revoke any time: \`sprid logout\` or Settings → Tokens.`));
+    ctx.print("  Next, in your app’s repo: sprid init, then sprid connect. Already set up? Run sprid status.");
+  }
+  return 0;
+}
+
+export async function logout(ctx) {
+  const file = readCredentials(ctx.env);
+  let revoked = false;
+  if (file?.tokenId) {
+    try {
+      // raw(): a token that is already gone (401/404) is not an error here.
+      const { status } = await ctx.clientFor(file.apiUrl || DEFAULT_API_URL, file.token).raw("DELETE", `/api/tokens/${file.tokenId}`);
+      revoked = status >= 200 && status < 300;
+    } catch {
+      revoked = false;
+    }
+  }
+  const path = deleteCredentials(ctx.env);
+  if (ctx.json) {
+    ctx.out({ ok: true, revoked, removed: Boolean(file), credentials: path });
+  } else if (!file) {
+    ctx.print(`  Nothing stored at ${path}. Already logged out.`);
+  } else {
+    ctx.print(`  ${C.ok(OK)} Logged out. ${revoked ? "Token revoked on the server, local file" : "Local file"} removed.`);
+  }
+  return 0;
+}
+
+export async function whoami(ctx) {
+  const a = ctx.auth();
+  const me = await ctx.me();
+  const user = me?.user ?? {};
+  const workspaces = user.workspaces ?? [];
+  // The current one, if it can be known without asking; never exit 2 from whoami.
+  const current = await ctx.workspace().catch(() => null);
+  const source = a.source === "env" ? "SPRID_PAT" : credentialsPath(ctx.env);
+  if (ctx.json) {
+    ctx.out({
+      email: user.email ?? a.email ?? null,
+      userId: user.id ?? null,
+      workspace: current,
+      workspaces,
+      apiUrl: a.apiUrl,
+      tokenSource: source,
+      tokenId: a.tokenId,
+    });
+    return 0;
+  }
+  const wsLine = current
+    ? `${current.slug}${current.tier ? ` (${tierName(current.tier)})` : ""}`
+    : workspaces.length
+      ? "none chosen"
+      : "no workspace";
+  ctx.print(`  ${user.email ?? a.email ?? "(unknown)"} · workspace ${wsLine}`);
+  ctx.print(C.dim(`  ${a.apiUrl} · token from ${source}`));
+  if (workspaces.length > 1) {
+    ctx.print(workspaceList(workspaces, current));
+    if (!current) ctx.print(C.dim("  Pick one: sprid use <slug>"));
+  }
+  return 0;
+}
+
+export function workspaceList(workspaces, current) {
+  const w = Math.max(...workspaces.map((x) => x.slug.length)) + 2;
+  return workspaces
+    .map((x) => `  ${x.id === current?.id ? "*" : " "} ${x.slug.padEnd(w)}${x.name}${x.tier ? C.dim(`  ${tierName(x.tier)}`) : ""}  ${C.dim(`id ${x.id}`)}`)
+    .join("\n");
+}
+
+/**
+ * `sprid use <slug|id>` remembers the workspace in the credentials file. With
+ * SPRID_PAT and no file, the file is written with only `workspace`; token
+ * resolution stays env > file, so nothing about auth changes.
+ */
+export async function use(ctx) {
+  const [ref] = ctx.positionals;
+  const workspaces = await ctx.workspaces();
+  if (!ref) {
+    const current = await ctx.workspace().catch(() => null);
+    if (ctx.json) {
+      ctx.out({ current, workspaces });
+      return 0;
+    }
+    if (!workspaces.length) {
+      ctx.print("  This token sees no workspaces.");
+      return 0;
+    }
+    ctx.print(workspaceList(workspaces, current));
+    if (!current) ctx.print(C.dim("  Pick one: sprid use <slug>"));
+    return 0;
+  }
+  const picked = await pickWorkspace(ctx, ref);
+  const file = readCredentials(ctx.env) ?? {};
+  const path = writeCredentials({ ...file, workspace: picked }, ctx.env);
+  if (ctx.json) ctx.out({ ok: true, workspace: picked, credentials: path });
+  else ctx.print(`  ${C.ok(OK)} Using ${picked.name} (${picked.slug})`);
+  return 0;
+}
+
+export function tierName(tier) {
+  return { starter: "Pulse", growth: "Push", dev: "Push", founding: "Founding", lifetime: "Founding", founder: "Founder" }[tier] ?? tier;
+}

package/src/commands/completion.mjs

@@ -0,0 +1,90 @@
+import { commandNames, commandEntries, subcommands, HELP_TOPICS } from '../docs/help.mjs';
+import { getDocumentation } from '../docs/index.mjs';
+import { VALUE_FLAGS, UsageError } from '../args.mjs';
+
+export function completionWords() {
+  return Object.fromEntries(commandNames().map(command => {
+    const entries = commandEntries(command);
+    const words = entries.flatMap(entry => [...subcommands(entry), ...(entry.usage.match(/--[a-z][a-z-]*/g) ?? [])]);
+    if (command === 'docs') words.push(...getDocumentation().guides.map(g => g.id));
+    if (command === 'help') words.push(...commandNames(), ...Object.keys(HELP_TOPICS));
+    return [command, [...new Set([...words, '--help', '--json', '--workspace'])].sort()];
+  }));
+}
+
+// Only catalog-owned words enter generated shell code. No user values or API calls.
+export function completionScript(shell) {
+  const words = completionWords();
+  const names = Object.keys(words).join(' ');
+  const valueFlags = new Set(VALUE_FLAGS);
+  for (const command of commandNames()) for (const entry of commandEntries(command)) {
+    for (const [, flag, value] of entry.usage.matchAll(/--([a-z-]+)\s+(\S+)/g)) {
+      if (!value.startsWith('-') && !value.startsWith('[--')) valueFlags.add(flag);
+    }
+  }
+  const valueOptions = [...valueFlags].map(flag => `--${flag}`).concat('-w');
+  if (shell === 'bash') return `# Source with: source <(sprid completion bash)
+_sprid_complete() {
+  local cur prev command word skip=0 i options
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  COMPREPLY=()
+  case "$prev" in ${valueOptions.join('|')}) return ;; esac
+  for ((i=1; i<COMP_CWORD; i++)); do
+    word="\${COMP_WORDS[i]}"
+    if ((skip)); then skip=0; continue; fi
+    case "$word" in
+      --) return ;;
+      ${valueOptions.join('|')}) skip=1 ;;
+      -*) ;;
+      *) command="$word"; break ;;
+    esac
+  done
+  options='${names} --help --version --json'
+  case "$command" in
+${Object.entries(words).map(([name, options]) => `    ${name}) options='${options.join(' ')}' ;;`).join('\n')}
+  esac
+  COMPREPLY=( $(compgen -W "$options" -- "$cur") )
+}
+complete -o default -F _sprid_complete sprid
+`;
+  if (shell === 'zsh') return `# Run compinit first, then: source <(sprid completion zsh)
+_sprid_complete() {
+  local command word skip=0 i
+  local -a candidates
+  case "$words[CURRENT-1]" in ${valueOptions.join('|')}) _files; return ;; esac
+  for ((i=2; i<CURRENT; i++)); do
+    word="$words[i]"
+    if ((skip)); then skip=0; continue; fi
+    case "$word" in
+      --) _files; return ;;
+      ${valueOptions.join('|')}) skip=1 ;;
+      -*) ;;
+      *) command="$word"; break ;;
+    esac
+  done
+  candidates=(${names} --help --version --json)
+  case "$command" in
+${Object.entries(words).map(([name, options]) => `    ${name}) candidates=(${options.join(' ')}) ;;`).join('\n')}
+  esac
+  compadd -- $candidates
+  _files
+}
+compdef _sprid_complete sprid
+`;
+  if (shell === 'fish') return `# Load with: sprid completion fish | source
+complete -c sprid -n '__fish_use_subcommand' -a '${names}'
+${Object.entries(words).flatMap(([name, options]) => options.map(option => option.startsWith('--')
+    ? `complete -c sprid -n '__fish_seen_subcommand_from ${name}' -l ${option.slice(2)}${valueFlags.has(option.slice(2)) ? ' -r' : ''}`
+    : `complete -c sprid -n '__fish_seen_subcommand_from ${name}' -a '${option}'`)).join('\n')}
+`;
+  throw new UsageError('Use sprid completion bash, zsh or fish.');
+}
+
+export async function completion(ctx) {
+  if (ctx.positionals.length !== 1) throw new UsageError('Use sprid completion bash, zsh or fish.');
+  const shell = ctx.positionals[0];
+  const script = completionScript(shell);
+  ctx.json ? ctx.out({ shell, script }) : ctx.print(script);
+  return 0;
+}