@sprid/cli 0.1.2

package/src/commands/plan.mjs

@@ -0,0 +1,230 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { UsageError } from '../args.mjs';
+import { resolveProfile } from '../profiles.mjs';
+import { createHash } from 'node:crypto';
+
+export function linkLocalTask(cwd, plan, actionId, apiUrl, workspaceId) {
+  const dir = resolve(realpathSync(cwd), '.sprid');
+  if (realpathSync(dir) !== dir) throw new UsageError('.sprid must remain inside this repository.');
+  const lock = resolve(dir, 'setup.lock');
+  try { writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code === 'EEXIST') throw new UsageError('Setup is already locked. Finish or resume sprid setup before linking this task.'); throw error; }
+  try { return linkLocalTaskUnlocked(cwd, plan, actionId, apiUrl, workspaceId); }
+  finally { unlinkSync(lock); }
+}
+
+function linkLocalTaskUnlocked(cwd, plan, actionId, apiUrl, workspaceId) {
+  const state = readPlanFile(cwd, '.sprid/setup.json');
+  if (state.version !== 1 || !state.key || !state.artifact) throw new UsageError('Keep the existing version 1 setup task before linking it.');
+  const action = plan.actions?.find(item => item.id === actionId);
+  if (!action) throw new UsageError('That action does not belong to the selected app.');
+  const app = plan.appProfile;
+  if (!app?.id || !workspaceId) throw new UsageError('The plan did not return a scoped app identity.');
+  if ((state.appId && state.appId !== app.id) || (state.workspaceId && state.workspaceId !== workspaceId) || (state.apiUrl && state.apiUrl !== apiUrl)) throw new UsageError('The local task belongs to a different app, workspace or server.');
+  if (state.marketingAction && state.marketingAction.id !== actionId) throw new UsageError('This task already continues a different action. Preserve that link.');
+  const root = realpathSync(cwd), path = realpathSync(resolve(root, state.artifact)), rel = relative(root, path);
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new UsageError('The prepared artifact must remain inside this repository.');
+  const dir = resolve(root, '.sprid');
+  if (realpathSync(dir) !== dir) throw new UsageError('.sprid must remain inside this repository.');
+  const artifactHash = createHash('sha256').update(readFileSync(path)).digest('hex');
+  state.marketingAction = { id: actionId, artifactVersion: action.artifactVersion, localTaskId: state.key, artifactHash };
+  state.appId = app.id; state.workspaceId = workspaceId; state.apiUrl = apiUrl;
+  const target = resolve(dir, 'setup.json'), tmp = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, target);
+  return { status: 'linked', actionId, localTaskId: state.key, artifact: state.artifact, assurance: 'Local reference only. No artifact was uploaded, replaced or approved.' };
+}
+
+// Only explicitly selected files leave the repository. No automatic folder upload.
+export function readPlanFile(cwd, file) {
+  if (!file) throw new UsageError('Use --file <JSON proposal>. Read the current revision before changing accepted work.');
+  const root = realpathSync(cwd), path = realpathSync(resolve(root, file));
+  const rel = relative(root, path);
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new UsageError('Select a file inside the authorized repository.');
+  const text = readFileSync(path, 'utf8');
+  if (Buffer.byteLength(text) > 4 * 1024 * 1024) throw new UsageError('The selected bundle exceeds 4 MiB. Split it before importing.');
+  try { return JSON.parse(text); } catch { throw new UsageError('The selected file must contain valid JSON.'); }
+}
+
+function saveProjection(cwd, value) {
+  const root = realpathSync(cwd), dir = resolve(root, '.sprid');
+  mkdirSync(dir, { recursive: true });
+  if (realpathSync(dir) !== dir) throw new UsageError('.sprid must be inside this repository, not a symlink.');
+  ignorePrivateExports(dir);
+  const path = resolve(dir, 'marketing.json');
+  // A downloaded projection never overwrites an unsynchronized local proposal.
+  if (existsSync(path)) {
+    const current = JSON.parse(readFileSync(path, 'utf8'));
+    if (current.pendingChanges) throw new UsageError('Local marketing changes are pending. Export to --file instead; reconcile both versions before replacing them.');
+  }
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+  return '.sprid/marketing.json';
+}
+
+function ignorePrivateExports(dir) {
+  const file = resolve(dir, '.gitignore');
+  if (existsSync(file) && realpathSync(file) !== file) throw new UsageError('Do not write private-export rules through a symlink.');
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const missing = ['research/', 'documents.json', 'marketing.json'].filter(line => !current.split('\n').includes(line));
+  if (missing.length) appendFileSync(file, `${current && !current.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`, { mode: 0o600 });
+}
+
+function exportPath(cwd, value) {
+  const root = realpathSync(cwd), path = resolve(root, value), rel = relative(root, path);
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new UsageError('Export inside the authorized repository.');
+  let parent = dirname(path);
+  while (!existsSync(parent)) parent = dirname(parent);
+  const resolved = relative(root, realpathSync(parent));
+  if (isAbsolute(resolved) || resolved === '..' || resolved.startsWith('../')) throw new UsageError('Export parent escapes the authorized repository.');
+  return path;
+}
+
+async function scope(ctx) {
+  const workspaceId = await ctx.workspaceId();
+  const profile = await resolveProfile(ctx, workspaceId);
+  return new URLSearchParams({ workspaceId: String(workspaceId), app: profile.slug }).toString();
+}
+function id(ctx) {
+  const value = ctx.flags.id ?? ctx.positionals[1];
+  if (!value || !/^[a-zA-Z0-9_-]{1,100}$/.test(value)) throw new UsageError('Supply the saved identifier with --id.');
+  return encodeURIComponent(value);
+}
+async function mutate(ctx, path, input) {
+  const response = await ctx.api().raw('POST', path, input);
+  ctx.out(response.data);
+  return response.status >= 200 && response.status < 300 ? 0 : 1;
+}
+
+export async function plan(ctx) {
+  const [verb = 'get'] = ctx.positionals;
+  if (ctx.flags.offline) {
+    if (verb === 'import') {
+      const bundle = readPlanFile(ctx.cwd, ctx.flags.file);
+      if (bundle.schemaVersion !== 2 || !Number.isInteger(bundle.baseRevision) || bundle.baseRevision < 0 || !bundle.app?.slug) throw new UsageError('Local plan requires schemaVersion 2, baseRevision and app.slug.');
+      const path = resolve(ctx.cwd, '.sprid/marketing.json');
+      if (existsSync(path)) throw new UsageError('A local plan already exists. Preserve it and reconcile the proposed file explicitly.');
+      ctx.out({ savedTo: saveProjection(ctx.cwd, bundle), status: 'local', message: 'Local work saved. No account or import to Sprid was required.' });
+      return 0;
+    }
+    if (verb !== 'get') throw new UsageError('Offline: use sprid plan get or import --file <bundle>. Local proposals remain available without login.');
+    ctx.out(readPlanFile(ctx.cwd, '.sprid/marketing.json'));
+    return 0;
+  }
+  const paths = { discover: '/discover', propose: '/propose', prepare: '/actions/prepare', import: '/import', guidance: '/guidance', research: '/research', 'review-prepare': '/reviews', 'execute-prepare': '/execution/prepare' };
+  const scoped = await scope(ctx), base = '/api/marketing-plan';
+  if (verb === 'screenshot-capabilities') {
+    ctx.out(await ctx.api().get(`/api/marketing-screenshots/capabilities?${scoped}`));
+    return 0;
+  }
+  if (verb === 'screenshot-uploads' || verb === 'screenshot-compose') {
+    return mutate(ctx, `/api/marketing-screenshots/${verb === 'screenshot-uploads' ? 'uploads' : 'compose'}?${scoped}`, readPlanFile(ctx.cwd, ctx.flags.file));
+  }
+  if (verb === 'capabilities') {
+    ctx.out(await ctx.api().get(`${base}/capabilities?${scoped}`));
+    return 0;
+  }
+  if (verb === 'job-cancel') return mutate(ctx, `${base}/research/${id(ctx)}/cancel?${scoped}`, {});
+  if (verb === 'prepare-local') {
+    const state = readPlanFile(ctx.cwd, '.sprid/setup.json');
+    if (state.marketingAction) throw new UsageError('This local task already has a shared action. Continue its saved link.');
+    const input = readPlanFile(ctx.cwd, ctx.flags.file);
+    const root = realpathSync(ctx.cwd), file = realpathSync(resolve(root, state.artifact ?? ''));
+    const rel = relative(root, file);
+    if (!state.key || isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new UsageError('Select the original local task and artifact inside this repository.');
+    const bytes = readFileSync(file);
+    if (bytes.length > 262144 || bytes.includes(0)) throw new UsageError('Import text artifacts up to 256 KiB here. Keep media in its existing upload workflow.');
+    const original = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (input.artifact?.body !== original) throw new UsageError('The proposed artifact must contain the original saved text exactly. Revise the shared artifact after importing.');
+    const current = await ctx.api().get(`${base}?${scoped}`);
+    const wid = Number(new URLSearchParams(scoped).get('workspaceId'));
+    if ((state.appId && state.appId !== current.appProfile.id) || (state.workspaceId && state.workspaceId !== wid) || (state.apiUrl && state.apiUrl !== ctx.auth().apiUrl)) throw new UsageError('The local task belongs to another app, workspace or server.');
+    const response = await ctx.api().raw('POST', `${base}/actions/prepare?${scoped}`, { ...input, idempotencyKey: `local-task:${state.key}` });
+    if (response.status < 200 || response.status >= 300) { ctx.out(response.data); return 1; }
+    const action = response.data.action;
+    ctx.out({ ...response.data, local: linkLocalTask(ctx.cwd, { ...current, actions: [action] }, action.id, ctx.auth().apiUrl, wid) });
+    return 0;
+  }
+  if (verb === 'link-local') {
+    const result = await ctx.api().get(`${base}?${scoped}`);
+    ctx.out(linkLocalTask(ctx.cwd, result, decodeURIComponent(id(ctx)), ctx.auth().apiUrl, Number(new URLSearchParams(scoped).get('workspaceId'))));
+    return 0;
+  }
+  if (verb === 'get' || verb === 'export') {
+    const query = new URLSearchParams(scoped);
+    if (verb === 'get') for (const [flag, key] of [['history-before', 'historyBefore'], ['history-before-id', 'historyBeforeId'], ['history-limit', 'historyLimit']]) {
+      if (ctx.flags[flag]) query.set(key, ctx.flags[flag]);
+    }
+    const result = await ctx.api().get(`${base}${verb === 'export' ? '/export' : ''}?${query}`);
+    if (verb === 'export') {
+      if (ctx.flags.file) {
+        const path = exportPath(ctx.cwd, ctx.flags.file);
+        if (existsSync(path)) throw new UsageError('Export target already exists. Choose a new file to preserve both versions.');
+        writeFileSync(path, JSON.stringify(result, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+        ctx.out({ ...result, savedTo: ctx.flags.file });
+      } else ctx.out({ ...result, savedTo: saveProjection(ctx.cwd, result) });
+    } else ctx.out(result);
+    return 0;
+  }
+  if (verb === 'review' || verb === 'job') {
+    ctx.out(await ctx.api().get(`${base}/${verb === 'review' ? 'reviews' : 'research'}/${id(ctx)}?${scoped}`));
+    return 0;
+  }
+  const actionPaths = { accept: `/decisions/${idFor(verb, ctx)}/accept`, continue: `/actions/${idFor(verb, ctx)}/continue`, verify: `/actions/${idFor(verb, ctx)}/verify`, defer: `/actions/${idFor(verb, ctx)}/defer`, 'review-update': `/reviews/${idFor(verb, ctx)}` };
+  const suffix = paths[verb] ?? actionPaths[verb];
+  if (!suffix) throw new UsageError('Use sprid plan get|capabilities|discover|propose|accept|prepare|prepare-local|link-local|continue|verify|defer|guidance|export|import|research|job|job-cancel|review|review-prepare|review-update|execute-prepare.');
+  return mutate(ctx, `${base}${suffix}?${scoped}`, readPlanFile(ctx.cwd, ctx.flags.file));
+}
+function idFor(verb, ctx) { return ['accept', 'continue', 'verify', 'defer', 'review-update'].includes(verb) ? id(ctx) : ''; }
+
+export async function research(ctx) {
+  const [verb = 'list'] = ctx.positionals, scoped = await scope(ctx);
+  const base = '/api/marketing-plan/documents';
+  if (verb === 'export') {
+    const query = new URLSearchParams(scoped);
+    query.set('includeArchived', 'true'); query.set('limit', '200');
+    const summaries = [];
+    let page;
+    for (let count = 0; count < 100; count++) {
+      page = await ctx.api().get(`${base}?${query}`);
+      summaries.push(...(page.documents ?? []));
+      if (!page.pagination?.truncated) break;
+      if (!page.pagination.nextBefore || !page.pagination.nextBeforeId) throw new UsageError('Server returned an incomplete export cursor. Nothing was written.');
+      query.set('before', page.pagination.nextBefore); query.set('beforeId', page.pagination.nextBeforeId);
+    }
+    if (page?.pagination?.truncated) throw new UsageError('Export exceeds the bounded snapshot size. Export selected documents instead; nothing was written.');
+    const dir = exportPath(ctx.cwd, ctx.flags.directory ?? '.sprid/research');
+    if (existsSync(dir)) throw new UsageError('Research export directory already exists. Choose a new --directory to preserve local edits.');
+    const manifestPath = ctx.flags.directory ? resolve(dir, 'documents.json') : exportPath(ctx.cwd, '.sprid/documents.json');
+    if (existsSync(manifestPath)) throw new UsageError('Document manifest already exists. Export a separate snapshot with --directory and reconcile both versions.');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!ctx.flags.directory) ignorePrivateExports(dirname(dir));
+    const manifest = { schemaVersion: 2, scope: Object.fromEntries(new URLSearchParams(scoped)), exportedAt: new Date().toISOString(), documents: [] };
+    for (const summary of summaries) {
+      const document = await ctx.api().get(`${base}/${encodeURIComponent(summary.id)}?${scoped}&revision=${summary.revision}`);
+      if (!/^[a-f0-9-]{36}$/i.test(document.id)) throw new UsageError('Server returned an invalid document identity.');
+      const filename = `${document.id}.md`;
+      const frontmatter = JSON.stringify({ id: document.id, revision: document.revision, scope: document.scope, sources: document.sources, origin: document.origin });
+      writeFileSync(resolve(dir, filename), `---\n${frontmatter}\n---\n\n${document.bodyMarkdown}`, { flag: 'wx', mode: 0o600 });
+      manifest.documents.push({ id: document.id, revision: document.revision, lastSyncedRevision: document.revision, contentHash: document.contentHash, source: document.origin, path: relative(dirname(manifestPath), resolve(dir, filename)), sections: document.sections });
+    }
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    ctx.out({ directory: dir, ...manifest });
+    return 0;
+  }
+  if (verb === 'list' || verb === 'get') {
+    const query = new URLSearchParams(scoped);
+    if (ctx.flags.revision) query.set('revision', ctx.flags.revision);
+    if (ctx.flags.search) query.set('search', ctx.flags.search);
+    for (const [flag, key] of [['before', 'before'], ['before-id', 'beforeId'], ['limit', 'limit']]) {
+      if (ctx.flags[flag]) query.set(key, ctx.flags[flag]);
+    }
+    ctx.out(await ctx.api().get(`${base}${verb === 'get' ? `/${id(ctx)}` : ''}?${query}`));
+    return 0;
+  }
+  if (verb === 'save' || verb === 'import') return mutate(ctx, `${base}?${scoped}`, readPlanFile(ctx.cwd, ctx.flags.file));
+  if (verb === 'archive') return mutate(ctx, `${base}/${id(ctx)}/archive?${scoped}`, readPlanFile(ctx.cwd, ctx.flags.file));
+  throw new UsageError('Use sprid research list|get|save|import|archive|export.');
+}

package/src/commands/post.mjs

@@ -0,0 +1,41 @@
+// Preserve local command arguments, including flag values and the -- separator.
+import { fork } from "node:child_process";
+import { run as runPost } from "../post/cli.mjs";
+import { remotePost } from './studio.mjs';
+
+export async function post(ctx) {
+  if (await remotePost(ctx)) return 0;
+  return localPost(ctx);
+}
+export async function localPost(ctx) {
+  let literal = false;
+  const argv = (ctx.commandArgv ?? []).filter(arg => {
+    if (arg === "--") literal = true;
+    return literal || arg !== "--json";
+  });
+  if (!ctx.json) {
+    const result = await runPost(argv, { cwd: ctx.cwd });
+    return result?.exitCode ?? 0;
+  }
+  // Isolate legacy renderer logs and inherited builder stdout from the JSON
+  // document. The worker sends data over IPC; all human output goes to stderr.
+  return new Promise((resolve, reject) => {
+    const child = fork(new URL("../post/json-worker.mjs", import.meta.url), argv, {
+      cwd: ctx.cwd, env: ctx.env, stdio: ["inherit", "pipe", "pipe", "ipc"],
+    });
+    child.stdout.on("data", chunk => ctx.warn(chunk.toString()));
+    child.stderr.on("data", chunk => ctx.warn(chunk.toString()));
+    let delivered = false;
+    child.on("message", message => {
+      if (delivered) return;
+      delivered = true;
+      ctx.out(message);
+      if (argv.includes("--serve") && message.ok) resolve(message.exitCode ?? 0);
+    });
+    child.on("error", reject);
+    child.on("exit", code => {
+      if (!delivered) ctx.out({ ok: false, error: "Local post process ended without a result.", exitCode: code || 1 });
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/commands/reviews.mjs

@@ -0,0 +1,149 @@
+// reviews: what users wrote in the stores, the reply the workspace's model
+// drafted, and the one call that sends it. Sending is public and cannot be
+// undone on Play, so `reply` is the single interactive prompt in the CLI:
+// it shows the exact text and asks y/N, unless --yes.
+
+import readline from "node:readline";
+import { UsageError } from "../args.mjs";
+import { ApiError } from "../http.mjs";
+import { C, OK } from "../format.mjs";
+
+/** Apple caps a developer response at 5970 characters; Google at 350. */
+export const REPLY_LIMITS = { app_store: 5970, google_play: 350 };
+const STORE_LABEL = { app_store: "App Store", google_play: "Google Play" };
+
+export async function reviews(ctx) {
+  const [sub, arg] = ctx.positionals;
+  if (sub === "draft") return draft(ctx, arg);
+  if (sub === "reply") return reply(ctx, arg);
+  if (sub) throw new UsageError("sprid reviews [--app <slug>] [--unanswered] [--max-rating N] [--limit N] | draft <id> | reply <id> [--text …] [--yes]");
+  return list(ctx);
+}
+
+async function fetchReviews(ctx, { limit } = {}) {
+  const wid = await ctx.workspaceId();
+  const params = new URLSearchParams({ workspaceId: String(wid) });
+  if (ctx.flags.app) params.set("profile", String(ctx.flags.app));
+  if (ctx.flags.unanswered) params.set("unanswered", "1");
+  if (ctx.flags["max-rating"] !== undefined) params.set("maxRating", String(ctx.flags["max-rating"]));
+  if (limit ?? ctx.flags.limit) params.set("limit", String(limit ?? ctx.flags.limit));
+  const res = await ctx.api().get(`/api/store-reviews?${params}`);
+  return res?.reviews ?? [];
+}
+
+async function list(ctx) {
+  const rows = await fetchReviews(ctx);
+  if (ctx.json) {
+    ctx.out({ reviews: rows });
+    return 0;
+  }
+  if (rows.length === 0) {
+    ctx.print("  No reviews match.");
+    return 0;
+  }
+  ctx.print(rows.map(renderReview).join("\n\n"));
+  return 0;
+}
+
+export function stars(n) {
+  const r = Math.max(0, Math.min(5, Number(n) || 0));
+  return "★".repeat(r) + "☆".repeat(5 - r);
+}
+
+export function truncate(s, n = 200) {
+  s = String(s ?? "").replace(/\s+/g, " ").trim();
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+export function renderReview(r) {
+  const date = r.reviewedAt ? String(r.reviewedAt).slice(0, 10) : "";
+  const head = `  ${stars(r.rating)}  ${r.app?.slug ?? r.appProfileId}  ${STORE_LABEL[r.source] ?? r.source}  ${date}  ${C.dim(`#${r.id}`)}`;
+  const lines = [head];
+  const text = [r.title, r.body].filter(Boolean).join(" · ");
+  if (text) lines.push(`  ${truncate(text)}`);
+  if (r.repliedAt || r.developerResponse) {
+    lines.push(C.dim(`  replied${r.repliedAt ? ` ${String(r.repliedAt).slice(0, 10)}` : ""}: ${truncate(r.replyText ?? r.developerResponse, 120)}`));
+  } else if (r.draftReply) {
+    lines.push(`  ${C.dim("draft →")} ${truncate(r.draftReply, 200)}`);
+    lines.push(C.dim(`  sprid reviews reply ${r.id}`));
+  }
+  return lines.join("\n");
+}
+
+function needId(arg, usage) {
+  const id = Number(arg);
+  if (!Number.isInteger(id) || id <= 0) throw new UsageError(usage);
+  return id;
+}
+
+async function draft(ctx, arg) {
+  const id = needId(arg, "sprid reviews draft <id>");
+  const res = await ctx.api().post(`/api/store-reviews/${id}/draft`);
+  if (ctx.json) ctx.out(res);
+  else {
+    ctx.print(`  Draft for review #${id}:`);
+    ctx.print(`  ${res.draftReply ?? ""}`);
+    ctx.print(C.dim(`  Send it: sprid reviews reply ${id}   (edit first: --text "…")`));
+  }
+  return 0;
+}
+
+async function reply(ctx, arg) {
+  const id = needId(arg, "sprid reviews reply <id> [--text …] [--yes]");
+  // No GET /api/store-reviews/:id exists; the list (max 100, newest first) is
+  // the lookup. Good enough for a reply, which is about a recent review.
+  const rows = await fetchReviews(ctx, { limit: 100 });
+  const row = rows.find((r) => r.id === id);
+  let text = ctx.flags.text && ctx.flags.text !== true ? String(ctx.flags.text) : null;
+  if (!text) {
+    if (!row) throw new ApiError(404, `Review #${id} is not among the latest 100${ctx.flags.app ? ` for ${ctx.flags.app}` : ""}; pass --text to reply anyway.`);
+    if (!row.draftReply) throw new UsageError(`Review #${id} has no draft. Run \`sprid reviews draft ${id}\` or pass --text.`);
+    text = row.draftReply;
+  }
+  const source = row?.source ?? null;
+  const limit = source ? REPLY_LIMITS[source] : null;
+  if (limit && text.length > limit) {
+    throw new UsageError(`${text.length} characters; ${STORE_LABEL[source]} allows ${limit}. Shorten it with --text.`);
+  }
+
+  if (!ctx.flags.yes) {
+    const interactive = Boolean(ctx.stdin?.isTTY);
+    if (ctx.json || !interactive) {
+      const msg = "Replying is public. Re-run with --yes to send without the prompt.";
+      if (ctx.json) {
+        ctx.out({ ok: false, error: msg, id, text, store: source, limit });
+      } else {
+        ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+        ctx.print(`  ${text}`);
+        ctx.warn(`  ✗ ${msg}`);
+      }
+      return 2;
+    }
+    ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+    if (row) ctx.print(C.dim(`  re: ${stars(row.rating)} ${truncate([row.title, row.body].filter(Boolean).join(" · "), 120)}`));
+    ctx.print("");
+    ctx.print(`  ${text}`);
+    ctx.print("");
+    const ok = await confirm(ctx, "  Send it? [y/N] ");
+    if (!ok) {
+      ctx.print("  Not sent.");
+      return 1;
+    }
+  }
+
+  const res = await ctx.api().post(`/api/store-reviews/${id}/reply`, { text });
+  if (ctx.json) ctx.out({ ok: true, id, text, review: res.review ?? null });
+  else ctx.print(`  ${C.ok(OK)} Reply sent for review #${id}${source ? ` on ${STORE_LABEL[source]}` : ""}.`);
+  return 0;
+}
+
+export function confirm(ctx, prompt) {
+  return new Promise((resolve) => {
+    ctx.rawWrite(prompt);
+    const rl = readline.createInterface({ input: ctx.stdin });
+    rl.question("", (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}

package/src/commands/setup.mjs

@@ -0,0 +1,220 @@
+// The local task survives every browser boundary. The server remains the
+// authority for identity, connected reads and publishing outcomes.
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { UsageError } from "../args.mjs";
+import { NotLoggedIn } from "../creds.mjs";
+import { readLocalApp, listProfiles } from "../profiles.mjs";
+import { init } from "./init.mjs";
+import { login } from "./auth.mjs";
+import { connect } from "./connect.mjs";
+import { marketingReview } from "./marketing-review.mjs";
+
+const TASKS = ["publish", "review", "repo"];
+const PLATFORMS = ["instagram", "tiktok", "youtube", "facebook", "linkedin", "pinterest", "x"];
+const hash = data => createHash("sha256").update(data).digest("hex");
+const quote = s => /^[a-zA-Z0-9_./:-]+$/.test(String(s)) ? String(s) : "'" + String(s).replaceAll("'", "'\\''") + "'";
+function command(...args) { return { argv: args, command: args.map(quote).join(" ") }; }
+function localFile(ctx, value) {
+  const path = realpathSync(resolve(ctx.cwd, String(value)));
+  const rel = relative(realpathSync(ctx.cwd), path);
+  if (isAbsolute(rel) || rel === ".." || rel.startsWith("../")) throw new UsageError("Keep the prepared artifact inside this repo.");
+  return rel;
+}
+function readState(ctx) {
+  const path = resolve(ctx.cwd, ".sprid/setup.json");
+  if (!existsSync(path)) return null;
+  const state = JSON.parse(readFileSync(path, "utf8"));
+  if (state.version !== 1 || !TASKS.includes(state.task) || typeof state.key !== "string") throw new UsageError("Unsupported .sprid/setup.json; restore the original task file.");
+  return state;
+}
+function save(ctx, state, stage) {
+  state.stage = stage;
+  if (state.history.at(-1)?.stage !== stage) state.history.push({ stage, at: new Date().toISOString() });
+  const path = resolve(ctx.cwd, ".sprid/setup.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
+function report(ctx, state, stage, message, extra = {}) {
+  save(ctx, state, stage);
+  const result = { ok: true, stage, message, task: state.task, artifact: state.artifact,
+    workspaceId: state.workspaceId ?? null, appId: state.appId ?? null, postId: state.postId ?? null,
+    resume: command("sprid", "setup", "continue"), ...extra };
+  if (ctx.json) ctx.out(result);
+  else {
+    ctx.print(message);
+    ctx.print(`Prepared work: ${state.artifact}`);
+    if (extra.app) {
+      ctx.print(`App: ${extra.app.name} (${extra.app.slug}), workspace ${state.workspaceId}`);
+      for (const field of ["appStoreId", "playPackageName", "websiteUrl"]) {
+        if (extra.app[field]) ctx.print(`${field}: ${extra.app[field]}`);
+      }
+    }
+    for (const account of extra.accounts ?? []) ctx.print(`${account.slug}: ${account.name} (app ${account.appId ?? "unlinked"})`);
+    for (const destination of extra.destinations ?? []) ctx.print(`Destination: ${destination.platform}, ${destination.name ?? destination.id}`);
+    for (const delivery of extra.publishes ?? []) {
+      const status = delivery.status === "published" && !(delivery.platformPostId && delivery.publishedAt)
+        ? "published status, awaiting confirmation" : delivery.status;
+      ctx.print(`${delivery.platform}: ${status}${delivery.publishedAt ? ` at ${delivery.publishedAt}` : delivery.scheduledFor ? ` for ${delivery.scheduledFor}` : ""}`);
+    }
+    if (extra.evidence) ctx.print(`Evidence: ${JSON.stringify(extra.evidence)}`);
+    if (extra.next) ctx.print(extra.next.command);
+    if (extra.verify) ctx.print(extra.verify.command);
+    if (extra.href) ctx.print(extra.href);
+  }
+  return 0;
+}
+async function capture(ctx, fn, overrides = {}) {
+  let result;
+  const code = await fn({ ...ctx, ...overrides, json: true, out: data => { result = data; }, print: ctx.warn });
+  if (code) throw new UsageError(result?.error || "This step is unfinished. Run sprid setup continue to resume.");
+  return result;
+}
+
+export async function setup(ctx) {
+  const [verb = "status"] = ctx.positionals;
+  if (!["begin", "status", "continue", "verify", "results"].includes(verb)) throw new UsageError("sprid setup begin|status|continue|verify|results [--file artifact] [--task publish|review|repo]");
+  const dir = resolve(ctx.cwd, ".sprid");
+  mkdirSync(dir, { recursive: true });
+  const lock = resolve(dir, "setup.lock");
+  if (existsSync(lock)) {
+    const pid = Number(readFileSync(lock, "utf8"));
+    let alive = true;
+    try { process.kill(pid, 0); } catch (e) { if (e.code === "ESRCH") alive = false; }
+    if (alive) throw new UsageError("Setup is already running in this repo. Continue in that terminal.");
+    rmSync(lock);
+  }
+  writeFileSync(lock, String(process.pid), { flag: "wx", mode: 0o600 });
+  try { return await runSetup(ctx, verb); } finally { rmSync(lock, { force: true }); }
+}
+
+async function runSetup(ctx, verb) {
+  let state = readState(ctx);
+  if (verb === "results") {
+    const account = ctx.flags.account ?? state?.accountId;
+    if (!account) throw new UsageError("Use --account <slug> or resume a publishing task first.");
+    ctx.out(await ctx.api().get(`/api/posts/setup-results?account=${encodeURIComponent(account)}`));
+    return 0;
+  }
+  if (verb === "begin") {
+    if (!ctx.flags.file) throw new UsageError("Use --file <prepared artifact> to keep the work you already made.");
+    const artifact = localFile(ctx, ctx.flags.file);
+    const task = ctx.flags.task ?? "publish";
+    if (!TASKS.includes(task)) throw new UsageError(`Use --task ${TASKS.join("|")}`);
+    if (state && (state.artifact !== artifact || state.task !== task)) throw new UsageError(`An unfinished task already points to ${state.artifact}. Resume it; do not replace the first result during setup.`);
+    state ??= { version: 1, key: randomUUID(), task, artifact, entry: ctx.flags.entry ?? "installed-skill", source: ctx.flags.source ?? null, history: [] };
+    return report(ctx, state, state.stage ?? "local-result", "Your prepared work is saved. Connecting Sprid will continue this task.", { next: command("sprid", "setup", "continue") });
+  }
+  if (!state) throw new UsageError("Ask your agent to prepare the first result, then run sprid setup begin --file <artifact> --task publish|review|repo.");
+  localFile(ctx, state.artifact); // Never replace a missing artifact with a new draft.
+  if (verb === "status") return report(ctx, state, state.stage, "Resume the saved task from this repo.", { history: state.history, next: command("sprid", "setup", "continue") });
+  if (state.marketingAction) return report(ctx, state, state.stage, "Continue the linked marketing action. The original local artifact is unchanged; review its current shared version before approving it.", {
+    actionId: state.marketingAction.id,
+    next: command("sprid", "plan", "get", "--app", String(state.appId), "--workspace", String(state.workspaceId)),
+  });
+  if (state.task === "repo") return report(ctx, state, "review-local-work", "Return to the prepared repo change. Review the diff and verify the release after approval; Sprid setup is optional.");
+  const local = readLocalApp(ctx.cwd);
+  if (!local?.data?.name) throw new UsageError("The app identity is missing. Ask your agent to prepare .sprid/app.json from this repo before continuing.");
+  try { await ctx.me(); } catch (e) {
+    if (!(e instanceof NotLoggedIn) && e.status !== 401) throw e;
+    if (ctx.env.SPRID_PAT) throw new UsageError("The supplied SPRID_PAT was refused. Restore that connection before resuming.");
+    save(ctx, state, "login");
+    await capture(ctx, login);
+    ctx._auth = null; ctx._me = null; ctx._workspace = undefined;
+    await ctx.me();
+  }
+  const wid = await ctx.workspaceId();
+  const apiUrl = ctx.auth().apiUrl;
+  if (state.apiUrl && state.apiUrl !== apiUrl) throw new UsageError("This task belongs to a different Sprid server. Restore its API address before resuming.");
+  state.apiUrl = apiUrl;
+  if ((state.workspaceId && state.workspaceId !== wid) || (local.data.workspaceId && local.data.workspaceId !== wid))
+    throw new UsageError(`This task belongs to workspace ${state.workspaceId ?? local.data.workspaceId}. Resume there.`);
+  state.workspaceId = wid;
+  const profiles = await listProfiles(ctx, wid);
+  const pinned = state.appId ?? local.data.appId;
+  let profile = profiles.find(p => pinned ? p.id === pinned : p.slug === local.data.slug);
+  if (pinned && !profile) throw new UsageError("The saved app is inaccessible. Restore access; do not create another app.");
+  if (!pinned && !ctx.flags.yes) return report(ctx, state, "confirm-app", "Confirm the app inferred from this repo before registering or linking it.", {
+    app: { id: profile?.id ?? null, name: local.data.name, slug: local.data.slug, appStoreId: local.data.appStoreId, playPackageName: local.data.playPackageName, websiteUrl: local.data.websiteUrl },
+    next: command("sprid", "setup", "continue", "--yes"),
+  });
+  if (!profile || !local.data.appId) {
+    save(ctx, state, "register-app");
+    profile = (await capture(ctx, init, { flags: { ...ctx.flags, workspace: String(wid) } })).profile;
+  }
+  if (!state.appId) {
+    state.appId = profile.id;
+    save(ctx, state, "app-confirmed");
+  }
+  if (state.task === "review") {
+    if (state.evidence && verb !== "verify") return report(ctx, state, "review-evidence", "Return to the original question with the saved evidence. Run setup verify to refresh it explicitly.", { evidence: state.evidence });
+    if (verb !== "verify") return report(ctx, state, "verify-source", "Use the source that answers the original question. A saved key alone is not verified access.", {
+      source: state.source, next: command("sprid", "marketing-review", "capabilities", "--app", String(profile.id), "--workspace", String(wid)),
+      verify: command("sprid", "setup", "verify", "--source", state.source ?? "<source>", "--operation", "<operation>", "--params-file", "<params.json>"),
+    });
+    if (state.source && ctx.flags.source !== state.source) throw new UsageError(`This task needs ${state.source}; verify that source before continuing.`);
+    state.evidence = null;
+    save(ctx, state, "verify-source");
+    const result = await capture(ctx, marketingReview, { positionals: ["query"], flags: { ...ctx.flags, app: String(profile.id), workspace: String(wid) } });
+    if (!["ready", "partial"].includes(result.status) || result.measurement?.scope !== `workspace:${wid}:app:${profile.id}`) throw new UsageError("The source did not return verified evidence for this app. Keep the task open and fix its connection.");
+    state.evidence = result.evidence;
+    return report(ctx, state, "review-evidence", "The connected read succeeded for this app. Return to the original question with this evidence; review its coverage before drawing conclusions.", { evidence: result.evidence, resource: result.resource, coverage: result.measurement.coverage });
+  }
+  const all = await ctx.api().get("/api/accounts");
+  const rows = (Array.isArray(all) ? all : all.accounts ?? []).filter(a => a.workspaceId === wid);
+  const linked = rows.filter(a => a.appProfileId === profile.id);
+  const wanted = state.accountId ?? ctx.flags.account;
+  let account = wanted ? rows.find(a => String(a.id) === String(wanted) || a.slug === wanted) : linked.length === 1 ? linked[0] : null;
+  if (wanted && !account) throw new UsageError("The saved publishing account is unavailable in this workspace.");
+  if (account && account.appProfileId !== profile.id) throw new UsageError("Link this publishing account to the confirmed app in Settings before continuing.");
+  if (!account && (linked.length > 1 || rows.some(a => a.appProfileId == null))) return report(ctx, state, "choose-account", "Choose the publishing identity for this app. Existing unlinked accounts can be linked in Settings.", { accounts: rows.map(a => ({ id: a.id, name: a.name, slug: a.slug, appId: a.appProfileId })), next: command("sprid", "setup", "continue", "--account", "<slug>") });
+  if (!account) {
+    save(ctx, state, "create-account");
+    account = await ctx.api().post("/api/accounts", { workspaceId: wid, appProfileId: profile.id, name: profile.name, slug: `${profile.slug}-${wid}` });
+  }
+  state.accountId = account.id;
+  if (ctx.flags.payload) {
+    const path = localFile(ctx, ctx.flags.payload);
+    const data = readFileSync(resolve(ctx.cwd, path), "utf8");
+    if (state.payloadHash && state.payloadHash !== hash(data)) throw new UsageError("This task already has a draft payload. Edit its existing post instead of replacing it during setup.");
+    state.payload = path; state.payloadHash = hash(data);
+  }
+  if (!state.postId) {
+    if (!state.payload) return report(ctx, state, "prepare-draft", "Return to the saved draft. Have your agent convert that same copy to the setup payload, then continue.", { next: command("sprid", "setup", "continue", "--payload", "<draft.json>") });
+    const data = readFileSync(resolve(ctx.cwd, localFile(ctx, state.payload)), "utf8");
+    if (hash(data) !== state.payloadHash) throw new UsageError("The saved payload changed. Restore it before retrying; edit the hosted draft after recovery.");
+    save(ctx, state, "prepare-draft");
+    const prepared = await ctx.api().post(`/api/posts/setup-draft?account=${encodeURIComponent(account.slug)}`, { ...JSON.parse(data), key: state.key });
+    state.postId = prepared.post.id;
+    save(ctx, state, "draft-prepared");
+  }
+  const post = await ctx.api().get(`/api/posts/${state.postId}`);
+  if (post.accountId !== account.id) throw new UsageError("The prepared post no longer belongs to this task's account.");
+  const deliveries = await ctx.api().get(`/api/posts/${state.postId}/publishes`);
+  const publishes = Array.isArray(deliveries) ? deliveries : deliveries.publishes ?? [];
+  const href = `${ctx.appUrl()}/p/${state.postId}`;
+  if (publishes.length) return report(ctx, state, publishes.every(p => p.status === "published" && p.platformPostId && p.publishedAt) ? "published" : "delivery-pending", "Read each destination's result separately. A scheduled post is still waiting to publish.", {
+    href, publishes: publishes.map(p => ({ id: p.id, platform: p.platform, status: p.status, scheduledFor: p.scheduledFor, publishedAt: p.publishedAt, platformPostId: p.platformPostId })),
+  });
+  let channels = await ctx.api().get(`/api/channels?account=${encodeURIComponent(account.slug)}`);
+  if (ctx.flags.platform) {
+    if (!PLATFORMS.includes(ctx.flags.platform)) throw new UsageError(`Use --platform ${PLATFORMS.join("|")}`);
+    if (state.platform && state.platform !== ctx.flags.platform) throw new UsageError(`This task targets ${state.platform}. Review a destination change in the post editor.`);
+    state.platform = ctx.flags.platform;
+    save(ctx, state, "connect-channel");
+    if (!channels.some(c => c.platform === state.platform && c.status === "active")) {
+      await capture(ctx, connect, { positionals: [state.platform], flags: { ...ctx.flags, account: account.slug } });
+      channels = await ctx.api().get(`/api/channels?account=${encodeURIComponent(account.slug)}`);
+    }
+  }
+  const active = channels.filter(c => c.status === "active" && (!state.platform || c.platform === state.platform));
+  if (!active.length) return report(ctx, state, "connect-channel", "The draft is ready to edit. Connect its publishing destination, then return to the same preview.", { href, next: command("sprid", "setup", "continue", "--platform", state.platform ?? "<platform>"), readiness: { draft: true, publish: false, review: "not-required" } });
+  return report(ctx, state, "review-draft", "Return to the original draft in Sprid. Review its rendered slides and exact destination, then approve in the publish or schedule screen.", {
+    href, next: command("sprid", "open", "post", String(state.postId)),
+    destinations: active.map(c => ({ id: c.id, platform: c.platform, name: c.displayName })),
+    readiness: { draft: true, publish: "channel-connected", review: "not-required" },
+  });
+}