@mpgd/cli 0.39.0 → 0.40.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/index.js

@@ -9,6 +9,9 @@ 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';
@@ -146,7 +149,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 +158,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 +169,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 '';
             }
@@ -1195,6 +1198,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": "ccd019a49651a6730a4f0214d9dfcf0094bda226",
   "kitDirty": false,
-  "packageVersion": "0.39.0"
+  "packageVersion": "0.40.0"
 }