@bitmagic/cli 0.1.0

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,18 @@
+import type { Environment } from '../config/environments.js';
+import type { StoredCredentials } from '../config/credentials.js';
+export interface DeviceCodeGrant {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresInSeconds: number;
+    intervalSeconds: number;
+}
+export interface DeviceFlowDeps {
+    fetch: typeof globalThis.fetch;
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export declare function requestDeviceCode(environment: Environment, clientId: string, deps: DeviceFlowDeps): Promise<DeviceCodeGrant>;
+export declare function pollForToken(environment: Environment, clientId: string, grant: DeviceCodeGrant, deps: DeviceFlowDeps): Promise<StoredCredentials>;
+export declare function refreshAccessToken(environment: Environment, clientId: string, refreshToken: string, deps: DeviceFlowDeps): Promise<StoredCredentials>;

package/dist/auth/device-flow.js

@@ -0,0 +1,130 @@
+import { URLSearchParams } from 'url';
+import { CliError } from '../errors.js';
+const SCOPE = 'openid profile email offline_access';
+const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+// RFC 8628 §3.2 makes `interval` OPTIONAL with a client-side default of 5 seconds. `expires_in`
+// is REQUIRED by the RFC, but we default it too: a misbehaving Auth0 tenant omitting it must not
+// make the wall-clock expiry guard in pollForToken compare against NaN and loop forever.
+const DEFAULT_INTERVAL_SECONDS = 5;
+const DEFAULT_EXPIRES_IN_SECONDS = 900;
+/**
+ * Coerces `value` to a number, falling back to `fallback` unless the result is finite and
+ * positive. Deliberately not `Number(value) || fallback`: that reads as if it protects against
+ * `NaN` alone, but the field would also need to reject a legitimate `0`, which never applies to
+ * either interval or expires_in.
+ */
+function positiveNumberOr(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return {};
+    }
+}
+function errorCode(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const { error } = body;
+    return typeof error === 'string' ? error : undefined;
+}
+export async function requestDeviceCode(environment, clientId, deps) {
+    const response = await deps.fetch(`https://${environment.auth0Domain}/oauth/device/code`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_id: clientId,
+            scope: SCOPE,
+            audience: environment.auth0Audience,
+        }).toString(),
+    });
+    const body = await readJson(response);
+    if (!response.ok) {
+        // The response body can echo configuration detail; report the code only.
+        throw new CliError(`Auth0 rejected the device-code request for "${environment.name}" ` +
+            `(${errorCode(body) ?? `HTTP ${response.status}`}). ` +
+            'Check that the Auth0 application has the Device Code grant enabled.');
+    }
+    const grant = body;
+    return {
+        deviceCode: String(grant.device_code),
+        userCode: String(grant.user_code),
+        verificationUri: String(grant.verification_uri),
+        verificationUriComplete: String(grant.verification_uri_complete ?? grant.verification_uri),
+        expiresInSeconds: positiveNumberOr(grant.expires_in, DEFAULT_EXPIRES_IN_SECONDS),
+        intervalSeconds: positiveNumberOr(grant.interval, DEFAULT_INTERVAL_SECONDS),
+    };
+}
+function toCredentials(body, fallbackRefreshToken, nowMs) {
+    const token = body;
+    return {
+        accessToken: String(token.access_token),
+        refreshToken: typeof token.refresh_token === 'string' ? token.refresh_token : fallbackRefreshToken,
+        expiresAt: nowMs + Number(token.expires_in) * 1000,
+    };
+}
+export async function pollForToken(environment, clientId, grant, deps) {
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    let intervalSeconds = grant.intervalSeconds;
+    for (;;) {
+        const response = await deps.fetch(`https://${environment.auth0Domain}/oauth/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: DEVICE_CODE_GRANT,
+                device_code: grant.deviceCode,
+                client_id: clientId,
+            }).toString(),
+        });
+        const body = await readJson(response);
+        if (response.ok) {
+            const credentials = toCredentials(body, '', now());
+            if (!credentials.refreshToken) {
+                // offline_access should always yield one. Storing an empty string here would look like
+                // a successful login and then fail every later refresh with no obvious cause.
+                throw new CliError('Auth0 returned no refresh token. Check that the Auth0 application allows the ' +
+                    'offline_access scope for the Device Code grant.');
+            }
+            return credentials;
+        }
+        const code = errorCode(body);
+        if (code === 'access_denied') {
+            throw new CliError('Authorization was denied. Nothing has been stored.');
+        }
+        if (code === 'expired_token') {
+            throw new CliError('The login request expired before it was approved. Run `bitmagic login` again.');
+        }
+        if (code !== 'authorization_pending' && code !== 'slow_down') {
+            throw new CliError(`Auth0 rejected the login (${code ?? `HTTP ${response.status}`}). Run \`bitmagic login\` again.`);
+        }
+        if (code === 'slow_down') {
+            intervalSeconds += SLOW_DOWN_INCREMENT_SECONDS;
+        }
+        if (now() - startedAt >= grant.expiresInSeconds * 1000) {
+            throw new CliError('The login request expired before it was approved. Run `bitmagic login` again.');
+        }
+        await deps.sleep(intervalSeconds * 1000);
+    }
+}
+export async function refreshAccessToken(environment, clientId, refreshToken, deps) {
+    const now = deps.now ?? Date.now;
+    const response = await deps.fetch(`https://${environment.auth0Domain}/oauth/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: clientId,
+            refresh_token: refreshToken,
+        }).toString(),
+    });
+    if (!response.ok) {
+        throw new CliError('Your saved session is no longer valid. Run `bitmagic login`.');
+    }
+    return toCredentials(await readJson(response), refreshToken, now());
+}
+//# sourceMappingURL=device-flow.js.map

package/dist/auth/device-flow.js.map

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

package/dist/auth/session.d.ts

@@ -0,0 +1,3 @@
+import type { Environment } from '../config/environments.js';
+import { type DeviceFlowDeps } from './device-flow.js';
+export declare function getAccessToken(environment: Environment, clientId: string, deps: DeviceFlowDeps, baseDir?: string): Promise<string>;

package/dist/auth/session.js

@@ -0,0 +1,19 @@
+import { CliError } from '../errors.js';
+import { readCredentials, writeCredentials, defaultBaseDir } from '../config/credentials.js';
+import { refreshAccessToken } from './device-flow.js';
+/** Refresh slightly early so a request cannot expire mid-flight. */
+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\`.`);
+    }
+    const now = deps.now ?? Date.now;
+    if (stored.expiresAt - EXPIRY_SKEW_MS > now()) {
+        return stored.accessToken;
+    }
+    const refreshed = await refreshAccessToken(environment, clientId, stored.refreshToken, deps);
+    writeCredentials(environment.name, refreshed, baseDir);
+    return refreshed.accessToken;
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +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"}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { runMain } from 'citty';
+import { main } from './cli.js';
+import { CliError } from './errors.js';
+// The actual executable entrypoint — this is what package.json's `bin` points at. It is
+// deliberately the only place that calls `runMain`, and it does so unconditionally: unlike the
+// old path-comparison guard in cli.ts (which broke when invoked through a symlink, e.g. every
+// `npm i -g` install), there is no heuristic here to get wrong. Importing `./cli.js` never runs
+// the CLI by itself, so this file is the sole source of the "actually run it" side effect.
+runMain(main).catch((error) => {
+    if (error instanceof CliError) {
+        console.error(error.message);
+        process.exit(error.exitCode);
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wFAAwF;AACxF,+FAA+F;AAC/F,8FAA8F;AAC9F,gGAAgG;AAChG,2FAA2F;AAC3F,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACrC,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,70 @@
+import type { ArgsDef, CommandDef } from 'citty';
+export declare function withCleanErrors<T extends ArgsDef>(command: CommandDef<T>): CommandDef<T>;
+/**
+ * Structural check for tests: has this command actually passed through `withCleanErrors`? A leaf
+ * command (one with its own `run`) is wrapped when that `run` is in `wrappedRuns`. A grouping
+ * command with no `run` of its own (see the doc comment above) is wrapped when it has at least
+ * one subcommand and every one of them is — recursively, so nesting can go arbitrarily deep.
+ */
+export declare function isWrappedWithCleanErrors(command: CommandDef<ArgsDef>): boolean;
+declare const rawCommands: {
+    login: CommandDef<{
+        readonly env: {
+            readonly type: "string";
+            readonly description: "Environment to log in to (dev, prod, local).";
+        };
+    }>;
+    logout: CommandDef<{
+        readonly env: {
+            readonly type: "string";
+            readonly description: "Environment to log out of (dev, prod, local).";
+        };
+    }>;
+    whoami: CommandDef<{
+        readonly env: {
+            readonly type: "string";
+            readonly description: "Environment to query (dev, prod, local).";
+        };
+    }>;
+    init: CommandDef<{
+        readonly dir: {
+            readonly type: "positional";
+            readonly required: false;
+            readonly description: "Directory to create the project in.";
+        };
+        readonly template: {
+            readonly type: "string";
+            readonly description: "Template id (see templates in the engine bundle).";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Game name.";
+        };
+        readonly env: {
+            readonly type: "string";
+            readonly description: "Environment (dev, prod, local).";
+        };
+        readonly force: {
+            readonly type: "boolean";
+            readonly description: "Scaffold into a non-empty directory.";
+        };
+    }>;
+    check: CommandDef<ArgsDef>;
+    dev: CommandDef<{
+        readonly port: {
+            readonly type: "string";
+            readonly description: "Port to serve on (default 3010).";
+        };
+    }>;
+    verify: CommandDef<{
+        readonly timeout: {
+            readonly type: "string";
+            readonly description: "Settle time in ms (default 15000).";
+        };
+    }>;
+    generate: CommandDef<ArgsDef>;
+};
+type CommandName = keyof typeof rawCommands;
+export declare const subCommands: Record<CommandName, CommandDef<ArgsDef>>;
+export declare const main: CommandDef<ArgsDef>;
+export {};

package/dist/cli.js

@@ -0,0 +1,96 @@
+import { defineCommand } from 'citty';
+import { CliError } from './errors.js';
+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 { checkCommand } from './commands/check.js';
+import { devCommand } from './commands/dev.js';
+import { verifyCommand } from './commands/verify.js';
+import { generateCommand } from './commands/generate.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
+// does `console.error(error, '\n')`, which for our CliError (an Error instance) prints the full
+// stack trace. Wrap each command's `run` so a CliError is formatted into a clean, single-line
+// message and the process exits before citty ever gets a chance to dump it.
+// Tracks which `run` functions have already been through `withCleanErrors`, so tests can assert
+// "every entry of subCommands is wrapped" structurally, by reference, instead of maintaining a
+// separate list of command names that could drift out of sync with the real map.
+const wrappedRuns = new WeakSet();
+export function withCleanErrors(command) {
+    const originalRun = command.run;
+    const wrapped = { ...command };
+    if (originalRun) {
+        wrapped.run = async (context) => {
+            try {
+                return await originalRun(context);
+            }
+            catch (error) {
+                if (error instanceof CliError) {
+                    console.error(error.message);
+                    process.exit(error.exitCode);
+                }
+                // Not one of ours: let citty's default handling show it, stack trace included — that's
+                // a genuine bug, not a user-facing condition we've designed a message for.
+                throw error;
+            }
+        };
+        wrappedRuns.add(wrapped.run);
+    }
+    // A command that only groups subcommands (e.g. `generate`, whose actual `run`s live one level
+    // down on `generate skybox`, `generate sound`, ...) has no `run` of its own to wrap here. Left
+    // unrecursed, a CliError thrown from one of those would clear this command's own (nonexistent)
+    // run untouched and hit citty's default handling instead — a raw stack trace, the exact thing
+    // this wrapper exists to prevent. Recurse so every depth gets the same clean single-line
+    // treatment. Every subCommands value in this CLI is a plain synchronous object literal (never a
+    // citty Promise/function Resolvable), so narrowing it that way here is safe for this codebase's
+    // actual usage even though citty's own type allows more.
+    if (command.subCommands && typeof command.subCommands === 'object') {
+        const rawSubCommands = command.subCommands;
+        wrapped.subCommands = Object.fromEntries(Object.entries(rawSubCommands).map(([name, sub]) => [name, withCleanErrors(sub)]));
+    }
+    return wrapped;
+}
+/**
+ * Structural check for tests: has this command actually passed through `withCleanErrors`? A leaf
+ * command (one with its own `run`) is wrapped when that `run` is in `wrappedRuns`. A grouping
+ * command with no `run` of its own (see the doc comment above) is wrapped when it has at least
+ * one subcommand and every one of them is — recursively, so nesting can go arbitrarily deep.
+ */
+export function isWrappedWithCleanErrors(command) {
+    if (command.run !== undefined) {
+        return wrappedRuns.has(command.run);
+    }
+    if (command.subCommands && typeof command.subCommands === 'object') {
+        const entries = Object.values(command.subCommands);
+        return entries.length > 0 && entries.every((sub) => isWrappedWithCleanErrors(sub));
+    }
+    return false;
+}
+// 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
+// place where someone could forget to apply `withCleanErrors`.
+const rawCommands = {
+    login: loginCommand,
+    logout: logoutCommand,
+    whoami: whoamiCommand,
+    init: initCommand,
+    check: checkCommand,
+    dev: devCommand,
+    verify: verifyCommand,
+    generate: generateCommand,
+};
+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`)
+// for `bin.ts` to run and for cli.test.ts to import — it must not call `runMain` or otherwise
+// have a side effect when imported, e.g. by cli.test.ts, which needs `subCommands` and
+// `withCleanErrors` without triggering a real citty run against the test runner's own argv.
+export const main = defineCommand({
+    meta: {
+        name: 'bitmagic',
+        description: 'Build Bitmagic games from your own agent tool.',
+    },
+    subCommands,
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/commands/check.d.ts

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

package/dist/commands/check.js

@@ -0,0 +1,22 @@
+import { defineCommand } from 'citty';
+import { spawnSync } from 'child_process';
+import { CliError } from '../errors.js';
+import { loadProjectContext, projectBin } from '../project/context.js';
+export const checkCommand = defineCommand({
+    meta: { name: 'check', description: 'Type-check the game against the vendored engine.' },
+    run() {
+        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.
+        const result = spawnSync(tsc, ['--noEmit'], { cwd: context.root, stdio: 'inherit' });
+        if (result.error) {
+            throw new CliError(`Could not run the TypeScript compiler: ${result.error.message}`);
+        }
+        if (result.status !== 0) {
+            // 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.');
+    },
+});
+//# sourceMappingURL=check.js.map

package/dist/commands/check.js.map

@@ -0,0 +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"}

package/dist/commands/dev.d.ts

@@ -0,0 +1,6 @@
+export declare const devCommand: import("citty").CommandDef<{
+    readonly port: {
+        readonly type: "string";
+        readonly description: "Port to serve on (default 3010).";
+    };
+}>;

package/dist/commands/dev.js

@@ -0,0 +1,89 @@
+import { defineCommand } from 'citty';
+import { spawn, spawnSync } from 'child_process';
+import { CliError } from '../errors.js';
+import { loadProjectContext, projectBin } from '../project/context.js';
+import { waitForServer } from '../verify/wait-for-server.js';
+const DEFAULT_PORT = 3010;
+export const devCommand = defineCommand({
+    meta: { name: 'dev', description: 'Build the game, then serve it with live rebuilds.' },
+    args: {
+        port: { type: 'string', description: `Port to serve on (default ${DEFAULT_PORT}).` },
+    },
+    async run({ args }) {
+        const context = loadProjectContext();
+        const tsc = projectBin(context.root, 'tsc');
+        const vite = projectBin(context.root, 'vite');
+        const port = args.port ?? String(DEFAULT_PORT);
+        // Build to completion first. Every alias resolves into dist/, so serving before the first
+        // emit 404s every module — a failure that reads as "the engine is broken", not "not built".
+        console.log('Building…');
+        const build = spawnSync(tsc, [], { cwd: context.root, stdio: 'inherit' });
+        if (build.error) {
+            throw new CliError(`Could not run the TypeScript compiler: ${build.error.message}`);
+        }
+        if (build.status !== 0) {
+            throw new CliError('Build failed. Fix the errors above, then run `bitmagic dev` again.', build.status ?? 1);
+        }
+        const children = [
+            {
+                name: 'tsc --watch',
+                process: spawn(tsc, ['--watch', '--preserveWatchOutput'], { cwd: context.root, stdio: 'inherit' }),
+            },
+            {
+                name: 'vite',
+                process: spawn(vite, ['--port', port, '--strictPort'], { cwd: context.root, stdio: 'inherit' }),
+            },
+        ];
+        let shuttingDown = false;
+        let requestedByUser = false;
+        const shutdown = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            for (const child of children)
+                child.process.kill('SIGTERM');
+        };
+        process.on('SIGINT', () => {
+            requestedByUser = true;
+            shutdown();
+        });
+        process.on('SIGTERM', () => {
+            requestedByUser = true;
+            shutdown();
+        });
+        // Print the URL ourselves once vite actually answers, rather than relying on vite's own
+        // startup banner — that output is vite's to change, this is ours to keep stable.
+        void waitForServer(Number(port), 30_000)
+            .then(() => console.log(`\nServing at http://localhost:${port}/`))
+            .catch(() => {
+            // The child-exit watcher below reports a vite that never comes up; this poll simply has
+            // nothing to announce in that case.
+        });
+        // If a child exits on its own (not because we asked it to via shutdown()), that's a failure:
+        // take the other child down too rather than leaving a half-dead stack that serves stale
+        // output, and say which one died so an agent gating on the exit code knows where to look.
+        const failure = await new Promise((resolve) => {
+            let exitedCount = 0;
+            for (const child of children) {
+                child.process.on('error', (error) => {
+                    shutdown();
+                    resolve({ name: child.name, detail: `could not start: ${error.message}` });
+                });
+                child.process.on('exit', (code, signal) => {
+                    exitedCount += 1;
+                    if (!requestedByUser && !shuttingDown) {
+                        shutdown();
+                        resolve({ name: child.name, detail: `exited with code ${code}${signal ? ` (signal ${signal})` : ''}` });
+                    }
+                    else if (exitedCount === children.length) {
+                        resolve(undefined);
+                    }
+                });
+            }
+        });
+        if (failure) {
+            throw new CliError(`${failure.name} ${failure.detail}. \`bitmagic dev\` stopped.`);
+        }
+    },
+});
+//# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

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

package/dist/commands/generate.d.ts

@@ -0,0 +1,62 @@
+export interface SkyboxArgs {
+    description: string;
+    referenceImageUrl?: string;
+}
+export declare function buildSkyboxBody(args: SkyboxArgs): Record<string, unknown>;
+export interface SoundArgs {
+    prompt: string;
+    duration?: string;
+    promptInfluence?: string;
+    loop?: boolean;
+}
+export declare function buildSoundBody(args: SoundArgs): Record<string, unknown>;
+export interface ImageArgs {
+    name: string;
+    prompt: string;
+    width?: string;
+    height?: string;
+    referenceImageUrl?: string;
+}
+export declare function buildImageBody(args: ImageArgs): Record<string, unknown>;
+export interface CharacterArgs {
+    name: string;
+    prompt: string;
+    applyToPlayer?: boolean;
+    headScale?: string;
+}
+export declare function buildCharacterBody(args: CharacterArgs): Record<string, unknown>;
+export interface AnimationArgs {
+    description: string;
+    length?: string;
+    cfgScale?: string;
+    seed?: string;
+    footIk?: boolean;
+    inPlace?: boolean;
+    loop?: boolean;
+}
+export declare function buildAnimationBody(args: AnimationArgs): Record<string, unknown>;
+export interface GenerateRunDeps {
+    fetch: typeof globalThis.fetch;
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Test-only override; production omits it and loadProjectContext walks up from process.cwd(). */
+    startDir?: string;
+    /** Test-only override; production omits it and getAccessToken/readDefaultEnvironment read ~/.bitmagic. */
+    baseDir?: string;
+    log: (message: string) => void;
+}
+/**
+ * Runs one `bitmagic generate <subcommand>`: requests the asset, then applies the returned
+ * patches to world.json. Every failure path says explicitly whether world.json changed, because
+ * a creator (or the agent driving this CLI) who does not know has to go look for themselves:
+ *
+ *  - Anything that fails before a `result`/`error` frame arrives (auth, ownership, spark balance,
+ *    a network error, ...) — world.json is untouched; the message says so.
+ *  - A terminal `success: false` outcome — asset-core's `fail()` always carries an empty patch
+ *    array (see shared/asset-core/src/result.ts), so this is also an unchanged world.json.
+ *  - A successful outcome whose patches could not be written (a corrupt world.json, an
+ *    unrecognised patch shape) — distinct from the above: the Forger may already have billed for
+ *    this generation, so the message says the asset was NOT lost, only not yet applied.
+ */
+export declare function runAssetGeneration(type: string, label: string, body: Record<string, unknown>, deps?: GenerateRunDeps): Promise<void>;
+export declare const generateCommand: import("citty").CommandDef<import("citty").ArgsDef>;