@sprid/cli 0.1.2

package/src/commands/family.mjs

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { UsageError } from "../args.mjs";
+import { resolveProfile } from "../profiles.mjs";
+
+function objectFile(ctx) {
+  if (!ctx.flags.file)
+    throw new UsageError(
+      "Pass --file <payload.json>. The file must contain a JSON object.",
+    );
+  const data = JSON.parse(
+    readFileSync(resolve(ctx.cwd, String(ctx.flags.file)), "utf8"),
+  );
+  if (!data || Array.isArray(data) || typeof data !== "object")
+    throw new UsageError("Expected a JSON object.");
+  return data;
+}
+function positiveId(raw) {
+  const id = Number(raw);
+  if (!Number.isInteger(id) || id <= 0)
+    throw new UsageError("Pass a positive family or edition ID.");
+  return id;
+}
+export async function apps(ctx) {
+  ctx.out(await ctx.api().get("/api/app-profiles/hierarchy"));
+  return 0;
+}
+export async function family(ctx) {
+  const [verb = "list", raw] = ctx.positionals;
+  let result;
+  if (verb === "list" || verb === "compare") {
+    const workspaceId = await ctx.workspaceId();
+    const app = await resolveProfile(ctx, workspaceId);
+    result = await ctx
+      .api()
+      .get(
+        `/api/content-families${verb === "compare" ? "/performance" : ""}?workspaceId=${workspaceId}&app=${app.id}&ageDays=${encodeURIComponent(ctx.flags.days ?? 7)}`,
+      );
+  } else if (verb === "create")
+    result = await ctx.api().post("/api/content-families", objectFile(ctx));
+  else {
+    const id = positiveId(raw);
+    const edition = ["get", "preview", "review", "localize"].includes(verb);
+    const path = edition
+      ? `/api/content-families/editions/${id}`
+      : `/api/content-families/${id}`;
+    if (verb === "get") result = await ctx.api().get(path);
+    else if (verb === "preview")
+      result = await ctx.api().post(`${path}/preview`, {});
+    else if (
+      ["edition", "review", "localize", "plan", "schedule"].includes(verb)
+    )
+      result = await ctx
+        .api()
+        .post(
+          `${path}/${verb === "edition" ? "editions" : verb}`,
+          objectFile(ctx),
+        );
+    else
+      throw new UsageError(
+        "sprid family list|create|edition|get|localize|preview|review|plan|schedule|compare [id] [--file payload.json]",
+      );
+  }
+  // Always print exact IDs, preview URLs, blockers and revision fingerprints.
+  ctx.out(result);
+  return 0;
+}
+export async function insights(ctx) {
+  const workspaceId = await ctx.workspaceId();
+  const app = await resolveProfile(ctx, workspaceId);
+  const query = new URLSearchParams({
+    workspaceId: String(workspaceId),
+    app: String(app.id),
+    days: String(ctx.flags.days ?? 30),
+  });
+  if (ctx.flags.account) query.set("account", ctx.flags.account);
+  ctx.out(await ctx.api().get(`/api/insights?${query}`));
+  return 0;
+}
+
+export async function account(ctx) {
+  const [verb, raw] = ctx.positionals;
+  if (verb === "create")
+    ctx.out(await ctx.api().post("/api/accounts", objectFile(ctx)));
+  else if (verb === "update")
+    ctx.out(
+      await ctx
+        .api()
+        .patch(`/api/accounts/${positiveId(raw)}`, objectFile(ctx)),
+    );
+  else
+    throw new UsageError(
+      "sprid account create|update [id] --file payload.json",
+    );
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,137 @@
+// init: .sprid/app.json (written by /sprid:bootstrap, or by the flags here)
+// becomes an App Profile on the server. Ids only; keys go through `sprid
+// connect`, which is the line between the free diagnosis and the paid sensor.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { UsageError } from "../args.mjs";
+import { C, NONE, OK, table } from "../format.mjs";
+import { createProfile, listProfiles, patchProfile, readLocalApp } from "../profiles.mjs";
+
+/** The App Profile's own field names, as bootstrap writes them. */
+export const PROFILE_FIELDS = [
+  "slug",
+  "name",
+  "appStoreId",
+  "playPackageName",
+  "gscProperty",
+  "posthogProjectId",
+  "posthogHost",
+  "revenuecatProjectId",
+  "cloudflareZoneId",
+  "cloudflareAccountTag",
+  "playExportBucket",
+  "repoUrl",
+  "websiteUrl",
+  "accountId",
+  "posthogEvents",
+  "posthogConfig",
+  "metricsCollectionEnabled",
+  "polarOrganizationId",
+  "lemonSqueezyStoreId",
+  "paddleEnvironment",
+];
+
+const FLAG_TO_FIELD = {
+  name: "name",
+  slug: "slug",
+  "app-store-id": "appStoreId",
+  "play-package": "playPackageName",
+  "gsc-property": "gscProperty",
+  "posthog-project": "posthogProjectId",
+  "posthog-host": "posthogHost",
+  "revenuecat-project": "revenuecatProjectId",
+  "cloudflare-zone": "cloudflareZoneId",
+  "repo-url": "repoUrl",
+  "website-url": "websiteUrl",
+};
+
+export function profileFromFlags(flags) {
+  const out = {};
+  for (const [flag, field] of Object.entries(FLAG_TO_FIELD)) {
+    if (flags[flag] && flags[flag] !== true) out[field] = String(flags[flag]);
+  }
+  return out;
+}
+
+export function pickProfileFields(data) {
+  const out = {};
+  for (const k of PROFILE_FIELDS) {
+    if (data[k] !== undefined && data[k] !== null && data[k] !== "") out[k] = data[k];
+  }
+  return out;
+}
+
+export async function init(ctx) {
+  const local = readLocalApp(ctx.cwd);
+  const fromFlags = profileFromFlags(ctx.flags);
+  let input;
+  let source;
+  if (Object.keys(fromFlags).length) {
+    if (!fromFlags.name) throw new UsageError("sprid init --name <app name> [--app-store-id N] [--play-package P] …");
+    input = { ...(local ? pickProfileFields(local.data) : {}), ...fromFlags };
+    source = "flags";
+  } else if (local) {
+    input = pickProfileFields(local.data);
+    source = local.path;
+    if (!input.name) throw new UsageError(`${local.path} has no "name".`);
+  } else {
+    const msg = [
+      `  No .sprid/app.json in ${ctx.cwd}. Three ways to make one:`,
+      `    1. In the app's repo, in your agent: /sprid:bootstrap  (reads the repo, grades the listing, writes the file)`,
+      `    2. sprid init --name "My App" --app-store-id 123456789 --play-package com.example.app [--gsc-property sc-domain:example.com …]`,
+      `    3. The web form: ${ctx.appUrlSafe()}/settings/app-profiles`,
+    ].join("\n");
+    if (ctx.json) {
+      ctx.out({ ok: false, error: "No .sprid/app.json", ways: ["/sprid:bootstrap", "sprid init --name … flags", `${ctx.appUrlSafe()}/settings/app-profiles`] });
+    } else {
+      ctx.print(msg);
+    }
+    return 2;
+  }
+
+  const wid = await ctx.workspaceId();
+  if (local?.data.workspaceId && Number(local.data.workspaceId) !== Number(wid))
+    throw new UsageError(`This repo belongs to workspace ${local.data.workspaceId}. Use --workspace ${local.data.workspaceId}; do not register it in a different workspace.`);
+  const profiles = await listProfiles(ctx, wid);
+  const pinnedId = local?.data.appId;
+  const existing = pinnedId
+    ? profiles.find(p => Number(p.id) === Number(pinnedId))
+    : profiles.find(p => input.slug && p.slug === input.slug);
+  if (pinnedId && !existing) throw new UsageError(`App ${pinnedId} is unavailable in workspace ${wid}. Restore access before registering again.`);
+  // A server rename does not change the app this repo is attached to.
+  if (pinnedId && !fromFlags.slug) input.slug = existing.slug;
+  if (pinnedId && !fromFlags.name) input.name = existing.name;
+  const profile = existing ? await patchProfile(ctx, wid, existing.id, input) : await createProfile(ctx, wid, input);
+
+  // Pin server identity after either bootstrap-file or flags initialization.
+  {
+    const p = resolve(ctx.cwd, ".sprid", "app.json");
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ ...local?.data, ...pickProfileFields({ ...input, slug: profile.slug }), appId: profile.id, workspaceId: wid }, null, 2) + "\n");
+    source = p;
+  }
+
+  // What is still missing, for this app only.
+  let missing = [];
+  try {
+    const { connections = [] } = await ctx.api().get(`/api/connections?workspaceId=${wid}`);
+    missing = connections.filter((c) => c.kind === "sensor" && c.scope === profile.slug && c.health !== "ok");
+  } catch {
+    missing = [];
+  }
+
+  if (ctx.json) {
+    ctx.out({ ok: true, created: !existing, source, profile, missing });
+    return 0;
+  }
+  ctx.print(`  ${C.ok(OK)} ${existing ? "Updated" : "Created"} App Profile ${C.bold(profile.slug)} (${profile.name}) from ${source}`);
+  const set = PROFILE_FIELDS.filter((k) => k !== "slug" && k !== "name" && profile[k]).map((k) => [k, profile[k]]);
+  if (set.length) ctx.print(table(set, { indent: "    " }));
+  if (missing.length) {
+    ctx.print("  Still missing:");
+    ctx.print(table(missing.map((m) => [`${NONE} ${m.label.split(" · ")[0]}`, C.dim("→"), m.cli]), { indent: "    " }));
+  }
+  ctx.print("  Next: sprid connect. Your dashboard: " + ctx.appUrlSafe() + "/home?workspaceId=" + wid);
+  return 0;
+}

package/src/commands/local-tools.mjs

@@ -0,0 +1,31 @@
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+
+// Packages are installed with Sprid; never download or execute a fresh npx target.
+export async function localTool(ctx, packageName) {
+  const entry = require.resolve(`${packageName}/cli`);
+  const args = (ctx.commandArgv ?? []).filter(arg => arg !== '--json');
+  return new Promise((resolve, reject) => {
+    const child = spawn('bun', [entry, ...args], { cwd: ctx.cwd, env: ctx.env, stdio: ['inherit', 'pipe', 'pipe'] });
+    let output = '', truncated = false, failedToStart = false;
+    child.stdout.on('data', chunk => {
+      if (!ctx.json) return ctx.rawWrite(chunk.toString());
+      const remaining = 8 * 1024 * 1024 - output.length;
+      output += chunk.toString().slice(0, Math.max(0, remaining));
+      if (chunk.length > remaining) truncated = true;
+    });
+    child.stderr.on('data', chunk => ctx.warn(chunk.toString()));
+    child.on('error', error => { failedToStart = true; reject(new Error(error.code === 'ENOENT' ? 'Screenshots and releases need Bun. Install Bun, then run the same sprid command again.' : error.message)); });
+    child.on('close', code => {
+      if (failedToStart) return;
+      const exitCode = code ?? 1;
+      if (ctx.json) ctx.out({ ok: exitCode === 0, exitCode, output, outputTruncated: truncated });
+      resolve(exitCode);
+    });
+  });
+}
+
+export const screenshots = ctx => localTool(ctx, '@sprid/shots');
+export const release = ctx => localTool(ctx, '@sprid/release');

package/src/commands/marketing-review.mjs

@@ -0,0 +1,106 @@
+// Read the shared server contract. No provider key or local analytics credential needed.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { UsageError } from '../args.mjs';
+import { readLocalApp, resolveProfile, patchProfile } from '../profiles.mjs';
+import { saveEvidence } from '../evidence.mjs';
+
+export async function marketingReview(ctx) {
+  const local = readLocalApp(ctx.cwd)?.data;
+  if ((local?.enabled === false || local?.review?.enabled === false) && !['context', 'collection', 'evidence'].includes(ctx.positionals[0])) throw new UsageError(`Review paused: ${local.review?.disabledReason || local.disabledReason || local.slug}`);
+  if (ctx.positionals.length > 1 || (ctx.positionals.length && !['query', 'capabilities', 'context', 'collection', 'evidence'].includes(ctx.positionals[0]))) throw new UsageError('Use sprid marketing-review [capabilities | query | context | collection | evidence]');
+  if (['context', 'collection', 'evidence'].includes(ctx.positionals[0])) return reviewSettings(ctx);
+  if (ctx.positionals[0] === 'capabilities' || (ctx.positionals[0] === 'query' && ctx.flags.source)) return connectedQuery(ctx);
+  if (ctx.positionals[0] === 'query') {
+    if (!ctx.flags['query-file']) throw new UsageError('sprid marketing-review query --query-file <file.sql> --app <slug>');
+    const query = readFileSync(resolve(ctx.cwd, ctx.flags['query-file']), 'utf8');
+    if (!/^(SELECT|WITH)\b/i.test(query.trim()) || query.length > 20000) throw new UsageError('Use a SELECT/WITH HogQL query of at most 20000 characters');
+    const wid = await ctx.workspaceId();
+    const profile = await resolveProfile(ctx, wid);
+    const result = await ctx.api().post(`/api/marketing-review/query?${new URLSearchParams({ workspaceId: String(wid), app: profile.slug })}`, { query });
+    const evidence = saveEvidence(ctx.cwd, 'query', { request: { workspaceId: wid, app: profile.slug, source: 'posthog', query }, response: result });
+    ctx.out({ ...result, evidence });
+    return 0;
+  }
+  const end = ctx.flags.end || new Date().toISOString().slice(0, 10);
+  const date = value => {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0,10) !== value) throw new UsageError('Use valid YYYY-MM-DD dates');
+    return Date.parse(value);
+  };
+  date(end);
+  if (ctx.flags.since && ctx.flags.days) throw new UsageError('Use --since or --days, not both');
+  const days = ctx.flags.since ? (date(end) - date(ctx.flags.since)) / 86400000 : Number(ctx.flags.days ?? 30);
+  if (!Number.isInteger(days) || days < 1 || days > 90) throw new UsageError('Review period must be 1 to 90 days');
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  const query = new URLSearchParams({ workspaceId: String(wid), app: profile.slug, days: String(days), end, check: String(Boolean(ctx.flags.check)) });
+  if (ctx.flags.view) {
+    if (!['summary', 'full'].includes(ctx.flags.view)) throw new UsageError('--view must be summary or full');
+    query.set('view', ctx.flags.view);
+  }
+  if (ctx.flags.sources) query.set('sources', ctx.flags.sources);
+  if (ctx.flags.refresh) query.set('refresh', 'true');
+  if (ctx.flags['cached-only']) query.set('cachedOnly', 'true');
+  if (ctx.flags.refresh && ctx.flags['cached-only']) throw new UsageError('--refresh and --cached-only cannot be combined');
+  const result = await ctx.api().get(`/api/marketing-review?${query}`, { timeoutMs: 120000 });
+  if (result.dataset && !ctx.flags.check && ctx.flags.view !== 'summary') result.evidence = saveEvidence(ctx.cwd, 'review', result);
+  ctx.out(result);
+  return 0;
+}
+
+async function connectedQuery(ctx) {
+  let input;
+  if (ctx.positionals[0] === 'query') {
+    if (!ctx.flags.operation || ctx.flags['query-file']) throw new UsageError('Use --source <source> --operation <operation> [--params-file <params.json>]. Discover parameters with marketing-review capabilities.');
+    let params = {};
+    if (ctx.flags['params-file']) {
+      const text = readFileSync(resolve(ctx.cwd, ctx.flags['params-file']), 'utf8');
+      if (text.length > 64000) throw new UsageError('Query parameters exceed 64000 characters');
+      try { params = JSON.parse(text); } catch { throw new UsageError('Parameter file must contain valid JSON'); }
+      if (!params || Array.isArray(params) || typeof params !== 'object') throw new UsageError('Parameter file must contain a JSON object');
+    }
+    input = { source: ctx.flags.source, operation: ctx.flags.operation, params };
+  }
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  const query = new URLSearchParams({ workspaceId: String(wid), app: profile.slug });
+  if (!input) {
+    const result = await ctx.api().get(`/api/marketing-review/capabilities?${query}`);
+    if (ctx.flags.source) {
+      result.operations = result.operations.filter(op => op.source === ctx.flags.source);
+      if (!result.operations.length) throw new UsageError('Unknown source; list capabilities without --source');
+    }
+    ctx.out(result);
+    return 0;
+  }
+  const result = await ctx.api().post(`/api/marketing-review/query-source?${query}`, input);
+  if (result.measurement) result.evidence = saveEvidence(ctx.cwd, 'query', result);
+  ctx.out(result);
+  return ['error', 'unconfigured', 'pending'].includes(result.status) ? 1 : 0;
+}
+
+async function reviewSettings(ctx) {
+  const wid = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, wid);
+  if (ctx.positionals[0] === 'evidence') {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ctx.flags.id ?? '')) throw new UsageError('Use marketing-review evidence --id <evidence.id> --app <slug>');
+    const result = await ctx.api().get(`/api/marketing-review/evidence/${ctx.flags.id}?${new URLSearchParams({ workspaceId: String(wid), app: profile.slug })}`);
+    ctx.out({ ...result, localEvidence: saveEvidence(ctx.cwd, 'snapshot', result) });
+    return 0;
+  }
+  if (ctx.positionals[0] === 'collection') {
+    if (!['true', 'false'].includes(ctx.flags.enabled)) throw new UsageError('Use marketing-review collection --enabled true|false --app <slug>');
+    ctx.out(await patchProfile(ctx, wid, profile.id, { metricsCollectionEnabled: ctx.flags.enabled === 'true' }));
+    return 0;
+  }
+  const path = `/api/marketing-review/context?${new URLSearchParams({ workspaceId: String(wid), app: profile.slug })}`;
+  if (!ctx.flags.file) { ctx.out(await ctx.api().get(path)); return 0; }
+  const text = readFileSync(resolve(ctx.cwd, ctx.flags.file), 'utf8');
+  if (text.length > 70000) throw new UsageError('Context file exceeds 70000 characters');
+  let input;
+  try { input = JSON.parse(text); } catch { throw new UsageError('Context file must contain JSON with baseRevision and context'); }
+  if (!Number.isInteger(input.baseRevision) || input.baseRevision < 0 || !input.context) throw new UsageError('Context file needs baseRevision from the latest read and a context object');
+  const response = await ctx.api().raw('PUT', path, input);
+  ctx.out(response.data);
+  return response.status >= 200 && response.status < 300 ? 0 : 1;
+}

package/src/commands/mcp.mjs

@@ -0,0 +1,53 @@
+// sprid mcp: the stdio adapter for MCP clients that cannot do OAuth on an
+// HTTP server. Newline-delimited JSON-RPC in on stdin, forwarded to
+// /api/mcp with the stored login (SPRID_PAT still wins), responses out on
+// stdout. Nothing else is written to stdout, ever: the client parses it.
+
+import readline from "node:readline";
+
+export async function mcp(ctx) {
+  const a = ctx.auth();
+  const surface = ctx.flags.surface && ctx.flags.surface !== true ? String(ctx.flags.surface) : "core";
+  if (!["core", "all"].includes(surface)) {
+    ctx.warn("sprid mcp: --surface must be core or all");
+    return 2;
+  }
+  const url = `${a.apiUrl}/api/mcp?surface=${surface}`;
+  const rl = readline.createInterface({ input: ctx.stdin });
+  const write = ctx.rawWrite;
+
+  await new Promise((resolve) => {
+    let inflight = 0;
+    let closed = false;
+    const maybeDone = () => {
+      if (closed && inflight === 0) resolve();
+    };
+    rl.on("line", async (line) => {
+      if (!line.trim()) return;
+      inflight++;
+      try {
+        const res = await ctx.fetch(url, {
+          method: "POST",
+          redirect: 'error',
+          signal: AbortSignal.timeout(120000),
+          headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: `Bearer ${a.token}` },
+          body: line,
+        });
+        const text = await res.text();
+        // A notification gets 202/204 with no body; nothing to hand back.
+        if (text.trim()) write(text.trim() + "\n");
+        else if (!res.ok) ctx.warn(`sprid mcp: ${res.status} from ${url}`);
+      } catch (err) {
+        ctx.warn(`sprid mcp: forward error: ${err && err.message}`);
+      } finally {
+        inflight--;
+        maybeDone();
+      }
+    });
+    rl.on("close", () => {
+      closed = true;
+      maybeDone();
+    });
+  });
+  return 0;
+}

package/src/commands/misc.mjs

@@ -0,0 +1,94 @@
+// open / invite / upgrade: deep links and the two workspace verbs.
+
+import { UsageError } from "../args.mjs";
+import { ApiError } from "../http.mjs";
+import { C, OK } from "../format.mjs";
+
+export async function open(ctx) {
+  const [what, arg] = ctx.positionals;
+  const base = ctx.appUrl();
+  let path;
+  switch (what ?? "app") {
+    case "app":
+      path = "/";
+      break;
+    case "post": {
+      const id = Number(arg);
+      if (!Number.isInteger(id) || id <= 0) throw new UsageError("sprid open post <id>");
+      path = `/p/${id}`;
+      break;
+    }
+    case "calendar":
+      path = "/calendar";
+      break;
+    case "draft":
+      path = "/posts?new=1";
+      break;
+    case "accounts":
+      path = `/settings/accounts/new?workspaceId=${await ctx.workspaceId()}`;
+      break;
+    case "connections":
+      path = `/settings/connections?workspaceId=${await ctx.workspaceId()}`;
+      break;
+    case "billing":
+      // The plan screen, not the workspace settings page: this is the one the
+      // trial, the prices and the Stripe portal live on.
+      path = "/billing";
+      break;
+    case "spend":
+      // The AI spend caps. `next` points here when one is hit, so the target
+      // has to exist or the command it prints is a lie.
+      path = "/settings/ai-spend";
+      break;
+    default:
+      throw new UsageError("sprid open [post <id>|draft|calendar|connections|accounts|billing|spend|app]");
+  }
+  const url = `${base}${path}`;
+  const opened = await ctx.openBrowser(url);
+  if (ctx.json) ctx.out({ url, opened });
+  else ctx.print(`  ${opened ? "Opened" : "Open"} ${url}`);
+  return 0;
+}
+
+export async function invite(ctx) {
+  const [email] = ctx.positionals;
+  if (!email || !email.includes("@")) throw new UsageError("sprid invite <email> [--role editor|admin] [--account <slug>]");
+  const role = ctx.flags.role ? String(ctx.flags.role) : "editor";
+  if (!["editor", "admin"].includes(role)) throw new UsageError("--role must be editor or admin");
+  const wid = await ctx.workspaceId();
+  const body = { email, role, scope: "workspace" };
+  if (ctx.flags.account) {
+    if (role !== "editor") throw new UsageError("An account-scoped collaborator is always an editor; drop --role.");
+    const rows = await ctx.api().get("/api/accounts");
+    const list = Array.isArray(rows) ? rows : rows?.accounts ?? [];
+    const acct = list.find((a) => a.slug === ctx.flags.account);
+    if (!acct) throw new UsageError(`No account "${ctx.flags.account}" visible to this token.`);
+    body.scope = "account";
+    body.accountIds = [acct.id];
+  }
+  const res = await ctx.api().post(`/api/workspaces/${wid}/invites`, body);
+  if (ctx.json) ctx.out({ ok: true, invite: res });
+  else ctx.print(`  ${C.ok(OK)} Invited ${email} as ${role}${body.scope === "account" ? ` on ${ctx.flags.account}` : ""}. They get a mail with the link.`);
+  return 0;
+}
+
+const TIER_ARG = { pulse: "starter", push: "growth", founding: "founding", starter: "starter", growth: "growth" };
+
+export async function upgrade(ctx) {
+  const [want] = ctx.positionals;
+  const tier = want ? TIER_ARG[want.toLowerCase()] : "starter";
+  if (!tier) throw new UsageError("sprid upgrade [pulse|push|founding]");
+  const wid = await ctx.workspaceId();
+  let res;
+  try {
+    res = await ctx.api().post("/api/billing/checkout", { workspaceId: wid, tier });
+  } catch (e) {
+    if (e instanceof ApiError && e.status === 403) throw new ApiError(403, "Only the workspace owner can change the plan.");
+    throw e;
+  }
+  if (!res?.url) throw new ApiError(500, "Checkout returned no URL.");
+  const opened = await ctx.openBrowser(res.url);
+  if (ctx.json) ctx.out({ tier, url: res.url, opened });
+  else ctx.print(`  ${opened ? "Opened" : "Open"} checkout for ${want ?? "pulse"}: ${res.url}`);
+  return 0;
+}

package/src/commands/pinterest.mjs

@@ -0,0 +1,120 @@
+import { UsageError } from "../args.mjs";
+import { C } from "../format.mjs";
+
+function required(ctx, name) {
+  const value = ctx.flags[name];
+  if (!value || value === true) throw new UsageError(`--${name} needs a value`);
+  return String(value);
+}
+
+async function channel(ctx) {
+  const account = required(ctx, "account");
+  const rows = await ctx.api().get(`/api/channels?account=${encodeURIComponent(account)}`);
+  const active = (rows ?? []).filter((row) => row.platform === "pinterest" && row.status === "active");
+  const wanted = ctx.flags.channel ? active.filter((row) => String(row.id) === String(ctx.flags.channel)) : active;
+  if (wanted.length !== 1) {
+    if (!active.length) throw new UsageError(`No active Pinterest channel on ${account}. Run sprid connect pinterest --account ${account}.`);
+    throw new UsageError(`Several Pinterest channels are active on ${account}. Pass --channel <id>: ${active.map((row) => row.id).join(", ")}`);
+  }
+  return { account, channel: wanted[0] };
+}
+
+export async function pinterest(ctx) {
+  const [verb, ref] = ctx.positionals;
+  if (verb === "boards") {
+    const selected = await channel(ctx);
+    const bookmark = ctx.flags.bookmark ? `?bookmark=${encodeURIComponent(String(ctx.flags.bookmark))}` : "";
+    const result = await ctx.api().get(`/api/channels/${selected.channel.id}/pinterest/boards${bookmark}`);
+    if (ctx.json) ctx.out({ ...result, account: selected.account, channelId: selected.channel.id });
+    else {
+      ctx.print(`  Pinterest boards for ${selected.channel.displayName ?? selected.account}`);
+      for (const board of result.items ?? []) {
+        ctx.print(`  ${C.bold(board.id)}  ${board.name}${board.privacy ? C.dim(`  ${board.privacy}`) : ""}`);
+        for (const section of board.sections ?? []) ctx.print(C.dim(`      ${section.id}  ${section.name}`));
+      }
+      if (!(result.items ?? []).length) ctx.print(`  No Pinterest boards yet. Create one with: sprid pinterest create --account ${selected.account} --name <name>`);
+      if (result.bookmark) ctx.print(C.dim(`  More boards: sprid pinterest boards --account ${selected.account} --channel ${selected.channel.id} --bookmark ${result.bookmark}`));
+    }
+    return 0;
+  }
+
+  if (verb === "create") {
+    const selected = await channel(ctx);
+    const name = required(ctx, "name").trim();
+    const description = ctx.flags.description ? String(ctx.flags.description).trim() : "";
+    const privacy = String(ctx.flags.privacy ?? "public").toUpperCase();
+    if (!name) throw new UsageError("--name needs a value");
+    if (!["PUBLIC", "SECRET"].includes(privacy)) throw new UsageError("--privacy must be public or secret");
+    const board = await ctx.api().post(`/api/channels/${selected.channel.id}/pinterest/boards`, {
+      name,
+      ...(description ? { description } : {}),
+      privacy,
+    });
+    if (ctx.json) ctx.out({ ...board, account: selected.account, channelId: selected.channel.id });
+    else ctx.print(`  ${C.ok("✓")} Created Pinterest board ${C.bold(board.name)} (${board.id}).`);
+    return 0;
+  }
+
+  if (verb === "set") {
+    if (!ref || !/^\d+$/.test(ref)) throw new UsageError("sprid pinterest set <postId> --board <id> --link <url> [metadata]");
+    const post = await ctx.api().get(`/api/posts/${ref}`);
+    const previous = post.pinterestOptions ?? {};
+    const hasFlag = (name) => Object.prototype.hasOwnProperty.call(ctx.flags, name);
+    const boardChanged = hasFlag("board") && String(ctx.flags.board) !== String(previous.boardId ?? "");
+    const boardId = ctx.flags.board ? String(ctx.flags.board) : previous.boardId;
+    const link = ctx.flags.link ? String(ctx.flags.link) : previous.link;
+    if (!boardId) throw new UsageError("Pinterest metadata needs --board <id>.");
+    if (!/^\d+$/.test(boardId)) throw new UsageError("--board must be the numeric Pinterest board id returned by `sprid pinterest boards`.");
+    if (hasFlag("section") && ctx.flags.section && !/^\d+$/.test(String(ctx.flags.section))) throw new UsageError("--section must be a numeric Pinterest section id.");
+    if (!link) throw new UsageError("Pinterest metadata needs --link <absolute-url>.");
+    let url;
+    try { url = new URL(link); } catch { throw new UsageError("--link must be an absolute http or https URL."); }
+    if (!["http:", "https:"].includes(url.protocol)) throw new UsageError("--link must be an absolute http or https URL.");
+    const disclosures = hasFlag("ai-disclosures")
+      ? String(ctx.flags["ai-disclosures"] === true ? "" : ctx.flags["ai-disclosures"]).split(",").filter(Boolean)
+      : previous.aiDisclosures;
+    const allowed = new Set(["AI_MODIFIED", "SYNTHETIC_PERFORMER"]);
+    if (disclosures?.some((value) => !allowed.has(value))) throw new UsageError("--ai-disclosures accepts AI_MODIFIED,SYNTHETIC_PERFORMER.");
+    const value = {
+      boardId,
+      ...(
+        hasFlag("section")
+          ? (ctx.flags.section ? { boardSectionId: String(ctx.flags.section) } : {})
+          : (!boardChanged && previous.boardSectionId ? { boardSectionId: String(previous.boardSectionId) } : {})
+      ),
+      ...(ctx.flags.title || previous.title ? { title: String(ctx.flags.title ?? previous.title) } : {}),
+      ...(ctx.flags.description || previous.description ? { description: String(ctx.flags.description ?? previous.description) } : {}),
+      link: url.toString(),
+      ...(ctx.flags["alt-text"] || previous.altText ? { altText: String(ctx.flags["alt-text"] ?? previous.altText) } : {}),
+      ...(disclosures?.length ? { aiDisclosures: disclosures } : {}),
+    };
+    if ((value.title?.length ?? 0) > 100) throw new UsageError("Pinterest title exceeds 100 characters.");
+    if ((value.description?.length ?? 0) > 800) throw new UsageError("Pinterest description exceeds 800 characters.");
+    if ((value.altText?.length ?? 0) > 500) throw new UsageError("Pinterest alt text exceeds 500 characters.");
+    const updated = await ctx.api().patch(`/api/posts/${ref}`, { pinterestOptions: value });
+    if (ctx.json) ctx.out({ ok: true, postId: Number(ref), pinterestOptions: updated.pinterestOptions });
+    else ctx.print(`  ${C.ok("✓")} Pinterest details saved on post ${ref}. Review the visual and schedule in Sprid.`);
+    return 0;
+  }
+
+  if (verb === "metrics") {
+    if (!ref || !/^\d+$/.test(ref)) throw new UsageError("sprid pinterest metrics <publishId> --account <slug> [--days 30] [--refresh]");
+    const account = required(ctx, "account");
+    const params = new URLSearchParams({ account, publishId: ref, days: String(ctx.flags.days ?? 30) });
+    if (ctx.flags.refresh) params.set("refresh", "true");
+    const result = await ctx.api().get(`/api/metrics/pinterest?${params}`);
+    if (ctx.json) ctx.out(result);
+    else if (!result.available) ctx.print(`  Pinterest metrics unavailable: ${result.reason ?? "no data returned"}`);
+    else {
+      ctx.print(`  Pinterest ${result.from} → ${result.to}`);
+      ctx.print(`  impressions ${result.impressions ?? "–"}  clicks ${result.pinClicks ?? "–"}  outbound ${result.outboundClicks ?? "–"}  saves ${result.saves ?? "–"}`);
+      if (typeof result.observedDays === "number" && typeof result.expectedDays === "number") {
+        ctx.print(`  coverage ${result.observedDays}/${result.expectedDays} days · ${result.source ?? "live"}`);
+      }
+      for (const note of result.notes ?? []) ctx.print(`  ${C.dim(note)}`);
+    }
+    return 0;
+  }
+
+  throw new UsageError("sprid pinterest boards --account <slug> [--channel <id>] [--bookmark <token>] | create --account <slug> --name <name> [--description <text>] [--privacy public|secret] | set <postId> --board <id> --link <url> | metrics <publishId> --account <slug>");
+}