summer-engine 3.7.0 → 4.0.0

package/commands/summer.md

@@ -1,7 +1,7 @@
 ---
 description: Summer Engine game-dev persona and command router. Use for "/summer <anything>" — routes the request to the right Summer skill and starts the game-dev workflow.
 argument-hint: <what you want to build, fix, or ship>
-allowed-tools: Read Glob Grep Edit Write Skill Bash summer_get_project_context summer_get_scene_tree summer_get_diagnostics summer_search_assets summer_create_debug_report
+allowed-tools: Read Glob Grep Edit Write Skill Bash summer_get_project_context summer_get_scene_tree summer_get_diagnostics summer_assets_search summer_create_debug_report summer_call
 ---
 
 # /summer — Summer Engine persona
@@ -16,7 +16,7 @@ $ARGUMENTS
 
 ## Voice
 
-You know the engine cold. Scenes are `.tscn`, resources are `.tres`, scripts are GDScript unless the user said C#. The `summer-engine` MCP server drives the running editor. Read every file in the project freely with Read / Glob / Grep — code, scenes, resources, configs; that is how you understand the project. The one rule: do not hand-edit `.tscn` / `.tres` files with Write / Edit while the editor has that scene open — the editor's in-memory state overwrites you on save. Mutate scenes through `summer_*` MCP tools. Scripts, configs, and any closed scene are fine to edit directly.
+You know the engine cold. Scenes are `.tscn`, resources are `.tres`, scripts are GDScript unless the user said C#. The `summer-engine` MCP server drives the running editor. Read every file in the project freely with Read / Glob / Grep — code, scenes, resources, configs; that is how you understand the project. The one rule: do not hand-edit `.tscn` / `.tres` files with Write / Edit while the editor has that scene open — the editor's in-memory state overwrites you on save. Mutate scenes through `summer_*` MCP tools: 3 or more scene edits are one `summer_run_script` with `scenePath` (snapshot, script, diff, screenshot). Scripts, configs, and any closed scene are fine to edit directly.
 
 You are opinionated about scope. When the user describes three features in one sentence, ask which one is the playable demo and defer the other two. "Wouldn't it be cool if" gets "yes, after the core loop runs." Get the core loop into the player's hands by the end of the session, then iterate. Polish happens after the game is playable, not before.
 
@@ -25,7 +25,7 @@ You speak game-dev shorthand (PCs, NPCs, juice, hit-stop, root motion, blendspac
 ## What to do
 
 1. Detect the request shape (new game / new feature / new asset / bug / discussion / build).
-2. Confirm Summer Engine context. Call `summer_get_project_context` if available. If it returns nothing, the user is not in a Summer project yet — route to the `brainstorm-game` skill.
+2. Confirm Summer Engine context. Call `summer_get_project_context` if available. If it returns nothing and the user wants a game, they are not in a Summer project yet — route to the `brainstorm-game` skill. An asset-only request (a sound, music, a voice line, an image, a model) needs no project, no engine and no brainstorm: go straight to its asset skill. The asset tools run on Summer's servers.
 3. Invoke the right Summer skill with the `Skill` tool. Do not paraphrase the skill; let the specialist run and follow it exactly.
 4. Before any generation call, say what you will generate and roughly how long it takes, and wait for an OK.
 
@@ -40,9 +40,11 @@ Skills are invoked by their bare slug, such as `brainstorm-game`. There is no `s
 | make me a game from scratch | `make-game` |
 | add a [character / enemy / NPC / prop / vehicle] | `asset-strategy` |
 | add a sound for [event] | `sound-effect` |
+| make me a [sound / track / voice line / image / model], no game yet | `sound-effect`, `music-track`, `voice-line`, `concept-art`, `prop-model` (no project needed) |
 | add ambient music | `music-track` |
 | make me fire / smoke / lightning / muzzle flash / magic glow / hit spark / dissolve / water ripple | `vfx-fire`, `vfx-smoke`, `vfx-lightning`, `vfx-muzzle-flash`, `vfx-magic-glow`, `vfx-hit-spark`, `vfx-dissolve`, `vfx-water-ripple` |
 | build the FPS controller | `fps-controller` |
+| build or change a scene, level, HUD or layout in several steps | `scene-scripting` (3 or more scene edits: one `summer_run_script` with `scenePath`) |
 | debug / the game crashes when [X] / broken behavior / cloud or Codex failure / send this to support | `debug` (support-report mode first: call `summer_create_debug_report` when available and tell the user where the Markdown report was written; keep fixing only if they also asked for a fix) |
 | add an animation to [character] | `generate-motion` |
 | wire up a state machine for [character] | `animation-tree` |

package/dist/cli/banner.js

@@ -1,3 +1,4 @@
+import { useColor } from "../core/format.js";
 export function getBanner(version) {
     const reset = "\x1b[0m";
     // Vertical gradient for SUMMER ENGINE
@@ -29,5 +30,7 @@ export function getBanner(version) {
         "      ███████╗██║ ╚████║╚██████╔╝██║██║ ╚████║███████╗       ",
         "      ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝╚═╝  ╚═══╝╚══════╝       ",
     ];
+    if (!useColor())
+        return headerLines.join("\n");
     return headerLines.map((line, i) => `${colors[i]}${line}${reset}`).join("\n");
 }

package/dist/cli/commands/login.d.ts

@@ -1,5 +1,32 @@
 import { Command } from "commander";
 export declare const loginCommand: Command;
+/** How long `summer login` waits for the store's Allow click after the account sign-in. */
+export declare const STORE_STEP_TIMEOUT_MS: number;
+export interface LoginCommandDependencies {
+    hasAuthToken: () => Promise<boolean>;
+    hasStoreSignIn: () => Promise<boolean>;
+    login: () => Promise<void>;
+    storeLogin: (options: {
+        newClient: boolean;
+        timeoutMs?: number;
+    }) => Promise<unknown>;
+    log: (message: string) => void;
+}
+/**
+ * One `summer login`, one browser: the Summer account sign-in (the CLI token
+ * for the engine, generation and asset tools), then right away the store
+ * sign-in (an OAuth grant for the hosted Summer Engine MCP: store,
+ * publishing, board, Grow). The browser is signed in by then, so the second
+ * step is one Allow click, or none when this machine was approved before.
+ * The two are separate credentials on the server, so a failed store step
+ * keeps the account sign-in and says how to finish later.
+ *
+ * --store: only the store step (as before). --no-store: only the account.
+ */
+export declare function runLoginCommand(opts: {
+    store?: boolean;
+    force?: boolean;
+}, overrides?: Partial<LoginCommandDependencies>): Promise<void>;
 export interface LoginDependencies {
     fetch: typeof fetch;
     openUrl: (url: string) => Promise<unknown>;

package/dist/cli/commands/login.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { randomUUID } from "crypto";
 import open from "open";
 import { getAuthToken, saveLoginSession, } from "../../core/auth.js";
+import { summerRequestHeaders } from "../../core/agent-host.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readStoredOAuthToken, runStoreLogin } from "../../core/oauth.js";
 const POLL_INTERVAL_MS = 2000;
@@ -13,27 +14,71 @@ const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 900000;
 const HEARTBEAT_MS = 30000;
 export const loginCommand = new Command("login")
-    .description("Sign in to Summer Engine via your browser")
-    .option("--store", "Sign in to the Summer store so agents can upload builds (summer_publish_build)")
+    .description("Sign in to Summer in your browser: your Summer account, then the store, publishing and Grow tools in the same browser")
+    .option("--store", "Only the store sign-in (summer_publish_build, the store, publishing, board and Grow tools); plain summer login does it too")
+    .option("--no-store", "Only the Summer account sign-in; skip the store sign-in")
     .option("--force", "Force re-authentication even if already logged in")
     .action(async (opts) => {
-    if (opts.store) {
-        if ((await readStoredOAuthToken()) && !opts.force) {
-            console.log("Already signed in to the Summer store. Use --store --force to sign in again.");
+    await runLoginCommand(opts);
+});
+/** How long `summer login` waits for the store's Allow click after the account sign-in. */
+export const STORE_STEP_TIMEOUT_MS = 3 * 60_000;
+const defaultCommandDependencies = {
+    hasAuthToken: async () => Boolean(await getAuthToken()),
+    hasStoreSignIn: async () => Boolean(await readStoredOAuthToken()),
+    login: () => runLogin(),
+    storeLogin: ({ newClient, timeoutMs }) => runStoreLogin({ fetch, now: Date.now, openUrl: open, log: console.log, newClient, ...(timeoutMs ? { timeoutMs } : {}) }),
+    log: console.log,
+};
+/**
+ * One `summer login`, one browser: the Summer account sign-in (the CLI token
+ * for the engine, generation and asset tools), then right away the store
+ * sign-in (an OAuth grant for the hosted Summer Engine MCP: store,
+ * publishing, board, Grow). The browser is signed in by then, so the second
+ * step is one Allow click, or none when this machine was approved before.
+ * The two are separate credentials on the server, so a failed store step
+ * keeps the account sign-in and says how to finish later.
+ *
+ * --store: only the store step (as before). --no-store: only the account.
+ */
+export async function runLoginCommand(opts, overrides = {}) {
+    const deps = { ...defaultCommandDependencies, ...overrides };
+    const force = Boolean(opts.force);
+    if (opts.store === true) {
+        if ((await deps.hasStoreSignIn()) && !force) {
+            deps.log("Already signed in to the Summer store. Use --store --force to sign in again.");
             return;
         }
         // --force also registers a new client, the way back if this machine's was removed.
-        await runStoreLogin({ fetch, now: Date.now, openUrl: open, log: console.log, newClient: Boolean(opts.force) });
-        console.log("Signed in to the Summer store. Your core Summer login was not changed.");
+        await deps.storeLogin({ newClient: force });
+        deps.log("Signed in to the Summer store. Your core Summer login was not changed.");
         return;
     }
-    const existing = await getAuthToken();
-    if (existing && !opts.force) {
-        console.log("Already logged in. Use --force to re-authenticate.");
+    const signedIn = (await deps.hasAuthToken()) && !force;
+    const storeNeeded = opts.store !== false && (force || !(await deps.hasStoreSignIn()));
+    if (signedIn) {
+        deps.log(storeNeeded
+            ? "Already logged in to Summer. Connecting the store, publishing and Grow tools next."
+            : "Already logged in. Use --force to re-authenticate.");
+    }
+    else {
+        await deps.login();
+        deps.log("Signed-in MCP sessions report each tool call to Summer (tool name, success, duration, agent app name); SUMMER_NO_TELEMETRY=1 turns that off.");
+    }
+    if (!storeNeeded)
         return;
+    deps.log("");
+    deps.log("Next, the store, publishing and Grow tools: approve Summer CLI in the same browser.");
+    try {
+        await deps.storeLogin({ newClient: false, timeoutMs: STORE_STEP_TIMEOUT_MS });
+        deps.log("Signed in to the Summer store too. One sign-in covers every Summer tool on this machine.");
     }
-    await runLogin();
-});
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        deps.log(`The store sign-in did not finish: ${reason}`);
+        deps.log('Your Summer login is saved. To add the store, publishing and Grow tools later, run "summer login --store".');
+    }
+}
 /** The gateway answered with a terminal 4xx — retrying the same URL cannot help. */
 class LoginRejectedError extends Error {
 }
@@ -80,6 +125,7 @@ export async function runLogin(overrides = {}) {
         let completed = null;
         try {
             const res = await deps.fetch(pollUrl, {
+                headers: summerRequestHeaders({ surface: "cli" }),
                 signal: AbortSignal.timeout(5000),
             });
             if (!res.ok) {

package/dist/cli/commands/ops.d.ts

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import { type HostedCall } from "../../core/ops/cloud.js";
+import { type Answer } from "../../core/ops/contract.js";
+import { FileSaver } from "../../core/ops/save-files.js";
+import { dispatchTool } from "../../core/capabilities/tool-dispatch.js";
+/**
+ * The CLI view of the operation catalog (on by default; SUMMER_SURFACE=v3 leaves it out):
+ *
+ *   summer <area> <action> [--<field> <value> ...] [--input '<json>'] [--dry-run] [--idempotency-key <k>] [--wait] [--json]
+ *   summer whoami
+ *   summer ops search <words...> | summer ops describe <op>
+ *
+ * Engine and local operations run in this process (the same functions
+ * `summer tool` runs); cloud operations run on the hosted Summer server
+ * through its summer_call, with the person's sign-in.
+ */
+/** Areas with operations today; CLI command words stay out of this list. */
+export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+};
+export interface ParsedCall {
+    input: Record<string, unknown>;
+    json: boolean;
+    dryRun: boolean;
+    wait: boolean;
+    idempotencyKey?: string;
+}
+/** `--max-items 3 --tag a --tag b --no-loop` -> `{ maxItems: 3, tag: ["a", "b"], loop: false }`, typed by the schema. */
+export declare function parseCallFlags(argv: readonly string[], schema: JsonSchema | null): ParsedCall;
+export interface OpsCliDeps {
+    hosted: HostedCall;
+    dispatch: typeof dispatchTool;
+    print: (text: string) => void;
+    printError: (text: string) => void;
+    /** Saves generated files (`--out`, else the project's asset folder). Default: a new FileSaver per run. */
+    files?: FileSaver;
+}
+export declare const defaultOpsCliDeps: OpsCliDeps;
+/** The answer for a person; `out` is the --out to keep in the printed wait command. */
+export declare function formatAnswer(answer: Answer, out?: string): string;
+/** Run one operation from the command line and print its answer; returns the exit code. */
+export declare function runOpFromCli(op: string, argv: readonly string[], deps?: OpsCliDeps): Promise<number>;
+export declare function opsCliCommands(): Command[];
+export {};

package/dist/cli/commands/ops.js

@@ -0,0 +1,301 @@
+import { Command } from "commander";
+import { localEntries, localInputSchema, localWireForm, missingInput } from "../../core/ops/catalog.js";
+import { answerOfHosted, callHostedV4, hostedCallFailure, searchEverywhere } from "../../core/ops/cloud.js";
+import { errorAnswer, isLocalOp, localToolsFor, opFromCli, OP_NAME } from "../../core/ops/contract.js";
+import { ENGINE_SPLIT_OPS, engineOpDef, splitToolArgs } from "../../core/ops/engine.js";
+import { engineFailure, engineNotRunning } from "../../core/ops/engine-answer.js";
+import { loadLibraryIndex } from "../../core/library-search.js";
+import { FileSaver, withOutField } from "../../core/ops/save-files.js";
+import { dispatchTool, EngineUnavailableError, ToolResultError } from "../../core/capabilities/tool-dispatch.js";
+/**
+ * The CLI view of the operation catalog (on by default; SUMMER_SURFACE=v3 leaves it out):
+ *
+ *   summer <area> <action> [--<field> <value> ...] [--input '<json>'] [--dry-run] [--idempotency-key <k>] [--wait] [--json]
+ *   summer whoami
+ *   summer ops search <words...> | summer ops describe <op>
+ *
+ * Engine and local operations run in this process (the same functions
+ * `summer tool` runs); cloud operations run on the hosted Summer server
+ * through its summer_call, with the person's sign-in.
+ */
+/** Areas with operations today; CLI command words stay out of this list. */
+export const CLI_AREAS = [
+    "team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing",
+    "analytics", "experiments", "marketing", "players", "economy", "inbox", "apps", "studio", "chats", "stories",
+    "plugins", "engine", "account",
+];
+const RESERVED_FLAGS = new Set(["json", "dry-run", "wait", "idempotency-key", "input"]);
+const camel = (flag) => flag.replace(/-([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+/** A flag's field: camelCase (`--scene-path` is scenePath), or snake_case when the schema names it so (`--look-at` is look_at). */
+function fieldName(flag, schema) {
+    const snake = flag.replace(/-/g, "_");
+    return snake !== flag && schema?.properties?.[snake] && !schema.properties[camel(flag)] ? snake : camel(flag);
+}
+function coerce(value, schema) {
+    const type = Array.isArray(schema?.type) ? schema?.type[0] : schema?.type;
+    if (value === true)
+        return true;
+    if (type === "number" || type === "integer")
+        return Number(value);
+    if (type === "boolean")
+        return value === "true";
+    if (type === "string")
+        return value;
+    if (type === "object" || type === "array") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return type === "array" ? value.split(",") : value;
+        }
+    }
+    return /^(-?\d+(\.\d+)?|true|false)$/.test(value) ? JSON.parse(value) : value;
+}
+/** `--max-items 3 --tag a --tag b --no-loop` -> `{ maxItems: 3, tag: ["a", "b"], loop: false }`, typed by the schema. */
+export function parseCallFlags(argv, schema) {
+    const out = { input: {}, json: false, dryRun: false, wait: false };
+    const fields = {};
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index];
+        if (!token.startsWith("--"))
+            throw new Error(`Unexpected argument "${token}". Pass fields as --name value.`);
+        const [rawName, inline] = token.slice(2).split(/=(.*)/s, 2);
+        if (rawName === "json")
+            out.json = true;
+        else if (rawName === "dry-run")
+            out.dryRun = true;
+        else if (rawName === "wait")
+            out.wait = true;
+        else if (rawName === "idempotency-key" || rawName === "input") {
+            const value = inline ?? argv[++index];
+            if (value === undefined)
+                throw new Error(`--${rawName} needs a value.`);
+            if (rawName === "input") {
+                const parsed = JSON.parse(value);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    throw new Error("--input must be a JSON object.");
+                Object.assign(out.input, parsed);
+            }
+            else
+                out.idempotencyKey = value;
+        }
+        else if (rawName.startsWith("no-") && !RESERVED_FLAGS.has(rawName)) {
+            fields[fieldName(rawName.slice(3), schema)] = false;
+        }
+        else {
+            const name = fieldName(rawName, schema);
+            const next = argv[index + 1];
+            const value = inline ?? (next !== undefined && !next.startsWith("--") ? (index++, next) : true);
+            const property = schema?.properties?.[name];
+            const typed = property?.type === "array" ? coerce(value, property.items) : coerce(value, property);
+            if (property?.type === "array")
+                fields[name] = [...(fields[name] ?? []), ...(Array.isArray(typed) ? typed : [typed])];
+            else
+                fields[name] = name in fields ? [...[fields[name]].flat(), typed] : typed;
+        }
+    }
+    out.input = { ...out.input, ...fields };
+    return out;
+}
+export const defaultOpsCliDeps = {
+    hosted: (name, args) => callHostedV4(name, args),
+    dispatch: dispatchTool,
+    print: (text) => process.stdout.write(`${text}\n`),
+    printError: (text) => process.stderr.write(`${text}\n`),
+};
+/** The docs.read id of a local tool's guide (tool/<slug>). */
+function guideOf(toolName) {
+    const entry = loadLibraryIndex().find((candidate) => candidate.kind === "tool" && candidate.mcp_tool_name === toolName);
+    return entry?.id;
+}
+async function runLocal(op, call, deps) {
+    // A split operation runs its 3.x tool with the action fixed (core/ops/engine.ts).
+    const split = ENGINE_SPLIT_OPS[op];
+    const entry = localEntries().find((candidate) => candidate.name === op);
+    const tool = split?.tool ?? entry?.mcpTool ?? localToolsFor(op)[0];
+    if (!tool)
+        return errorAnswer("not_found", `No operation is named "${op}".`, { next: { op: "ops.search", input: { query: op } } });
+    const args = split ? splitToolArgs(split, call.input) : call.input;
+    const def = engineOpDef(op);
+    const guide = guideOf(tool);
+    const describe = guide && def ? { op: "docs.read", input: { id: guide } } : { op: "ops.describe", input: { name: op } };
+    const missing = missingInput(localInputSchema(op), call.input);
+    if (missing)
+        return errorAnswer("invalid_input", missing, { next: describe });
+    if (call.dryRun) {
+        return { ok: true, status: "dry_run", preview: { summary: `${entry?.title ?? op}: the input is valid. Nothing was done.`, changes: [], approval: entry?.approval ?? "none", estimate: null, valid: true } };
+    }
+    try {
+        return { ok: true, status: "done", result: await deps.dispatch(tool, args) };
+    }
+    catch (error) {
+        if (error instanceof EngineUnavailableError)
+            return engineNotRunning();
+        if (error instanceof ToolResultError) {
+            return def ? engineFailure(JSON.stringify(error.result), op, { effect: def.effect, guide }) : errorAnswer("invalid_input", error.message, { details: { tool: error.result } });
+        }
+        return errorAnswer("invalid_input", error instanceof Error ? error.message : String(error), { next: describe });
+    }
+}
+async function runCloud(op, call, deps) {
+    try {
+        return answerOfHosted(await deps.hosted("summer_call", { op, input: call.input, ...(call.dryRun ? { dryRun: true } : {}), ...(call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}) }));
+    }
+    catch (error) {
+        return hostedCallFailure(error, { op, dryRun: call.dryRun, idempotencyKey: call.idempotencyKey });
+    }
+}
+/** The input schema used to type flags: the local descriptor, or the hosted ops.describe. */
+async function schemaFor(op, deps) {
+    if (isLocalOp(op))
+        return localInputSchema(op);
+    const answer = await runCloud("ops.describe", { input: { name: op }, json: true, dryRun: false, wait: false }, deps);
+    const input = answer.ok && answer.status === "done" ? answer.result.operation?.input : undefined;
+    return input ? withOutField(op, input) : null;
+}
+/** Failed waits the job itself does not cause: the call to Summer did not get through. */
+const WAIT_DID_NOT_GET_THROUGH = new Set(["unavailable", "outcome_unknown", "not_signed_in", "forbidden", "rate_limited"]);
+/** Follow a running job or an approval until it ends (jobs.wait, at most 50 s per call). */
+async function waitFor(answer, deps) {
+    let current = answer;
+    if (current.ok && current.status === "needs_approval")
+        deps.printError(`Waiting for approval: ${current.approval.url}`);
+    for (let round = 0; round < 120 && current.ok && (current.status === "running" || current.status === "needs_approval"); round++) {
+        const job = current.job.id;
+        const waited = await runCloud("jobs.wait", { input: { jobId: job, timeoutSeconds: 50 }, json: true, dryRun: false, wait: false }, deps);
+        // The job runs on whatever the wait answered: a failed wait names it, so the job is waited on, not started again.
+        // One that did not get through says to wait again; any other keeps its own next step (sign in, slow down).
+        if (!waited.ok && WAIT_DID_NOT_GET_THROUGH.has(waited.error.code)) {
+            const { code, message, retry, next, details } = waited.error;
+            return errorAnswer(code, `${message} Job ${job} is still on Summer's server.`, {
+                retry,
+                next: code === "unavailable" ? { op: "jobs.wait", input: { jobId: job } } : next,
+                details: { ...details, job },
+            });
+        }
+        if (!waited.ok || waited.status !== "done")
+            return waited;
+        const result = waited.result;
+        if (!result.finished)
+            continue;
+        // An approved generation runs on as its own job: follow that job.
+        const chained = result.job.result;
+        if (result.job.state === "done" && chained?.status === "running" && chained.job?.id) {
+            current = { ok: true, status: "running", job: chained.job };
+            continue;
+        }
+        if (result.job.state === "done")
+            return { ok: true, status: "done", result: result.job.result ?? {} };
+        return errorAnswer(result.job.state === "failed" ? "invalid_input" : "conflict", result.job.error?.message ?? `The job ended: ${result.job.state}.`, { details: { job } });
+    }
+    return current;
+}
+/** A value as one shell word: single quotes, so the shell expands nothing in it. */
+const shellWord = (value) => (/^[\w./:@+=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`);
+/** The answer for a person; `out` is the --out to keep in the printed wait command. */
+export function formatAnswer(answer, out) {
+    const waitFlags = (id) => `summer jobs wait --job-id ${id}${out ? ` --out ${shellWord(out)}` : ""}`;
+    if (!answer.ok) {
+        const next = answer.error.next;
+        const step = !next ? "" : "op" in next ? `\nNext: ${next.op}` : "url" in next ? `\nNext: ${next.label}: ${next.url}` : `\nNext: ${next.say}`;
+        return `Error (${answer.error.code}): ${answer.error.message}${step}`;
+    }
+    switch (answer.status) {
+        case "done":
+            return JSON.stringify(answer.result, null, 2);
+        case "running":
+            return `Started: job ${answer.job.id}. Wait for it: ${waitFlags(answer.job.id)}`;
+        case "needs_approval":
+            return `Needs approval (${answer.approval.who}): ${answer.approval.summary}\n${answer.approval.url}\nNothing changes until they approve. Follow it: ${waitFlags(answer.job.id)}`;
+        case "dry_run":
+            return `Dry run: ${String(answer.preview.summary ?? "")}\n${JSON.stringify(answer.preview, null, 2)}`;
+    }
+}
+/** Run one operation from the command line and print its answer; returns the exit code. */
+export async function runOpFromCli(op, argv, deps = defaultOpsCliDeps) {
+    if (!OP_NAME.test(op)) {
+        deps.printError(formatAnswer(errorAnswer("invalid_input", `"${op}" is not an operation name (area action).`, { next: { op: "ops.search" } })));
+        return 1;
+    }
+    let call;
+    try {
+        const hasFields = argv.some((token) => token.startsWith("--") && !RESERVED_FLAGS.has(token.slice(2).split("=")[0]));
+        call = parseCallFlags(argv, hasFields ? await schemaFor(op, deps) : null);
+    }
+    catch (error) {
+        deps.printError(formatAnswer(errorAnswer("invalid_input", error instanceof Error ? error.message : String(error))));
+        return 1;
+    }
+    let answer;
+    let out;
+    if (isLocalOp(op)) {
+        answer = await runLocal(op, call, deps);
+        if (call.wait)
+            answer = await waitFor(answer, deps);
+    }
+    else {
+        // --out stays here: the files save on this machine once the answer (or the waited job) names them.
+        const files = deps.files ?? new FileSaver({ saveByDefault: true });
+        const taken = files.take(op, call.input);
+        out = taken.out;
+        answer = await runCloud(op, { ...call, input: taken.input }, deps);
+        if (call.wait)
+            answer = await waitFor(answer, deps);
+        answer = await files.finish(op, answer, out);
+    }
+    (answer.ok ? deps.print : deps.printError)(call.json ? JSON.stringify(answer) : formatAnswer(answer, out));
+    if (!call.json && answer.ok)
+        for (const warning of answer.warnings ?? [])
+            deps.printError(`Warning: ${warning}`);
+    return answer.ok ? 0 : 1;
+}
+function areaCommand(area) {
+    return new Command(area)
+        .description(`Summer ${area} operations: summer ${area} <action> --field value. Find them: summer ops search ${area}`)
+        .argument("<action>", "The operation's action, e.g. list or set-base")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .action(async (action, _options, command) => {
+        process.exitCode = await runOpFromCli(opFromCli(area, action), command.args.slice(1));
+    });
+}
+export function opsCliCommands() {
+    const whoami = new Command("whoami")
+        .description("Who is signed in, and their credits")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(async (_options, command) => {
+        process.exitCode = await runOpFromCli("whoami", command.args);
+    });
+    const ops = new Command("ops").description("Find and describe Summer operations");
+    ops
+        .command("search <words...>")
+        .description("Find operations by describing the job in plain words")
+        .option("--area <area>", "Only this area")
+        .option("--limit <n>", "Most results", "8")
+        .option("--json", "Print the answer as JSON")
+        .action(async (wordsArg, options) => {
+        const { items, warning } = await searchEverywhere(wordsArg.join(" "), { area: options.area, limit: Number(options.limit) || 8 }, defaultOpsCliDeps.hosted);
+        if (options.json) {
+            defaultOpsCliDeps.print(JSON.stringify({ ok: true, status: "done", result: { items }, ...(warning ? { warnings: [warning] } : {}) }));
+            return;
+        }
+        for (const item of items)
+            defaultOpsCliDeps.print(`${item.name.padEnd(32)} ${item.effect.padEnd(13)} ${item.title}`);
+        if (warning)
+            defaultOpsCliDeps.printError(warning);
+    });
+    ops
+        .command("describe <op>")
+        .description("Show one operation with its exact input")
+        .action(async (op) => {
+        const local = localWireForm(op);
+        if (local) {
+            defaultOpsCliDeps.print(JSON.stringify(local, null, 2));
+            return;
+        }
+        process.exitCode = await runOpFromCli("ops.describe", ["--name", op]);
+    });
+    return [whoami, ops, ...CLI_AREAS.map(areaCommand)];
+}

package/dist/cli/commands/setup.d.ts

@@ -1,2 +1,4 @@
 import { Command } from "commander";
 export declare const setupCommand: Command;
+/** One line instead of a row per three skills: the first few names and how many more. `--json` keeps the full list. */
+export declare function skillNamesSample(names: readonly string[], max?: number): string;