@bitmagic/cli 0.1.14 → 0.1.16

package/README.md

@@ -18,6 +18,7 @@ bitmagic --version
 bitmagic login             # device-code auth in your browser
 bitmagic init my-game      # scaffold a new project into ./my-game
 cd my-game
+bitmagic cover              # generate cover art from GAME-DESIGN.md
 bitmagic check              # typecheck against the vendored engine
 bitmagic dev                 # build, then serve with live rebuilds
 bitmagic verify              # boot the game in a real browser and report what broke
@@ -31,7 +32,7 @@ bitmagic publish              # verify-gate, build, and ship — private by defa
 | `bitmagic login [--env <env>]` | Device-code auth against Auth0; stores credentials per environment. |
 | `bitmagic logout [--env <env>]` | Remove stored credentials for an environment. |
 | `bitmagic whoami [--env <env>]` | Show the identity the CLI is authenticated as. |
-| `bitmagic init [dir] [--template <id>] [--name <name>] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md` and templates. |
+| `bitmagic init [dir] [--template <id>] [--name <name>] [--idea "<pitch>"] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md`, `GAME-DESIGN.md` and templates. `--idea` seeds the design doc's pitch. |
 | `bitmagic check` | Typecheck (`tsc --noEmit`) against the vendored engine. Fast; does not prove the game runs. |
 | `bitmagic dev [--port <port>]` | Build, then serve with `tsc --watch` + `vite`, default port 3010. |
 | `bitmagic verify [--timeout <ms>]` | Build, boot the game in a headless browser, click the engine's Play button like a player would, and report what broke. A game without the button passes as long as gameplay starts by itself (auto-starting genres, custom start UIs); a run where gameplay never starts fails. `--timeout` is settle time in ms measured after gameplay starts, so the screenshot captures gameplay. Writes the artifacts the publish gate reads (see below). |
@@ -39,6 +40,7 @@ bitmagic publish              # verify-gate, build, and ship — private by defa
 | `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force]` | Verify-gate, build if needed, and upload straight to GCS. **Private unless `--visibility public` is passed.** |
 | `bitmagic upgrade [--engine <version>] [--force]` | Refresh vendored platform files to the currently published engine. Refuses a dirty git tree unless `--force`. |
 | `bitmagic generate <skybox\|sound\|image\|character\|animation> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. |
+| `bitmagic cover [--prompt "..."] [--force] [--no-start-screen]` | Generate the game's cover art from `GAME-DESIGN.md`: sets the start screen, saves `.bitmagic/cover.webp`, becomes the publish thumbnail. Costs sparks. |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Slow and expensive; supports `--resume`. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
@@ -56,16 +58,35 @@ my-game/
   src/work/          # your game — Game.ts, game.json, world.json
   engine/             # vendored engine, read-only, replaced wholesale by `bitmagic upgrade`
   AGENTS.md            # guidance for the agent editing this project
+  GAME-DESIGN.md        # what the game is — yours to write; bitmagic cover reads it
   .bitmagic/
+    cover.webp           # bitmagic cover's artwork — the publish thumbnail when present
+    cover.json            # its URL and the design hash it was generated from
     build/
-      index.html        # bitmagic build's output bundle
-      manifest.json      # engineVersion, fingerprint, bytes, sha256, builtAt
+      index.html            # bitmagic build's output bundle
+      manifest.json          # engineVersion, fingerprint, bytes, sha256, builtAt
     verify/
-      result.json         # bitmagic verify's verdict — ok, failures, warnings, fingerprint, at
-      screenshot.png        # becomes the publish thumbnail
-      console.log            # captured browser console output
+      result.json              # bitmagic verify's verdict — ok, failures, warnings, fingerprint, at
+      screenshot.png            # the publish thumbnail when there is no cover art
+      console.log                # captured browser console output
 ```
 
+## Cover art
+
+`bitmagic cover` generates the game's cover from `GAME-DESIGN.md` — the same artwork the web
+Creator's Planning Mode produces, from the same style direction. It sets `hud.startScreen.imageUrl`
+so the image appears in the game itself, saves `.bitmagic/cover.webp`, and hands that to
+`bitmagic publish` as the portal thumbnail.
+
+Run it **early** — right after the design doc says what the game is, before implementing it. The
+first build takes a while, and the cover is what there is to look at meanwhile. In iTerm2, WezTerm
+and Konsole it is drawn straight into the terminal; everywhere else the path and URL are printed
+and `.bitmagic/cover.webp` is there to open (`BITMAGIC_NO_INLINE_IMAGE=1` turns the drawing off).
+
+Re-running on an unchanged design generates nothing and costs nothing — it reports the existing
+cover. Edit the design and run again, or pass `--force`, to replace it. Because it writes
+`world.json`, it invalidates a passing verify: run it before `bitmagic verify`, not after.
+
 ## Publishing
 
 `bitmagic publish` is two gated steps in one command:
@@ -76,7 +97,8 @@ my-game/
    record stale immediately, while an unmodified project stays fresh no matter how much time has
    passed. There is no way to check freshness except running `bitmagic verify` again.
    `.git/`, `node_modules/`, `dist/`, `.bitmagic/` and `.vite-cache/` are excluded, so committing
-   between `bitmagic verify` and `bitmagic publish` does **not** invalidate the verify.
+   between `bitmagic verify` and `bitmagic publish` does **not** invalidate the verify. Neither
+   does editing `GAME-DESIGN.md`, which no build step reads.
 2. **The build.** If the project has changed since the last `.bitmagic/build/manifest.json`,
    publish rebuilds automatically; a prior manual `bitmagic build` is never required, only useful
    if you want to inspect `.bitmagic/build/index.html` before it ships.
@@ -89,9 +111,9 @@ service, so a previously-public game re-published bare is gone from bitmagic.ai
 publicly again.
 
 `--force` overrides a **stale or failed** verify verdict. It does **not** override a missing
-verify record — publish's thumbnail comes from the verify screenshot, so `bitmagic verify` must
-have produced at least one `.bitmagic/verify/screenshot.png`, ever, before `--force` has anything
-to work with.
+verify record — a project with no cover art has only the verify screenshot to publish a thumbnail
+from, so `bitmagic verify` must have produced at least one `.bitmagic/verify/screenshot.png`, ever,
+before `--force` has anything to work with.
 
 `--name` and `--description` apply to that one publish call only. They are never written back to
 `src/work/game.json`, so pass them again on every future `bitmagic publish` if you want them to
@@ -134,7 +156,7 @@ dependencies too.
 
 ## Machine-readable output
 
-`build`, `verify` and `publish` accept `--json`:
+Every command accepts `--json` except `dev`, which starts a server and never terminates with a result to report:
 
 - **stdout** carries exactly one JSON document — the result, or on failure
   `{ "ok": false, "exitCode": N, "error": "..." }`
@@ -145,6 +167,10 @@ parses one stream whether the command succeeded or not. The exit code remains au
 
 Without `--json` nothing changes: prose goes to stdout as before and no JSON is emitted.
 
+The result shape is per-command — `publish` reports `url`/`visibility`/`publishVersion`, `init`
+reports `gameId`/`root`/`dependenciesInstalled`, `upgrade` reports `replaced` and any
+`missingDependencies` as structured entries rather than only as a printed install command.
+
 ## Staying current
 
 Two nudges, both advisory — nothing is ever blocked because something is out of date.

package/dist/cli.d.ts

@@ -13,18 +13,30 @@ declare const rawCommands: {
             readonly type: "string";
             readonly description: "Environment to log in to (dev, prod, local).";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
     logout: CommandDef<{
         readonly env: {
             readonly type: "string";
             readonly description: "Environment to log out of (dev, prod, local).";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
     whoami: CommandDef<{
         readonly env: {
             readonly type: "string";
             readonly description: "Environment to query (dev, prod, local).";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
     init: CommandDef<{
         readonly dir: {
@@ -40,6 +52,10 @@ declare const rawCommands: {
             readonly type: "string";
             readonly description: "Game name.";
         };
+        readonly idea: {
+            readonly type: "string";
+            readonly description: "One-line pitch, seeded into GAME-DESIGN.md. Optional — you can write it yourself.";
+        };
         readonly env: {
             readonly type: "string";
             readonly description: "Environment (dev, prod, local).";
@@ -48,6 +64,10 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Scaffold into a non-empty directory.";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
     upgrade: CommandDef<{
         readonly engine: {
@@ -58,8 +78,17 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Upgrade even with uncommitted changes in the working tree.";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
+    }>;
+    check: CommandDef<{
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
-    check: CommandDef<ArgsDef>;
     dev: CommandDef<{
         readonly port: {
             readonly type: "string";
@@ -83,6 +112,28 @@ declare const rawCommands: {
         };
     }>;
     generate: CommandDef<ArgsDef>;
+    cover: CommandDef<{
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Describe the game for this call only, instead of reading GAME-DESIGN.md. Never written to the file.";
+        };
+        readonly force: {
+            readonly type: "boolean";
+            readonly description: "Generate a new cover even when the design has not changed since the last one.";
+        };
+        readonly 'start-screen': {
+            readonly type: "boolean";
+            readonly negativeDescription: "Leave hud.startScreen.imageUrl alone — still saves the cover and uses it as the publish thumbnail.";
+        };
+        readonly 'reference-image-url': {
+            readonly type: "string";
+            readonly description: "Style/composition reference image URL forwarded to the image model.";
+        };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
+    }>;
     forge: CommandDef<{
         readonly prompt: {
             readonly type: "string";
@@ -112,6 +163,10 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Build a custom place (arena, fortress, camp).";
         };
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+        };
     }>;
     publish: CommandDef<{
         readonly visibility: {

package/dist/cli.js

@@ -11,6 +11,7 @@ import { devCommand } from './commands/dev.js';
 import { verifyCommand } from './commands/verify.js';
 import { buildCommand } from './commands/build.js';
 import { generateCommand } from './commands/generate.js';
+import { coverCommand } from './commands/cover.js';
 import { forgeCommand } from './commands/forge.js';
 import { publishCommand } from './commands/publish.js';
 // citty's runMain() catches every error thrown from a command's `run()` internally and calls
@@ -88,7 +89,7 @@ export function isWrappedWithCleanErrors(command) {
     if (!subs)
         return false;
     const entries = Object.values(subs);
-    return entries.length > 0 && entries.every((sub) => isWrappedWithCleanErrors(sub));
+    return entries.length > 0 && entries.every(isWrappedWithCleanErrors);
 }
 // Wrapping happens once here, over the whole map, rather than per-entry at each call site —
 // a future command added to `rawCommands` is wrapped automatically, so there is no per-command
@@ -104,6 +105,7 @@ const rawCommands = {
     verify: verifyCommand,
     build: buildCommand,
     generate: generateCommand,
+    cover: coverCommand,
     forge: forgeCommand,
     publish: publishCommand,
 };

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/check.d.ts

@@ -1 +1,6 @@
-export declare const checkCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const checkCommand: import("citty").CommandDef<{
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+    };
+}>;

package/dist/commands/check.js

@@ -2,9 +2,17 @@ import { defineCommand } from 'citty';
 import { spawnSync } from 'child_process';
 import { CliError } from '../errors.js';
 import { loadProjectContext, projectBin } from '../project/context.js';
+import { createOutput } from '../output.js';
 export const checkCommand = defineCommand({
     meta: { name: 'check', description: 'Type-check the game against the vendored engine.' },
-    run() {
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Print the result as JSON on stdout; all progress goes to stderr.',
+        },
+    },
+    run({ args }) {
+        const output = createOutput(args.json === true);
         const context = loadProjectContext();
         const tsc = projectBin(context.root, 'tsc');
         // stdio inherit: tsc's own diagnostics are what the creator (or their agent) needs to read.
@@ -16,7 +24,11 @@ export const checkCommand = defineCommand({
             // tsc already printed the diagnostics; add nothing but the exit code.
             throw new CliError('Type check failed.', result.status ?? 1);
         }
-        console.log('Type check passed.');
+        output.info('Type check passed.');
+        // tsc's own diagnostics went straight to the inherited stdio, so a --json run's stdout is
+        // clean only on SUCCESS. A failure throws above and the wrapper emits the error document —
+        // interleaved with whatever tsc printed, which is documented rather than pretended away.
+        output.result({ ok: true, root: context.root });
     },
 });
 //# sourceMappingURL=check.js.map

package/dist/commands/check.js.map

@@ -1 +1 @@
-{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;IACxC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,kDAAkD,EAAE;IACxF,GAAG;QACD,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,4FAA4F;QAC5F,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACrF,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,IAAI,QAAQ,CAAC,0CAA0C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,sEAAsE;YACtE,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACpC,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;IACxC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,kDAAkD,EAAE;IACxF,IAAI,EAAE;QACJ,IAAI,EAAE;YACJ,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,kEAAkE;SAChF;KACF;IACD,GAAG,CAAC,EAAE,IAAI,EAAE;QACV,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,4FAA4F;QAC5F,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACrF,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,IAAI,QAAQ,CAAC,0CAA0C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,sEAAsE;YACtE,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAClC,0FAA0F;QAC1F,2FAA2F;QAC3F,yFAAyF;QACzF,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/cover.d.ts

@@ -0,0 +1,100 @@
+import { Buffer } from 'buffer';
+import { type WorldPatch } from '@bitmagic/asset-core';
+import type { GenerationOutcome } from '../generate/stream.js';
+import { type GenerateRunDeps } from './generate.js';
+/** The design document `bitmagic init` scaffolds and the coding agent maintains. */
+export declare const GAME_DESIGN_FILE = "GAME-DESIGN.md";
+export declare function coverImagePath(root: string): string;
+export interface CoverRecord {
+    /** The public image URL, as written into world.json. */
+    url: string;
+    /** Hash of the design text this cover was drawn from — see `readCoverRecord`. */
+    designHash: string;
+    generatedAt: string;
+}
+/**
+ * Identifies the design text a cover was generated from, so a repeat `bitmagic cover` on an
+ * unchanged design can decline to spend sparks on the same picture twice. This is the local
+ * equivalent of `PLAN_COVER_CACHE` in game-play-agent's PromptToGameController, which does the
+ * same for Planning Mode, keyed the same way — on the design text rather than the game.
+ */
+export declare function hashDesign(designText: string): string;
+export declare function readCoverRecord(root: string): CoverRecord | null;
+/**
+ * The prose the cover is drawn from: `--prompt` when given, otherwise GAME-DESIGN.md.
+ *
+ * `--prompt` is a one-call override and is never written to the file — the design document belongs
+ * to the creator, and a flag silently rewriting it would be a surprise the next `bitmagic cover`
+ * inherits.
+ *
+ * The error path matters as much as the happy one: projects scaffolded before GAME-DESIGN.md
+ * existed have no such file, and an agent that only sees "not found" cannot tell whether it should
+ * create one or has run the command in the wrong place. So the message says both what to write and
+ * what to run instead.
+ */
+export declare function resolveDesignText(options: {
+    promptFlag?: string | undefined;
+    root: string;
+    readFile?: (file: string) => string;
+}): string;
+/**
+ * The generated image's URL, read back out of the patch the image generator returned.
+ *
+ * The generator's terminal frame carries only `{ success, message, patches }` — the URL is not a
+ * separate field on the wire — so the patch it upserts into `assets[]` is where it lives. Matched
+ * on the patch's own shape rather than on the message text, which is prose and not a contract.
+ */
+export declare function coverUrlFromPatches(patches: WorldPatch[]): string | null;
+/**
+ * The patch that puts the cover behind the game's start screen.
+ *
+ * `set`, NOT `setRoot`: `set` addresses a path inside `worldProfileData`, which is where the
+ * engine's GameRuntimeController reads `hud.startScreen.imageUrl` from. A root-level write would
+ * land somewhere nothing ever looks and report success — the exact trap apply-patches.ts documents.
+ */
+export declare function startScreenPatch(url: string): WorldPatch;
+export interface CoverArgs {
+    prompt?: string;
+    force?: boolean;
+    'reference-image-url'?: string;
+    /** citty's negative form of the boolean flag: `--no-start-screen` arrives here as `false`. */
+    'start-screen'?: boolean;
+    json?: boolean;
+}
+export interface CoverRunDeps extends GenerateRunDeps {
+    /**
+     * Seam over `runAssetGeneration`, so a test can drive this without a network or a token.
+     *
+     * Deliberately narrower than `runAssetGeneration`'s own signature: it omits that function's
+     * `json` parameter, because this command always passes `false` there. Under `--json` stdout must
+     * carry exactly one document, and this command emits its own.
+     */
+    generate: (type: string, label: string, body: Record<string, unknown>, json: boolean, deps: GenerateRunDeps) => Promise<GenerationOutcome>;
+    /** Returns whether the terminal actually drew the image. */
+    renderImage: (bytes: Buffer) => boolean;
+    /** The machine-readable result, emitted only under `--json`. */
+    result: (value: unknown) => void;
+}
+export declare function runCover(args: CoverArgs, deps?: CoverRunDeps): Promise<void>;
+export declare const coverCommand: import("citty").CommandDef<{
+    readonly prompt: {
+        readonly type: "string";
+        readonly description: "Describe the game for this call only, instead of reading GAME-DESIGN.md. Never written to the file.";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Generate a new cover even when the design has not changed since the last one.";
+    };
+    readonly 'start-screen': {
+        readonly type: "boolean";
+        readonly negativeDescription: "Leave hud.startScreen.imageUrl alone — still saves the cover and uses it as the publish thumbnail.";
+    };
+    readonly 'reference-image-url': {
+        readonly type: "string";
+        readonly description: "Style/composition reference image URL forwarded to the image model.";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
+    };
+}>;