syndai 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to the `syndai` npm package. Versions follow semver.
 
+## 0.4.0
+
+Every published API operation, and a project's recurring runs.
+
+- `api <operationId>` calls any operation in the live API description (`/openapi.json`,
+  cached for 24 hours). `api` lists them; `api <operationId> --help` shows the parameters
+  and body. Fields come gh-style: `-f key=value` (string), `-F key=value` (true, false,
+  null, a number, or `@file`), `key[]=value` for a list. `--input FILE|-` sends a whole
+  body. `--paginate` follows `next_cursor` and prints one list. The workspace and this
+  directory's project fill required path parameters. `api <METHOD> <path>` still works.
+- `schedule list|show|add|edit|pause|resume|run-now|delete`: a project's recurring runs,
+  with cadence presets (`--every hourly|daily|weekdays|weekly` and `--at`, or a cron),
+  `--tz`, and a per-run cap (`--budget`).
+- `repeat <run> --every ...` repeats a run you liked. The server copies its original
+  prompt and project; the first run is the next scheduled time.
+- `login --scope S` asks for more access. A command that needs a scope the stored key
+  lacks asks once, on a terminal, to approve it in the browser and then retries.
+  `SYNDAI_API_KEY` never does this. Re-login now revokes the key it replaces.
+
+Breaking:
+
+- `--json` is machine output on every command. The request body on `api` and `answer`
+  is now `--input FILE|-` (the old string `--json` body is gone).
+
 ## 0.3.0
 
 The package becomes the Syndai owner CLI.

package/README.md

@@ -9,26 +9,37 @@ npx -y syndai@latest change "make the header blue"
 # Changing bakery.syndai.app · goes live when checks pass
 ```
 
-Node 22 or newer, zero dependencies, no telemetry. The customer guide is
-`apps/portal/content/docs/cli.mdx` (rendered as the docs site's **CLI** page);
-this README is for whoever works on the package.
+Node 22 or newer, zero dependencies, no telemetry. The customer guide is the docs
+site's **CLI** page, https://syndai.ai/docs/cli (`web/content/docs/cli.mdx`); this
+README is for whoever works on the package.
 
 ## Commands
 
 | command | does |
 |---|---|
-| `login [--with-token]`, `logout`, `whoami` | browser-approved key (device flow); `--with-token` reads a key from stdin |
+| `login [--with-token] [--scope S]...`, `logout`, `whoami` | browser-approved key (device flow); `--scope` asks for access on top of the key's current scopes; `--with-token` reads a key from stdin. Re-login saves the new key, then revokes the old one |
 | `link [project]` | remember which project this directory changes (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo) |
 | `change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome |
+| `new "<what>" [--no-learn] [--no-wait] [--timeout D]` | start a New project; a product URL in the text builds your own version of it (its feature pick is asked inline, Enter keeps the pre-checked core) |
 | `edit-text [--app A] [--page /] --from "..." --to "..."` / `--undo <sha>` | instant, free, undoable text swap on a live site |
 | `watch <run> [--timeout D] [--logs]` | follow any change; `--logs` tails its events |
-| `answer <run> [--json body]` | answer an open question |
+| `answer <run> [--input FILE\|-]` | answer an open question (`--input`: `{"entries":[...]}` from a file or stdin) |
 | `review <run> [--retry \| --close]` | see why a change is held, then approve it in the browser |
 | `go-live`, `revert`, `cancel <run>` | land actions |
 | `status [--app A]` | what is running, and everything that needs you |
 | `settings [--app A] [get \| set k=v...]` | `autonomy`, `feature_requests`, `bug_scan`, `protected_paths` (`+=` adds) |
 | `mcp install claude\|cursor\|codex` | add the Syndai MCP server to that tool's user config, with its own key |
-| `api <METHOD> <path> [--json body]` | call any route with your key |
+| `schedule list [--app A \| --all]`, `show <id>` | a project's recurring runs: cadence, next fires, History |
+| `schedule add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]` | create one; `E` is `hourly` (`--at :MM`), `daily`/`weekdays` (`--at HH:MM`), `weekly` (`--at "mon HH:MM"`) or a 5-field cron |
+| `schedule edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD\|none]` | change only what differs |
+| `schedule pause \| resume \| run-now \| delete <id> [--yes]` | manage one (`delete` asks on a terminal, needs `--yes` off one) |
+| `repeat <run> --every E [--at T] [--tz Z] [--budget USD]` | repeat a run you liked; the server copies its prompt and project; the first run is the next scheduled time |
+| `api` / `api <operationId> --help` | list every published operation / show one's parameters and body |
+| `api <operationId> \| <METHOD> <path> [-f k=v]... [-F k=v]... [--input FILE\|-] [--paginate] [--app A]` | call it with your key (`-f` string, `-F` typed, `k[]=v` lists) |
+
+A 403 that names a missing scope asks, on a terminal with a stored login, to approve
+it in the browser and retries once. `SYNDAI_API_KEY` never steps up; off a terminal the
+error names `syndai login --scope <scope>`. Members, keys and unpublish are portal-only.
 
 Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs you,
 4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
@@ -44,7 +55,10 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 - `src/auth.js`, `src/store.js`: credentials (0600, by workspace), links, pending change ids.
 - `src/projects.js`: which project a command acts on.
 - `src/watch.js`: the ChangeState long-poll loop, questions, `--logs`.
-- `src/changes.js`, `src/settings.js`, `src/mcp.js`: the commands.
+- `src/openapi.js`: the live `/openapi.json` (cached 24h per host in `$XDG_CACHE_HOME/syndai`).
+- `src/api.js`: `syndai api` (operations by id, fields, `--paginate`).
+- `src/schedules.js`: `schedule` and `repeat` (the preset to cron mapping of `apps/portal-v2/src/lib/cadence.ts`).
+- `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development
 
@@ -52,8 +66,15 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 cd tools/syndai-connect && node --test
 ```
 
-The suite runs a fake API on 127.0.0.1 and drives the CLI in-process (plus two
-child-process tests for Ctrl-C and a clean exit). `test/contract.test.js` checks
+CI runs it in its own **CLI Checks** job (`pr-ci.yml`, `main-ci.yml`) whenever
+`tools/syndai-connect/**`, `docs/api/**` or the portal's `cadence.ts` changes; it is
+part of **PR Gate** and deploys nothing.
+
+The suite runs a fake API on 127.0.0.1 (serving `/openapi.json` from the snapshot) and
+drives the CLI in-process (plus two child-process tests for Ctrl-C and a clean exit).
+`test/schedule.test.js` imports `apps/portal-v2/src/lib/cadence.ts` to prove the
+`--every` presets give the portal's cron; that needs a Node that strips TypeScript
+types (23.6+, as `.nvmrc`), and is skipped on Node 22. `test/contract.test.js` checks
 every route in `src/routes.js` against the published OpenAPI,
 `docs/api/external-coding-v1.openapi.json`. It goes red when a backend route the
 CLI uses is renamed or not yet published; regenerate the snapshot with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndai",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -0,0 +1,202 @@
+// `syndai api`: every published operation, by operationId (from the live OpenAPI, see
+// openapi.js) or as a raw `METHOD path`. Fields come gh-style: `-f key=value` is a string,
+// `-F key=value` is typed (true, false, null, a number, or @file for a file's text), and
+// `key[]=value` builds a list. A path-parameter field fills the path; any other field goes to
+// the query on GET and DELETE and to the JSON body otherwise. `--input FILE|-` is the whole
+// body instead. The step-up on a missing scope happens in http.js, so it covers this too.
+
+import fs from "node:fs";
+import path from "node:path";
+import { ApiError, CliError, EXIT, explain } from "./errors.js";
+import { findOperation, HTTP_METHODS, loadOperations, matchPath, shortPath } from "./openapi.js";
+import { resolveProject } from "./projects.js";
+import { readJsonInput } from "./ui.js";
+
+const EXT = "/api/v1/external/coding";
+const MAX_PAGES = 50;
+const USAGE = "syndai api [<operationId> | <METHOD> <path>] [-f k=v]... [-F k=v]... [--input F] [--paginate]";
+
+export async function api(ctx, args) {
+  const { flags } = ctx;
+  const [first, second, ...extra] = args;
+  if (!first) return listOperations(ctx);
+  const raw = HTTP_METHODS.includes(first.toUpperCase());
+  if (extra.length || (raw && !second) || (!raw && second)) {
+    throw new CliError(EXIT.USAGE, `Usage: ${USAGE}`, { next: "syndai api" });
+  }
+
+  let op = null;
+  let method;
+  let template;
+  const query = {};
+  if (raw) {
+    method = first.toUpperCase();
+    const full = second.startsWith("/api/") ? second : `${EXT}/${second.replace(/^\/+/, "")}`;
+    const [pathOnly, search = ""] = full.split("?");
+    template = pathOnly;
+    Object.assign(query, Object.fromEntries(new URLSearchParams(search)));
+    if (flags.help) {
+      ctx.io.stdout.write(`usage: ${USAGE}\n`);
+      return EXIT.OK;
+    }
+    if (flags.paginate) op = matchPath((await loadOperations(ctx)).operations, method, pathOnly);
+  } else {
+    op = await findOperation(ctx, first);
+    if (flags.help) return describeOperation(ctx, op);
+    method = op.method;
+    template = op.path;
+  }
+
+  const pathParams = new Set(
+    op && !raw ? op.params.filter((p) => p.in === "path").map((p) => p.name) : [],
+  );
+  const filled = {};
+  const body = {};
+  for (const [key, value] of Object.entries(collectFields(ctx))) {
+    if (pathParams.has(key)) filled[key] = value;
+    else if (method === "GET" || method === "DELETE") query[key] = value;
+    else body[key] = value;
+  }
+  let payload = Object.keys(body).length ? body : undefined;
+  if (flags.input !== undefined) {
+    if (payload) throw new CliError(EXIT.USAGE, "--input is the whole body; drop the body fields or --input.");
+    payload = await readJsonInput(ctx.io, flags.input);
+  }
+  for (const name of pathParams) {
+    if (filled[name] === undefined) filled[name] = await autoFill(ctx, op, name);
+  }
+  const target = template.replace(/\{(\w+)\}/g, (_, key) => encodeURIComponent(String(filled[key])));
+
+  if (flags.paginate) return paginate(ctx, op, method, target, query);
+  const res = await ctx.client.send(method, target, { query, body: payload, raw: true });
+  return printResponse(ctx, res);
+}
+
+/** `-f`/`-F` pairs as one object; a repeated key without `[]` is a usage error. */
+function collectFields(ctx) {
+  const fields = {};
+  const add = (pair, typed) => {
+    const eq = pair.indexOf("=");
+    if (eq < 1) throw new CliError(EXIT.USAGE, `Fields are key=value, not "${pair}".`);
+    let key = pair.slice(0, eq);
+    const value = typed ? typedValue(ctx, pair.slice(eq + 1)) : pair.slice(eq + 1);
+    const list = key.endsWith("[]");
+    if (list) key = key.slice(0, -2);
+    if (list && (fields[key] === undefined || Array.isArray(fields[key]))) {
+      fields[key] = [...(fields[key] ?? []), value];
+    } else if (key in fields) {
+      throw new CliError(EXIT.USAGE, `${key} is given twice; use ${key}[]=... for a list.`);
+    } else {
+      fields[key] = value;
+    }
+  };
+  for (const pair of ctx.flags["raw-field"] ?? []) add(pair, false);
+  for (const pair of ctx.flags.field ?? []) add(pair, true);
+  return fields;
+}
+
+function typedValue(ctx, text) {
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  if (text.startsWith("@")) {
+    try {
+      return fs.readFileSync(path.resolve(ctx.io.cwd, text.slice(1)), "utf8");
+    } catch (err) {
+      throw new CliError(EXIT.USAGE, `Cannot read ${text.slice(1)} (${err.code ?? err.message}).`);
+    }
+  }
+  return text;
+}
+
+/** Only required path parameters fill themselves: the workspace, and this directory's project. */
+async function autoFill(ctx, op, name) {
+  if (name === "customer_id") return ctx.customerId();
+  if (name === "coding_repository_id" || name === "repository_id") {
+    return (await resolveProject(ctx, { app: ctx.flags.app, picker: false })).id;
+  }
+  throw new CliError(EXIT.USAGE, `${op.id} needs ${name}.`, { next: `syndai api ${op.id} -f ${name}=...` });
+}
+
+async function paginate(ctx, op, method, target, query) {
+  if (method !== "GET") throw new CliError(EXIT.USAGE, "--paginate works on GET operations only.");
+  const names = new Set((op?.params ?? []).map((p) => p.name));
+  const cursorParam = ["cursor", "after"].find((name) => names.has(name));
+  if (!cursorParam) {
+    throw new CliError(EXIT.USAGE, `${op?.id ?? target} does not page (no cursor or after parameter).`);
+  }
+  const items = [];
+  for (let page = 1; ; page++) {
+    const res = await ctx.client.send(method, target, { query, raw: true });
+    if (res.status >= 400) return printResponse(ctx, res);
+    const arrays = Object.entries(res.body ?? {}).filter(([, value]) => Array.isArray(value));
+    if (arrays.length !== 1) {
+      throw new CliError(EXIT.FAILED, `${op.id} does not answer with one list, so it cannot be paged.`);
+    }
+    items.push(...arrays[0][1]);
+    const next = res.body.next_cursor;
+    if (!next) break;
+    if (page >= MAX_PAGES) {
+      ctx.ui.progress(ctx.ui.yellow(`Stopped after ${MAX_PAGES} pages; narrow the query to see the rest.`));
+      break;
+    }
+    query[cursorParam] = next;
+  }
+  ctx.io.stdout.write(`${JSON.stringify(items, null, ctx.ui.json ? 0 : 2)}\n`);
+  return EXIT.OK;
+}
+
+/** The body as JSON on stdout (problem bodies too); an error line and its next step on stderr. */
+function printResponse(ctx, res) {
+  const { io, ui } = ctx;
+  if (res.body !== null && res.body !== undefined) {
+    io.stdout.write(`${JSON.stringify(res.body, null, ui.json ? 0 : 2)}\n`);
+  }
+  if (res.status < 400) return EXIT.OK;
+  const { exitCode, message, next } = explain(new ApiError(res.status, res.body, res.headers));
+  ui.progress(`${ui.red("error:")} ${message}`);
+  if (next) ui.progress(`  next: ${next}`);
+  return exitCode;
+}
+
+async function listOperations(ctx) {
+  const { ui } = ctx;
+  const { operations } = await loadOperations(ctx);
+  const sorted = [...operations].sort((a, b) => a.group.localeCompare(b.group) || a.id.localeCompare(b.id));
+  const width = Math.max(...sorted.map((op) => op.id.length));
+  const lines = [];
+  let group = null;
+  for (const op of sorted) {
+    if (op.group !== group) {
+      group = op.group;
+      lines.push(`${lines.length ? "\n" : ""}${ui.bold(group)}`);
+    }
+    lines.push(`  ${op.id.padEnd(width)}  ${op.method.padEnd(6)} ${shortPath(op.path)}`);
+  }
+  lines.push(
+    "",
+    `usage: ${USAGE}`,
+    "Details of one: syndai api <operationId> --help. Paths are relative to /api/v1/external/coding.",
+  );
+  ui.result(
+    { operations: sorted.map(({ id, method, path: opPath, summary }) => ({ operation_id: id, method, path: opPath, summary })) },
+    lines.join("\n"),
+  );
+  return EXIT.OK;
+}
+
+function describeOperation(ctx, op) {
+  const lines = [`${ctx.ui.bold(op.id)}  ${op.method} ${op.path}`];
+  if (op.summary) lines.push(op.summary);
+  if (op.params.length) {
+    lines.push("", "Parameters (-f name=value):");
+    for (const p of op.params) lines.push(`  ${p.name}  ${p.in}${p.required ? ", required" : ""}`);
+  }
+  if (op.body) {
+    lines.push("", `Body${op.body.schema ? ` (${op.body.schema})` : ""}: fields, or --input FILE`);
+    for (const f of op.body.fields) lines.push(`  ${f.name}  ${f.type}${f.required ? ", required" : ""}`);
+  }
+  ctx.ui.result(op, lines.join("\n"));
+  return EXIT.OK;
+}

package/src/auth.js

@@ -6,10 +6,10 @@
 // There is no --api-key flag, so a key never lands in shell history.
 
 import { hostname } from "node:os";
-import { ApiError, CliError, EXIT } from "./errors.js";
+import { ApiError, CliError, EXIT, explain, PORTAL_URL, steppable } from "./errors.js";
 import { createClient, DEFAULT_API_URL, interrupted } from "./http.js";
 import { findLink, loadCredentials, removeCredential, saveCredential, storePaths } from "./store.js";
-import { createUi } from "./ui.js";
+import { ask, createUi, readAll } from "./ui.js";
 
 /** The key this invocation uses: env first, then the cwd link's workspace, then the default. */
 export function resolveCredential(io, paths) {
@@ -27,47 +27,111 @@ function storedCredential(io, paths) {
   return { apiKey: entry.api_key, customerId, source: paths.credentials };
 }
 
-/** Per-invocation state shared by every command. */
-export function createContext(io, flags) {
+/**
+ * Per-invocation state shared by every command. `stepUp: false` (the commands that follow a
+ * change live) never asks for a missing scope mid-stream: they print it and exit 5.
+ */
+export function createContext(io, flags, { stepUp = true } = {}) {
   const paths = storePaths(io.env);
   const ui = createUi(io, { json: flags.json === true, noInput: flags["no-input"] === true });
   const baseUrl = (io.env.SYNDAI_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
   let cached;
+  let me;
   const credential = () => {
     cached ??= resolveCredential(io, paths);
     if (!cached) throw new CliError(EXIT.AUTH, "You are not logged in.", { next: "syndai login" });
     return cached;
   };
   const clientFor = (getKey) => createClient({ baseUrl, getKey, io });
-  const client = clientFor(async () => credential().apiKey);
-  let me;
-  return {
+  const ctx = {
     io,
     ui,
     paths,
     flags,
     baseUrl,
-    client,
     clientFor,
     credential,
+    /** Forget the memoised key and `/me` (after a new key is stored). */
+    reset() {
+      cached = undefined;
+      me = undefined;
+    },
     async me() {
-      me ??= await client.call("me");
+      me ??= await ctx.client.call("me");
       return me;
     },
     async customerId() {
-      return credential().customerId ?? (await this.me()).customer_id;
+      return credential().customerId ?? (await ctx.me()).customer_id;
     },
   };
+  ctx.client = createClient({
+    baseUrl,
+    getKey: async () => credential().apiKey,
+    io,
+    onMissingScope: stepUp ? (scope) => stepUpScope(ctx, scope) : undefined,
+  });
+  return ctx;
+}
+
+/**
+ * A 403 named the scope it needs. On a terminal, with the stored login (never
+ * SYNDAI_API_KEY, which belongs to CI), ask once, approve a key with the current scopes plus
+ * that one in the browser, store it, and let the client retry. Declining mints nothing.
+ */
+async function stepUpScope(ctx, scope) {
+  const { io, ui } = ctx;
+  if (!ui.interactive || !steppable(scope) || ctx.credential().source === "SYNDAI_API_KEY") return false;
+  const answer = await ask(io, `This needs the ${scope} scope. Approve it in your browser? [Y/n] `);
+  if (/^n/i.test(answer)) return false;
+  const token = await deviceApproval(ctx, "CLI", await scopesWith(ctx, [scope]));
+  await storeKey(ctx, token);
+  return true;
+}
+
+/** The stored key's scopes plus `extra` (an unknown or dead stored key adds nothing). */
+async function scopesWith(ctx, extra) {
+  const stored = storedCredential(ctx.io, ctx.paths);
+  let current = [];
+  if (stored) {
+    try {
+      current = (await ctx.clientFor(async () => stored.apiKey).call("me")).scopes ?? [];
+    } catch (err) {
+      if (!(err instanceof ApiError && err.status === 401)) throw err;
+    }
+  }
+  return [...new Set([...current, ...extra])];
+}
+
+/**
+ * Save a new key, THEN revoke the key it replaces (best-effort: a failed revoke only warns,
+ * so the new key is never lost). The same key id again is not revoked.
+ */
+async function storeKey(ctx, token) {
+  const { paths, ui } = ctx;
+  const old = loadCredentials(paths).customers[token.customer_id];
+  saveCredential(paths, token);
+  ctx.reset();
+  if (!old || old.api_key === token.api_key || (old.key_id && old.key_id === token.key_id)) return;
+  try {
+    await ctx.clientFor(async () => old.api_key).call("revokeMe");
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) return; // already revoked or expired
+    if (err instanceof CliError && err.exitCode === EXIT.INTERRUPTED) throw err;
+    ui.progress(
+      ui.yellow(`Warning: the previous key was not revoked (${explain(err).message}). Revoke it at ${PORTAL_URL}.`),
+    );
+  }
 }
 
 /**
  * Ask for a key and wait until an owner approves it in the browser. Returns the token
  * response `{api_key, customer_id, key_id, expires_at}`.
  */
-export async function deviceApproval(ctx, clientName) {
+export async function deviceApproval(ctx, clientName, scopes) {
   const { client, ui, io } = ctx;
   const start = await client.call("deviceStart", {
-    body: { client_name: clientName, host: hostname() },
+    // No `scopes` means the owner preset (owner_door); a list asks for those on top of it.
+    body: { client_name: clientName, host: hostname(), ...(scopes ? { scopes } : {}) },
     auth: false,
     retry: true,
   });
@@ -114,7 +178,15 @@ export async function deviceApproval(ctx, clientName) {
 }
 
 export async function login(ctx) {
-  const { io, ui, paths, flags } = ctx;
+  const { io, ui, flags } = ctx;
+  const extra = flags.scope ?? [];
+  const portalOnly = extra.find((scope) => !steppable(scope));
+  if (portalOnly) {
+    throw new CliError(EXIT.USAGE, `${portalOnly} is granted in the portal only.`, { next: PORTAL_URL });
+  }
+  if (extra.length && flags["with-token"]) {
+    throw new CliError(EXIT.USAGE, "--scope asks the browser for a key; it does not go with --with-token.");
+  }
   let token;
   if (flags["with-token"]) {
     if (io.stdin.isTTY) ui.progress("Paste a Syndai API key, then press Ctrl-D:");
@@ -123,9 +195,9 @@ export async function login(ctx) {
     const me = await ctx.clientFor(async () => apiKey).call("me");
     token = { api_key: apiKey, customer_id: me.customer_id, key_id: me.key_id, expires_at: me.expires_at };
   } else {
-    token = await deviceApproval(ctx, "CLI");
+    token = await deviceApproval(ctx, "CLI", extra.length ? await scopesWith(ctx, extra) : undefined);
   }
-  saveCredential(paths, token);
+  await storeKey(ctx, token);
   if (io.env.SYNDAI_API_KEY) ui.progress(ui.yellow("Note: SYNDAI_API_KEY is set and wins over this login."));
   const expires = token.expires_at ? ` until ${token.expires_at.slice(0, 10)}` : "";
   ui.result(
@@ -171,9 +243,3 @@ export async function whoami(ctx) {
   );
   return EXIT.OK;
 }
-
-async function readAll(stream) {
-  let text = "";
-  for await (const chunk of stream) text += chunk;
-  return text;
-}

package/src/changes.js

@@ -8,7 +8,7 @@ import path from "node:path";
 import { ApiError, CliError, EXIT } from "./errors.js";
 import { projectHost, projectLabel, resolveProject } from "./projects.js";
 import { clearPending, findPending, writePending } from "./store.js";
-import { ask, parseDuration, ulid } from "./ui.js";
+import { ask, parseDuration, readJsonInput, ulid } from "./ui.js";
 import { answerInteractively, describe, finish, getChange, nextFor, respond, watchChange } from "./watch.js";
 
 const TERMINAL_PHASES = new Set(["completed", "failed", "cancelled"]);
@@ -65,6 +65,57 @@ export async function change(ctx, words) {
   return watchChange(ctx, runId, { timeoutMs });
 }
 
+/** The first non-GitHub product URL in the text, normalised to https; null when there is none.
+ * Same rule as Build home (portal-v2 `productUrlFromText`): a GitHub URL means an existing repo. */
+export function productUrlFromText(text) {
+  for (const m of text.matchAll(/\b(?:https?:\/\/|www\.)[^\s<>"')\]]+/gi)) {
+    const raw = m[0].replace(/[.,;:!?]+$/, "");
+    try {
+      const url = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+      const host = url.hostname.toLowerCase();
+      if (!host.includes(".") || host === "github.com" || host.endsWith(".github.com")) continue;
+      return url.href;
+    } catch {}
+  }
+  return null;
+}
+
+/** Build-home parity: start a New project. A product URL in the text makes it "your own version
+ * of X" (SPEC-build-your-own D5) unless --no-learn; its feature-pick question is asked inline. */
+export async function newProject(ctx, words) {
+  const { flags, ui, paths, io } = ctx;
+  const text = words.join(" ").trim();
+  if (!text) throw new CliError(EXIT.USAGE, 'Say what to build: syndai new "a booking site for my salon"');
+  const timeoutMs = timeoutOf(flags);
+  const reference = flags["no-learn"] ? null : productUrlFromText(text);
+  ui.progress(
+    reference
+      ? `New project · your own version of ${new URL(reference).hostname.replace(/^www\./, "")}`
+      : "New project",
+  );
+  const pending = findPending(paths, { app: "new", text }) ?? {
+    request_id: `cli:${ulid()}`,
+    app: "new",
+    text,
+    created_at: new Date(io.now()).toISOString(),
+  };
+  writePending(paths, pending);
+  const runId = await createRun(ctx, {
+    body: {
+      prompt: text,
+      new_repository: { scaffold: "syndai-web" },
+      external_request_id: pending.request_id,
+      ...(reference ? { metadata: { reference_product: { kind: "url", value: reference } } } : {}),
+    },
+  });
+  clearPending(paths, pending.request_id);
+  ui.progress(ui.dim(`Change ${runId}`));
+  if (flags["no-wait"]) {
+    return finish(ctx, await getChange(ctx, runId), { exitCode: EXIT.OK, next: `syndai watch ${runId}` });
+  }
+  return watchChange(ctx, runId, { timeoutMs });
+}
+
 async function createRun(ctx, { body }) {
   try {
     const created = await ctx.client.call("createRun", { body, retry: true });
@@ -111,23 +162,15 @@ export async function answer(ctx, runId) {
     ui.result({ ...state, next: nextFor(state) }, `Nothing to answer. ${describe(state)}`);
     return EXIT.OK;
   }
-  if (typeof flags.json === "string") {
-    let body;
-    try {
-      body = JSON.parse(flags.json);
-    } catch {
-      throw new CliError(
-        EXIT.USAGE,
-        '--json must be JSON, like {"entries":[{"input_id":"q1","text":"blue"}]}.',
-      );
-    }
-    const entries = Array.isArray(body) ? body : body.entries;
+  if (flags.input !== undefined) {
+    const body = await readJsonInput(ctx.io, flags.input);
+    const entries = Array.isArray(body) ? body : body?.entries;
     const hitlRequestId =
-      body.hitl_request_id ?? (questions.length === 1 ? questions[0].hitl_request_id : null);
+      body?.hitl_request_id ?? (questions.length === 1 ? questions[0].hitl_request_id : null);
     if (!hitlRequestId || !Array.isArray(entries)) {
       throw new CliError(
         EXIT.USAGE,
-        "--json needs entries, and hitl_request_id when several questions are open.",
+        '--input needs {"entries":[...]}, and hitl_request_id when several questions are open.',
       );
     }
     await respond(ctx, runId, hitlRequestId, entries);

package/src/errors.js

@@ -1,6 +1,6 @@
 // Exit codes and the one place a server problem becomes a sentence plus the next command.
 //
-// The exit codes are a contract with scripts and agents (docs: cli.mdx "Exit codes"):
+// The exit codes are a contract with scripts and agents (docs: syndai.ai/docs/cli, "Exit codes"):
 // never renumber one.
 
 export const EXIT = Object.freeze({
@@ -41,11 +41,31 @@ export class ApiError extends Error {
 export class UnavailableError extends Error {}
 
 const BILLING_URL = "https://app.syndai.ai/billing";
+export const PORTAL_URL = "https://app.syndai.ai";
+
+/**
+ * A scope `syndai login --scope` may add with one browser approval. Members, keys and
+ * unpublish stay portal-only: the approval page promises a CLI key never manages members or
+ * keys, and those powers stay out of a device-code grant.
+ */
+export function steppable(scope) {
+  return !/:members:|keys|:unpublish$/.test(scope);
+}
 
 // code -> [exit, sentence, next]. Either may be a function of the problem body.
 const KNOWN = {
   INVALID_TOKEN: [EXIT.AUTH, "Your Syndai key is missing, expired or revoked.", "syndai login"],
-  INVALID_SCOPE: [EXIT.AUTH, "This key is not allowed to do that.", "syndai login"],
+  INVALID_SCOPE: [
+    EXIT.AUTH,
+    ({ required_scope: scope }) =>
+      !scope
+        ? "This key is not allowed to do that."
+        : steppable(scope)
+          ? `This key does not have the ${scope} scope.`
+          : `Only the portal can do this (it needs ${scope}).`,
+    ({ required_scope: scope }) =>
+      !scope ? "syndai login" : steppable(scope) ? `syndai login --scope ${scope}` : PORTAL_URL,
+  ],
   ROLE_REQUIRED: [EXIT.AUTH, "Only workspace owners and admins can do that.", null],
   PLAN_UPGRADE_REQUIRED: [EXIT.AUTH, "Your plan does not include that.", BILLING_URL],
   BUDGET_EXHAUSTED: [EXIT.AUTH, "This workspace is out of credits.", BILLING_URL],