@bitmagic/cli 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,140 @@
+# @bitmagic/cli
+
+Build Bitmagic games from your own agent tool (Claude Code, Codex, OpenCode, ...) instead of the
+web Creator UI. `bitmagic init` scaffolds a project with the engine vendored in as source, your
+agent edits `src/work/`, and `bitmagic verify` / `bitmagic publish` take it to bitmagic.ai — no
+web project or per-session pod required.
+
+## Install
+
+```bash
+npm install -g @bitmagic/cli
+bitmagic --version
+```
+
+## Quick start
+
+```bash
+bitmagic login             # device-code auth in your browser
+bitmagic init my-game      # scaffold a new project into ./my-game
+cd my-game
+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
+bitmagic publish              # verify-gate, build, and ship — private by default
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `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 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, and report what broke. Writes the artifacts the publish gate reads (see below). |
+| `bitmagic build` | Bundle the game into one self-contained `.bitmagic/build/index.html`. Rarely needs to be run by hand — `publish` builds automatically when the project changed. |
+| `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 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
+distinction is useful to an automated caller, a specific exit code — see **Exit codes** below.
+
+## Environments
+
+`--env` accepts `dev`, `prod`, or `local`. The environment used at `login` becomes the stored
+default for subsequent commands until you log in to a different one.
+
+## Project layout and artifacts
+
+```
+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
+  .bitmagic/
+    build/
+      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
+```
+
+## Publishing
+
+`bitmagic publish` is two gated steps in one command:
+
+1. **The verify gate.** Publish refuses to run unless `.bitmagic/verify/result.json` records a
+   passing run of the **current** project state. "Current" is decided by a content fingerprint —
+   a hash of your project's files — not a timestamp: editing any file after verifying makes the
+   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.
+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.
+
+**Publishing does not make a game public.** Every `bitmagic publish` uploads and registers the
+game, but by default `visibility` is `private` — reachable by URL, not listed anywhere on
+bitmagic.ai. You must pass `--visibility public` explicitly, every time you want the game listed;
+omitting it on a later publish makes it private again — and takes the game's `/play/` page out of
+service, so a previously-public game re-published bare is gone from bitmagic.ai until you publish
+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.
+
+`--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
+stick — and note that writing them into `game.json` yourself would change the fingerprint and
+invalidate the verify you just checked.
+
+### Exit codes
+
+`bitmagic publish` uses these to let a script or agent branch without parsing the message:
+
+| Code | Meaning |
+|---|---|
+| 1 | Build failed |
+| 2 | Not logged in |
+| 3 | Verify missing, stale, or failed |
+| 4 | Engine below the publish floor |
+| 5 | Not the game's owner, or the account/game is banned |
+| 6 | Upload or finalize failed — usually transient (network/storage), but also covers permanent failures such as an unknown game or a rejected request. Retry once; if it fails identically, stop and report it. |
+
+`bitmagic build` alone exits 1 on a build failure and 0 on success.
+
+## Upgrading
+
+`bitmagic upgrade` refreshes the vendored `engine/`, the generated config files, and `index.html`
+to the currently published engine version. It never touches `src/`, `world.json`, `game.json`,
+`package.json`, or the agent guidance files (`AGENTS.md`, `CLAUDE.md`, `.claude/skills/`) — those
+are yours. It refuses to run against a dirty git working tree unless `--force`, so the upgrade
+always shows up as its own reviewable diff.
+
+`upgrade` **reports** missing or outdated dependencies rather than installing them — it prints the
+exact install command to run, using your project's own package manager (detected from
+`pnpm-lock.yaml` / `yarn.lock`, defaulting to npm). A project scaffolded before a dependency was
+added needs that command run once before `bitmagic build` (and therefore `bitmagic publish`) will
+work.
+
+A project scaffolded before `vite.publish.config.js` existed cannot be bundled at all: `bitmagic
+build` stops with a message naming `bitmagic upgrade`, which vendors the file without touching
+your game code. Run the printed install command afterwards if `upgrade` reports missing
+dependencies too.
+
+## Development
+
+```bash
+pnpm run check    # lint + typecheck (from cli/, or from the repo root for every project)
+pnpm test          # jest
+```

package/dist/auth/session.js

@@ -6,7 +6,7 @@ const EXPIRY_SKEW_MS = 60_000;
 export async function getAccessToken(environment, clientId, deps, baseDir = defaultBaseDir()) {
     const stored = readCredentials(environment.name, baseDir);
     if (!stored) {
-        throw new CliError(`You are not logged in to the "${environment.name}" environment. Run \`bitmagic login\`.`);
+        throw new CliError(`You are not logged in to the "${environment.name}" environment. Run \`bitmagic login\`.`, 2);
     }
     const now = deps.now ?? Date.now;
     if (stored.expiresAt - EXPIRY_SKEW_MS > now()) {

package/dist/auth/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAuB,MAAM,kBAAkB,CAAC;AAE3E,oEAAoE;AACpE,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAwB,EACxB,QAAgB,EAChB,IAAoB,EACpB,UAAkB,cAAc,EAAE;IAElC,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,QAAQ,CAChB,iCAAiC,WAAW,CAAC,IAAI,wCAAwC,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,IAAI,MAAM,CAAC,SAAS,GAAG,cAAc,GAAG,GAAG,EAAE,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC7F,gBAAgB,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,SAAS,CAAC,WAAW,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAuB,MAAM,kBAAkB,CAAC;AAE3E,oEAAoE;AACpE,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAwB,EACxB,QAAgB,EAChB,IAAoB,EACpB,UAAkB,cAAc,EAAE;IAElC,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,QAAQ,CAChB,iCAAiC,WAAW,CAAC,IAAI,wCAAwC,EACzF,CAAC,CACF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,IAAI,MAAM,CAAC,SAAS,GAAG,cAAc,GAAG,GAAG,EAAE,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC7F,gBAAgB,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,SAAS,CAAC,WAAW,CAAC;AAC/B,CAAC"}

package/dist/cli.d.ts

@@ -49,6 +49,16 @@ declare const rawCommands: {
             readonly description: "Scaffold into a non-empty directory.";
         };
     }>;
+    upgrade: CommandDef<{
+        readonly engine: {
+            readonly type: "string";
+            readonly description: "Engine version to upgrade to (must be the currently published one).";
+        };
+        readonly force: {
+            readonly type: "boolean";
+            readonly description: "Upgrade even with uncommitted changes in the working tree.";
+        };
+    }>;
     check: CommandDef<ArgsDef>;
     dev: CommandDef<{
         readonly port: {
@@ -62,6 +72,7 @@ declare const rawCommands: {
             readonly description: "Settle time in ms (default 15000).";
         };
     }>;
+    build: CommandDef<ArgsDef>;
     generate: CommandDef<ArgsDef>;
     forge: CommandDef<{
         readonly prompt: {
@@ -93,6 +104,24 @@ declare const rawCommands: {
             readonly description: "Build a custom place (arena, fortress, camp).";
         };
     }>;
+    publish: CommandDef<{
+        readonly visibility: {
+            readonly type: "string";
+            readonly description: "\"public\" or \"private\" (default). Public also requires an unbanned profile.";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Override the published name for this publish only — never written to game.json.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Override the published description for this publish only — never written to game.json.";
+        };
+        readonly force: {
+            readonly type: "boolean";
+            readonly description: "Publish despite a stale or failed verify. Does NOT bypass a missing verify record.";
+        };
+    }>;
 };
 type CommandName = keyof typeof rawCommands;
 export declare const subCommands: Record<CommandName, CommandDef<ArgsDef>>;

package/dist/cli.js

@@ -4,11 +4,14 @@ import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { initCommand } from './commands/init.js';
+import { upgradeCommand } from './commands/upgrade.js';
 import { checkCommand } from './commands/check.js';
 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 { 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
 // process.exit() itself — it never rejects the promise it returns, so the `.catch()` below
 // never runs for those. For anything that isn't citty's own internal CLIError class, its catch
@@ -87,11 +90,14 @@ const rawCommands = {
     logout: logoutCommand,
     whoami: whoamiCommand,
     init: initCommand,
+    upgrade: upgradeCommand,
     check: checkCommand,
     dev: devCommand,
     verify: verifyCommand,
+    build: buildCommand,
     generate: generateCommand,
     forge: forgeCommand,
+    publish: publishCommand,
 };
 export const subCommands = Object.fromEntries(Object.entries(rawCommands).map(([name, command]) => [name, withCleanErrors(command)]));
 // This module only builds `main` and exports it (along with `subCommands` and `withCleanErrors`)

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":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,6FAA6F;AAC7F,2FAA2F;AAC3F,+FAA+F;AAC/F,gGAAgG;AAChG,8FAA8F;AAC9F,4EAA4E;AAE5E,gGAAgG;AAChG,+FAA+F;AAC/F,iFAAiF;AACjF,MAAM,WAAW,GAAG,IAAI,OAAO,EAAU,CAAC;AAE1C;;;;;GAKG;AACH,SAAS,aAAa,CACpB,OAAsB;IAEtB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC;IACjC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,OAAO,IAA2C,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,eAAe,CAAoB,OAAsB;IACvE,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAChC,MAAM,OAAO,GAAkB,EAAE,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,CAAC,GAAG,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE;YAC9B,IAAI,CAAC;gBACH,OAAO,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;oBAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBAC7B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC/B,CAAC;gBACD,uFAAuF;gBACvF,2EAA2E;gBAC3E,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC;QACF,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,8FAA8F;IAC9F,+FAA+F;IAC/F,+FAA+F;IAC/F,8FAA8F;IAC9F,yFAAyF;IACzF,aAAa;IACb,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAA4B;IACnE,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,4FAA4F;AAC5F,+FAA+F;AAC/F,+DAA+D;AAC/D,MAAM,WAAW,GAAG;IAClB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;IACvB,KAAK,EAAE,YAAY;IACnB,GAAG,EAAE,UAAU;IACf,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,cAAc;CACxB,CAAC;AAIF,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAC1C,MAAM,CAAC,OAAO,CAAC,WAAW,CAA+C,CAAC,GAAG,CAC5E,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CACtD,CAC0C,CAAC;AAE9C,iGAAiG;AACjG,8FAA8F;AAC9F,uFAAuF;AACvF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,IAAI,GAAG,aAAa,CAAC;IAChC,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,gDAAgD;KAC9D;IACD,WAAW;CACZ,CAAC,CAAC"}

package/dist/commands/build.d.ts

@@ -0,0 +1 @@
+export declare const buildCommand: import("citty").CommandDef<import("citty").ArgsDef>;

package/dist/commands/build.js

@@ -0,0 +1,16 @@
+import { defineCommand } from 'citty';
+import { loadProjectContext } from '../project/context.js';
+import { runBuild } from '../publish/bundle.js';
+export const buildCommand = defineCommand({
+    meta: {
+        name: 'build',
+        description: 'Bundle the game for publishing into .bitmagic/build/index.html.',
+    },
+    async run() {
+        const context = loadProjectContext();
+        console.log('Building…');
+        const manifest = runBuild(context.root, context.metadata.engineVersion);
+        console.log(`Bundle ready: .bitmagic/build/index.html (${manifest.bytes} bytes)`);
+    },
+});
+//# sourceMappingURL=build.js.map

package/dist/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;IACxC,IAAI,EAAE;QACJ,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,iEAAiE;KAC/E;IACD,KAAK,CAAC,GAAG;QACP,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzB,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,6CAA6C,QAAQ,CAAC,KAAK,SAAS,CAAC,CAAC;IACpF,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/publish.d.ts

@@ -0,0 +1,44 @@
+import { type BuildManifest } from '../publish/bundle.js';
+/** `'public' | 'private'`, defaulting to private — a typo is rejected rather than silently
+ *  coerced, matching the server's own asymmetric contract (see cli-publish.ts). */
+export declare function resolveVisibility(raw: string | undefined): 'public' | 'private';
+export interface PublishRunDeps {
+    fetch: typeof globalThis.fetch;
+    sleep: (ms: number) => Promise<void>;
+    /** Test-only override; production omits it and loadProjectContext walks up from process.cwd(). */
+    startDir?: string;
+    /** Test-only override; production omits it and the credential helpers read ~/.bitmagic. */
+    baseDir?: string;
+    log: (message: string) => void;
+    /** Injectable so a test can assert reuse-vs-rebuild without a real tsc/vite toolchain. */
+    runBuild: (root: string, engineVersion: string) => BuildManifest;
+    readBuildManifest: (root: string) => BuildManifest | null;
+}
+export interface PublishArgs {
+    visibility?: string;
+    name?: string;
+    description?: string;
+    force?: boolean;
+}
+/**
+ * The whole command. See the file header for why the order below cannot be reshuffled.
+ */
+export declare function runPublish(args: PublishArgs, deps?: PublishRunDeps): Promise<void>;
+export declare const publishCommand: import("citty").CommandDef<{
+    readonly visibility: {
+        readonly type: "string";
+        readonly description: "\"public\" or \"private\" (default). Public also requires an unbanned profile.";
+    };
+    readonly name: {
+        readonly type: "string";
+        readonly description: "Override the published name for this publish only — never written to game.json.";
+    };
+    readonly description: {
+        readonly type: "string";
+        readonly description: "Override the published description for this publish only — never written to game.json.";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Publish despite a stale or failed verify. Does NOT bypass a missing verify record.";
+    };
+}>;

package/dist/commands/publish.js

@@ -0,0 +1,202 @@
+/**
+ * `bitmagic publish` — build, verify-gate, and ship one self-contained bundle straight to GCS.
+ *
+ * Two-phase, matching api-server's split (see `api-server/src/cli/cli-publish.ts`):
+ *
+ *   1. `POST /api/cli/v1/publish/begin` authorizes the publish, allocates a version, mints a
+ *      signed PUT URL, and issues the exact meta-tag block the bundle must carry.
+ *   2. This process PUTs the bundle straight to GCS — the multi-MB HTML never passes through
+ *      api-server.
+ *   3. `POST /api/cli/v1/publish/complete` verifies what actually landed and writes the row.
+ *
+ * The order below is load-bearing, not incidental:
+ *
+ *   - The verify gate runs BEFORE the build, because a stale or failing verify means there is
+ *     nothing worth building yet, and `bitmagic build` on top of a broken game just wastes time.
+ *   - The thumbnail — the verify screenshot, uploaded through the same signed-upload lane
+ *     `forge/upload-proxy.ts` bridges for the browser — is uploaded BEFORE `begin`, because
+ *     `begin` needs its public URL to render the meta block.
+ *   - The bundle is PUT to GCS BEFORE `complete`, because `complete` range-reads the object to
+ *     confirm it carries the meta block `begin` issued — there is nothing to confirm yet.
+ *
+ * `--force` overrides the verdict and staleness `checkVerifyGate` checks, never the existence of
+ * a record: the thumbnail comes from the verify screenshot, so with no verify there is nothing to
+ * publish a thumbnail from. `--name`/`--description` are sent on the wire for THIS publish only —
+ * they are never written back into the project's own `game.json`, which would change the
+ * fingerprint and invalidate the very verify this command just checked.
+ */
+import { defineCommand } from 'citty';
+import { Buffer } from 'buffer';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { loadProjectContext } from '../project/context.js';
+import { resolveEnvironment, resolveAuth0ClientId } from '../config/environments.js';
+import { readDefaultEnvironment } from '../config/credentials.js';
+import { getAccessToken } from '../auth/session.js';
+import { computeFingerprint } from '../publish/fingerprint.js';
+import { readVerifyRecord } from '../verify/result.js';
+import { checkVerifyGate, injectMetaBlock } from '../publish/meta-block.js';
+import { runBuild as runBuildImpl, readBuildManifest as readBuildManifestImpl, buildBundlePaths, } from '../publish/bundle.js';
+import { beginPublish, completePublish, putBundle, requestThumbnailUploadUrl, putThumbnail, } from '../publish/client.js';
+/** Where `bitmagic verify` writes its record and screenshot — see `commands/verify.ts`. */
+function verifyArtifactDir(root) {
+    return path.join(root, '.bitmagic', 'verify');
+}
+/** `'public' | 'private'`, defaulting to private — a typo is rejected rather than silently
+ *  coerced, matching the server's own asymmetric contract (see cli-publish.ts). */
+export function resolveVisibility(raw) {
+    if (raw === undefined)
+        return 'private';
+    if (raw === 'public' || raw === 'private')
+        return raw;
+    throw new CliError(`--visibility must be "public" or "private", got ${JSON.stringify(raw)}.`);
+}
+function defaultDeps() {
+    return {
+        fetch: globalThis.fetch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        log: (message) => console.log(message),
+        runBuild: runBuildImpl,
+        readBuildManifest: readBuildManifestImpl,
+    };
+}
+/**
+ * Upload the last verify run's screenshot as this publish's thumbnail, and return its public URL.
+ *
+ * There is no other source: this lane has no image generator of its own, and the verify gate
+ * above already guarantees a record exists — which is what the screenshot alongside it is for.
+ */
+async function uploadThumbnail(context, environment, token, apiDeps) {
+    const screenshotPath = path.join(verifyArtifactDir(context.root), 'screenshot.png');
+    let bytes;
+    try {
+        bytes = fs.readFileSync(screenshotPath);
+    }
+    catch {
+        // Exit 3, not 6: the record passed the verify gate above, but there is nothing to publish a
+        // thumbnail FROM — the same remedy as every other exit-3 case ("run bitmagic verify"), not an
+        // upload failure.
+        throw new CliError(`No verify screenshot found at ${screenshotPath}. Run \`bitmagic verify\` before publishing.`, 3);
+    }
+    const contentType = 'image/png';
+    const signed = await requestThumbnailUploadUrl(environment, token, { gameId: context.metadata.gameId, filename: 'thumbnail.png', contentType }, apiDeps);
+    await putThumbnail(signed, bytes, contentType, apiDeps);
+    return signed.publicUrl;
+}
+/**
+ * The whole command. See the file header for why the order below cannot be reshuffled.
+ */
+export async function runPublish(args, deps = defaultDeps()) {
+    const visibility = resolveVisibility(args.visibility);
+    const force = args.force === true;
+    const context = loadProjectContext(deps.startDir);
+    const fingerprint = computeFingerprint(context.root);
+    const gate = checkVerifyGate(readVerifyRecord(verifyArtifactDir(context.root)), fingerprint, force);
+    if (!gate.ok)
+        throw new CliError(gate.message, 3);
+    // Reuse: same inputs, same bundle — skip the rebuild. `manifest.bytes`/`manifest.sha256`
+    // themselves are never read past this point: what's actually PUT and what `complete` validates
+    // is the bundle AFTER the meta block is injected below, which this pre-injection manifest
+    // cannot describe either way.
+    const existing = deps.readBuildManifest(context.root);
+    if (existing?.fingerprint !== fingerprint) {
+        deps.runBuild(context.root, context.metadata.engineVersion);
+    }
+    const environment = resolveEnvironment({ storedDefault: readDefaultEnvironment(deps.baseDir) });
+    const clientId = resolveAuth0ClientId(environment);
+    const token = await getAccessToken(environment, clientId, { fetch: deps.fetch, sleep: deps.sleep }, deps.baseDir);
+    const apiDeps = { fetch: deps.fetch };
+    const thumbnailUrl = await uploadThumbnail(context, environment, token, apiDeps);
+    // No bundleBytes/sha256 sent here — see BeginPublishRequest's doc comment in publish/client.ts.
+    // The only honest number for those fields is the size/hash of the bundle AFTER the meta block
+    // below is injected, and that block (and the publishVersion inside it) isn't known until THIS
+    // call returns.
+    const begun = await beginPublish(environment, token, {
+        gameId: context.metadata.gameId,
+        visibility,
+        ...(args.name !== undefined ? { name: args.name } : {}),
+        ...(args.description !== undefined ? { description: args.description } : {}),
+        engineVersion: context.metadata.engineVersion,
+        thumbnailUrl,
+    }, apiDeps);
+    const htmlPath = buildBundlePaths(context.root).htmlPath;
+    let builtHtml;
+    try {
+        builtHtml = fs.readFileSync(htmlPath, 'utf-8');
+    }
+    catch {
+        // A reused build's manifest can outlive its own bundle file (e.g. `.bitmagic/build/` cleaned
+        // by hand) — report that plainly rather than letting the raw filesystem error (ENOENT, with
+        // its own stack) escape uncaught past citty's clean-error wrapper.
+        throw new CliError(`The built bundle at ${htmlPath} is missing. Run \`bitmagic build\` again, then publish.`, 1);
+    }
+    // Computed from the INJECTED bundle, not `manifest.bytes`/`manifest.sha256` — those describe
+    // the bundle BEFORE the meta block below is added, and `complete` (cli-publish.ts) 409s the
+    // instant `bundleBytes` doesn't match what's actually sitting in GCS: the object it heads is the
+    // injected one. Sending the pre-injection numbers would 409 every single publish.
+    const publishedHtml = injectMetaBlock(builtHtml, begun.metaBlock);
+    const publishedBytes = Buffer.byteLength(publishedHtml, 'utf-8');
+    const publishedSha256 = createHash('sha256').update(publishedHtml, 'utf-8').digest('hex');
+    // The PUT must send `Cache-Control: no-cache` — `begin` binds that header into the signed
+    // URL's signature (so the published entry HTML is never served stale), and GCS rejects a
+    // signed PUT whose headers don't match what was signed. Omitting it does not produce a stale
+    // cache — it produces a 403 on upload. `cli-uploads.ts` established the same pattern.
+    await putBundle(begun.signedUrl, publishedHtml, begun.cacheControl, apiDeps);
+    // `visibility`, `name`, `description`, and `thumbnailUrl` are all re-sent, not implied.
+    // `complete` re-authorizes against its OWN body — `begin` writes nothing, so nothing it
+    // validated is bound — and an absent visibility defaults to private. Omitting them here would
+    // make `--visibility public` pass the ban gate at `begin` and then silently publish as
+    // private, would overwrite a stored name with a default, and (for thumbnailUrl specifically)
+    // would make `complete`'s own meta-block recomputation diverge from what `begin` actually
+    // rendered — see `CompletePublishRequest`'s doc comment in publish/client.ts.
+    const done = await completePublish(environment, token, {
+        gameId: context.metadata.gameId,
+        key: begun.key,
+        publishVersion: begun.publishVersion,
+        visibility,
+        ...(args.name !== undefined ? { name: args.name } : {}),
+        ...(args.description !== undefined ? { description: args.description } : {}),
+        thumbnailUrl,
+        bundleBytes: publishedBytes,
+        sha256: publishedSha256,
+        // The spec's audit trail: engineVersion + fingerprint + sha256, recorded together against
+        // the publish that actually landed. See CompletePublishRequest's doc comment for why these
+        // are declarative (logged, never verified) and why engineVersion here is not a second gate.
+        engineVersion: context.metadata.engineVersion,
+        fingerprint,
+    }, apiDeps);
+    deps.log(`Published ${done.visibility}: ${done.url}`);
+    if (done.visibility === 'private') {
+        deps.log('Not listed. Publish with --visibility public when you are ready.');
+    }
+}
+export const publishCommand = defineCommand({
+    meta: {
+        name: 'publish',
+        description: 'Build, verify-gate, and publish the game — private unless --visibility public.',
+    },
+    args: {
+        visibility: {
+            type: 'string',
+            description: '"public" or "private" (default). Public also requires an unbanned profile.',
+        },
+        name: {
+            type: 'string',
+            description: 'Override the published name for this publish only — never written to game.json.',
+        },
+        description: {
+            type: 'string',
+            description: 'Override the published description for this publish only — never written to game.json.',
+        },
+        force: {
+            type: 'boolean',
+            description: 'Publish despite a stale or failed verify. Does NOT bypass a missing verify record.',
+        },
+    },
+    async run({ args }) {
+        await runPublish(args);
+    },
+});
+//# sourceMappingURL=publish.js.map

package/dist/commands/publish.js.map

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

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,36 @@
+export interface GitStatus {
+    dirty: boolean;
+}
+/**
+ * The boundary that makes `upgrade` safe to run at all: the whole value of the command is that a
+ * creator can read what it changed as a git diff. Overwriting vendored files on top of already
+ * -uncommitted work mixes the two together and makes that diff unreadable, so a dirty tree is
+ * refused unless the creator opts in with --force. Kept as a pure function, separate from the
+ * git call that produces `status`, so it is reachable from a test with no real repo involved.
+ */
+export declare function assertCleanTree(status: GitStatus, force: boolean): void;
+/**
+ * The other half of "package.json is never rewritten": upgradeProject leaves it untouched even
+ * when the vendored engine now needs a dependency it doesn't have (e.g. vite-plugin-singlefile,
+ * which every pre-Task-3 project's package.json predates) — silently doing nothing here would
+ * mean `upgrade` reports success while `bitmagic build` still fails later with an opaque
+ * module-resolution error. Prints the exact install command instead; never writes the file.
+ *
+ * The command names the project's OWN package manager (`detectPackageManager`), not a hardcoded
+ * npm: a creator on pnpm who runs the printed `npm install` gets a tree npm linked and a second,
+ * far less obvious failure on the next build.
+ *
+ * Exported for its test — the detection helpers can be unit-tested on their own, but only
+ * calling this proves the printed line actually uses them.
+ */
+export declare function printDependencyReport(root: string): void;
+export declare const upgradeCommand: import("citty").CommandDef<{
+    readonly engine: {
+        readonly type: "string";
+        readonly description: "Engine version to upgrade to (must be the currently published one).";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Upgrade even with uncommitted changes in the working tree.";
+    };
+}>;