@bitmagic/cli 0.1.0

package/dist/commands/verify.js

@@ -0,0 +1,124 @@
+import { defineCommand } from 'citty';
+import * as fs from 'fs';
+import * as net from 'net';
+import * as path from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { CliError } from '../errors.js';
+import { loadProjectContext, projectBin } from '../project/context.js';
+import { runHeadlessCheck } from '../verify/browser.js';
+import { classifyVerifyRun } from '../verify/classify.js';
+import { waitForServer } from '../verify/wait-for-server.js';
+const DEFAULT_SETTLE_MS = 15_000;
+/** Bind to port 0 so the OS picks a free one — verify must never collide with a running `dev`. */
+async function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.on('error', reject);
+        server.listen(0, () => {
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                server.close();
+                reject(new CliError('Could not reserve a local port for the dev server.'));
+                return;
+            }
+            const { port } = address;
+            server.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * Rejects if `child` exits (non-signal, non-zero) or errors before `waitForServer` resolves, so
+ * a vite that crashes on a broken config fails immediately with its stderr instead of `verify`
+ * waiting out the full startup timeout and reporting a port/timing diagnosis for what is
+ * actually a config error.
+ */
+function watchForEarlyExit(child, getStderr) {
+    return new Promise((_resolve, reject) => {
+        child.on('exit', (code, signal) => {
+            if (signal !== null)
+                return; // killed by us (shutdown) — not a startup failure.
+            if (code === 0)
+                return;
+            const stderr = getStderr().trim();
+            reject(new CliError(`vite exited before the dev server came up (code ${code}).` +
+                (stderr ? `\n${stderr}` : '')));
+        });
+        child.on('error', (error) => {
+            reject(new CliError(`Could not start vite: ${error.message}`));
+        });
+    });
+}
+/** `--timeout` is settle time in ms and must be a usable duration, not just "parses as a number":
+ *  NaN (e.g. `30s`) would settle for ~0ms and fail a healthy game; 0 or negative are meaningless. */
+function parseTimeoutArg(raw) {
+    if (raw === undefined)
+        return DEFAULT_SETTLE_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new CliError(`--timeout must be a positive number of milliseconds, got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+export const verifyCommand = defineCommand({
+    meta: { name: 'verify', description: 'Boot the game in a real browser and report what broke.' },
+    args: {
+        timeout: { type: 'string', description: `Settle time in ms (default ${DEFAULT_SETTLE_MS}).` },
+    },
+    async run({ args }) {
+        const settleMs = parseTimeoutArg(args.timeout);
+        const context = loadProjectContext();
+        const tsc = projectBin(context.root, 'tsc');
+        const vite = projectBin(context.root, 'vite');
+        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) {
+            // Nothing to verify: the emitted output the browser would load does not exist.
+            throw new CliError('Build failed, so there is nothing to verify.', build.status ?? 1);
+        }
+        const artifactDir = path.join(context.root, '.bitmagic', 'verify');
+        fs.mkdirSync(artifactDir, { recursive: true });
+        const screenshotPath = path.join(artifactDir, 'screenshot.png');
+        const consolePath = path.join(artifactDir, 'console.log');
+        const port = await freePort();
+        let server;
+        try {
+            server = spawn(vite, ['--port', String(port), '--strictPort'], {
+                cwd: context.root,
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+            let viteStderr = '';
+            server.stderr?.on('data', (chunk) => {
+                viteStderr += String(chunk);
+            });
+            await Promise.race([
+                waitForServer(port, 30_000),
+                watchForEarlyExit(server, () => viteStderr),
+            ]);
+            // ?autostart=1 skips the Play menu (engine/CreatorMode.ts:22) so gameplay actually starts —
+            // otherwise verify would only ever prove the menu renders.
+            const observations = await runHeadlessCheck({
+                url: `http://localhost:${port}/?autostart=1`,
+                screenshotPath,
+                consolePath,
+                settleMs,
+            });
+            const result = classifyVerifyRun(observations);
+            for (const warning of result.warnings)
+                console.log(`warning: ${warning}`);
+            if (!result.ok) {
+                for (const failure of result.failures)
+                    console.error(`✗ ${failure}`);
+                console.error(`\nArtifacts: ${consolePath}, ${screenshotPath}`);
+                throw new CliError('Verification failed.');
+            }
+            console.log(`Verification passed. Artifacts in ${artifactDir}`);
+        }
+        finally {
+            server?.kill('SIGTERM');
+        }
+    },
+});
+//# sourceMappingURL=verify.js.map

package/dist/commands/verify.js.map

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

package/dist/commands/whoami.d.ts

@@ -0,0 +1,11 @@
+export interface WhoamiResponse {
+    userId: string;
+    roles: string[];
+}
+export declare function runWhoami(explicitEnv?: string): Promise<WhoamiResponse>;
+export declare const whoamiCommand: import("citty").CommandDef<{
+    readonly env: {
+        readonly type: "string";
+        readonly description: "Environment to query (dev, prod, local).";
+    };
+}>;

package/dist/commands/whoami.js

@@ -0,0 +1,29 @@
+import { defineCommand } from 'citty';
+import { resolveEnvironment, resolveAuth0ClientId } from '../config/environments.js';
+import { readDefaultEnvironment } from '../config/credentials.js';
+import { getAccessToken } from '../auth/session.js';
+import { apiGet } from '../http/client.js';
+const deviceFlowDeps = { fetch: globalThis.fetch, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
+export async function runWhoami(explicitEnv) {
+    const environment = resolveEnvironment({
+        explicit: explicitEnv,
+        storedDefault: readDefaultEnvironment(),
+    });
+    const clientId = resolveAuth0ClientId(environment);
+    const token = await getAccessToken(environment, clientId, deviceFlowDeps);
+    return apiGet(environment, '/api/cli/v1/whoami', token, {
+        fetch: globalThis.fetch,
+    });
+}
+export const whoamiCommand = defineCommand({
+    meta: { name: 'whoami', description: 'Show the identity the CLI is authenticated as.' },
+    args: {
+        env: { type: 'string', description: 'Environment to query (dev, prod, local).' },
+    },
+    async run({ args }) {
+        const me = await runWhoami(args.env);
+        console.log(`user:  ${me.userId}`);
+        console.log(`roles: ${me.roles.length > 0 ? me.roles.join(', ') : '(none)'}`);
+    },
+});
+//# sourceMappingURL=whoami.js.map

package/dist/commands/whoami.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../../src/commands/whoami.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAO3C,MAAM,cAAc,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;AAEvH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,WAAoB;IAClD,MAAM,WAAW,GAAG,kBAAkB,CAAC;QACrC,QAAQ,EAAE,WAAW;QACrB,aAAa,EAAE,sBAAsB,EAAE;KACxC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC1E,OAAO,MAAM,CAAiB,WAAW,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACtE,KAAK,EAAE,UAAU,CAAC,KAAK;KACxB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;IACzC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gDAAgD,EAAE;IACvF,IAAI,EAAE;QACJ,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0CAA0C,EAAE;KACjF;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAChB,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChF,CAAC;CACF,CAAC,CAAC"}

package/dist/config/credentials.d.ts

@@ -0,0 +1,13 @@
+export interface StoredCredentials {
+    refreshToken: string;
+    accessToken: string;
+    /** Epoch milliseconds at which accessToken stops being valid. */
+    expiresAt: number;
+}
+export declare function defaultBaseDir(): string;
+export declare function credentialsPath(baseDir?: string): string;
+export declare function readCredentials(environment: string, baseDir?: string): StoredCredentials | null;
+export declare function writeCredentials(environment: string, credentials: StoredCredentials, baseDir?: string): void;
+export declare function clearCredentials(environment: string, baseDir?: string): void;
+export declare function readDefaultEnvironment(baseDir?: string): string | undefined;
+export declare function writeDefaultEnvironment(environment: string, baseDir?: string): void;

package/dist/config/credentials.js

@@ -0,0 +1,114 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+/**
+ * Runtime guard: is `value` usable as a stored default-environment name? This only checks the
+ * type (non-empty string) — credentials.ts must not import the environment table, so it cannot
+ * validate the value against the actual set of environment names. An unrecognised-but-well-typed
+ * name (e.g. a stale "staging" left by an older build) is passed through here and dropped later,
+ * where the environment is resolved: resolveEnvironment falls back to "dev" for a stored default
+ * it doesn't recognise instead of throwing, so a bad stored default can never wedge the CLI.
+ */
+function isStoredDefaultEnvironment(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** Runtime guard: is `value` a well-formed StoredCredentials entry? */
+function isStoredCredentials(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.refreshToken === 'string' &&
+        v.refreshToken.length > 0 &&
+        typeof v.accessToken === 'string' &&
+        v.accessToken.length > 0 &&
+        typeof v.expiresAt === 'number' &&
+        Number.isFinite(v.expiresAt));
+}
+export function defaultBaseDir() {
+    return path.join(os.homedir(), '.bitmagic');
+}
+export function credentialsPath(baseDir = defaultBaseDir()) {
+    return path.join(baseDir, 'credentials.json');
+}
+function readFile(baseDir) {
+    const filePath = credentialsPath(baseDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            // No credentials yet is the normal first-run state, not an error.
+            return { credentials: {} };
+        }
+        // A real filesystem problem (e.g. permissions) must not be reported as "not logged in" —
+        // that sends the user down a login flow that can't fix it.
+        throw new CliError(`Cannot read credentials file at ${filePath}: ${code ?? String(err)}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return { credentials: {} };
+        const file = parsed;
+        const rawCredentials = file.credentials;
+        const defaultEnvironment = isStoredDefaultEnvironment(file.defaultEnvironment)
+            ? file.defaultEnvironment
+            : undefined;
+        if (typeof rawCredentials !== 'object' || rawCredentials === null) {
+            return { defaultEnvironment, credentials: {} };
+        }
+        const credentials = {};
+        for (const [env, entry] of Object.entries(rawCredentials)) {
+            if (isStoredCredentials(entry)) {
+                credentials[env] = entry;
+            }
+            // Entries that fail the guard are dropped, same as a corrupt file: treated as absent.
+        }
+        return {
+            defaultEnvironment,
+            credentials,
+        };
+    }
+    catch {
+        // A corrupt file must not wedge the CLI: `bitmagic login` overwrites it.
+        return { credentials: {} };
+    }
+}
+function writeFile(baseDir, file) {
+    fs.mkdirSync(baseDir, { recursive: true, mode: DIR_MODE });
+    const filePath = credentialsPath(baseDir);
+    const tmpPath = path.join(baseDir, `.credentials.json.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmpPath, `${JSON.stringify(file, null, 2)}\n`, { mode: FILE_MODE });
+    // writeFileSync's mode applies only when it creates the file, so tighten explicitly before
+    // the file is visible under its final name, then again after rename for defense in depth.
+    fs.chmodSync(tmpPath, FILE_MODE);
+    fs.renameSync(tmpPath, filePath);
+    fs.chmodSync(filePath, FILE_MODE);
+    fs.chmodSync(baseDir, DIR_MODE);
+}
+export function readCredentials(environment, baseDir = defaultBaseDir()) {
+    return readFile(baseDir).credentials[environment] ?? null;
+}
+export function writeCredentials(environment, credentials, baseDir = defaultBaseDir()) {
+    const file = readFile(baseDir);
+    file.credentials[environment] = credentials;
+    writeFile(baseDir, file);
+}
+export function clearCredentials(environment, baseDir = defaultBaseDir()) {
+    const file = readFile(baseDir);
+    delete file.credentials[environment];
+    writeFile(baseDir, file);
+}
+export function readDefaultEnvironment(baseDir = defaultBaseDir()) {
+    return readFile(baseDir).defaultEnvironment;
+}
+export function writeDefaultEnvironment(environment, baseDir = defaultBaseDir()) {
+    const file = readFile(baseDir);
+    file.defaultEnvironment = environment;
+    writeFile(baseDir, file);
+}
+//# sourceMappingURL=credentials.js.map

package/dist/config/credentials.js.map

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

package/dist/config/environments.d.ts

@@ -0,0 +1,21 @@
+export type EnvironmentName = 'dev' | 'prod' | 'local';
+export interface Environment {
+    name: EnvironmentName;
+    apiUrl: string;
+    auth0Domain: string;
+    auth0Audience: string;
+    /** Empty until the Auth0 Native application exists; see resolveAuth0ClientId. */
+    auth0ClientId: string;
+}
+export declare const ENVIRONMENTS: Record<EnvironmentName, Environment>;
+export declare const ENVIRONMENT_NAMES: EnvironmentName[];
+export declare function isEnvironmentName(value: string): value is EnvironmentName;
+export interface ResolveEnvironmentOptions {
+    /** The --env flag, if given. */
+    explicit?: string;
+    /** The default recorded in the credentials file, if any. */
+    storedDefault?: string;
+    env?: Record<string, string | undefined>;
+}
+export declare function resolveEnvironment(options?: ResolveEnvironmentOptions): Environment;
+export declare function resolveAuth0ClientId(environment: Environment, env?: Record<string, string | undefined>): string;

package/dist/config/environments.js

@@ -0,0 +1,67 @@
+import { CliError } from '../errors.js';
+const DEV_AUTH0_DOMAIN = 'bitmagic-v3-staging.us.auth0.com';
+const DEV_AUTH0_AUDIENCE = 'https://api.bitmagic.cloud';
+// Public identifier of the "Bitmagic CLI APP" Auth0 Native application, not a secret — native
+// apps cannot hold one, which is why the device-code flow uses PKCE-free device verification.
+// Verified end to end against the staging tenant: the device-flow access token carries the
+// https://bitmagic.ai/roles claim, so the api-server Admin gate accepts it.
+const DEV_AUTH0_CLIENT_ID = 'wEp5Jsw43MyExDT1DfMCFyQSi8II0mSu';
+export const ENVIRONMENTS = {
+    dev: {
+        name: 'dev',
+        apiUrl: 'https://beta.portal.bitmagic.cloud',
+        auth0Domain: DEV_AUTH0_DOMAIN,
+        auth0Audience: DEV_AUTH0_AUDIENCE,
+        auth0ClientId: DEV_AUTH0_CLIENT_ID,
+    },
+    prod: {
+        name: 'prod',
+        apiUrl: 'https://bitmagic.ai',
+        auth0Domain: 'bitmagic-v3.us.auth0.com',
+        auth0Audience: 'https://api.bitmagic.ai',
+        // No prod Auth0 Native application exists yet, so `bitmagic login --env prod` fails
+        // before any network call, naming BITMAGIC_AUTH0_CLIENT_ID. Prod delivery of the pro lane
+        // is deferred anyway: prod has no engine bucket and no manifest.
+        auth0ClientId: '',
+    },
+    // There is no local Auth0. Pointing local at the dev tenant is deliberate: minting a fake
+    // local identity would reintroduce the localhost-bypass hazard the CLI auth design rejected.
+    local: {
+        name: 'local',
+        apiUrl: 'http://localhost:3002',
+        auth0Domain: DEV_AUTH0_DOMAIN,
+        auth0Audience: DEV_AUTH0_AUDIENCE,
+        auth0ClientId: DEV_AUTH0_CLIENT_ID,
+    },
+};
+export const ENVIRONMENT_NAMES = Object.keys(ENVIRONMENTS);
+export function isEnvironmentName(value) {
+    return Object.prototype.hasOwnProperty.call(ENVIRONMENTS, value);
+}
+export function resolveEnvironment(options = {}) {
+    const env = options.env ?? process.env;
+    // A stored default is written by an older or corrupted CLI, not typed by the user, so an
+    // unrecognised value (e.g. a stale "staging") must not wedge every command with a CliError —
+    // treat it as absent and fall through to "dev". An unrecognised --env flag or BITMAGIC_ENV is
+    // still a hard error below: those are typed by the user right now and deserve direct feedback.
+    const validStoredDefault = options.storedDefault !== undefined && isEnvironmentName(options.storedDefault)
+        ? options.storedDefault
+        : undefined;
+    const candidate = options.explicit ?? env.BITMAGIC_ENV ?? validStoredDefault ?? 'dev';
+    if (!isEnvironmentName(candidate)) {
+        throw new CliError(`Unknown environment "${candidate}". Valid environments: ${ENVIRONMENT_NAMES.join(', ')}.`);
+    }
+    const resolved = ENVIRONMENTS[candidate];
+    const apiUrlOverride = env.BITMAGIC_API_URL;
+    return apiUrlOverride ? { ...resolved, apiUrl: apiUrlOverride } : resolved;
+}
+export function resolveAuth0ClientId(environment, env = process.env) {
+    const clientId = env.BITMAGIC_AUTH0_CLIENT_ID ?? environment.auth0ClientId;
+    if (!clientId) {
+        throw new CliError(`No Auth0 client id is configured for the "${environment.name}" environment. ` +
+            'Set BITMAGIC_AUTH0_CLIENT_ID to the client id of the Auth0 Native application ' +
+            'that has the Device Code grant enabled.');
+    }
+    return clientId;
+}
+//# sourceMappingURL=environments.js.map

package/dist/config/environments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environments.js","sourceRoot":"","sources":["../../src/config/environments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAaxC,MAAM,gBAAgB,GAAG,kCAAkC,CAAC;AAC5D,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAExD,8FAA8F;AAC9F,8FAA8F;AAC9F,2FAA2F;AAC3F,4EAA4E;AAC5E,MAAM,mBAAmB,GAAG,kCAAkC,CAAC;AAE/D,MAAM,CAAC,MAAM,YAAY,GAAyC;IAChE,GAAG,EAAE;QACH,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,oCAAoC;QAC5C,WAAW,EAAE,gBAAgB;QAC7B,aAAa,EAAE,kBAAkB;QACjC,aAAa,EAAE,mBAAmB;KACnC;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,qBAAqB;QAC7B,WAAW,EAAE,0BAA0B;QACvC,aAAa,EAAE,yBAAyB;QACxC,oFAAoF;QACpF,0FAA0F;QAC1F,iEAAiE;QACjE,aAAa,EAAE,EAAE;KAClB;IACD,0FAA0F;IAC1F,6FAA6F;IAC7F,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,uBAAuB;QAC/B,WAAW,EAAE,gBAAgB;QAC7B,aAAa,EAAE,kBAAkB;QACjC,aAAa,EAAE,mBAAmB;KACnC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAsB,CAAC;AAEhF,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AACnE,CAAC;AAUD,MAAM,UAAU,kBAAkB,CAAC,UAAqC,EAAE;IACxE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,yFAAyF;IACzF,6FAA6F;IAC7F,8FAA8F;IAC9F,+FAA+F;IAC/F,MAAM,kBAAkB,GACtB,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,iBAAiB,CAAC,OAAO,CAAC,aAAa,CAAC;QAC7E,CAAC,CAAC,OAAO,CAAC,aAAa;QACvB,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC,YAAY,IAAI,kBAAkB,IAAI,KAAK,CAAC;IAEtF,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,QAAQ,CAChB,wBAAwB,SAAS,0BAA0B,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,cAAc,GAAG,GAAG,CAAC,gBAAgB,CAAC;IAC5C,OAAO,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,WAAwB,EACxB,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,QAAQ,GAAG,GAAG,CAAC,wBAAwB,IAAI,WAAW,CAAC,aAAa,CAAC;IAC3E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,QAAQ,CAChB,6CAA6C,WAAW,CAAC,IAAI,iBAAiB;YAC5E,gFAAgF;YAChF,yCAAyC,CAC5C,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An error whose message is meant for the user, not a stack trace.
+ * cli.ts prints the message and exits with `exitCode`.
+ */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/**
+ * An error whose message is meant for the user, not a stack trace.
+ * cli.ts prints the message and exits with `exitCode`.
+ */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,QAAQ,GAAG,CAAC;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/generate/apply-patches.d.ts

@@ -0,0 +1,7 @@
+import { type WorldPatch } from '@bitmagic/asset-core';
+export interface ApplyOutcome {
+    applied: number;
+    /** One human-readable line per patch, for the command to print. */
+    summary: string[];
+}
+export declare function applyPatchesToWorld(worldPath: string, patches: WorldPatch[]): ApplyOutcome;

package/dist/generate/apply-patches.js

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildUpsertPredicate, isUpsertRootPatch, validateWorldPatch, } from '@bitmagic/asset-core';
+import { CliError } from '../errors.js';
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Walks `path`, creating intermediate objects, and returns the container plus the final key. */
+function resolveContainer(root, segments) {
+    let current = root;
+    for (const segment of segments.slice(0, -1)) {
+        const next = current[segment];
+        if (!isJsonObject(next)) {
+            current[segment] = {};
+        }
+        current = current[segment];
+    }
+    const key = segments[segments.length - 1];
+    if (key === undefined) {
+        throw new CliError('A patch arrived with an empty path.');
+    }
+    return { container: current, key };
+}
+/**
+ * `set` and `push` address paths INSIDE worldProfileData; the Root variants address the document
+ * root. This mirrors game-play-agent/src/mastra/utils/world-json-editor.ts:315-331 exactly —
+ * writing a `set` at the root puts it where the engine never looks, which reads as success.
+ */
+function targetFor(world, patch) {
+    if (patch.type === 'set' || patch.type === 'push') {
+        if (!isJsonObject(world.worldProfileData)) {
+            world.worldProfileData = {};
+        }
+        return world.worldProfileData;
+    }
+    return world;
+}
+function applyOne(world, patch) {
+    const target = targetFor(world, patch);
+    const { container, key } = resolveContainer(target, patch.path);
+    if (isUpsertRootPatch(patch)) {
+        const existing = Array.isArray(container[key]) ? container[key] : [];
+        const matches = buildUpsertPredicate(patch);
+        const index = existing.findIndex(matches);
+        if (index >= 0) {
+            existing[index] = patch.value;
+            container[key] = existing;
+            return `updated ${patch.path.join('.')}[${index}]`;
+        }
+        existing.push(patch.value);
+        container[key] = existing;
+        return `added to ${patch.path.join('.')}`;
+    }
+    if (patch.type === 'push' || patch.type === 'pushRoot') {
+        const existing = Array.isArray(container[key]) ? container[key] : [];
+        existing.push(patch.value);
+        container[key] = existing;
+        return `added to ${patch.path.join('.')}`;
+    }
+    container[key] = patch.value;
+    return `set ${patch.path.join('.')}`;
+}
+export function applyPatchesToWorld(worldPath, patches) {
+    // Validate the whole batch BEFORE touching anything: a half-applied world is worse than an
+    // unchanged one, and the creator has no way to tell which half landed.
+    for (const patch of patches) {
+        const problem = validateWorldPatch(patch);
+        if (problem !== null) {
+            throw new CliError(`The server sent a patch this CLI cannot apply: ${problem}`);
+        }
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(worldPath, 'utf-8');
+    }
+    catch {
+        throw new CliError(`Cannot read ${worldPath}. Is this a Bitmagic project?`);
+    }
+    let world;
+    try {
+        world = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${worldPath} is not valid JSON. Nothing has been changed.`);
+    }
+    if (!isJsonObject(world)) {
+        throw new CliError(`${worldPath} does not contain a world object. Nothing has been changed.`);
+    }
+    const summary = patches.map((patch) => applyOne(world, patch));
+    // Write once, through a temp file in the same directory, so an interrupted write cannot leave
+    // a truncated world.json behind.
+    const temp = path.join(path.dirname(worldPath), `.world.json.${process.pid}.tmp`);
+    fs.writeFileSync(temp, `${JSON.stringify(world, null, 2)}\n`);
+    fs.renameSync(temp, worldPath);
+    return { applied: patches.length, summary };
+}
+//# sourceMappingURL=apply-patches.js.map

package/dist/generate/apply-patches.js.map

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

package/dist/generate/stream.d.ts

@@ -0,0 +1,33 @@
+import type { WorldPatch } from '@bitmagic/asset-core';
+import type { Environment } from '../config/environments.js';
+export interface SseEvent {
+    event: string;
+    data: unknown;
+}
+/**
+ * Pure, synchronous parse of a full set of chunks — cheap and exhaustive to test. Production
+ * streaming uses the same underlying buffer (`createSseFrameBuffer`) one network read at a time,
+ * via `requestGeneration`, so this function is not itself on that path.
+ */
+export declare function parseSseChunks(chunks: string[]): SseEvent[];
+export interface GenerationOutcome {
+    success: boolean;
+    message: string;
+    patches: WorldPatch[];
+}
+export interface StreamDeps {
+    fetch: typeof globalThis.fetch;
+    onProgress: (message: string) => void;
+}
+/**
+ * POSTs to `/api/cli/v1/assets/<type>/stream` and consumes the SSE response.
+ *
+ * - A non-2xx response fails before any stream opens; see `toCliError` for the status mapping.
+ * - On 200, each `progress` event invokes `deps.onProgress`; the terminal `result` or `error`
+ *   event resolves this call with the outcome it carried (an `error` event's `success: false`
+ *   is a legitimate generation failure, not a thrown CliError — the caller decides how to
+ *   present it).
+ * - A stream that closes with **no terminal event** is a truncated connection, not a success
+ *   with zero patches, and fails with a CliError.
+ */
+export declare function requestGeneration(environment: Environment, accessToken: string, type: string, body: Record<string, unknown>, deps: StreamDeps): Promise<GenerationOutcome>;