@mpgd/cli 0.39.0 → 0.41.0

package/dist/asset-pack-target.js

@@ -0,0 +1,251 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { validatePhaserPackBuildConfig, validatePhaserPackDeliveryManifest, } from '@mpgd/phaser-assets/pack-format';
+import { assertAssetPackTargetPolicy, resolveAssetPackLocations, } from '@mpgd/target-config/asset-packs';
+import { buildAssetPacks } from './asset-pack-build.js';
+import { verifyAssetPackDelivery } from './asset-pack-verify.js';
+export const assetPackTargetNamespace = 'mpgd-asset-packs';
+export const assetPackTargetManifestName = 'asset-pack-delivery.json';
+export const assetPackTargetPolicyName = 'target-policy.json';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function fileDigest(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+function inside(parent, child) {
+    const step = relative(parent, child);
+    return step === '' || (!isAbsolute(step) && step !== '..' && !step.startsWith(`..${sep}`));
+}
+async function noSymlink(path) {
+    let current = resolve(path);
+    while (true) {
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        });
+        if (stat?.isSymbolicLink()) {
+            // macOS exposes its system temporary directories through these fixed
+            // aliases. Accept only their canonical OS targets, never user links.
+            const systemAlias = process.platform === 'darwin'
+                && ((current === '/var' && await realpath(current) === '/private/var')
+                    || (current === '/tmp' && await realpath(current) === '/private/tmp'));
+            if (!systemAlias) {
+                throw new Error(`Asset target path must not traverse a symbolic link: ${path}`);
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+async function canonicalOutput(path) {
+    let ancestor = path;
+    while (true) {
+        try {
+            const canonical = await realpath(ancestor);
+            return resolve(canonical, relative(ancestor, path));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+            const parent = dirname(ancestor);
+            if (parent === ancestor) {
+                throw error;
+            }
+            ancestor = parent;
+        }
+    }
+}
+/** Stage verified immutable objects into disjoint packaged/remote roots.
+ * The output must not exist: a failed attempt never replaces a deployment. */
+export async function stageAssetPackTarget(options) {
+    await noSymlink(options.root);
+    await noSymlink(options.manifestPath);
+    const root = await realpath(resolve(options.root));
+    await noSymlink(options.outDir);
+    const out = await canonicalOutput(resolve(options.outDir));
+    if (inside(root, out) || inside(out, root)) {
+        throw new Error('Asset target output must be disjoint from the delivery source root');
+    }
+    if (await lstat(out).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    })) {
+        throw new Error('Asset target output already exists; choose a fresh deployment directory');
+    }
+    const verified = await verifyAssetPackDelivery({
+        manifestPath: options.manifestPath,
+        root,
+        hostLimits: { maxFiles: 100_000, maxTotalBytes: 1024 ** 3 },
+    });
+    if (!verified.ok) {
+        throw new Error(`Asset target source verification failed: ${verified.failures.map((failure) => failure.code).join(', ')}`);
+    }
+    const manifestBytes = await readFile(options.manifestPath);
+    if (digest(manifestBytes) !== verified.manifest.sha256) {
+        throw new Error('Delivery manifest changed during target staging');
+    }
+    const manifest = validatePhaserPackDeliveryManifest(JSON.parse(manifestBytes.toString('utf8')));
+    const locations = resolveAssetPackLocations(options.policy, manifest.packs);
+    const runtimePolicy = {
+        defaultLocation: 'packaged',
+        packs: locations,
+        ...(options.policy.offlineRequired === undefined ? {} : { offlineRequired: [...options.policy.offlineRequired] }),
+        ...(options.policy.remoteBaseUrl === undefined ? {} : { remoteBaseUrl: options.policy.remoteBaseUrl }),
+        ...(options.policy.maxPackagedBytes === undefined ? {} : { maxPackagedBytes: options.policy.maxPackagedBytes }),
+    };
+    const policyBytes = Buffer.from(JSON.stringify(runtimePolicy, null, 2) + '\n');
+    const objects = new Map();
+    for (const pack of manifest.packs) {
+        const files = pack.delivery === 'zip'
+            ? [pack.archive]
+            : pack.assets.flatMap((asset) => asset.files);
+        for (const file of files) {
+            const location = locations[pack.packId];
+            objects.set(`${location}:${file.path}`, {
+                path: file.path,
+                bytes: file.bytes,
+                sha256: file.sha256,
+                location,
+            });
+        }
+    }
+    const planned = [...objects.values()].sort((a, b) => a.location.localeCompare(b.location) || a.path.localeCompare(b.path));
+    const packagedAssetBytes = planned.filter((object) => object.location === 'packaged').reduce((sum, object) => sum + object.bytes, 0);
+    const packagedBytes = packagedAssetBytes + manifestBytes.length + policyBytes.length;
+    if (options.policy.maxPackagedBytes !== undefined && packagedBytes > options.policy.maxPackagedBytes) {
+        throw new Error(`Packaged asset namespace exceeds its budget: ${packagedBytes} > ${options.policy.maxPackagedBytes}`);
+    }
+    await mkdir(dirname(out), { recursive: true });
+    const temporary = await mkdtemp(join(dirname(out), '.mpgd-asset-target-'));
+    try {
+        await mkdir(join(temporary, 'packaged'));
+        await mkdir(join(temporary, 'remote'));
+        for (const object of planned) {
+            const source = join(root, object.path);
+            await noSymlink(source);
+            const destination = join(temporary, object.location, object.path);
+            await mkdir(dirname(destination), { recursive: true });
+            await copyFile(source, destination);
+            const stat = await lstat(destination);
+            if (stat.size !== object.bytes || await fileDigest(destination) !== object.sha256) {
+                throw new Error(`Asset object changed during target staging: ${object.path}`);
+            }
+        }
+        await writeFile(join(temporary, 'packaged', assetPackTargetManifestName), manifestBytes);
+        await writeFile(join(temporary, 'packaged', assetPackTargetPolicyName), policyBytes);
+        await rename(temporary, out);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return {
+        outDir: out,
+        packagedDir: join(out, 'packaged'),
+        remoteDir: join(out, 'remote'),
+        manifestSha256: verified.manifest.sha256,
+        locations,
+        packagedAssetBytes,
+        packagedBytes,
+        remoteBytes: planned.filter((object) => object.location === 'remote').reduce((sum, object) => sum + object.bytes, 0),
+        objects: planned,
+    };
+}
+/** Build from one target's policy without requiring a kit checkout. */
+export async function assertAssetPackTargetOutput(options) {
+    assertAssetPackTargetPolicy(options.policy);
+    const configPath = resolve(options.baseDir, options.policy.buildConfig);
+    const config = validatePhaserPackBuildConfig(JSON.parse(await readFile(configPath, 'utf8')));
+    const sourceRoot = await realpath(resolve(dirname(configPath), config.root));
+    await noSymlink(options.outDir);
+    const output = await canonicalOutput(resolve(options.outDir));
+    if (inside(sourceRoot, output) || inside(output, sourceRoot)) {
+        throw new Error('Asset target output must be disjoint from the original asset source root');
+    }
+    if (inside(output, await realpath(configPath))) {
+        throw new Error('Asset target output must not replace its build config');
+    }
+}
+export async function buildAssetPackTarget(options) {
+    await assertAssetPackTargetOutput(options);
+    const configPath = resolve(options.baseDir, options.policy.buildConfig);
+    const temporary = await mkdtemp(join(tmpdir(), 'mpgd-asset-source-'));
+    try {
+        const built = buildAssetPacks({
+            configPath,
+            outDir: join(temporary, 'delivery'),
+        });
+        return await stageAssetPackTarget({
+            manifestPath: built.manifestPath,
+            root: built.outDir,
+            policy: options.policy,
+            outDir: options.outDir,
+        });
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+/** Verify the real bundle's asset namespace and reject byte-identical remote
+ * objects copied elsewhere. This does not inspect transformed/embedded data. */
+export async function assertAssetPackTargetArtifact(report, artifactRoot, namespacePath = assetPackTargetNamespace) {
+    const root = resolve(artifactRoot);
+    const namespace = resolve(root, namespacePath);
+    if (!inside(root, namespace) || namespace === root) {
+        throw new Error('Asset namespace must be inside the target artifact');
+    }
+    const localHashes = new Set(report.objects.filter((object) => object.location === 'packaged').map((object) => object.sha256));
+    const remoteHashes = new Set(report.objects.filter((object) => object.location === 'remote' && !localHashes.has(object.sha256)).map((object) => object.sha256));
+    let count = 0;
+    let namespaceBytes = 0;
+    const pending = [root];
+    while (pending.length) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (++count > 100_000 || entry.isSymbolicLink()) {
+                throw new Error('Asset artifact inventory exceeds its limit or contains a symbolic link');
+            }
+            if (entry.isDirectory()) {
+                pending.push(path);
+            }
+            else if (entry.isFile()) {
+                if (inside(namespace, path)) {
+                    namespaceBytes += (await lstat(path)).size;
+                }
+                if (remoteHashes.has(await fileDigest(path))) {
+                    throw new Error(`Remote-only asset object is present in the packaged artifact: ${relative(root, path)}`);
+                }
+            }
+            else {
+                throw new Error('Asset artifact contains a non-regular entry');
+            }
+        }
+    }
+    if (namespaceBytes !== report.packagedBytes) {
+        throw new Error('Packaged asset namespace has extra, missing or modified bytes');
+    }
+    for (const name of [assetPackTargetManifestName, assetPackTargetPolicyName]) {
+        if (await fileDigest(join(namespace, name)) !== await fileDigest(join(report.packagedDir, name))) {
+            throw new Error(`Packaged asset metadata changed: ${name}`);
+        }
+    }
+    for (const object of report.objects.filter((object) => object.location === 'packaged')) {
+        if (await fileDigest(join(namespace, object.path)) !== object.sha256) {
+            throw new Error(`Packaged asset object changed: ${object.path}`);
+        }
+    }
+}

package/dist/game-acceptance.d.ts

@@ -1,3 +1,4 @@
+import { type PerformanceAcceptanceEvidence, type PerformanceAcceptanceInput } from './performance-acceptance.js';
 export declare const defaultGameAcceptanceCommandTimeoutMs: number;
 export declare const maximumGameplayE2EReportBytes: number;
 export declare function resolveGameAcceptanceReleaseManifestFile(gameRoot: string, env?: NodeJS.ProcessEnv): string;
@@ -32,6 +33,7 @@ export interface GameAcceptanceReport {
   readonly options: Readonly<Record<string, string | boolean | null>>;
   readonly steps: readonly GameAcceptanceStepResult[];
   readonly evidence: {
+    readonly performance?: PerformanceAcceptanceEvidence;
     readonly releaseManifest: {
       readonly file: string;
       readonly found: boolean;
@@ -57,6 +59,8 @@ export interface RunGameAcceptanceInput {
   readonly reportDir: string;
   readonly releaseManifestFile?: string;
   readonly gameplayE2EReportFile?: string;
+  /** Optional fresh performance collection and consumer-authored budget. */
+  readonly performance?: PerformanceAcceptanceInput;
   readonly requireGameplayE2EReport?: boolean;
   /** Step that must replace any previous gameplay report before evidence is accepted. */
   readonly gameplayE2EStepId?: string;

package/dist/game-acceptance.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { escapeMarkdownInline, escapeMarkdownTable, formatDuration, formatError, readBoundedUtf8File, relativeOrAbsolute, writeEvidenceReportFiles, } from './evidence-io.js';
 import { collectGameplayE2EPathEvidence, maximumGameplayE2EStates, readGameplayE2EPlan, resolveGameplayE2EPathInsideGameRoot, } from './gameplay-e2e.js';
+import { preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, } from './performance-acceptance.js';
 export const defaultGameAcceptanceCommandTimeoutMs = 30 * 60 * 1_000;
 const defaultGameAcceptanceReleaseManifestFile = 'artifacts/release-manifest.json';
 export const maximumGameplayE2EReportBytes = 1_024 * 1_024;
@@ -22,10 +23,25 @@ export function runGameAcceptance(input) {
     const commandRunner = input.commandRunner
         ?? ((step) => runAcceptanceCommand(step, input.env ?? process.env, commandTimeoutMs));
     const gameRoot = path.resolve(input.gameRoot);
+    const reportDir = path.resolve(input.reportDir);
+    const jsonFile = path.join(reportDir, 'acceptance-report.json');
+    const markdownFile = path.join(reportDir, 'acceptance-report.md');
     const startedAtMs = now();
     const results = [];
     let failed = false;
     let gameplayE2EReportFileToReplace;
+    const performance = input.performance === undefined
+        ? undefined
+        : preparePerformanceAcceptance(gameRoot, input.performance);
+    if (performance !== undefined && [jsonFile, markdownFile].some((file) => file === performance.reportFile || file === path.resolve(gameRoot, performance.budgetEvidence.file))) {
+        throw new Error('Performance budget and report must not overwrite acceptance handoff files.');
+    }
+    let performanceStartedAtMs;
+    if (input.performance !== undefined
+        && (input.steps.filter((step) => step.id === input.performance?.stepId).length !== 1
+            || input.steps.some((step) => step.id === input.performance?.stepId && step.skipReason !== undefined))) {
+        throw new Error('Performance evidence needs exactly one runnable collection step.');
+    }
     if (input.gameplayE2EStepId !== undefined) {
         if (input.gameplayE2EReportFile === undefined) {
             throw new Error('A gameplay E2E evidence step needs a report file.');
@@ -50,6 +66,16 @@ export function runGameAcceptance(input) {
                 continue;
             }
         }
+        if (!failed && step.id === input.performance?.stepId && performance !== undefined) {
+            try {
+                rmSync(resolveGameplayE2EPathInsideGameRoot(gameRoot, performance.reportFile, 'Performance report'), { force: true });
+            }
+            catch (error) {
+                results.push(failedStepResult(step, now(), formatError(error)));
+                failed = true;
+                continue;
+            }
+        }
         if (failed) {
             results.push(skippedStepResult(step, now(), 'A previous acceptance step failed.'));
             continue;
@@ -70,6 +96,9 @@ export function runGameAcceptance(input) {
         const cwd = path.resolve(runnableStep.cwd);
         const stepStartedAtMs = now();
         const startedAt = new Date(stepStartedAtMs).toISOString();
+        if (step.id === input.performance?.stepId) {
+            performanceStartedAtMs = stepStartedAtMs;
+        }
         log(`[mpgd:accept] ${step.label}`);
         let commandResult;
         try {
@@ -103,11 +132,23 @@ export function runGameAcceptance(input) {
             || !gameplayE2E.found
             || gameplayE2E.parseError !== null
             || gameplayE2E.validationError !== null);
+    const performanceEvidence = performance === undefined
+        ? undefined
+        : readPerformanceAcceptanceEvidence({
+            gameRoot,
+            prepared: performance,
+            startedAtMs: performanceStartedAtMs,
+            finishedAtMs: now(),
+            profile: typeof input.options.profile === 'string' ? input.options.profile : undefined,
+            releaseManifestFile: input.releaseManifestFile,
+        });
+    const performanceFailed = performanceEvidence?.validationError !== undefined
+        && performanceEvidence.validationError !== null;
     const finishedAtMs = now();
     const report = {
         schemaVersion: 1,
         generatedAt: new Date(finishedAtMs).toISOString(),
-        status: failed || evidenceFailed ? 'failed' : 'passed',
+        status: failed || evidenceFailed || performanceFailed ? 'failed' : 'passed',
         gameRoot,
         durationMs: Math.max(0, finishedAtMs - startedAtMs),
         options: input.options,
@@ -115,11 +156,9 @@ export function runGameAcceptance(input) {
         evidence: {
             releaseManifest,
             gameplayE2E,
+            ...(performanceEvidence === undefined ? {} : { performance: performanceEvidence }),
         },
     };
-    const reportDir = path.resolve(input.reportDir);
-    const jsonFile = path.join(reportDir, 'acceptance-report.json');
-    const markdownFile = path.join(reportDir, 'acceptance-report.md');
     mkdirSync(reportDir, { recursive: true });
     writeEvidenceReportFiles({
         jsonFile,
@@ -180,6 +219,12 @@ export function renderGameAcceptanceMarkdown(report) {
     else {
         lines.push(`- Gameplay E2E report: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`);
     }
+    if (report.evidence.performance !== undefined) {
+        const performance = report.evidence.performance;
+        lines.push('', '## Performance Evidence', '', `- Report: ${escapeMarkdownInline(performance.file)}`, `- Budget: ${escapeMarkdownInline(performance.budget.file)} (${performance.budget.sha256})`, performance.validationError === null
+            ? '- Budget validation passed.'
+            : `- Validation failed: ${escapeMarkdownInline(performance.validationError)}`);
+    }
     return `${lines.join('\n')}\n`;
 }
 function runAcceptanceCommand(step, env, timeoutMs) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, type GameAcceptanceCommandResult, type GameAcceptanceCommandRunner, type GameAcceptanceReport, type GameAcceptanceStatus, type GameAcceptanceStep, type GameAcceptanceStepResult, type GameAcceptanceStepStatus, type RunGameAcceptanceInput, type RunGameAcceptanceResult, } from './game-acceptance.js';
+export { maximumPerformanceEvidenceBytes, preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, validatePerformanceBudget, type PerformanceAcceptanceEvidence, type PerformanceAcceptanceInput, type PerformanceBudget, type PerformanceBudgetProfile, type PerformanceMetricBudget, type PreparedPerformanceAcceptance, } from './performance-acceptance.js';
 export { applyCapacitorShellStarter, materializeCapacitorShellStarter, planCapacitorShellStarter, type CapacitorShellCommandRunner, type CapacitorShellStarterInput, type CapacitorShellStarterPlan, } from './capacitor-shell-starter.js';
 export { ReleaseProcessError, runReleaseProcess, type ReleaseProcessInput, type ReleaseProcessResult, } from './deploy-process.js';
 export { installPinnedReleaseDependencies, pinNativeDeploymentPlan, preparePinnedReleaseWorkspace, runPinnedNativeBuild, withPinnedReleaseWorkspace, type PinnedNativeBuildResult, type PinnedReleaseInput, type PinnedReleaseWorkspace, } from './release-workspace.js';

package/dist/index.js

@@ -9,13 +9,16 @@ import { cli } from 'gunshi';
 import { assertPlatformVersionLedger } from '@mpgd/target-config';
 import { buildAssetPacks } from './asset-pack-build.js';
 import { verifyAssetPackDelivery } from './asset-pack-verify.js';
+import { buildAssetPackTarget } from './asset-pack-target.js';
+import { publishAssetPacks } from './asset-pack-publish.js';
+import { assertAssetPackTargetPolicy } from '@mpgd/target-config/asset-packs';
 import { materializeCapacitorShellStarter, planCapacitorShellStarter, } from './capacitor-shell-starter.js';
 import { doctorNativeDeployment, initializeDeployConfig, parseDeployTargets, planNativeDeployment, readNativeDeploymentPlan, writeNativeDeploymentPlan, } from './deploy-planning.js';
 import { initializeNativeDeployWorkflow } from './native-deploy-workflow.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';
-import { resolveGameplayE2EReportFile } from './gameplay-e2e.js';
+import { resolveGameplayE2EPathInsideGameRoot, resolveGameplayE2EReportFile, } from './gameplay-e2e.js';
 import { cloudflarePagesDeploymentProfiles, hostedPwaDeploymentHosts, verifyHostedPwaDeployment, } from './hosted-pwa-deployment.js';
 import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageAcceptance, } from './microsoft-store-package-acceptance.js';
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
@@ -28,6 +31,7 @@ import { readStoreCredential, runNativeDeployment } from './native-deploy-run.js
 import { submitRecordedNativeTarget } from './native-deploy-submission.js';
 import { readNativeReleaseStatus as readNativeReleaseStatusForCli } from './release-state.js';
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, } from './game-acceptance.js';
+export { maximumPerformanceEvidenceBytes, preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, validatePerformanceBudget, } from './performance-acceptance.js';
 export { applyCapacitorShellStarter, materializeCapacitorShellStarter, planCapacitorShellStarter, } from './capacitor-shell-starter.js';
 export { ReleaseProcessError, runReleaseProcess, } from './deploy-process.js';
 export { installPinnedReleaseDependencies, pinNativeDeploymentPlan, preparePinnedReleaseWorkspace, runPinnedNativeBuild, withPinnedReleaseWorkspace, } from './release-workspace.js';
@@ -108,6 +112,7 @@ const acceptanceStepIds = {
     targetBuild: 'target-build',
     targetSmoke: 'target-smoke',
     gameplayE2E: 'gameplay-e2e',
+    performance: 'performance',
 };
 /** Whether the last run reported a deadline failure that leaves
  * uncancellable filesystem work pending: the standalone binary forces its
@@ -146,7 +151,7 @@ export async function runMpgdCli(args) {
     await cli([...args], entryCommand, {
         name: 'mpgd',
         version: cliVersion,
-        // Machine-readable mode contract: `assets verify-delivery --json`
+        // Machine-readable asset reports and upgrade plans with --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
@@ -155,7 +160,7 @@ export async function runMpgdCli(args) {
         // partial document. Every other command keeps the default rendering.
         renderHeader: async (ctx) => {
             const values = ctx.values;
-            if ((ctx.name === 'verify-delivery' || ctx.name === 'upgrade') && values.json === true) {
+            if ((ctx.name === 'verify-delivery' || ctx.name === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade') && values.json === true) {
                 return '';
             }
             const title = ctx.env.description || ctx.env.name || '';
@@ -166,7 +171,7 @@ export async function runMpgdCli(args) {
         renderValidationErrors: async (ctx, error) => {
             const messages = error.errors.map((entry) => String(entry.message)).join('\n');
             const values = ctx.values;
-            if ((ctx.name === 'verify-delivery' || ctx.name === 'upgrade') && values.json === true) {
+            if ((ctx.name === 'verify-delivery' || ctx.name === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade') && values.json === true) {
                 process.stderr.write(`${messages}\n`);
                 return '';
             }
@@ -722,6 +727,18 @@ const gameCommand = defineI18n({
                     required: false,
                     description: 'Skip the game-owned playtest package script.',
                 },
+                performance: {
+                    type: 'boolean', required: false,
+                    description: 'Collect and validate fresh foreground performance evidence.',
+                },
+                'performance-script': {
+                    type: 'string', required: false, default: 'performance:e2e',
+                    description: 'Game-owned performance collection package script.',
+                },
+                'performance-budget': {
+                    type: 'string', required: false, default: 'agent/performance.budget.json',
+                    description: 'Consumer-authored performance budget JSON inside the game root.',
+                },
                 'skip-gameplay-e2e': {
                     type: 'boolean',
                     required: false,
@@ -761,6 +778,9 @@ const gameCommand = defineI18n({
                     skipGraph: ctx.values['skip-graph'] === true,
                     skipPlaytest: ctx.values['skip-playtest'] === true,
                     skipGameplayE2E: ctx.values['skip-gameplay-e2e'] === true,
+                    performance: ctx.values.performance === true,
+                    performanceScript: readOptionalString(ctx.values['performance-script']) ?? 'performance:e2e',
+                    performanceBudget: readOptionalString(ctx.values['performance-budget']) ?? 'agent/performance.budget.json',
                     skipTargetBuild: ctx.values['skip-target-build'] === true,
                     skipTargetSmoke: ctx.values['skip-target-smoke'] === true,
                 });
@@ -920,7 +940,7 @@ function acceptGame(input) {
     const packageManager = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
     const gameplayE2EEnabled = !input.skipGameplayE2E
         && gamePackage.scripts?.[input.gameplayScript] !== undefined;
-    const gameplayE2ETargets = gameplayE2EEnabled
+    const gameplayE2ETargets = gameplayE2EEnabled || input.performance
         ? parseTargetList(input.targets, {
             ...process.env,
             MPGD_PLATFORM_TARGETS_FILE: targetsFile,
@@ -1011,12 +1031,30 @@ function acceptGame(input) {
             skipped: input.skipGameplayE2E,
         }),
     ];
+    const performanceReportFile = input.performance
+        ? resolveGameplayE2EPathInsideGameRoot(gameRoot, readOptionalString(process.env.MPGD_PERFORMANCE_REPORT_FILE) ?? 'artifacts/performance/report.json', 'Performance report')
+        : undefined;
+    if (input.performance) {
+        steps.push(packageScriptAcceptanceStep({
+            id: acceptanceStepIds.performance,
+            label: 'Foreground performance collection',
+            script: input.performanceScript,
+            gameRoot,
+            packageManager,
+            scripts: gamePackage.scripts,
+            required: true,
+        }));
+    }
     const reportDir = path.resolve(gameRoot, input.reportDir ?? 'artifacts/acceptance');
     const releaseManifestFile = resolveGameAcceptanceReleaseManifestFile(gameRoot);
     const gameplayE2EReportFile = resolveGameplayE2EReportFile(gameRoot);
     const result = runGameAcceptance({
         gameRoot,
         reportDir,
+        ...(performanceReportFile === undefined ? {} : { performance: {
+                budgetFile: input.performanceBudget, reportFile: performanceReportFile,
+                stepId: acceptanceStepIds.performance, targets: gameplayE2ETargets,
+            } }),
         ...(input.skipTargetBuild
             ? {}
             : { releaseManifestFile }),
@@ -1035,6 +1073,8 @@ function acceptGame(input) {
             iosVariant: input.iosVariant ?? null,
             playtestScript: input.playtestScript,
             gameplayScript: input.gameplayScript,
+            ...(input.performance ? { performance: true, performanceScript: input.performanceScript,
+                performanceBudget: input.performanceBudget } : {}),
             skipTest: input.skipTest,
             skipGraph: input.skipGraph,
             skipPlaytest: input.skipPlaytest,
@@ -1048,12 +1088,16 @@ function acceptGame(input) {
         env: {
             ...process.env,
             MPGD_KIT_PATH: kitPath,
-            MPGD_ACCEPTANCE_TARGETS: gameplayE2EEnabled
+            MPGD_ACCEPTANCE_TARGETS: gameplayE2EEnabled || input.performance
                 ? gameplayE2ETargets.join(',')
                 : input.targets,
             MPGD_ACCEPTANCE_PROFILE: input.profile,
             MPGD_RELEASE_MANIFEST_FILE: releaseManifestFile,
             MPGD_GAMEPLAY_E2E_REPORT_FILE: gameplayE2EReportFile,
+            ...(performanceReportFile === undefined ? {} : {
+                MPGD_PERFORMANCE_REPORT_FILE: performanceReportFile,
+                MPGD_PERFORMANCE_BUDGET_FILE: path.resolve(gameRoot, input.performanceBudget),
+            }),
         },
     });
     console.info(`[mpgd:accept] JSON report: ${result.jsonFile}`);
@@ -1195,6 +1239,83 @@ const assetsCommand = defineI18n({
         ko: '결정적인 에셋 팩 전달 산출물을 빌드합니다.',
     }),
     subCommands: {
+        'publish-s3': defineI18n({
+            name: 'publish-s3',
+            description: 'Publish immutable remote objects from a staged asset deployment.',
+            resource: commandResource({ en: 'Publish immutable remote objects from a staged asset deployment.', ko: '배치된 에셋 배포의 원격 객체를 변경 불가능한 경로로 게시합니다.' }),
+            args: {
+                deployment: { type: 'string', required: true, description: 'stage-target output with packaged/ and remote/ children.' },
+                endpoint: { type: 'string', required: true, description: 'HTTPS S3 API root endpoint without credentials or query.' },
+                bucket: { type: 'string', required: true, description: 'Existing S3 bucket.' },
+                prefix: { type: 'string', required: true, description: 'Versioned object-key prefix matching the public asset origin.' },
+                region: { type: 'string', default: 'us-east-1', description: 'S3 signing region.' },
+                'dry-run': { type: 'boolean', default: false, description: 'Verify and report without credentials or network calls.' },
+                'allow-http-loopback': { type: 'boolean', default: false, description: 'Explicit development-only HTTP loopback endpoint opt-in.' },
+                'access-key-env': { type: 'string', default: 'MPGD_ASSETS_S3_ACCESS_KEY_ID', description: 'Access-key environment variable name, never its value.' },
+                'secret-key-env': { type: 'string', default: 'MPGD_ASSETS_S3_SECRET_ACCESS_KEY', description: 'Secret-key environment variable name, never its value.' },
+                'session-token-env': { type: 'string', default: 'MPGD_ASSETS_S3_SESSION_TOKEN', description: 'Optional session-token environment variable name.' },
+                'max-object-bytes': { type: 'number', description: 'Object-body cap; default64 MiB, maximum512 MiB.' },
+                'max-total-bytes': { type: 'number', description: 'Total planned object bodies; default1 GiB.' },
+                'max-objects': { type: 'number', description: 'Maximum objects including the immutable manifest snapshot; default10000.' },
+                'request-timeout-ms': { type: 'number', description: 'Per HTTP attempt deadline; default10000 ms.' },
+                'timeout-ms': { type: 'number', description: 'Whole preparation/publication deadline; default120000 ms.' },
+                json: { type: 'boolean', default: false, description: 'Print a single JSON report without sensitive headers or URLs.' },
+            },
+            run: async (ctx) => {
+                const report = await publishAssetPacks({
+                    deployment: ctx.values.deployment, endpoint: ctx.values.endpoint, bucket: ctx.values.bucket, prefix: ctx.values.prefix,
+                    region: ctx.values.region, dryRun: ctx.values['dry-run'], allowHttpLoopback: ctx.values['allow-http-loopback'],
+                    accessKeyEnv: ctx.values['access-key-env'], secretKeyEnv: ctx.values['secret-key-env'], sessionTokenEnv: ctx.values['session-token-env'],
+                    ...(ctx.values['max-object-bytes'] === undefined ? {} : { maxObjectBytes: ctx.values['max-object-bytes'] }),
+                    ...(ctx.values['max-total-bytes'] === undefined ? {} : { maxTotalBytes: ctx.values['max-total-bytes'] }),
+                    ...(ctx.values['max-objects'] === undefined ? {} : { maxObjects: ctx.values['max-objects'] }),
+                    ...(ctx.values['request-timeout-ms'] === undefined ? {} : { requestTimeoutMs: ctx.values['request-timeout-ms'] }),
+                    ...(ctx.values['timeout-ms'] === undefined ? {} : { timeoutMs: ctx.values['timeout-ms'] }),
+                });
+                if (ctx.values.json) {
+                    console.info(JSON.stringify(report, null, 2));
+                }
+                else {
+                    console.info(`${report.dryRun ? 'Planned' : 'Published'} ${report.objects.length} immutable objects; ${report.plannedBytes} planned body bytes, ${report.uploadedBytes} newly uploaded body bytes.`);
+                    console.info(`Manifest snapshot: ${report.objects.at(-1)?.key}`);
+                }
+            },
+        }),
+        'stage-target': defineI18n({
+            name: 'stage-target',
+            description: "Build and stage one target's packaged and remote asset packs.",
+            resource: commandResource({
+                en: "Build and stage one target's packaged and remote asset packs.",
+                ko: '한 타깃의 로컬·원격 에셋 팩을 빌드하고 배치합니다.',
+            }),
+            args: {
+                'targets-file': { type: 'string', default: 'mpgd.targets.json', description: 'Game target configuration file.' },
+                target: { type: 'string', required: true, description: 'Deployment target name.' },
+                out: { type: 'string', required: true, description: 'Fresh output directory with packaged/remote children.' },
+                json: { type: 'boolean', default: false, description: 'Print the actual byte and location report as JSON.' },
+            },
+            run: async (ctx) => {
+                const targetsPath = path.resolve(ctx.values['targets-file']);
+                const document = JSON.parse(readFileSync(targetsPath, 'utf8'));
+                if (!Object.hasOwn(document.targets ?? {}, ctx.values.target)) {
+                    throw new Error(`Target ${ctx.values.target} is not defined in the target configuration.`);
+                }
+                const policy = document.targets?.[ctx.values.target]?.assetPacks;
+                if (policy === undefined) {
+                    throw new Error(`Target ${ctx.values.target} has no assetPacks policy.`);
+                }
+                assertAssetPackTargetPolicy(policy);
+                const report = await buildAssetPackTarget({ policy, baseDir: path.dirname(targetsPath), outDir: ctx.values.out });
+                if (ctx.values.json) {
+                    console.info(JSON.stringify(report, null, 2));
+                }
+                else {
+                    console.info(`Packaged assets: ${report.packagedAssetBytes} bytes (${report.packagedBytes} including metadata)`);
+                    console.info(`Remote objects: ${report.remoteBytes} bytes; manifest sha256:${report.manifestSha256}`);
+                    console.info(`Asset pack deployment: ${report.outDir}`);
+                }
+            },
+        }),
         'build-packs': defineI18n({
             name: 'build-packs',
             description: 'Build files or ZIP delivery artifacts for configured packs.',

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "84316fe7a7da51e1b448d8935240a5f60aaf4adc",
+  "kitGitSha": "ca727bc6ebd8c1ecb7515ceb76f48ea5e913ab82",
   "kitDirty": false,
-  "packageVersion": "0.39.0"
+  "packageVersion": "0.41.0"
 }