@bitmagic/cli 0.1.7 → 0.1.9

package/dist/publish/client.d.ts

@@ -0,0 +1,94 @@
+import type { Environment } from '../config/environments.js';
+export interface ApiDeps {
+    fetch: typeof globalThis.fetch;
+}
+/**
+ * One status→exit-code mapping for both publish calls.
+ *
+ * The distinction that matters is 4 vs 5: "your engine is too old" is self-serve
+ * (`bitmagic upgrade`), while a ban or an ownership mismatch is not. An agent that cannot
+ * tell them apart will either loop on upgrade or give up on a fixable problem.
+ */
+export declare function publishExitCode(status: number, body: {
+    code?: string;
+}): number;
+export interface BeginPublishRequest {
+    gameId: string;
+    visibility: 'public' | 'private';
+    name?: string;
+    description?: string;
+    engineVersion: string;
+    thumbnailUrl: string;
+}
+export interface BeginPublishResponse {
+    signedUrl: string;
+    key: string;
+    publishVersion: number;
+    metaBlock: string;
+    cacheControl: string;
+}
+export declare function beginPublish(environment: Environment, accessToken: string, body: BeginPublishRequest, deps: ApiDeps): Promise<BeginPublishResponse>;
+export interface CompletePublishRequest {
+    gameId: string;
+    key: string;
+    publishVersion: number;
+    visibility: 'public' | 'private';
+    name?: string;
+    description?: string;
+    thumbnailUrl: string;
+    bundleBytes: number;
+    sha256: string;
+    /**
+     * The audit trail the spec calls for: `engineVersion`, `fingerprint` and `sha256` recorded
+     * together for the publish that actually landed. All three are declarative — the server logs
+     * them, it does not verify them (there is no column for any of them today, and verifying the
+     * hash would mean reading bytes this design deliberately never reads).
+     *
+     * `engineVersion` is NOT a second floor gate. It cannot be: `begin` is the only step that
+     * mints the signed URL, so its floor check is already unavoidable, and a value re-declared
+     * here proves nothing about what the bundle was built with. It is sent so the log line that
+     * records a publish says which engine produced it — without it, the only record of a bundle's
+     * engine is a `begin` log entry that may belong to an abandoned attempt.
+     *
+     * `fingerprint` is the same hash `verify` recorded and `publish` gated on, so a support
+     * question about a published bundle can be tied back to the exact project state that produced
+     * it. Nothing else on the wire identifies the source.
+     */
+    engineVersion: string;
+    fingerprint: string;
+}
+export interface CompletePublishResponse {
+    url: string;
+    publishVersion: number;
+    visibility: 'public' | 'private';
+}
+export declare function completePublish(environment: Environment, accessToken: string, body: CompletePublishRequest, deps: ApiDeps): Promise<CompletePublishResponse>;
+/**
+ * `begin` always signs `text/html` for the entry HTML (cli-publish.ts's `getSignedUrl` call) but
+ * does not echo a `contentType` field back in its response — there is nothing to echo, so this
+ * fixed value is the one Content-Type that can ever be correct for the PUT.
+ */
+export declare const PUBLISH_BUNDLE_CONTENT_TYPE = "text/html";
+/** PUT the built (and meta-block-injected) bundle to the signed URL `begin` minted. */
+export declare function putBundle(signedUrl: string, html: string, cacheControl: string, deps: ApiDeps): Promise<void>;
+export interface ThumbnailUploadRequest {
+    gameId: string;
+    filename: string;
+    contentType: string;
+}
+/** `cli-uploads.ts`'s `generateUploadSignedUrl` response shape, the fields this lane uses. */
+export interface ThumbnailUploadUrl {
+    signedUrl: string;
+    publicUrl: string;
+    cacheControl: string;
+    contentEncoding?: string;
+}
+export declare function requestThumbnailUploadUrl(environment: Environment, accessToken: string, body: ThumbnailUploadRequest, deps: ApiDeps): Promise<ThumbnailUploadUrl>;
+/**
+ * PUT the thumbnail bytes to the signed URL `requestThumbnailUploadUrl` minted. `contentType` is
+ * the SAME value this lane requested (the server never echoes it back — see
+ * `PUBLISH_BUNDLE_CONTENT_TYPE`'s doc comment for why that is fine: the caller already knows it),
+ * while `cacheControl` and `contentEncoding` are read back from the signed-URL response, because
+ * the server — not this lane — decides both.
+ */
+export declare function putThumbnail(signed: ThumbnailUploadUrl, bytes: Uint8Array, contentType: string, deps: ApiDeps): Promise<void>;

package/dist/publish/client.js

@@ -0,0 +1,150 @@
+/**
+ * The HTTP client for `bitmagic publish`: the two authorizing calls to api-server
+ * (`publish/begin`, `publish/complete`), the thumbnail's signed-upload lane
+ * (`uploads/signed-url`, the same route `forge/upload-proxy.ts` bridges for the browser), and the
+ * two raw PUTs against the signed GCS URLs those calls mint.
+ *
+ * `publishExitCode` is the one status→exit-code mapping every call above shares, so `publish.ts`
+ * never has to duplicate the 401/403/409 distinctions per call site.
+ */
+import { CliError } from '../errors.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringField(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+async function readJsonBody(response) {
+    try {
+        const parsed = await response.json();
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * One status→exit-code mapping for both publish calls.
+ *
+ * The distinction that matters is 4 vs 5: "your engine is too old" is self-serve
+ * (`bitmagic upgrade`), while a ban or an ownership mismatch is not. An agent that cannot
+ * tell them apart will either loop on upgrade or give up on a fixable problem.
+ */
+export function publishExitCode(status, body) {
+    if (status === 401)
+        return 2;
+    if (status === 403)
+        return 5;
+    if (status === 409 && body.code === 'engine-below-floor')
+        return 4;
+    return 6;
+}
+/**
+ * POST `path` as JSON with a bearer token, and map a non-2xx response through `publishExitCode`.
+ * Shared by every authenticated JSON call this module makes — begin, complete, and the thumbnail
+ * signed-URL mint — so the three cannot drift on how a failure is reported.
+ */
+async function postJson(url, accessToken, body, deps) {
+    let response;
+    try {
+        response = await deps.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        // A transport failure and an error status send people to very different places.
+        throw new CliError(`Cannot reach api-server at ${url}.`, 6);
+    }
+    // A 2xx response MUST parse as a JSON object — this is the one branch that feeds its result
+    // straight back to the caller as `T` with no further validation (`beginPublish`'s `signedUrl`,
+    // `completePublish`'s `url`, ...). Falling back to `{}` here the way the error branch below
+    // does would silently turn a malformed 200 into every field of `T` being `undefined` — e.g. a
+    // PUT sent to the literal string `"undefined"` — instead of a clear failure at the point the
+    // bad response actually arrived.
+    if (response.ok) {
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw new CliError(`api-server returned a ${response.status} from ${url} with a body that is not valid JSON.`, 6);
+        }
+        if (!isRecord(parsed)) {
+            throw new CliError(`api-server returned an unexpected response shape from ${url}.`, 6);
+        }
+        return parsed;
+    }
+    // The error path can tolerate an unparsable/absent body — the fallback is just a generic
+    // message, not a value silently flowing on to become someone else's `undefined`.
+    const parsedError = await readJsonBody(response);
+    const code = stringField(parsedError.code);
+    const message = stringField(parsedError.error) ?? `api-server returned HTTP ${response.status} for ${url}.`;
+    throw new CliError(message, publishExitCode(response.status, { code }));
+}
+/**
+ * Raw PUT of already-prepared bytes to a GCS V4 signed URL.
+ *
+ * `headers` must match exactly what the URL's signature bound (Cache-Control, and — for the
+ * thumbnail lane — Content-Encoding when the server chose to gzip). A mismatch is a 403 from GCS,
+ * not a stale-cache symptom; see cli-publish.ts's and cli-uploads.ts's own doc comments for why.
+ */
+async function putSignedUrl(url, body, headers, deps) {
+    let response;
+    try {
+        // `@types/node`'s ambient `Uint8Array` (generic over `ArrayBufferLike` since TS 5.7) does not
+        // structurally match this project's `BodyInit` (this tsconfig's `"DOM"` lib pulls in lib.dom's
+        // own copy, which `@types/node`'s conditional global-augmentation defers to whenever DOM
+        // globals are present — see node_modules/@types/node/web-globals/fetch.d.ts). Deriving the
+        // body type from `Parameters<typeof fetch>[1]` instead of naming `BodyInit` was tried and hits
+        // the identical mismatch, because it resolves to the same lib.dom type in THIS project. Both a
+        // `string` and a `Uint8Array` are valid `fetch` bodies at runtime regardless.
+        response = await deps.fetch(url, { method: 'PUT', headers, body: body });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Could not upload to storage: ${message}`, 6);
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new CliError(`Upload to storage failed: HTTP ${response.status}${text ? ` — ${text.slice(0, 200)}` : ''}`, 6);
+    }
+}
+export async function beginPublish(environment, accessToken, body, deps) {
+    return postJson(`${environment.apiUrl}/api/cli/v1/publish/begin`, accessToken, body, deps);
+}
+export async function completePublish(environment, accessToken, body, deps) {
+    return postJson(`${environment.apiUrl}/api/cli/v1/publish/complete`, accessToken, body, deps);
+}
+/**
+ * `begin` always signs `text/html` for the entry HTML (cli-publish.ts's `getSignedUrl` call) but
+ * does not echo a `contentType` field back in its response — there is nothing to echo, so this
+ * fixed value is the one Content-Type that can ever be correct for the PUT.
+ */
+export const PUBLISH_BUNDLE_CONTENT_TYPE = 'text/html';
+/** PUT the built (and meta-block-injected) bundle to the signed URL `begin` minted. */
+export async function putBundle(signedUrl, html, cacheControl, deps) {
+    await putSignedUrl(signedUrl, html, { 'Content-Type': PUBLISH_BUNDLE_CONTENT_TYPE, 'Cache-Control': cacheControl }, deps);
+}
+export async function requestThumbnailUploadUrl(environment, accessToken, body, deps) {
+    return postJson(`${environment.apiUrl}/api/cli/v1/uploads/signed-url`, accessToken, body, deps);
+}
+/**
+ * PUT the thumbnail bytes to the signed URL `requestThumbnailUploadUrl` minted. `contentType` is
+ * the SAME value this lane requested (the server never echoes it back — see
+ * `PUBLISH_BUNDLE_CONTENT_TYPE`'s doc comment for why that is fine: the caller already knows it),
+ * while `cacheControl` and `contentEncoding` are read back from the signed-URL response, because
+ * the server — not this lane — decides both.
+ */
+export async function putThumbnail(signed, bytes, contentType, deps) {
+    const headers = { 'Content-Type': contentType, 'Cache-Control': signed.cacheControl };
+    if (signed.contentEncoding)
+        headers['Content-Encoding'] = signed.contentEncoding;
+    await putSignedUrl(signed.signedUrl, bytes, headers, deps);
+}
+//# sourceMappingURL=client.js.map

package/dist/publish/client.js.map

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

package/dist/publish/fingerprint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A relative path as the fingerprint hashes it: always forward-slashed.
+ *
+ * `sep` is a parameter rather than a direct `path.sep` read so this is testable on any
+ * platform — the Windows behaviour that makes normalization necessary cannot otherwise be
+ * exercised on the POSIX runners CI uses, which is exactly how a vacuous test gets written.
+ */
+export declare function toPosixPath(relativePath: string, sep?: string): string;
+/**
+ * A hash of everything that determines the published bundle.
+ *
+ * This is what lets `publish` decide whether a `verify` is too stale to trust, by CONTENT
+ * rather than by clock: a timestamp policy would accept an edit made one second after
+ * verifying and reject an untouched project that merely sat overnight.
+ *
+ * The path is hashed alongside the content so that moving a file — which changes what the
+ * bundle imports — changes the fingerprint even though no byte of any file did.
+ *
+ * Kept deliberately coarse (every tracked file, not a module graph): a false "stale" costs one
+ * `bitmagic verify`, while a false "fresh" ships an unverified bundle.
+ *
+ * Any filesystem error (unreadable directory, permission denied, etc.) propagates immediately
+ * rather than being silently omitted: the project source is the creator's own files, so an
+ * unreadable subtree is a real problem worth surfacing, not something to hide. An omitted
+ * directory would produce a fingerprint that matches a stale project — the costly failure mode.
+ */
+export declare function computeFingerprint(root: string): string;

package/dist/publish/fingerprint.js

@@ -0,0 +1,84 @@
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Directories whose contents never change what the bundle contains: our own artifacts
+ * (`.bitmagic/`, `dist/`), the dependency tree (`node_modules/` — pinned by the lockfile the
+ * scaffold writes), vite's cache, and git's object store. Including any of them would make the
+ * fingerprint change on something other than an edit, which would make the staleness gate reject
+ * a publish of an unchanged project.
+ *
+ * `.git` is the one that bit in practice. Hashing it means an EMPTY `git commit` — no source
+ * change at all — flips the fingerprint, because the commit writes new objects, a new ref value
+ * and a new reflog entry. That turns the ordinary `bitmagic verify` → `git commit` →
+ * `bitmagic publish` sequence into exit 3 ("The project has changed since it was last verified"),
+ * and `bitmagic upgrade` actively pushes creators into git by refusing a dirty tree. The
+ * scaffolded AGENTS.md's "do not edit any tracked file between verifying and publishing" cannot
+ * prevent it either: committing is not editing. It also made every publish rebuild, since the
+ * build manifest's own recorded fingerprint could never still match by the time publish ran.
+ *
+ * `.DS_Store` is excluded for the same reason at file granularity: on macOS, Finder writes it
+ * merely for opening the project folder, and no build tool ever reads it — so it is another way
+ * to flip the fingerprint without editing anything. It is the only excluded FILE; the list is
+ * deliberately not a general ignore mechanism, because a false "fresh" ships an unverified
+ * bundle while a false "stale" only costs one `bitmagic verify`.
+ */
+const EXCLUDED_DIRS = new Set(['.bitmagic', 'node_modules', 'dist', '.vite-cache', '.git']);
+/** See EXCLUDED_DIRS: tool-written files that can never change what the bundle contains. */
+const EXCLUDED_FILES = new Set(['.DS_Store']);
+/**
+ * A relative path as the fingerprint hashes it: always forward-slashed.
+ *
+ * `sep` is a parameter rather than a direct `path.sep` read so this is testable on any
+ * platform — the Windows behaviour that makes normalization necessary cannot otherwise be
+ * exercised on the POSIX runners CI uses, which is exactly how a vacuous test gets written.
+ */
+export function toPosixPath(relativePath, sep = path.sep) {
+    return relativePath.split(sep).join('/');
+}
+function walk(dir, root, out) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (EXCLUDED_DIRS.has(entry.name))
+                continue;
+            walk(path.join(dir, entry.name), root, out);
+        }
+        else if (entry.isFile()) {
+            if (EXCLUDED_FILES.has(entry.name))
+                continue;
+            const relPath = path.relative(root, path.join(dir, entry.name));
+            out.push(toPosixPath(relPath));
+        }
+    }
+}
+/**
+ * A hash of everything that determines the published bundle.
+ *
+ * This is what lets `publish` decide whether a `verify` is too stale to trust, by CONTENT
+ * rather than by clock: a timestamp policy would accept an edit made one second after
+ * verifying and reject an untouched project that merely sat overnight.
+ *
+ * The path is hashed alongside the content so that moving a file — which changes what the
+ * bundle imports — changes the fingerprint even though no byte of any file did.
+ *
+ * Kept deliberately coarse (every tracked file, not a module graph): a false "stale" costs one
+ * `bitmagic verify`, while a false "fresh" ships an unverified bundle.
+ *
+ * Any filesystem error (unreadable directory, permission denied, etc.) propagates immediately
+ * rather than being silently omitted: the project source is the creator's own files, so an
+ * unreadable subtree is a real problem worth surfacing, not something to hide. An omitted
+ * directory would produce a fingerprint that matches a stale project — the costly failure mode.
+ */
+export function computeFingerprint(root) {
+    const files = [];
+    walk(root, root, files);
+    files.sort();
+    const hash = createHash('sha256');
+    for (const rel of files) {
+        const content = fs.readFileSync(path.join(root, rel));
+        hash.update(`${rel}:${createHash('sha256').update(content).digest('hex')}\n`);
+    }
+    return hash.digest('hex');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/publish/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/publish/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5F,4FAA4F;AAC5F,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoB,EAAE,MAAc,IAAI,CAAC,GAAG;IACtE,OAAO,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,IAAI,CAAC,GAAW,EAAE,IAAY,EAAE,GAAa;IACpD,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACxB,KAAK,CAAC,IAAI,EAAE,CAAC;IAEb,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}

package/dist/publish/meta-block.d.ts

@@ -0,0 +1,26 @@
+import type { VerifyRunRecord } from '../verify/result.js';
+/**
+ * Put the server-issued block immediately after `<head>`, matching where the web lane puts its
+ * own meta tags — and close enough to the start of the file that the server's 64KB range read
+ * always covers it.
+ *
+ * String insertion, not DOM parsing: this HTML carries the whole inlined engine.
+ */
+export declare function injectMetaBlock(html: string, block: string): string;
+export type VerifyGate = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * May this project be published?
+ *
+ * Three distinct answers, deliberately: "never verified", "verified then edited", and "verified
+ * and broken" have three different fixes, and collapsing them into "run verify" is how an agent
+ * ends up looping verify against a game that is genuinely broken.
+ *
+ * `force` overrides the VERDICT and STALENESS, not the existence of a record: the thumbnail comes
+ * from the verify screenshot, so with no verify there is nothing to publish a thumbnail from.
+ */
+export declare function checkVerifyGate(record: VerifyRunRecord | null, fingerprint: string, force: boolean): VerifyGate;

package/dist/publish/meta-block.js

@@ -0,0 +1,48 @@
+import { CliError } from '../errors.js';
+const HEAD_OPEN = '<head>';
+/**
+ * Put the server-issued block immediately after `<head>`, matching where the web lane puts its
+ * own meta tags — and close enough to the start of the file that the server's 64KB range read
+ * always covers it.
+ *
+ * String insertion, not DOM parsing: this HTML carries the whole inlined engine.
+ */
+export function injectMetaBlock(html, block) {
+    if (html.includes('<!--bitmagic:meta:v1-->')) {
+        throw new CliError('This bundle already carries a meta block. Run `bitmagic build` again.', 6);
+    }
+    const at = html.indexOf(HEAD_OPEN);
+    if (at === -1) {
+        throw new CliError('The built bundle has no <head> to inject into.', 1);
+    }
+    const cut = at + HEAD_OPEN.length;
+    return html.slice(0, cut) + block + html.slice(cut);
+}
+/**
+ * May this project be published?
+ *
+ * Three distinct answers, deliberately: "never verified", "verified then edited", and "verified
+ * and broken" have three different fixes, and collapsing them into "run verify" is how an agent
+ * ends up looping verify against a game that is genuinely broken.
+ *
+ * `force` overrides the VERDICT and STALENESS, not the existence of a record: the thumbnail comes
+ * from the verify screenshot, so with no verify there is nothing to publish a thumbnail from.
+ */
+export function checkVerifyGate(record, fingerprint, force) {
+    if (record === null) {
+        return { ok: false, message: 'This game has not been verified. Run `bitmagic verify` first.' };
+    }
+    if (force)
+        return { ok: true };
+    if (record.fingerprint !== fingerprint) {
+        return { ok: false, message: 'The project has changed since it was last verified. Run `bitmagic verify` again.' };
+    }
+    if (!record.ok) {
+        return {
+            ok: false,
+            message: `The last verify failed:\n${record.failures.map((f) => `  ✗ ${f}`).join('\n')}\nFix these, or publish with --force.`,
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=meta-block.js.map

package/dist/publish/meta-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-block.js","sourceRoot":"","sources":["../../src/publish/meta-block.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAGxC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAAa;IACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,QAAQ,CAAC,uEAAuE,EAAE,CAAC,CAAC,CAAC;IACjG,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,QAAQ,CAAC,gDAAgD,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC;AAID;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA8B,EAC9B,WAAmB,EACnB,KAAc;IAEd,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,+DAA+D,EAAE,CAAC;IACjG,CAAC;IACD,IAAI,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,kFAAkF,EAAE,CAAC;IACpH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,4BAA4B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,uCAAuC;SAC9H,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/scaffold/dependency-diff.d.ts

@@ -0,0 +1,28 @@
+/** The subset of package.json this module reads — never the whole file. */
+export interface PackageJsonDeps {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export interface RequiredDependencies {
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+}
+export interface DependencyMismatch {
+    name: string;
+    kind: 'dependency' | 'devDependency';
+    required: string;
+    /** undefined when the package is missing from package.json entirely, not just outdated. */
+    current?: string;
+}
+/**
+ * Compares a project's declared dependencies against what the vendored engine actually needs
+ * (`DEPENDENCIES`/`DEV_DEPENDENCIES` in project-files.ts), and reports every mismatch — missing
+ * entirely, or present at a different version string.
+ *
+ * Pure and filesystem-free by design: `upgradeProject` never writes package.json (a creator's
+ * added dependencies must survive an upgrade untouched), so this is the other half of that
+ * decision — the mismatch it creates has to be *reported*, not silently left for `bitmagic build`
+ * to fail on later with an opaque module-resolution error. Kept separate from the command layer
+ * that reads package.json off disk so the comparison itself is testable without a fixture file.
+ */
+export declare function diffDependencies(pkg: PackageJsonDeps, required: RequiredDependencies): DependencyMismatch[];

package/dist/scaffold/dependency-diff.js

@@ -0,0 +1,28 @@
+/**
+ * Compares a project's declared dependencies against what the vendored engine actually needs
+ * (`DEPENDENCIES`/`DEV_DEPENDENCIES` in project-files.ts), and reports every mismatch — missing
+ * entirely, or present at a different version string.
+ *
+ * Pure and filesystem-free by design: `upgradeProject` never writes package.json (a creator's
+ * added dependencies must survive an upgrade untouched), so this is the other half of that
+ * decision — the mismatch it creates has to be *reported*, not silently left for `bitmagic build`
+ * to fail on later with an opaque module-resolution error. Kept separate from the command layer
+ * that reads package.json off disk so the comparison itself is testable without a fixture file.
+ */
+export function diffDependencies(pkg, required) {
+    const mismatches = [];
+    for (const [name, version] of Object.entries(required.dependencies)) {
+        const current = pkg.dependencies?.[name];
+        if (current !== version) {
+            mismatches.push({ name, kind: 'dependency', required: version, current });
+        }
+    }
+    for (const [name, version] of Object.entries(required.devDependencies)) {
+        const current = pkg.devDependencies?.[name];
+        if (current !== version) {
+            mismatches.push({ name, kind: 'devDependency', required: version, current });
+        }
+    }
+    return mismatches;
+}
+//# sourceMappingURL=dependency-diff.js.map

package/dist/scaffold/dependency-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-diff.js","sourceRoot":"","sources":["../../src/scaffold/dependency-diff.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAoB,EAAE,QAA8B;IACnF,MAAM,UAAU,GAAyB,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACvE,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/scaffold/project-files.d.ts

@@ -1,7 +1,29 @@
+/**
+ * Mirrors game/package.json so the pro lane resolves exactly what CI builds against.
+ *
+ * Exported so `bitmagic upgrade` can diff a project's actual package.json against what the
+ * vendored engine currently needs — package.json itself is never rewritten (see
+ * PLATFORM_GENERATED_FILES in project.ts), so this is the only source of truth upgrade has for
+ * telling a creator what to add by hand.
+ */
+export declare const DEPENDENCIES: Record<string, string>;
+export declare const DEV_DEPENDENCIES: Record<string, string>;
 export declare function renderPackageJson(name: string): string;
 export declare function renderTsconfig(): string;
 export declare function renderIndexHtml(): string;
 export declare function renderViteConfig(): string;
+/**
+ * The production bundle config, vendored into the project next to `engine/`.
+ *
+ * One self-contained HTML: `viteSingleFile` with an effectively unlimited inline limit, so the
+ * engine and all JS/CSS land inside index.html. Game ASSETS are deliberately NOT inlined — they
+ * already live on the CDN with absolute URLs, and inlining them is what produced multi-hundred-MB
+ * bundles and OOM-killed the web publish pod.
+ *
+ * Vendored rather than generated per-build so a creator can read exactly what ships, and so it
+ * versions with the engine it was written for.
+ */
+export declare function renderVitePublishConfig(): string;
 export declare function renderGitignore(): string;
 export interface ProjectMetadata {
     gameId: string;