@mpgd/cli 0.31.0 → 0.32.0

package/dist/asset-pack-zip.d.ts

@@ -0,0 +1,19 @@
+/**
+* Deterministic ZIP writer for pack delivery archives. The builder targets
+* this limited format only: STORE and DEFLATE entries, no ZIP64, no split
+* archives, no encryption, no directory or symlink entries, no comments.
+* Fixed metadata: DOS timestamp 1980-01-01 00:00:00, UNIX permissions 0644,
+* UTF-8 name flag, no extra fields. Given the same entries in the same order
+* and the same Node/zlib build, the produced bytes are identical.
+*/
+export interface DeterministicZipEntry {
+  /** Normalized relative entry path; validated by the pack format module. */
+  readonly path: string;
+  /** Uncompressed entry bytes. */
+  readonly data: Buffer;
+  readonly method: 'store' | 'deflate';
+  /** Precomputed stored bytes for the entry method, when the builder already
+  * produced them (for example while choosing the method). */
+  readonly stored?: Buffer | undefined;
+}
+export declare function createDeterministicZip(entries: readonly DeterministicZipEntry[]): Buffer;

package/dist/asset-pack-zip.js

@@ -0,0 +1,81 @@
+import { crc32, deflateRawSync } from 'node:zlib';
+const DOS_TIME = 0;
+const DOS_DATE = 0x0021;
+const VERSION_NEEDED = 20;
+const VERSION_MADE_BY = 0x0300;
+const UTF8_FLAG = 0x0800;
+const EXTERNAL_ATTRIBUTES = (0o100644 << 16) >>> 0;
+const MAX_ENTRIES = 0xffff;
+const MAX_ENTRY_BYTES = 0xffffffff;
+export function createDeterministicZip(entries) {
+    if (entries.length === 0 || entries.length > MAX_ENTRIES) {
+        throw new Error(`Deterministic ZIP requires 1..${MAX_ENTRIES} entries`);
+    }
+    const localChunks = [];
+    const centralChunks = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.path, 'utf8');
+        if (name.length > MAX_ENTRIES) {
+            throw new Error(`Deterministic ZIP entry name exceeds 65535 bytes: ${entry.path}`);
+        }
+        if (entry.data.length > MAX_ENTRY_BYTES) {
+            throw new Error(`Deterministic ZIP entry exceeds 4 GiB: ${entry.path}`);
+        }
+        const compressed = entry.method === 'deflate'
+            ? (entry.stored ?? deflateRawSync(entry.data, { level: 9 }))
+            : entry.data;
+        if (compressed.length > MAX_ENTRY_BYTES) {
+            throw new Error(`Deterministic ZIP entry exceeds 4 GiB: ${entry.path}`);
+        }
+        const methodCode = entry.method === 'deflate' ? 8 : 0;
+        const digest = crc32(entry.data) >>> 0;
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(VERSION_NEEDED, 4);
+        local.writeUInt16LE(UTF8_FLAG, 6);
+        local.writeUInt16LE(methodCode, 8);
+        local.writeUInt16LE(DOS_TIME, 10);
+        local.writeUInt16LE(DOS_DATE, 12);
+        local.writeUInt32LE(digest, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(entry.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        localChunks.push(local, name, compressed);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(VERSION_MADE_BY, 4);
+        central.writeUInt16LE(VERSION_NEEDED, 6);
+        central.writeUInt16LE(UTF8_FLAG, 8);
+        central.writeUInt16LE(methodCode, 10);
+        central.writeUInt16LE(DOS_TIME, 12);
+        central.writeUInt16LE(DOS_DATE, 14);
+        central.writeUInt32LE(digest, 16);
+        central.writeUInt32LE(compressed.length, 20);
+        central.writeUInt32LE(entry.data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt16LE(0, 30);
+        central.writeUInt16LE(0, 32);
+        central.writeUInt16LE(0, 34);
+        central.writeUInt16LE(0, 36);
+        central.writeUInt32LE(EXTERNAL_ATTRIBUTES, 38);
+        central.writeUInt32LE(offset, 42);
+        centralChunks.push(central, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    const centralDirectory = Buffer.concat(centralChunks);
+    if (offset > MAX_ENTRY_BYTES || centralDirectory.length > MAX_ENTRY_BYTES) {
+        throw new Error('Deterministic ZIP archive exceeds 4 GiB');
+    }
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(0, 4);
+    end.writeUInt16LE(0, 6);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralDirectory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    end.writeUInt16LE(0, 20);
+    return Buffer.concat([...localChunks, centralDirectory, end]);
+}

package/dist/bin.js

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
-import { readCliArgs, runMpgdCli } from './index.js';
+import { mpgdCliNeedsForcedExit, readCliArgs, runMpgdCli } from './index.js';
 await runMpgdCli(readCliArgs());
+if (mpgdCliNeedsForcedExit()) {
+    // Stalled threadpool filesystem work cannot be cancelled; only the
+    // standalone binary may terminate the process to outrun it.
+    process.exit(process.exitCode ?? 1);
+}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { createMicrosoftStorePackageAcceptanceRuntime, microsoftStorePackageAcce
 export { createMicrosoftStorePackageGenerationRuntime, microsoftStorePackageGeneratorEndpoint, microsoftStorePackageGeneratorSourceRevision, microsoftStorePackageGenerationSchemaVersion, renderMicrosoftStorePackageGenerationMarkdown, runMicrosoftStorePackageGeneration, type CreateMicrosoftStorePackageGenerationRuntimeInput, type MicrosoftStoreAddressResolver, type MicrosoftStorePackageGenerationEvidence, type MicrosoftStorePackageGenerationRuntime, type MicrosoftStoreResolvedAddress, type RunMicrosoftStorePackageGenerationInput, } from './microsoft-store-package-generation.js';
 export { microsoftStoreSubmissionSchemaVersion, parseMicrosoftStoreSubmissionConfig, renderMicrosoftStoreSubmissionMarkdown, runMicrosoftStoreSubmissionPreflight, type MicrosoftStoreSubmissionConfig, type MicrosoftStoreSubmissionCommerce, type MicrosoftStoreSubmissionCommerceProduct, type MicrosoftStoreSubmissionEvidence, type RunMicrosoftStoreSubmissionPreflightInput, } from './microsoft-store-submission.js';
 export { assertProductionTargetReadiness, type ProductionTargetReadinessInput, } from './production-target-readiness.js';
+export declare function mpgdCliNeedsForcedExit(): boolean;
 export declare function runMpgdCli(args: readonly string[]): Promise<void>;
 export declare function runCreateGameCli(args: readonly string[]): Promise<void>;
 export declare function readCliArgs(): readonly string[];

package/dist/index.js

@@ -6,6 +6,8 @@ import completion from '@gunshi/plugin-completion';
 import i18n, { defineI18n } from '@gunshi/plugin-i18n';
 import resources from '@gunshi/resources';
 import { cli } from 'gunshi';
+import { buildAssetPacks } from './asset-pack-build.js';
+import { verifyAssetPackDelivery } from './asset-pack-verify.js';
 import { normalizeConfiguredBuildTargets, normalizeBuildTarget as normalizeConfiguredTargetName, supportedBuildTargets, } from './build-targets.js';
 import { escapeMarkdownInline as escapeEvidenceMarkdownInline, writeEvidenceReportFiles, } from './evidence-io.js';
 import { defaultGameAcceptanceCommandTimeoutMs, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, } from './game-acceptance.js';
@@ -85,11 +87,71 @@ const acceptanceStepIds = {
     targetSmoke: 'target-smoke',
     gameplayE2E: 'gameplay-e2e',
 };
+/** Whether the last run reported a deadline failure that leaves
+ * uncancellable filesystem work pending: the standalone binary forces its
+ * exit (see bin.ts); in-process library callers handle it themselves. */
+let forcedExitPending = false;
+/** A blocked pipe must not prevent the standalone binary from reaching its
+ * forced-exit path after a deadline report. The callback may remain queued
+ * behind a stalled reader, so the drain is best effort and bounded. */
+const CLI_OUTPUT_DRAIN_TIMEOUT_MS = 250;
+const drainOutput = (stream) => new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        resolve();
+    };
+    const timer = setTimeout(finish, CLI_OUTPUT_DRAIN_TIMEOUT_MS);
+    try {
+        stream.write('', () => {
+            clearTimeout(timer);
+            finish();
+        });
+    }
+    catch {
+        clearTimeout(timer);
+        finish();
+    }
+});
+export function mpgdCliNeedsForcedExit() {
+    return forcedExitPending;
+}
 export async function runMpgdCli(args) {
+    forcedExitPending = false;
     await cli([...args], entryCommand, {
         name: 'mpgd',
         version: cliVersion,
+        // Machine-readable mode contract: `assets verify-delivery --json`
+        // owns stdout entirely — exactly one JSON document, parseable with
+        // JSON.parse(stdout) and nothing else. The framework's banner is
+        // suppressed for that command, and framework-level argument errors
+        // (bad value types, missing required arguments — rejected before the
+        // command handler runs) move to stderr so stdout never carries a
+        // partial document. Every other command keeps the default rendering.
+        renderHeader: async (ctx) => {
+            const values = ctx.values;
+            if (ctx.name === 'verify-delivery' && values.json === true) {
+                return '';
+            }
+            const title = ctx.env.description || ctx.env.name || '';
+            return title
+                ? `${title} (${ctx.env.name || ''}${ctx.env.version ? ` v${ctx.env.version}` : ''})`
+                : title;
+        },
+        renderValidationErrors: async (ctx, error) => {
+            const messages = error.errors.map((entry) => String(entry.message)).join('\n');
+            const values = ctx.values;
+            if (ctx.name === 'verify-delivery' && values.json === true) {
+                process.stderr.write(`${messages}\n`);
+                return '';
+            }
+            return messages;
+        },
         subCommands: {
+            assets: assetsCommand,
             game: gameCommand,
             legal: legalCommand,
             target: targetCommand,
@@ -143,7 +205,7 @@ const entryCommand = defineI18n({
         ko: 'mpgd-kit 스타터와 타깃 워크플로우를 관리합니다.',
     }),
     run: () => {
-        console.info('Use a sub-command: game, target, kit.');
+        console.info('Use a sub-command: assets, game, legal, target, kit.');
         console.info('Run "pnpm mpgd --help" for available commands.');
     },
 });
@@ -774,6 +836,226 @@ function readPositiveInteger(value, label) {
     }
     return parsed;
 }
+function assetPackVerifyArgs() {
+    return {
+        manifest: {
+            type: 'string',
+            required: true,
+            description: 'Path to the delivery manifest JSON document.',
+        },
+        root: {
+            type: 'string',
+            required: true,
+            description: 'Deployment root the manifest artifact paths resolve against.',
+        },
+        json: {
+            type: 'boolean',
+            required: false,
+            description: 'Print a single machine-readable JSON report to stdout.',
+        },
+        'max-object-bytes': {
+            type: 'number',
+            required: false,
+            description: 'Optional static-host limit: largest allowed deployed object in bytes.',
+        },
+        'max-files': {
+            type: 'number',
+            required: false,
+            description: 'Optional static-host limit: total regular files allowed under the root.',
+        },
+        'max-total-bytes': {
+            type: 'number',
+            required: false,
+            description: 'Optional static-host limit: total deployed bytes allowed under the root.',
+        },
+        'max-archive-bytes': {
+            type: 'number',
+            required: false,
+            description: 'Optional cap: largest zip archive read for verification, in bytes.',
+        },
+        'max-entry-bytes': {
+            type: 'number',
+            required: false,
+            description: 'Optional cap: largest expanded zip entry allowed, in bytes.',
+        },
+        'max-expanded-bytes': {
+            type: 'number',
+            required: false,
+            description: 'Optional cap: total expanded bytes allowed per archive, in bytes.',
+        },
+    };
+}
+function assetPackBuildArgs() {
+    return {
+        config: {
+            type: 'string',
+            required: true,
+            description: 'Path to the asset pack build config JSON file.',
+        },
+        out: {
+            type: 'string',
+            required: true,
+            description: 'Output directory for delivery artifacts, outside the source root.',
+        },
+    };
+}
+const assetsCommand = defineI18n({
+    name: 'assets',
+    description: 'Build deterministic asset pack delivery artifacts.',
+    resource: commandResource({
+        en: 'Build deterministic asset pack delivery artifacts.',
+        ko: '결정적인 에셋 팩 전달 산출물을 빌드합니다.',
+    }),
+    subCommands: {
+        'build-packs': defineI18n({
+            name: 'build-packs',
+            description: 'Build files or ZIP delivery artifacts for configured packs.',
+            resource: commandResource({
+                en: 'Build files or ZIP delivery artifacts for configured packs.',
+                ko: '설정된 팩의 files 또는 ZIP 전달 산출물을 빌드합니다.',
+            }, {
+                config: {
+                    en: 'Path to the asset pack build config JSON file.',
+                    ko: '에셋 팩 빌드 설정 JSON 파일 경로.',
+                },
+                out: {
+                    en: 'Output directory for delivery artifacts, outside the source root.',
+                    ko: '전달 산출물 출력 디렉터리. 소스 루트 밖이어야 합니다.',
+                },
+            }),
+            args: assetPackBuildArgs(),
+            run: (ctx) => {
+                const report = buildAssetPacks({
+                    configPath: ctx.values.config,
+                    outDir: ctx.values.out,
+                });
+                for (const output of report.outputs) {
+                    console.info(`${output.action === 'written' ? 'wrote' : 'unchanged'} ${output.path} `
+                        + `(${output.bytes} bytes, sha256:${output.sha256})`);
+                }
+                for (const archive of report.archives) {
+                    console.info(`archive ${archive.path}: ${archive.entryCount} entries `
+                        + `(${archive.storeEntries} store, ${archive.deflateEntries} deflate), `
+                        + `sources ${archive.sourceBytes} bytes, archive ${archive.archiveBytes} bytes, `
+                        + `sha256:${archive.sha256}`);
+                }
+                console.info(`Asset pack delivery manifest: ${report.manifestPath}`);
+            },
+        }),
+        'verify-delivery': defineI18n({
+            name: 'verify-delivery',
+            description: 'Verify delivery artifacts read-only against the manifest.',
+            resource: commandResource({
+                en: 'Verify delivery artifacts read-only against the manifest.',
+                ko: '전달 산출물을 manifest 기준으로 읽기 전용으로 검증합니다.',
+            }, {
+                manifest: {
+                    en: 'Path to the delivery manifest JSON document.',
+                    ko: '전달 manifest JSON 문서 경로.',
+                },
+                root: {
+                    en: 'Deployment root the manifest artifact paths resolve against.',
+                    ko: 'manifest 산출물 경로의 기준이 되는 배포 루트 디렉터리.',
+                },
+                json: {
+                    en: 'Print a single machine-readable JSON report to stdout.',
+                    ko: '기계 판독 가능한 JSON 보고서 하나를 stdout에 출력합니다.',
+                },
+                'max-object-bytes': {
+                    en: 'Optional static-host limit: largest allowed deployed object in bytes.',
+                    ko: '선택적 정적 호스트 한도: 허용되는 최대 배포 object 바이트 수.',
+                },
+                'max-files': {
+                    en: 'Optional static-host limit: total regular files allowed under the root.',
+                    ko: '선택적 정적 호스트 한도: 루트 아래 허용되는 일반 파일 총 개수.',
+                },
+                'max-total-bytes': {
+                    en: 'Optional static-host limit: total deployed bytes allowed under the root.',
+                    ko: '선택적 정적 호스트 한도: 루트 아래 허용되는 총 배포 바이트 수.',
+                },
+                'max-archive-bytes': {
+                    en: 'Optional cap: largest zip archive read for verification, in bytes.',
+                    ko: '선택적 상한: 검증 시 읽는 zip 아카이브의 최대 바이트 수.',
+                },
+                'max-entry-bytes': {
+                    en: 'Optional cap: largest expanded zip entry allowed, in bytes.',
+                    ko: '선택적 상한: 허용되는 확장(zip 해제) 엔트리 최대 바이트 수.',
+                },
+                'max-expanded-bytes': {
+                    en: 'Optional cap: total expanded bytes allowed per archive, in bytes.',
+                    ko: '선택적 상한: 아카이브별 허용되는 총 확장 바이트 수.',
+                },
+            }),
+            args: assetPackVerifyArgs(),
+            run: async (ctx) => {
+                const hostLimits = {
+                    ...(ctx.values['max-object-bytes'] === undefined
+                        ? {}
+                        : { maxObjectBytes: ctx.values['max-object-bytes'] }),
+                    ...(ctx.values['max-files'] === undefined
+                        ? {}
+                        : { maxFiles: ctx.values['max-files'] }),
+                    ...(ctx.values['max-total-bytes'] === undefined
+                        ? {}
+                        : { maxTotalBytes: ctx.values['max-total-bytes'] }),
+                };
+                const report = await verifyAssetPackDelivery({
+                    manifestPath: ctx.values.manifest,
+                    root: ctx.values.root,
+                    ...(Object.keys(hostLimits).length > 0 ? { hostLimits } : {}),
+                    ...(ctx.values['max-archive-bytes'] === undefined
+                        ? {}
+                        : { maxArchiveBytes: ctx.values['max-archive-bytes'] }),
+                    ...(ctx.values['max-entry-bytes'] === undefined
+                        ? {}
+                        : { maxEntryBytes: ctx.values['max-entry-bytes'] }),
+                    ...(ctx.values['max-expanded-bytes'] === undefined
+                        ? {}
+                        : { maxExpandedBytes: ctx.values['max-expanded-bytes'] }),
+                });
+                if (ctx.values.json === true) {
+                    console.info(JSON.stringify(report, null, 2));
+                }
+                else {
+                    for (const archive of report.archives) {
+                        console.info(`verified archive ${archive.packId}: ${archive.entries} entries, ${archive.expandedBytes} expanded bytes`);
+                    }
+                    console.info(`manifest ${report.manifest.sha256.slice(0, 12)}… (${report.manifest.bytes} bytes, ${report.manifest.packs} packs)`);
+                    console.info(`referenced objects: ${report.referenced.files} files, ${report.referenced.bytes} bytes`);
+                    if (report.inventory !== undefined) {
+                        console.info(`root inventory: ${report.inventory.files} files, ${report.inventory.bytes} bytes${report.inventory.truncated ? ' (truncated)' : ''}`);
+                    }
+                    for (const failure of report.failures) {
+                        console.error(`[${failure.stage}/${failure.code}] ${failure.message}`);
+                    }
+                    if (report.ok) {
+                        console.info('Delivery verification passed.');
+                    }
+                    else {
+                        console.error('Delivery verification failed; see the failures above.');
+                    }
+                }
+                if (report.failures.some((failure) => failure.code === 'deadline')) {
+                    // Piped console output is asynchronous; drain both streams so a
+                    // large report is not truncated by the binary's forced exit.
+                    await Promise.all([drainOutput(process.stdout), drainOutput(process.stderr)]);
+                    // Stalled filesystem requests cannot be cancelled once the
+                    // deadline fires; the standalone binary forces its exit so a
+                    // pending threadpool call cannot keep the process (and its
+                    // leaked handle) alive past the reported budget. In-process
+                    // callers of runMpgdCli observe mpgdCliNeedsForcedExit instead.
+                    forcedExitPending = true;
+                }
+                if (!report.ok) {
+                    process.exitCode = 1;
+                }
+            },
+        }),
+    },
+    run: () => {
+        console.info('Use "mpgd assets build-packs" or "mpgd assets verify-delivery".');
+    },
+});
 const legalCommand = defineI18n({
     name: 'legal',
     description: 'Build static legal/support pages for store and release evidence.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -46,25 +46,25 @@
     "entities": "^8.0.0",
     "esbuild": "^0.28.1",
     "gunshi": "^0.35.1",
-    "undici": "^7.28.0"
+    "undici": "^7.28.0",
+    "@mpgd/phaser-assets": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.12.1",
+    "@mpgd/adapter-browser": "0.7.3",
     "@mpgd/adapter-capacitor": "0.4.10",
-    "@mpgd/adapter-verse8": "0.3.6",
     "@mpgd/adapter-devvit": "0.9.8",
-    "@mpgd/adapter-browser": "0.7.3",
-    "@mpgd/analytics": "0.3.12",
-    "@mpgd/catalog": "0.7.2",
-    "@mpgd/game-services": "0.15.1",
+    "@mpgd/adapter-ait": "0.12.1",
+    "@mpgd/adapter-verse8": "0.3.6",
     "@mpgd/bridge": "0.9.0",
-    "@mpgd/phaser-assets": "0.5.0",
+    "@mpgd/catalog": "0.7.2",
+    "@mpgd/i18n": "0.6.1",
     "@mpgd/platform": "0.12.0",
+    "@mpgd/game-services": "0.15.1",
     "@mpgd/target-config": "0.15.0",
-    "@mpgd/i18n": "0.6.1"
+    "@mpgd/analytics": "0.3.12"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",