@bitmagic/cli 0.1.1 → 0.1.2

package/dist/forge/browser-host.d.ts

@@ -0,0 +1,100 @@
+import type { ForgeTransport } from '@bitmagic/world-forger/pipeline/transport-types.js';
+import { type ForgePageTransportOptions } from './transport.js';
+export interface ForgeBrowserHostOptions {
+    /** Port of the project's own vite dev server. */
+    gamePort: number;
+    gameId: string;
+    /** The project's `src/work/world.json`, parsed — see {@link readProjectGameData}. */
+    gameData: Record<string, unknown>;
+    /**
+     * Base URL the engine reads back as `window.AI_AGENT_URL` (`engine/agentUrl.ts`). In this lane
+     * that must be **api-server**, not game-play-agent: the engine's uploads go to
+     * `POST /api/cli/v1/uploads/signed-url`, which api-server serves.
+     */
+    agentUrl: string;
+    log?: (message: string) => void;
+    gameLoadedTimeoutMs?: number;
+    /** Passed through to the transport (retry gap). Exposed for tests. */
+    transportOptions?: ForgePageTransportOptions;
+}
+/**
+ * The page URL. `source=creator` is not cosmetic — see precondition 1 in the file header.
+ */
+export declare function forgePageUrl(gamePort: number, gameId: string): string;
+/**
+ * Chromium flags for a forge run. Split out so the two rules that matter are testable without a
+ * browser: web security is always off (presigned PUTs from localhost), and software GL is added
+ * only where there is no GPU — CI, or an explicit opt-in for a headless dev box.
+ */
+export declare function forgeLaunchArgs(env: Record<string, string | undefined>): string[];
+/**
+ * The game data `LOAD_GAME` carries. There is no `/api/get-game-config` in this lane — the CLI
+ * project owns its game on disk.
+ *
+ * It takes BOTH of the project's `work/` JSON files, because `GameEngine.loadGame` reads from
+ * both: `gameData.worldProfileData` comes from world.json (GameEngine.ts:1431) and
+ * `gameData.gameGenre` from game.json (:1432). Passing world.json alone leaves the engine with no
+ * genre, and it refuses to load. This mirrors the web lane, where `session-file-manager.ts` keeps
+ * `<genre>-game.json` and `<genre>-world.json` as separate templates and the engine is handed the
+ * combination.
+ *
+ * `gameGenre` must be the GenreLoader REGISTRY name — `Voxel`, not `voxel`. `GenreLoader`'s map is
+ * keyed by it (`GenreLoader.ts:43-46`), and an unmatched key logs "Unknown genre" and returns null,
+ * which surfaces as `Failed to load genre "..."`. game.json already carries the registry-cased
+ * value, which is exactly why it is read rather than derived from `bitmagic.json`'s lowercase
+ * `genre` (that one names the genre DIRECTORY).
+ *
+ * `gameId` is forced from `bitmagic.json` and wins over both files. A scaffolded project's
+ * work-copy JSON is taken from a template and still carries the TEMPLATE's id — a game this
+ * creator does not own. Everything else in a forge already keys off `bitmagic.json` (the design
+ * request, the ownership check), so leaving the template's id in the game data splits one run
+ * across two games; and the engine uses `currentGameData.gameId` as the storage-key prefix when it
+ * asks for a signed upload URL, so every `.vxl`/`.vwld` PUT would be scoped to the wrong game and
+ * refused by `assertOwnsGame`.
+ */
+export declare function readProjectGameData(root: string, metadata: {
+    gameId: string;
+}): Record<string, unknown>;
+export declare class ForgeBrowserHost {
+    private readonly options;
+    private readonly log;
+    private readonly listeners;
+    private readonly pageBridge;
+    private readonly forgeTransport;
+    private context;
+    private page;
+    private userDataDir;
+    constructor(options: ForgeBrowserHostOptions);
+    /**
+     * The pipeline's `ForgeDeps.transport`. Available before `loadGame()` only so the caller can
+     * build its deps in one place; using it earlier fails as a transport failure (null), because
+     * `postCommand` below refuses without a page.
+     */
+    get transport(): ForgeTransport;
+    /**
+     * Subscribe to every message the page posts, returning an unsubscribe.
+     *
+     * Exists for PROGRESS REPORTING, which the transport deliberately does not do: its
+     * `progressType` option only re-arms an idle timer, so the 20-minute level bake would otherwise
+     * run to completion without printing a single line and a creator would conclude it had hung and
+     * kill it mid-bake. The command subscribes here and prints the bake's own
+     * `VOXELIZE_GLB_AS_LEVEL_PROGRESS` chunk counts.
+     */
+    onPageMessage(listener: (message: Record<string, unknown>) => void): () => void;
+    private buildBridge;
+    private dispatch;
+    launch(): Promise<void>;
+    /**
+     * Open the game page and complete the `LOAD_GAME` → `GAME_LOADED` handshake. Every forge command
+     * sent before this resolves would be queued by the engine, not executed (precondition 2).
+     */
+    loadGame(): Promise<void>;
+    /**
+     * Wait for one handshake message. Unlike the transport's waits, these REJECT on timeout: a page
+     * that never boots or a game that never loads is not a "no answer" the caller can shrug off and
+     * retry — nothing downstream can run.
+     */
+    private waitForPageMessage;
+    closePage(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/forge/browser-host.js

@@ -0,0 +1,351 @@
+/**
+ * The CLI lane's browser host. Steps 3-5 of the world-forger pipeline (create archetypes, bake the
+ * voxel level, place instances) are not pure compute: they drive the game engine over
+ * `postMessage`, and the round trip through the engine is the only source of the instance ids
+ * step 5 persists. The web lane borrows the Creator's browser over a WebSocket relay; here the CLI
+ * owns a headless Chrome and posts into the page directly.
+ *
+ * Four preconditions, each of which fails SILENTLY if missed — they are the reason this file
+ * exists rather than a few lines inside the forge command:
+ *
+ *  1. `?source=creator` in the URL. Without it `safePostMessageToCreator`
+ *     (`game/src/engine/CreatorMode.ts:28-36`) returns without posting, every reply is discarded,
+ *     and the pipeline times out with no error logged anywhere.
+ *  2. `GAME_TEMPLATE_READY` → `LOAD_GAME` → `GAME_LOADED` must complete first, in that order. All
+ *     six forge message types are in the engine's `REQUIRES_GAME_LOADED` set
+ *     (`CreatorMessageHandler.ts:67`) and are queued, not run, before the handshake finishes — and
+ *     `LOAD_GAME` itself is DROPPED, not queued, if it is posted before the engine registers its
+ *     listener (see the long comment in `loadGame`).
+ *  3. `--disable-web-security`. The engine PUTs to presigned upload URLs from a `localhost`
+ *     origin; the CORS preflight refuses them otherwise. Chromium only accepts that flag on a
+ *     persistent context, which is why this is `launchPersistentContext` and why
+ *     `src/verify/browser.ts` (which uses `newContext`) cannot be reused.
+ *  4. A real GPU context. Without one, Three.js renders nothing and the engine's scene validation
+ *     bails — hence the SwiftShader flags on GPU-less machines.
+ *
+ * The page is top-level, so `window.parent === window` and the engine's `safePostMessageToCreator`
+ * posts to the page's own listener. That is the load-bearing reason this works with no creator
+ * frame at all: our injected listener sees exactly what the Creator would have seen.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { chromium } from 'playwright-core';
+import { CliError } from '../errors.js';
+import { aliasSourceDir } from '../scaffold/aliases.js';
+import { createForgePageTransport, } from './transport.js';
+/** Name of the Node-side function the injected shim forwards page messages to. */
+const MESSAGE_BRIDGE = '__bitmagicOnGameMessage';
+/** The engine has to boot Rapier, load world.json and warm the scene before it answers. */
+const DEFAULT_GAME_LOADED_TIMEOUT_MS = 120_000;
+/**
+ * How long to wait for the engine to register its `message` listener. Much shorter than the
+ * GAME_LOADED budget: reaching this point only needs the bundle to parse and i18n to initialise,
+ * with no world, no physics and no assets involved. A separate budget AND a separate message keep
+ * "the page never booted" from being reported as "the world never loaded".
+ */
+const DEFAULT_TEMPLATE_READY_TIMEOUT_MS = 60_000;
+/**
+ * The page URL. `source=creator` is not cosmetic — see precondition 1 in the file header.
+ */
+export function forgePageUrl(gamePort, gameId) {
+    return `http://localhost:${gamePort}/?source=creator&gameId=${encodeURIComponent(gameId)}`;
+}
+/**
+ * Chromium flags for a forge run. Split out so the two rules that matter are testable without a
+ * browser: web security is always off (presigned PUTs from localhost), and software GL is added
+ * only where there is no GPU — CI, or an explicit opt-in for a headless dev box.
+ */
+export function forgeLaunchArgs(env) {
+    const args = ['--disable-web-security'];
+    if (env.CI === 'true' || env.BITMAGIC_BROWSER_SOFTWARE_GL === 'true') {
+        args.push('--enable-unsafe-swiftshader', '--use-gl=angle', '--use-angle=swiftshader');
+    }
+    return args;
+}
+/** Read one of the project's `work/` JSON files, naming it in every failure. */
+function readWorkJson(root, name, why) {
+    // Via the alias model, not a hardcoded 'src/work': `scaffold/aliases.ts` is the one source of
+    // truth for where the creator's game lives, and `generate.ts` already resolves world.json the
+    // same way. Two hardcoded copies would drift the day the scaffold layout moves.
+    const file = path.join(root, aliasSourceDir('work'), name);
+    if (!fs.existsSync(file)) {
+        throw new CliError(`No ${name} at ${file}. \`bitmagic forge\` ${why} — run this from inside a Bitmagic project.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        throw new CliError(`${file} is not valid JSON, so the game cannot be loaded.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CliError(`${file} does not contain an object.`);
+    }
+    return parsed;
+}
+/**
+ * The game data `LOAD_GAME` carries. There is no `/api/get-game-config` in this lane — the CLI
+ * project owns its game on disk.
+ *
+ * It takes BOTH of the project's `work/` JSON files, because `GameEngine.loadGame` reads from
+ * both: `gameData.worldProfileData` comes from world.json (GameEngine.ts:1431) and
+ * `gameData.gameGenre` from game.json (:1432). Passing world.json alone leaves the engine with no
+ * genre, and it refuses to load. This mirrors the web lane, where `session-file-manager.ts` keeps
+ * `<genre>-game.json` and `<genre>-world.json` as separate templates and the engine is handed the
+ * combination.
+ *
+ * `gameGenre` must be the GenreLoader REGISTRY name — `Voxel`, not `voxel`. `GenreLoader`'s map is
+ * keyed by it (`GenreLoader.ts:43-46`), and an unmatched key logs "Unknown genre" and returns null,
+ * which surfaces as `Failed to load genre "..."`. game.json already carries the registry-cased
+ * value, which is exactly why it is read rather than derived from `bitmagic.json`'s lowercase
+ * `genre` (that one names the genre DIRECTORY).
+ *
+ * `gameId` is forced from `bitmagic.json` and wins over both files. A scaffolded project's
+ * work-copy JSON is taken from a template and still carries the TEMPLATE's id — a game this
+ * creator does not own. Everything else in a forge already keys off `bitmagic.json` (the design
+ * request, the ownership check), so leaving the template's id in the game data splits one run
+ * across two games; and the engine uses `currentGameData.gameId` as the storage-key prefix when it
+ * asks for a signed upload URL, so every `.vxl`/`.vwld` PUT would be scoped to the wrong game and
+ * refused by `assertOwnsGame`.
+ */
+export function readProjectGameData(root, metadata) {
+    const game = readWorkJson(root, 'game.json', 'loads the project\'s own game.json into the game');
+    const world = readWorkJson(root, 'world.json', 'loads the project\'s own world.json into the game');
+    // world.json last: it owns worldProfileData/assets/environmentObjects. `gameId` is the only key
+    // the two files share, and it is overridden below regardless of which won.
+    return { ...game, ...world, gameId: metadata.gameId };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export class ForgeBrowserHost {
+    options;
+    log;
+    listeners = new Set();
+    pageBridge;
+    forgeTransport;
+    context = null;
+    page = null;
+    userDataDir = null;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+        // Built once and reused: `postCommand` reads `this.page` at call time, so the bridge survives
+        // the page being replaced by a later `loadGame()`, and the transport handed out by `transport`
+        // stays valid across it.
+        this.pageBridge = this.buildBridge();
+        this.forgeTransport = createForgePageTransport(this.pageBridge, {
+            log: this.log,
+            ...options.transportOptions,
+        });
+    }
+    /**
+     * The pipeline's `ForgeDeps.transport`. Available before `loadGame()` only so the caller can
+     * build its deps in one place; using it earlier fails as a transport failure (null), because
+     * `postCommand` below refuses without a page.
+     */
+    get transport() {
+        return this.forgeTransport;
+    }
+    /**
+     * Subscribe to every message the page posts, returning an unsubscribe.
+     *
+     * Exists for PROGRESS REPORTING, which the transport deliberately does not do: its
+     * `progressType` option only re-arms an idle timer, so the 20-minute level bake would otherwise
+     * run to completion without printing a single line and a creator would conclude it had hung and
+     * kill it mid-bake. The command subscribes here and prints the bake's own
+     * `VOXELIZE_GLB_AS_LEVEL_PROGRESS` chunk counts.
+     */
+    onPageMessage(listener) {
+        return this.pageBridge.onMessage(listener);
+    }
+    buildBridge() {
+        return {
+            postCommand: async (command) => {
+                const page = this.page;
+                if (!page)
+                    throw new Error('No game page is open — call loadGame() first.');
+                await page.evaluate((message) => {
+                    // Runs inside the browser, where `window` is a real global. The CLI's own eslint config
+                    // declares no DOM globals for the Node process it actually lints.
+                    // eslint-disable-next-line no-undef
+                    window.postMessage({ type: message.type, data: message.data }, '*');
+                }, command);
+            },
+            onMessage: (listener) => {
+                this.listeners.add(listener);
+                return () => this.listeners.delete(listener);
+            },
+        };
+    }
+    dispatch(message) {
+        if (!isRecord(message))
+            return;
+        for (const listener of [...this.listeners])
+            listener(message);
+    }
+    async launch() {
+        const args = forgeLaunchArgs(process.env);
+        this.userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bitmagic-forge-chrome-'));
+        try {
+            // `channel: 'chrome'` drives the creator's installed Chrome, the same choice `verify` makes
+            // so that installing the CLI stays a small npm install with no browser download.
+            this.context = await chromium.launchPersistentContext(this.userDataDir, {
+                headless: true,
+                channel: 'chrome',
+                args,
+                viewport: { width: 1280, height: 720 },
+                bypassCSP: true,
+            });
+        }
+        catch {
+            // Not a forge failure. Saying so plainly matters: an agent told "the forge failed" would
+            // start editing game code to fix a missing browser.
+            throw new CliError('Could not launch Google Chrome. `bitmagic forge` bakes the world in the Chrome ' +
+                'installed on this machine — install it from https://www.google.com/chrome/ and try again.');
+        }
+        this.log('Forge browser launched (headless Chrome).');
+    }
+    /**
+     * Open the game page and complete the `LOAD_GAME` → `GAME_LOADED` handshake. Every forge command
+     * sent before this resolves would be queued by the engine, not executed (precondition 2).
+     */
+    async loadGame() {
+        const context = this.context;
+        if (!context)
+            throw new CliError('ForgeBrowserHost.launch() must run before loadGame().');
+        await this.closePage();
+        const page = await context.newPage();
+        this.page = page;
+        // A silent renderer crash is otherwise indistinguishable from a slow bake.
+        page.on('pageerror', (error) => this.log(`[browser pageerror] ${error.message}`));
+        page.on('console', (message) => {
+            // Errors always. Everything else only under BITMAGIC_FORGE_VERBOSE, because the engine's
+            // handlers narrate themselves at console.log level and a bake is thousands of lines.
+            //
+            // That verbosity switch is not a convenience: several engine handlers bail with a plain
+            // `if (!ctx) return;` and post NO reply (see `validateSceneContext` in
+            // VoxelMessageHandlers.ts). From this side that is indistinguishable from a message that
+            // never arrived — the transport just waits out its idle timeout. When a step times out, the
+            // engine's own log line for that handler is the only evidence of which side went quiet.
+            if (message.type() === 'error') {
+                this.log(`[browser console error] ${message.text()}`);
+            }
+            else if (process.env.BITMAGIC_FORGE_VERBOSE === 'true') {
+                this.log(`[browser ${message.type()}] ${message.text()}`);
+            }
+        });
+        await page.exposeFunction(MESSAGE_BRIDGE, (message) => this.dispatch(message));
+        await page.addInitScript((bridgeName) => {
+            /* eslint-disable no-undef -- this callback body runs in the browser, not in the CLI's Node process. */
+            window.addEventListener('message', (event) => {
+                const forward = window[bridgeName];
+                // Looked up per message, not captured: exposeFunction installs it via its own init script,
+                // which may run after this one.
+                if (typeof forward === 'function')
+                    forward(event.data);
+            });
+            /* eslint-enable no-undef */
+        }, MESSAGE_BRIDGE);
+        const timeoutMs = this.options.gameLoadedTimeoutMs ?? DEFAULT_GAME_LOADED_TIMEOUT_MS;
+        // BOTH waits are subscribed before `goto`, because both signals can arrive during page load.
+        const templateReady = this.waitForPageMessage('GAME_TEMPLATE_READY', DEFAULT_TEMPLATE_READY_TIMEOUT_MS, `The game page never reported GAME_TEMPLATE_READY within ${DEFAULT_TEMPLATE_READY_TIMEOUT_MS}ms, ` +
+            'so it never finished booting. Run `bitmagic verify` to see what broke on startup.');
+        const gameLoaded = this.waitForPageMessage('GAME_LOADED', timeoutMs, `The game did not report GAME_LOADED within ${timeoutMs}ms. Nothing can be forged ` +
+            'until it loads — run `bitmagic verify` to see what broke on startup.');
+        // Swallow late rejections so an earlier throw on the navigation path below (e.g. `goto`
+        // timing out) cannot escape as an unhandledRejection with no handler attached yet.
+        templateReady.promise.catch(() => undefined);
+        gameLoaded.promise.catch(() => undefined);
+        const url = forgePageUrl(this.options.gamePort, this.options.gameId);
+        this.log(`Loading ${this.options.gameId} for forging: ${url}`);
+        try {
+            await page.goto(url, { waitUntil: 'domcontentloaded' });
+            // Wait for the engine to say it is listening before posting LOAD_GAME. `domcontentloaded` is
+            // NOT enough: the engine registers its `message` listener in `init()`
+            // (`game/src/engine/GameTemplate.ts:248`), which the module IIFE reaches only after
+            // `await initI18n()` — strictly later. `index.html` buffers nothing, and
+            // `CreatorMessageHandler`'s `pendingMessages` queue cannot help because it lives BEHIND the
+            // listener that does not exist yet, so a LOAD_GAME landing in that window is dropped
+            // outright and the only symptom is a GAME_LOADED timeout pointing at the wrong culprit.
+            // `GAME_TEMPLATE_READY` is posted on the line right after the listener is registered
+            // (:249) and is what the real Creator waits on
+            // (`creator/src/vue/composables/useIframeMessages.ts:1617`).
+            //
+            // `lab/browser.ts` does not hit this only by luck: its `await fetch('/api/get-game-config')`
+            // sits between goto and LOAD_GAME and provides accidental slack. This lane reads world.json
+            // from disk, so that slack is gone and the race is real.
+            await templateReady.promise;
+            await page.evaluate((payload) => {
+                // eslint-disable-next-line no-undef -- browser-side callback, see above.
+                window.postMessage({
+                    type: 'LOAD_GAME',
+                    data: {
+                        gameId: payload.gameId,
+                        gameData: payload.gameData,
+                        skipMenu: true,
+                        agentUrl: payload.agentUrl,
+                    },
+                }, '*');
+            }, {
+                gameId: this.options.gameId,
+                gameData: this.options.gameData,
+                agentUrl: this.options.agentUrl,
+            });
+            await gameLoaded.promise;
+            this.log(`Game loaded in the forge browser (${this.options.gameId}).`);
+        }
+        finally {
+            templateReady.cancel();
+            gameLoaded.cancel();
+        }
+    }
+    /**
+     * Wait for one handshake message. Unlike the transport's waits, these REJECT on timeout: a page
+     * that never boots or a game that never loads is not a "no answer" the caller can shrug off and
+     * retry — nothing downstream can run.
+     */
+    waitForPageMessage(type, timeoutMs, timeoutMessage) {
+        let timer;
+        let unsubscribe;
+        const cancel = () => {
+            if (timer)
+                clearTimeout(timer);
+            unsubscribe?.();
+        };
+        const promise = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                cancel();
+                reject(new CliError(timeoutMessage));
+            }, timeoutMs);
+            unsubscribe = this.pageBridge.onMessage((message) => {
+                if (message.type !== type)
+                    return;
+                cancel();
+                resolve();
+            });
+        });
+        return { promise, cancel };
+    }
+    async closePage() {
+        if (!this.page)
+            return;
+        const page = this.page;
+        this.page = null;
+        await page.close();
+    }
+    async close() {
+        await this.closePage();
+        if (this.context) {
+            const context = this.context;
+            this.context = null;
+            await context.close();
+        }
+        if (this.userDataDir) {
+            fs.rmSync(this.userDataDir, { recursive: true, force: true });
+            this.userDataDir = null;
+        }
+    }
+}
+//# sourceMappingURL=browser-host.js.map

package/dist/forge/browser-host.js.map

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

package/dist/forge/local-store.d.ts

@@ -0,0 +1,30 @@
+import type { ForgeStorageClient, ForgeStorageEnv } from '@bitmagic/world-forger/pipeline/index.js';
+/** Where forge job artifacts live, relative to the project root. `.bitmagic/` is gitignored by
+ *  the scaffold (see scaffold/project-files.ts) and already holds `verify/`'s artifacts. */
+export declare const FORGE_STORE_DIR: string;
+/**
+ * Resolve one storage key to a file path, refusing anything that would escape the store root.
+ *
+ * The keys this store sees are built by the shared package from a jobId api-server already
+ * validated against `FORGE_JOB_ID_PATTERN`, so this can never fire in practice today. It is here
+ * because the check is what makes that a *fact about the current callers* rather than a
+ * *property of this module*: a key is untrusted input the moment anything else builds one, and
+ * "it happens to be safe upstream" is not a guarantee a filesystem writer should rely on.
+ * Refuses loudly — it is never correct to silently write somewhere else.
+ */
+export declare function resolveStoreKeyPath(rootDir: string, key: string): string;
+/**
+ * A `ForgeStorageClient` over the local filesystem. `bucket` is an absolute DIRECTORY here
+ * rather than a bucket name — the seam is structural (see the package's storage-types.ts), and a
+ * directory is exactly the "namespace a key is resolved against" the field means.
+ */
+export declare function createLocalForgeStorageClient(): ForgeStorageClient;
+/**
+ * The `ForgeStorageEnv` steps 3-5 run against, rooted in this project.
+ *
+ * `publicUrl` is a `file://` URL for the store directory. Nothing in steps 3-5 reads it — it
+ * exists for step 2's uploads, which run on api-server — but the seam declares it required, and
+ * the honest value for a local store is where those bytes actually are. (`storage-types.ts`
+ * names `file://` as an expected form.)
+ */
+export declare function createLocalForgeStorage(projectRoot: string): ForgeStorageEnv;

package/dist/forge/local-store.js

@@ -0,0 +1,130 @@
+/**
+ * The CLI lane's `ForgeDeps.storage` — a LOCAL, project-scoped artifact store under
+ * `<root>/.bitmagic/forge/`, not the GCS bucket api-server writes to.
+ *
+ * ── Why local, and why that is not a shortcut ─────────────────────────────────────────────
+ *
+ * The obvious reading of "storage must reach the job's artifacts" is that the CLI needs
+ * credentialed access to `PORTAL_WEBSITE_BUCKET`. It does not, and giving a creator's machine a
+ * bucket credential would be a real regression in the security posture of this lane — the CLI
+ * authenticates as a *user* through Auth0 and every privileged action it takes is mediated by
+ * api-server, which is what makes ownership checks and spark billing enforceable at all.
+ *
+ * It is unnecessary because of what steps 3-5 actually read from the store. Exhaustively:
+ *
+ *   | artifact              | who writes it            | how the CLI gets it                     |
+ *   |-----------------------|--------------------------|-----------------------------------------|
+ *   | `forge`               | step 2, on api-server    | the terminal SSE frame carries it        |
+ *   | `input`               | the route, at job start  | it IS this CLI's own frozen request      |
+ *   | `platformer-movement` | step 1, on api-server    | the terminal SSE frame carries it        |
+ *   | `archetype-progress`  | step 3, HERE             | written and read locally                 |
+ *   | `archetype-assets`    | step 3, HERE             | written and read locally                 |
+ *   | `level-bake`          | step 4, HERE             | written and read locally                 |
+ *   | `persisted`           | the host, HERE           | written locally                          |
+ *
+ * `forge` arrives in the terminal frame on a fresh run AND on a resume — `forgeWorld` ends every
+ * successful run with `store.get<ForgeArtifact>('forge')` regardless of whether either step was
+ * skipped (`api-server/src/cli/cli-forge.ts`). `platformer-movement` rides the same frame, as an
+ * optional field, and `seedForgeStore` writes both into this store. So the two artifacts that
+ * genuinely cross the machine boundary travel over the wire, and the other four are produced and
+ * consumed entirely on this side. Round-tripping those four through a remote bucket would add
+ * latency and a write credential in exchange for nothing.
+ *
+ * ── The two caveats, stated rather than hidden ────────────────────────────────────────────
+ *
+ *  1. An api-server deployed BEFORE `platformerMovement` was added to the terminal frame sends
+ *     no such field, and the CLI and api-server ship independently — so a platformer level
+ *     forged against an older server still persists without its `worldForgerMovement` contract.
+ *     `placeAndPersistLevel` reads it with `store.get` (not `requireArtifact`) and omits the
+ *     field when absent, so this degrades rather than fails, and
+ *     `warnIfPlatformerMovementMissing` says so out loud before the level is written.
+ *  2. A resume from a DIFFERENT machine (or after `.bitmagic/` is deleted) re-runs steps 3-5
+ *     from scratch. It still skips steps 1-2, which are the paid ones — the server's own store
+ *     is what makes that work — so the expensive half of a resume is unaffected. A platformer
+ *     resume does re-fetch `platformer-movement`, since it rides the terminal frame the resumed
+ *     request returns.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+/** Where forge job artifacts live, relative to the project root. `.bitmagic/` is gitignored by
+ *  the scaffold (see scaffold/project-files.ts) and already holds `verify/`'s artifacts. */
+export const FORGE_STORE_DIR = path.join('.bitmagic', 'forge');
+/**
+ * Resolve one storage key to a file path, refusing anything that would escape the store root.
+ *
+ * The keys this store sees are built by the shared package from a jobId api-server already
+ * validated against `FORGE_JOB_ID_PATTERN`, so this can never fire in practice today. It is here
+ * because the check is what makes that a *fact about the current callers* rather than a
+ * *property of this module*: a key is untrusted input the moment anything else builds one, and
+ * "it happens to be safe upstream" is not a guarantee a filesystem writer should rely on.
+ * Refuses loudly — it is never correct to silently write somewhere else.
+ */
+export function resolveStoreKeyPath(rootDir, key) {
+    const base = path.resolve(rootDir);
+    const target = path.resolve(base, key);
+    if (target !== base && !target.startsWith(base + path.sep)) {
+        throw new CliError(`Refusing to write forge artifact outside ${base}: the key "${key}" escapes it.`);
+    }
+    return target;
+}
+/**
+ * A `ForgeStorageClient` over the local filesystem. `bucket` is an absolute DIRECTORY here
+ * rather than a bucket name — the seam is structural (see the package's storage-types.ts), and a
+ * directory is exactly the "namespace a key is resolved against" the field means.
+ */
+export function createLocalForgeStorageClient() {
+    return {
+        async putObject(params) {
+            const file = resolveStoreKeyPath(params.bucket, params.key);
+            const body = typeof params.body === 'string' ? new TextEncoder().encode(params.body) : params.body;
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            // Written through a temp file in the same directory then renamed, so an interrupted write
+            // cannot leave a truncated artifact behind. A truncated `archetype-assets` would fail a
+            // resume with a JSON parse error rather than re-baking, which is the worse outcome.
+            const temp = `${file}.${process.pid}.tmp`;
+            fs.writeFileSync(temp, body);
+            fs.renameSync(temp, file);
+            return body.length;
+        },
+        async headObject(params) {
+            return fs.existsSync(resolveStoreKeyPath(params.bucket, params.key));
+        },
+        async getObject(params) {
+            const file = resolveStoreKeyPath(params.bucket, params.key);
+            // "Absent" is the seam's `null`. Anything else (a permissions error, a directory where a
+            // file belongs) is a real failure and must propagate rather than be reported as "missing",
+            // which would make a resume silently re-bake instead of naming what is wrong.
+            if (!fs.existsSync(file))
+                return null;
+            return new Uint8Array(fs.readFileSync(file));
+        },
+    };
+}
+/**
+ * The `ForgeStorageEnv` steps 3-5 run against, rooted in this project.
+ *
+ * `publicUrl` is a `file://` URL for the store directory. Nothing in steps 3-5 reads it — it
+ * exists for step 2's uploads, which run on api-server — but the seam declares it required, and
+ * the honest value for a local store is where those bytes actually are. (`storage-types.ts`
+ * names `file://` as an expected form.)
+ */
+export function createLocalForgeStorage(projectRoot) {
+    const dir = path.join(projectRoot, FORGE_STORE_DIR);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (error) {
+        // A read-only checkout or a permissions problem is creator-actionable, so it gets a designed
+        // message rather than an EACCES stack trace from several frames down. Named here because this
+        // is the one condition in the pre-request span that would otherwise surface as a plain Error.
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Cannot create ${dir}, where a forge keeps its resumable state: ${detail}`);
+    }
+    return {
+        storageClient: createLocalForgeStorageClient(),
+        bucket: dir,
+        publicUrl: `file://${dir}`,
+    };
+}
+//# sourceMappingURL=local-store.js.map

package/dist/forge/local-store.js.map

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