syndai 0.3.0 → 0.4.0

package/src/http.js

@@ -1,7 +1,7 @@
 // The one HTTP client. Raw `fetch`, no SDK: `test/contract.test.js` checks every route
 // against the published OpenAPI instead.
 //
-// Retry rule (docs: cli.mdx "Retries"): only GETs and POSTs that carry their own
+// Retry rule (docs: syndai.ai/docs/cli, "Retries"): only GETs and POSTs that carry their own
 // idempotency key are retried — callers opt in with `retry: true`. A 429 waits out
 // `Retry-After`; a 5xx, 408, network error or `MISSION_BUSY_RETRY` backs off from 0.5 s
 // towards 8 s with jitter. Five tries, then `UnavailableError` (exit 7).
@@ -37,9 +37,13 @@ export function interrupted() {
 }
 
 /**
- * @param {{baseUrl: string, getKey: () => Promise<string>, io: object}} options
+ * `onMissingScope(scope)` is asked once per request when a 403 names the scope it needs
+ * (`required_scope`); when it answers true (a new key was approved), the request is sent
+ * again with the new key.
+ *
+ * @param {{baseUrl: string, getKey: () => Promise<string>, io: object, onMissingScope?: (scope: string) => Promise<boolean>}} options
  */
-export function createClient({ baseUrl, getKey, io }) {
+export function createClient({ baseUrl, getKey, io, onMissingScope }) {
   /** Call a named route from `routes.js`. */
   function call(name, { params, ...opts } = {}) {
     const [method, path] = route(name, params);
@@ -53,15 +57,15 @@ export function createClient({ baseUrl, getKey, io }) {
   ) {
     const url = new URL(baseUrl + path);
     for (const [key, value] of Object.entries(query ?? {})) {
-      if (value !== undefined && value !== null && value !== "") {
-        url.searchParams.set(key, String(value));
-      }
+      if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, String(item));
+      else if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
     }
     const headers = { "user-agent": USER_AGENT, accept: "application/json" };
     if (body !== undefined) headers["content-type"] = "application/json";
     if (auth) headers.authorization = `Bearer ${await getKey()}`;
     const payload = body === undefined ? undefined : JSON.stringify(body);
 
+    let steppedUp = false;
     for (let attempt = 1; ; attempt++) {
       let res;
       let parsed;
@@ -82,6 +86,15 @@ export function createClient({ baseUrl, getKey, io }) {
       }
 
       const problem = res.ok ? null : new ApiError(res.status, parsed, res.headers);
+      const scope = problem?.code === "INVALID_SCOPE" ? problem.problem.required_scope : null;
+      if (scope && auth && onMissingScope && !steppedUp) {
+        steppedUp = true;
+        if (await onMissingScope(scope)) {
+          headers.authorization = `Bearer ${await getKey()}`;
+          attempt = 0;
+          continue;
+        }
+      }
       const transient =
         problem !== null &&
         (res.status >= 500 ||

package/src/main.js

@@ -4,12 +4,14 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { createContext, login, logout, whoami } from "./auth.js";
-import { answer, cancel, change, editText, goLive, review, revert, status, watch } from "./changes.js";
+import { answer, cancel, change, editText, goLive, newProject, review, revert, status, watch } from "./changes.js";
 import { CliError, EXIT, explain } from "./errors.js";
 import { VERSION } from "./http.js";
 import { mcp } from "./mcp.js";
 import { link } from "./projects.js";
-import { api, settings } from "./settings.js";
+import { api } from "./api.js";
+import { repeat, schedule } from "./schedules.js";
+import { settings } from "./settings.js";
 import { closeInput, openBrowser, page } from "./ui.js";
 
 const str = { type: "string" };
@@ -28,17 +30,26 @@ const COMMANDS = {
       timeout: str,
     },
     run: (ctx, args) => change(ctx, args),
+    stepUp: false,
+  },
+  new: {
+    usage: 'new "<what>" [--no-learn] [--no-wait] [--timeout D]',
+    summary: "Start a new project; a product URL in the text builds your own version of it.",
+    options: { "no-learn": bool, "no-wait": bool, timeout: str },
+    run: (ctx, args) => newProject(ctx, args),
+    stepUp: false,
   },
   watch: {
     usage: "watch <run> [--timeout D] [--logs]",
     summary: "Follow a change to its outcome (Ctrl-C detaches; the change keeps going).",
     options: { timeout: str, logs: bool },
     run: (ctx, [run]) => watch(ctx, run),
+    stepUp: false,
   },
   answer: {
-    usage: "answer <run> [--json '{\"entries\":[...]}']",
-    summary: "Answer a change's open question.",
-    options: { json: str },
+    usage: "answer <run> [--input FILE|-]",
+    summary: 'Answer a change\'s open question (--input: {"entries":[...]} from a file or stdin).',
+    options: { input: str },
     run: (ctx, [run]) => answer(ctx, run),
   },
   review: {
@@ -52,12 +63,14 @@ const COMMANDS = {
     summary: "Put a ready change live.",
     options: { timeout: str },
     run: (ctx, [run]) => goLive(ctx, run),
+    stepUp: false,
   },
   revert: {
     usage: "revert <run> [--force] [--timeout D]",
     summary: "Undo a change that went live.",
     options: { force: bool, timeout: str },
     run: (ctx, [run]) => revert(ctx, run),
+    stepUp: false,
   },
   cancel: {
     usage: "cancel <run>",
@@ -78,9 +91,10 @@ const COMMANDS = {
     run: (ctx) => editText(ctx),
   },
   login: {
-    usage: "login [--with-token]",
-    summary: "Log in by approving this computer in your browser (--with-token reads a key from stdin).",
-    options: { "with-token": bool },
+    usage: "login [--with-token] [--scope S]...",
+    summary:
+      "Log in by approving this computer in your browser (--scope adds access to the key's; --with-token reads a key from stdin).",
+    options: { "with-token": bool, scope: { type: "string", multiple: true } },
     run: (ctx) => login(ctx),
   },
   logout: {
@@ -113,10 +127,33 @@ const COMMANDS = {
     options: {},
     run: (ctx, args) => mcp(ctx, args),
   },
+  schedule: {
+    usage:
+      'schedule list [--app A | --all] | show <id> | add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]\n' +
+      "               | edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD|none]\n" +
+      "               | pause | resume | run-now | delete <id> [--yes]",
+    summary:
+      'A project\'s recurring runs. E: hourly (--at :MM), daily or weekdays (--at HH:MM), weekly (--at "mon HH:MM"), or a 5-field cron.',
+    options: { app: str, all: bool, every: str, at: str, tz: str, budget: str, prompt: str, yes: bool },
+    run: (ctx, args) => schedule(ctx, args),
+  },
+  repeat: {
+    usage: "repeat <run> --every E [--at T] [--tz Z] [--budget USD]",
+    summary: "Run a change you liked again on a schedule (its first run is the next scheduled time).",
+    options: { every: str, at: str, tz: str, budget: str },
+    run: (ctx, args) => repeat(ctx, args),
+  },
   api: {
-    usage: "api <METHOD> <path> [--json body]",
-    summary: "Call any Syndai API route with your key.",
-    options: { json: str },
+    usage: "api [<operationId> | <METHOD> <path>] [-f k=v]... [-F k=v]... [--input FILE|-] [--paginate] [--app A]",
+    summary: "Call any Syndai API operation with your key (no arguments: list them; <operationId> --help: its fields).",
+    options: {
+      "raw-field": { type: "string", short: "f", multiple: true },
+      field: { type: "string", short: "F", multiple: true },
+      input: str,
+      paginate: bool,
+      app: str,
+    },
+    ownHelp: true,
     run: (ctx, args) => api(ctx, args),
   },
 };
@@ -175,11 +212,11 @@ export async function main(argv, io) {
     io.stderr.write(`error: ${err.message}\n  usage: syndai ${spec.usage}\n`);
     return EXIT.USAGE;
   }
-  if (parsed.values.help) {
+  if (parsed.values.help && !spec.ownHelp) {
     io.stdout.write(`usage: syndai ${spec.usage}\n${spec.summary}\n`);
     return EXIT.OK;
   }
-  const ctx = createContext(io, parsed.values);
+  const ctx = createContext(io, parsed.values, { stepUp: spec.stepUp !== false });
   try {
     return await spec.run(ctx, parsed.positionals);
   } catch (err) {

package/src/openapi.js

@@ -0,0 +1,145 @@
+// The live API description behind `syndai api <operationId>`. The server's public
+// `/openapi.json` is the one source, so a new route is callable the day it deploys. It is
+// cached per host for 24 hours ($XDG_CACHE_HOME/syndai/openapi-<host>.json) and fetched again
+// once when an operationId is not in the cached copy. The server sends no ETag, and a ~27 KB
+// gzipped fetch a day does not justify one.
+
+import path from "node:path";
+import { CliError, EXIT } from "./errors.js";
+import { readJson, writeFileAtomic } from "./store.js";
+import { hostOf } from "./ui.js";
+
+const TTL_MS = 24 * 60 * 60 * 1000;
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const EXT_PREFIX = /^\/api\/v1\/(external\/coding\/)?/;
+
+function cacheFile(ctx) {
+  const host = (hostOf(ctx.baseUrl) ?? "api").replace(/[^\w.-]/g, "_");
+  return path.join(ctx.paths.cache, `openapi-${host}.json`);
+}
+
+/** The operations, from the cache when it is fresh (or `refresh` is false and it exists). */
+export async function loadOperations(ctx, { refresh = false } = {}) {
+  const file = cacheFile(ctx);
+  let cached = null;
+  try {
+    cached = readJson(file, null);
+  } catch {
+    // A corrupt cache is refetched, never an error.
+  }
+  if (!refresh && cached?.spec && ctx.io.now() - cached.fetched_at < TTL_MS) {
+    return { operations: index(cached.spec), fresh: false };
+  }
+  const spec = await ctx.client.send("GET", "/openapi.json", { auth: false });
+  writeFileAtomic(file, JSON.stringify({ fetched_at: ctx.io.now(), spec }), 0o644);
+  return { operations: index(spec), fresh: true };
+}
+
+/** One operation by id (exact, or ignoring case, `-` and `_`); refetches once when unknown. */
+export async function findOperation(ctx, id) {
+  let { operations, fresh } = await loadOperations(ctx);
+  let op = lookup(operations, id);
+  if (!op && !fresh) {
+    ({ operations } = await loadOperations(ctx, { refresh: true }));
+    op = lookup(operations, id);
+  }
+  if (op) return op;
+  const near = closest(operations, id);
+  throw new CliError(EXIT.USAGE, `No API operation is called "${id}".`, {
+    next: near.length ? `did you mean: ${near.join(", ")}? (syndai api lists them all)` : "syndai api",
+  });
+}
+
+/** The operation a concrete METHOD + path calls, or null. */
+export function matchPath(operations, method, concretePath) {
+  return (
+    operations.find(
+      (op) =>
+        op.method === method &&
+        new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, "\\$&").replace(/\\?\{[^}]+\\?\}/g, "[^/]+")}$`).test(
+          concretePath,
+        ),
+    ) ?? null
+  );
+}
+
+const norm = (name) => name.toLowerCase().replace(/[-_]/g, "");
+
+function lookup(operations, id) {
+  return operations.find((op) => op.id === id) ?? operations.find((op) => norm(op.id) === norm(id)) ?? null;
+}
+
+function closest(operations, id, count = 3) {
+  const wanted = norm(id);
+  return operations
+    .map((op) => [distance(norm(op.id), wanted), op.id])
+    .sort((a, b) => a[0] - b[0] || a[1].localeCompare(b[1]))
+    .slice(0, count)
+    .map(([, name]) => name);
+}
+
+function distance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = row;
+  }
+  return prev[b.length];
+}
+
+/** Flatten an OpenAPI document to `[{id, method, path, group, summary, params, body}]`. */
+export function index(spec) {
+  const resolve = (schema) => {
+    const ref = schema?.$ref;
+    return ref ? (spec.components?.schemas?.[ref.split("/").pop()] ?? {}) : (schema ?? {});
+  };
+  const operations = [];
+  for (const [opPath, item] of Object.entries(spec.paths ?? {})) {
+    for (const method of HTTP_METHODS) {
+      const op = item[method.toLowerCase()];
+      if (!op?.operationId) continue;
+      const params = [...(item.parameters ?? []), ...(op.parameters ?? [])].map((p) => ({
+        name: p.name,
+        in: p.in,
+        required: Boolean(p.required),
+      }));
+      const schemaRef = op.requestBody?.content?.["application/json"]?.schema;
+      const schema = resolve(schemaRef);
+      const required = new Set(schema.required ?? []);
+      const body = schemaRef
+        ? {
+            schema: schemaRef.$ref?.split("/").pop() ?? null,
+            fields: Object.entries(schema.properties ?? {}).map(([name, prop]) => ({
+              name,
+              type: typeName(prop),
+              required: required.has(name),
+            })),
+          }
+        : null;
+      operations.push({
+        id: op.operationId,
+        method,
+        path: opPath,
+        group: opPath.replace(EXT_PREFIX, "").split("/")[0] || "other",
+        summary: op.summary ?? "",
+        params,
+        body,
+      });
+    }
+  }
+  return operations;
+}
+
+function typeName(schema) {
+  const options = schema.oneOf ?? schema.anyOf;
+  if (options) return options.map((o) => o.type ?? o.$ref?.split("/").pop() ?? "object").join(" | ");
+  return schema.type ?? schema.$ref?.split("/").pop() ?? "object";
+}
+
+/** `/api/v1/external/coding/runs` -> `/runs`, for compact listings. */
+export function shortPath(opPath) {
+  return opPath.startsWith("/api/v1/external/coding/") ? opPath.slice("/api/v1/external/coding".length) : opPath;
+}

package/src/projects.js

@@ -1,4 +1,4 @@
-// Which project a command acts on. Order (docs: cli.mdx "Choosing the project"):
+// Which project a command acts on. Order (docs: syndai.ai/docs/cli, "Choosing the project"):
 // --app, SYNDAI_APP, the link for this directory or a parent, a git remote that matches a
 // connected repo, the only project, a picker on a terminal. Otherwise exit 2 with the list.
 //

package/src/routes.js

@@ -1,7 +1,7 @@
 // Every REST route the CLI calls, in one table. Code builds paths only through `path()`,
 // so `test/contract.test.js` can prove each one exists, with the same method, in the
 // published OpenAPI (`docs/api/external-coding-v1.openapi.json`). `syndai api` is the one
-// escape hatch that bypasses this table.
+// command that bypasses this table: it reads the live OpenAPI instead (openapi.js).
 
 const EXT = "/api/v1/external/coding";
 
@@ -27,6 +27,7 @@ export const ROUTES = Object.freeze({
   imageIngest: ["POST", `${EXT}/runs/image-ingest`],
   createRun: ["POST", `${EXT}/runs`],
   listRuns: ["GET", `${EXT}/runs`],
+  getRun: ["GET", `${EXT}/runs/{coding_run_id}`],
   changeState: ["GET", `${EXT}/runs/{run_id}/change`],
   runEvents: ["GET", `${EXT}/runs/{run_id}/events`],
   respond: ["POST", `${EXT}/runs/{run_id}/responses`],
@@ -36,6 +37,14 @@ export const ROUTES = Object.freeze({
   landClose: ["POST", `${EXT}/runs/{run_id}/land/close`],
   goLive: ["POST", `${EXT}/runs/{run_id}/land/go-live`],
   heldDiff: ["GET", `${EXT}/runs/{run_id}/land/held-diff`],
+  listSchedules: ["GET", `${EXT}/schedules`],
+  createSchedule: ["POST", `${EXT}/schedules`],
+  getSchedule: ["GET", `${EXT}/schedules/{schedule_id}`],
+  updateSchedule: ["PATCH", `${EXT}/schedules/{schedule_id}`],
+  deleteSchedule: ["DELETE", `${EXT}/schedules/{schedule_id}`],
+  pauseSchedule: ["POST", `${EXT}/schedules/{schedule_id}/pause`],
+  resumeSchedule: ["POST", `${EXT}/schedules/{schedule_id}/resume`],
+  runScheduleNow: ["POST", `${EXT}/schedules/{schedule_id}/run-now`],
 });
 
 /** The MCP endpoint `syndai mcp install` points clients at (JSON-RPC, not REST). */