@mpgd/cli 0.53.0 → 0.54.1

package/dist/capacitor-shell-starter.js

@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { DOMParser } from '@xmldom/xmldom';
 import { satisfies, valid, validRange } from 'semver';
-import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
+import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsCapacitorTemplateSupportFiles, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
 import { isNonPublicServiceHostname } from './production-target-readiness.js';
 import { assertAndroidSettingsAppProject, assertAndroidSettingsNoAppRemap, assertIosReleaseInfoPlistExpansion, assertIosReleasePackagingSettings, assertIosReleaseProductName, assertNativeShellIdentity, hasAndroidDisplayNameResourceOverride, hasAndroidManifestSourceSetOverride, hasAndroidResourceSourceSetOverride, hasGradleIdentityMutation, hasGradleTaskAction, maskGradleStrings, readIosAppTargetId, readIosReleaseInfoPlist, stripGradleComments, } from './native-shell-identity.js';
 const shellPath = 'apps/mobile-capacitor';
@@ -2793,6 +2793,14 @@ function planNotificationsProvider(input) {
                 files.push({ path: file, content: starterFile(overlayRoot, file) });
             }
         }
+        // Base-template modules they import, missing from a game an earlier release created.
+        if (input.templateRoot !== undefined) {
+            for (const file of notificationsCapacitorTemplateSupportFiles) {
+                if (readExisting(safeDestination(gameRoot, file)) === undefined) {
+                    files.push({ path: file, content: starterFile(input.templateRoot, file) });
+                }
+            }
+        }
         warnings.push('The notification settings screen is not added to an existing game; render one from '
             + 'src/platform/notificationSettings.ts (see docs/NOTIFICATIONS.md) so players can turn '
             + 'reminders and advertising consent on and off.');

package/dist/deploy-planning.js

@@ -356,8 +356,8 @@ function assertGameOwnedNativePaths(gameRoot, target, config) {
             throw new Error(`${target} ${field} still points to a Kit checkout; initialize a game-owned shell.`);
         }
         const expanded = value
-            .replaceAll('${MPGD_GAME_ROOT}', root)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', root);
+            .replaceAll('${MPGD_GAME_ROOT}', () => root)
+            .replaceAll('${MPGD_GAME_APP_ROOT}', () => root);
         const candidate = resolve(root, expanded);
         let ancestor = candidate;
         while (!existsSync(ancestor)) {

package/dist/index.js

@@ -12,6 +12,7 @@ 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 { assertLegalProjectPath, publishLegalSiteFiles } from './legal-site-output.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';
@@ -1818,7 +1819,10 @@ const targetCommand = defineI18n({
                     action: 'build',
                     target,
                     profile,
-                    env: createTargetCommandEnv(ctx.values, { nativeBuildTarget: target }),
+                    env: createTargetCommandEnv(ctx.values, {
+                        nativeBuildTarget: target,
+                        requireSourceRevision: true,
+                    }),
                     ...(variant === undefined ? {} : { variant }),
                 });
             },
@@ -2448,7 +2452,7 @@ const targetCommand = defineI18n({
             run: (ctx) => {
                 const aitVariant = readOptionalString(ctx.values['ait-variant']);
                 const iosVariant = readOptionalString(ctx.values['ios-variant']);
-                const env = createTargetCommandEnv(ctx.values);
+                const env = createTargetCommandEnv(ctx.values, { requireSourceRevision: true });
                 runTargetMatrix({
                     action: 'build',
                     targets: parseTargetList(readOptionalString(ctx.values.targets), env),
@@ -2774,9 +2778,13 @@ function resolveLegalCommandOptions(values) {
 function buildLegalSite(input) {
     const legalDir = path.resolve(process.cwd(), input.legalDir);
     const outDir = path.resolve(process.cwd(), input.outDir);
+    assertLegalProjectPath('legal-dir', legalDir);
+    assertLegalProjectPath('out-dir', outDir);
     const outputs = createLegalSiteOutputs(legalDir, outDir);
     if (input.check) {
+        assertLegalProjectPath('out-dir', outDir);
         const stale = outputs.filter((output) => {
+            assertLegalProjectPath('out-dir', output.file);
             if (!existsSync(output.file)) {
                 return true;
             }
@@ -2792,29 +2800,24 @@ function buildLegalSite(input) {
             outDir,
         };
     }
-    for (const output of outputs) {
-        mkdirSync(path.dirname(output.file), { recursive: true });
-        writeFileSync(output.file, output.content);
-    }
+    publishLegalSiteFiles(outDir, outputs);
     return {
         outDir,
     };
 }
 function createLegalSiteOutputs(legalDir, outDir) {
-    const relativeLegalDir = path.relative(process.cwd(), legalDir);
-    const relativeOutDir = path.relative(process.cwd(), outDir);
-    if (relativeLegalDir.startsWith('..') || path.isAbsolute(relativeLegalDir)) {
-        throw new Error(`legal-dir must be inside the project root: ${legalDir}`);
-    }
-    if (relativeOutDir.startsWith('..') || path.isAbsolute(relativeOutDir)) {
-        throw new Error(`out-dir must be inside the project root: ${outDir}`);
-    }
-    const sourceRoot = toTemplatePath(relativeLegalDir || '.');
+    assertLegalProjectPath('legal-dir', legalDir);
+    assertLegalProjectPath('out-dir', outDir);
+    const sourceRoot = toTemplatePath(path.relative(process.cwd(), legalDir) || '.');
     const outputs = legalPageSlugs.map((slug) => {
         const sourceFile = path.join(legalDir, `${slug}.html`);
+        // existsSync and readFileSync follow a page symlink. Check the file
+        // itself, not only the legal directory, immediately before reading it.
+        assertLegalProjectPath('legal-dir', sourceFile);
         if (!existsSync(sourceFile)) {
             throw new Error(`Missing legal page source: ${sourceFile}`);
         }
+        assertLegalProjectPath('legal-dir', sourceFile);
         return {
             file: path.join(outDir, slug, 'index.html'),
             content: normalizeLegalHtml(readFileSync(sourceFile, 'utf8'), sourceFile),
@@ -2976,7 +2979,14 @@ function createGameApp(input) {
             relativePath: file.relativePath,
             content: file.content,
         });
-        return prepared === undefined ? [] : [{ ...file, content: renderTemplate(prepared, context) }];
+        return prepared === undefined
+            ? []
+            : [
+                {
+                    ...file,
+                    content: renderTemplate(prepared, context, file.relativePath),
+                },
+            ];
     });
     if (input.dryRun) {
         console.info(`Would create ${path.relative(process.cwd(), appDir) || appDir}:`);
@@ -3187,8 +3197,10 @@ function assertValidGameTitle(title) {
     if (title.trim().length === 0) {
         throw new Error('Game title cannot be empty.');
     }
-    if (/[\u0000-\u001f<>"'\\]/u.test(title)) {
-        throw new Error('Game title cannot contain control characters, quotes, backslashes, or angle brackets.');
+    // Quotes, backslashes, and `$` are allowed: JSON files and JS string literals
+    // escape them. `<` would break the generated HTML title.
+    if (/[\u0000-\u001f<>]/u.test(title)) {
+        throw new Error('Game title cannot contain control characters or angle brackets.');
     }
 }
 function collectTemplateFiles(templateDir) {
@@ -3210,28 +3222,79 @@ function walkTemplateDir(templateDir, relativeDir, files) {
         });
     }
 }
-function renderTemplate(content, context) {
-    let rendered = content
-        .replaceAll("from '@mpgd/cli/devvit'", `from ${context.devvitOutputPluginImport}`)
-        .replaceAll('__GAME_NAME__', context.gameName)
-        .replaceAll('__DEVVIT_APP_NAME__', context.devvitAppName)
-        .replaceAll('__GAME_TITLE_TS_LITERAL__', context.gameTitleTsLiteral)
-        .replaceAll('__GAME_TITLE__', context.gameTitle)
-        .replaceAll('__LEGAL_LAST_UPDATED__', context.legalLastUpdated)
-        .replaceAll('__PACKAGE_NAME__', context.packageName)
-        .replaceAll('__MPGD_DEPENDENCY_VERSION__', context.defaultDependencyVersion)
-        .replaceAll('__TSCONFIG_EXTENDS_LINE__', context.tsconfigExtendsLine)
-        .replaceAll('__TSCONFIG_ROOT_DIR__', context.tsconfigRootDir)
-        .replaceAll('__TSCONFIG_WORKSPACE_INCLUDES__', context.tsconfigWorkspaceIncludes)
-        .replaceAll('__TSCONFIG_WORKSPACE_EXCLUDES__', context.tsconfigWorkspaceExcludes)
-        .replaceAll('__WORKSPACE_I18N_BUILD_PREFIX__', context.workspaceI18nBuildPrefix)
-        .replaceAll('__DEFAULT_KIT_PATH__', context.defaultKitPath)
-        .replaceAll('__RECOMMENDED_MATRIX_TARGETS__', context.recommendedMatrixTargets)
-        .replaceAll('__PNPM_WORKSPACE_KIT_PACKAGES__', context.pnpmWorkspaceKitPackages)
-        .replaceAll('__PASCAL_NAME__', context.pascalName)
-        .replaceAll('__CAMEL_NAME__', context.camelName);
+/**
+ * String replacements treat `$&`, `$'`, `` $` ``, and `$$` as patterns.
+ * A function replacer inserts `value` literally.
+ */
+function replaceLiteral(content, placeholder, value) {
+    return content.replaceAll(placeholder, () => value);
+}
+/** Interior of a JSON string, without the surrounding quotes. */
+function jsonStringContents(value) {
+    return JSON.stringify(value).slice(1, -1);
+}
+/**
+ * Placeholders substituted inside an existing JSON string. Structural
+ * fragments (`__TSCONFIG_EXTENDS_LINE__` and the workspace include/exclude
+ * lists) stay raw so their quotes remain JSON syntax.
+ */
+function jsonEscapedPlaceholder(placeholder) {
+    return placeholder === '__GAME_TITLE__'
+        || placeholder === '__GAME_NAME__'
+        || placeholder === '__PACKAGE_NAME__'
+        || placeholder === '__DEVVIT_APP_NAME__'
+        || placeholder === '__DEFAULT_KIT_PATH__'
+        || placeholder === '__WORKSPACE_I18N_BUILD_PREFIX__'
+        || placeholder === '__TSCONFIG_ROOT_DIR__'
+        || placeholder === '__LEGAL_LAST_UPDATED__'
+        || placeholder === '__MPGD_DEPENDENCY_VERSION__'
+        || placeholder.startsWith('__MPGD_DEPENDENCY_VERSION_');
+}
+/** Interior of a single-quoted JS string. Backslash first, then quote. */
+function singleQuotedContents(value) {
+    return value.replaceAll('\\', () => '\\\\').replaceAll("'", () => "\\'");
+}
+function renderTemplate(content, context, relativePath) {
+    // `.webmanifest` is JSON. Hosted PWA deploy and Microsoft Store submission parse it.
+    const jsonFile = relativePath.endsWith('.json') || relativePath.endsWith('.webmanifest');
+    const typescriptFile = relativePath.endsWith('.ts');
+    const insert = (placeholder, value) => {
+        if (jsonFile && jsonEscapedPlaceholder(placeholder)) {
+            return jsonStringContents(value);
+        }
+        // Template titles sit in single quotes (`title: '__GAME_TITLE__'`).
+        if (typescriptFile && placeholder === '__GAME_TITLE__') {
+            return singleQuotedContents(value);
+        }
+        return value;
+    };
+    const pairs = [
+        [`from '@mpgd/cli/devvit'`, `from ${context.devvitOutputPluginImport}`],
+        ['__GAME_NAME__', context.gameName],
+        ['__DEVVIT_APP_NAME__', context.devvitAppName],
+        // Longer than `__GAME_TITLE__`, so a title is not written into the literal name.
+        ['__GAME_TITLE_TS_LITERAL__', context.gameTitleTsLiteral],
+        ['__GAME_TITLE__', context.gameTitle],
+        ['__LEGAL_LAST_UPDATED__', context.legalLastUpdated],
+        ['__PACKAGE_NAME__', context.packageName],
+        ['__MPGD_DEPENDENCY_VERSION__', context.defaultDependencyVersion],
+        ['__TSCONFIG_EXTENDS_LINE__', context.tsconfigExtendsLine],
+        ['__TSCONFIG_ROOT_DIR__', context.tsconfigRootDir],
+        ['__TSCONFIG_WORKSPACE_INCLUDES__', context.tsconfigWorkspaceIncludes],
+        ['__TSCONFIG_WORKSPACE_EXCLUDES__', context.tsconfigWorkspaceExcludes],
+        ['__WORKSPACE_I18N_BUILD_PREFIX__', context.workspaceI18nBuildPrefix],
+        ['__DEFAULT_KIT_PATH__', context.defaultKitPath],
+        ['__RECOMMENDED_MATRIX_TARGETS__', context.recommendedMatrixTargets],
+        ['__PNPM_WORKSPACE_KIT_PACKAGES__', context.pnpmWorkspaceKitPackages],
+        ['__PASCAL_NAME__', context.pascalName],
+        ['__CAMEL_NAME__', context.camelName],
+    ];
+    let rendered = content;
+    for (const [placeholder, value] of pairs) {
+        rendered = replaceLiteral(rendered, placeholder, insert(placeholder, value));
+    }
     for (const replacement of context.mpgdDependencyVersionReplacements) {
-        rendered = rendered.replaceAll(replacement.placeholder, replacement.version);
+        rendered = replaceLiteral(rendered, replacement.placeholder, insert(replacement.placeholder, replacement.version));
     }
     return rendered;
 }
@@ -3287,7 +3350,11 @@ function createTargetCommandEnv(values, options = {}) {
     });
     const env = {
         ...process.env,
-        ...createGameOwnedReleaseEnv(gameRoot, process.env),
+        // Release provenance is recorded only by build commands. Smoke, doctor,
+        // icons, and submission preflight must still run on an exported game tree.
+        ...createGameOwnedReleaseEnv(gameRoot, process.env, {
+            requireSourceRevision: options.requireSourceRevision === true,
+        }),
         MPGD_PLATFORM_TARGETS_FILE: preparedTargetsFile,
         ...(targetConfigExtensionsFile === undefined
             ? {}
@@ -3336,8 +3403,8 @@ function resolveStandaloneNativeBuild(targetsFile, requestedTarget, values) {
             return undefined;
         }
         const candidate = path.resolve(gameRoot, configuredPath
-            .replaceAll('${MPGD_GAME_ROOT}', gameRoot)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', gameRoot));
+            .replaceAll('${MPGD_GAME_ROOT}', () => gameRoot)
+            .replaceAll('${MPGD_GAME_APP_ROOT}', () => gameRoot));
         let existingAncestor = candidate;
         while (!existsSync(existingAncestor)) {
             const parent = path.dirname(existingAncestor);
@@ -3390,10 +3457,9 @@ function resolveTargetConfigExtensionsFile(gameRoot, configuredFile) {
     const gameOwnedFile = path.join(gameRoot, 'mpgd.target-config.json');
     return existsSync(gameOwnedFile) ? gameOwnedFile : undefined;
 }
-function createGameOwnedReleaseEnv(gameRoot, baseEnv) {
+function createGameOwnedReleaseEnv(gameRoot, baseEnv, options) {
     const monetizationFiles = resolveGameOwnedMonetizationFiles(gameRoot, baseEnv);
-    const sourceGitSha = readOptionalString(baseEnv.MPGD_SOURCE_GIT_SHA)
-        ?? readSourceGitSha(gameRoot);
+    const sourceGitSha = resolveCommandSourceGitSha(gameRoot, baseEnv, options.requireSourceRevision);
     const appVersion = readOptionalString(baseEnv.APP_VERSION)
         ?? readGamePackageVersion(gameRoot);
     const notificationTopicsFile = readConfiguredPath(baseEnv.MPGD_NOTIFICATION_TOPICS_FILE);
@@ -3404,7 +3470,7 @@ function createGameOwnedReleaseEnv(gameRoot, baseEnv) {
         ...(notificationTopicsFile === undefined
             ? {}
             : { MPGD_NOTIFICATION_TOPICS_FILE: path.resolve(gameRoot, notificationTopicsFile) }),
-        MPGD_SOURCE_GIT_SHA: sourceGitSha,
+        ...(sourceGitSha === undefined ? {} : { MPGD_SOURCE_GIT_SHA: sourceGitSha }),
         ...(appVersion === undefined ? {} : { APP_VERSION: appVersion }),
     };
 }
@@ -3439,15 +3505,48 @@ function readConfiguredPath(value) {
     const normalized = value?.trim();
     return normalized === undefined || normalized.length === 0 ? undefined : normalized;
 }
+function resolveCommandSourceGitSha(gameRoot, baseEnv, requireSourceRevision) {
+    const configuredSourceGitSha = readOptionalString(baseEnv.MPGD_SOURCE_GIT_SHA);
+    if (requireSourceRevision) {
+        return configuredSourceGitSha === undefined
+            ? readSourceGitSha(gameRoot)
+            : requireSourceGitSha(configuredSourceGitSha);
+    }
+    if (configuredSourceGitSha !== undefined) {
+        return isSourceGitSha(configuredSourceGitSha) ? configuredSourceGitSha : undefined;
+    }
+    const detectedSourceGitSha = readGitHead(gameRoot);
+    return detectedSourceGitSha !== undefined && isSourceGitSha(detectedSourceGitSha)
+        ? detectedSourceGitSha
+        : undefined;
+}
 function readSourceGitSha(gameRoot) {
+    const head = readGitHead(gameRoot);
+    if (head === undefined) {
+        throw new Error(`Failed to resolve the game source Git revision for ${gameRoot}. `
+            + 'Set MPGD_SOURCE_GIT_SHA to its lowercase 40-character commit SHA.');
+    }
+    return requireSourceGitSha(head);
+}
+function readGitHead(gameRoot) {
     const result = spawnSync('git', ['-C', gameRoot, 'rev-parse', 'HEAD'], {
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
     if (result.error !== undefined || result.status !== 0) {
-        return 'uncommitted';
+        return undefined;
+    }
+    const head = result.stdout.trim();
+    return head.length === 0 ? undefined : head;
+}
+function requireSourceGitSha(value) {
+    if (!isSourceGitSha(value)) {
+        throw new Error('MPGD_SOURCE_GIT_SHA must be a lowercase 40-character game source SHA.');
     }
-    return result.stdout.trim() || 'uncommitted';
+    return value;
+}
+function isSourceGitSha(value) {
+    return /^[0-9a-f]{40}$/u.test(value);
 }
 function readGamePackageVersion(gameRoot) {
     const packageFile = path.join(gameRoot, 'package.json');
@@ -3495,10 +3594,7 @@ function formatError(error) {
 }
 function replaceTargetTokens(value, context) {
     if (typeof value === 'string') {
-        return value
-            .replaceAll('${MPGD_KIT_PATH}', context.kitPath)
-            .replaceAll('${MPGD_GAME_ROOT}', context.gameRoot)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', context.gameRoot);
+        return replaceLiteral(replaceLiteral(replaceLiteral(value, '${MPGD_KIT_PATH}', context.kitPath), '${MPGD_GAME_ROOT}', context.gameRoot), '${MPGD_GAME_APP_ROOT}', context.gameRoot);
     }
     if (Array.isArray(value)) {
         return value.map((entry) => replaceTargetTokens(entry, context));

package/dist/kit-upgrade.js

@@ -1,6 +1,6 @@
 import { execFile as execFileCallback, spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { compare, intersects, minVersion, satisfies, valid, validRange } from 'semver';
@@ -154,6 +154,9 @@ export function applyKitUpgrade(plan, runLockfileUpdate = updatePnpmLockfile) {
         ...plan.manifestDigests,
         ...plan.lockfileDigests,
     })) {
+        // Re-check links before the digest read. readFileSync follows a symlink,
+        // so a same-bytes swap would otherwise look unchanged.
+        assertOwnedUpgradePath(upgradeWriteAnchor(plan, file), file);
         const current = readFileSync(file, 'utf8');
         if (digest(current) !== expected) {
             throw new Error('File changed after upgrade planning: ' + file);
@@ -176,9 +179,11 @@ export function applyKitUpgrade(plan, runLockfileUpdate = updatePnpmLockfile) {
                 section[update.packageName] = update.next;
                 parsed[update.section] = section;
             }
-            writeFileSync(manifest, stringifyLike(source, parsed));
+            writeUpgradeFile(plan, manifest, stringifyLike(source, parsed));
         }
         for (const root of plan.workspaceRoots) {
+            const lockfile = path.join(root, 'pnpm-lock.yaml');
+            assertOwnedUpgradePath(upgradeWriteAnchor(plan, lockfile), lockfile);
             runLockfileUpdate(root);
         }
     }
@@ -186,7 +191,7 @@ export function applyKitUpgrade(plan, runLockfileUpdate = updatePnpmLockfile) {
         const restoreFailures = [];
         for (const [file, original] of snapshots) {
             try {
-                writeFileSync(file, original);
+                writeUpgradeFile(plan, file, original);
             }
             catch (restoreError) {
                 restoreFailures.push(file + ': ' + formatError(restoreError));
@@ -278,8 +283,8 @@ function discoverGameManifests(gameRoot, notes, blockers, targetsFileName) {
                 continue;
             }
             const resolvedLocation = location
-                .replaceAll('${MPGD_GAME_ROOT}', targetsDirectory)
-                .replaceAll('${MPGD_GAME_APP_ROOT}', targetsDirectory);
+                .replaceAll('${MPGD_GAME_ROOT}', () => targetsDirectory)
+                .replaceAll('${MPGD_GAME_APP_ROOT}', () => targetsDirectory);
             if (resolvedLocation.includes('$' + '{')) {
                 notes.push('Skipped target with unresolved path token: ' + location);
                 continue;
@@ -473,6 +478,100 @@ function stringifyLike(original, value) {
     return JSON.stringify(value, null, indent).replaceAll('\n', newline)
         + (original.endsWith('\n') ? newline : '');
 }
+function upgradeWriteAnchor(plan, file) {
+    const resolved = path.resolve(file);
+    let anchor = plan.gameRoot;
+    while (!inside(anchor, resolved)) {
+        const parent = path.dirname(anchor);
+        if (parent === anchor) {
+            throw new Error('Refusing to write outside the planned upgrade directory: ' + file);
+        }
+        anchor = parent;
+    }
+    // In-game files used to return plan.gameRoot before this check. A game
+    // directory or parent swapped for a symlink after planning then skipped
+    // lstat/realpath, and assertOwnedUpgradePath only inspects children.
+    let anchorStat;
+    try {
+        anchorStat = lstatSync(anchor);
+    }
+    catch (error) {
+        throw new Error('Refusing to write through a symbolic link: ' + anchor, { cause: error });
+    }
+    if (anchorStat.isSymbolicLink()) {
+        throw new Error('Refusing to write through a symbolic link: ' + anchor);
+    }
+    const anchorReal = realpathSync(anchor);
+    // Compare with the game root captured at planning time. A fresh realpath of
+    // both sides would follow a parent swapped for a symlink and look consistent.
+    if (!inside(anchorReal, plan.gameRoot)
+        && path.resolve(anchorReal) !== path.resolve(plan.gameRoot)) {
+        throw new Error('Refusing to write through a symbolic link: ' + anchor);
+    }
+    return anchor;
+}
+function assertOwnedUpgradePath(anchor, file) {
+    const resolved = path.resolve(file);
+    if (!inside(anchor, resolved)) {
+        throw new Error('Refusing to write outside the planned upgrade directory: ' + file);
+    }
+    const relative = path.relative(anchor, resolved);
+    const parts = relative.split(path.sep).filter((part) => part !== '' && part !== '.');
+    let current = anchor;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (part === undefined) {
+            continue;
+        }
+        current = path.join(current, part);
+        const isFinal = index === parts.length - 1;
+        let stat;
+        try {
+            stat = lstatSync(current);
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT') && isFinal) {
+                return;
+            }
+            throw new Error('Upgrade file disappeared before write: ' + file, { cause: error });
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error('Refusing to write through a symbolic link: ' + current);
+        }
+    }
+    if (!inside(realpathSync(anchor), realpathSync(resolved))) {
+        throw new Error('Refusing to write through a symbolic link: ' + file);
+    }
+}
+function writeUpgradeFile(plan, file, source) {
+    const anchor = upgradeWriteAnchor(plan, file);
+    assertOwnedUpgradePath(anchor, file);
+    const temporary = `${file}.mpgd-${randomUUID()}.tmp`;
+    try {
+        let mode = 0o644;
+        try {
+            const stat = lstatSync(file);
+            if (stat.isSymbolicLink()) {
+                throw new Error('Refusing to write through a symbolic link: ' + file);
+            }
+            mode = stat.mode & 0o777;
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT')) {
+                throw error;
+            }
+        }
+        writeFileSync(temporary, source, { flag: 'wx', mode });
+        assertOwnedUpgradePath(anchor, file);
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function isErrno(error, code) {
+    return error !== null && typeof error === 'object' && 'code' in error && error.code === code;
+}
 function inside(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..'

package/dist/legal-site-output.d.ts

@@ -0,0 +1,12 @@
+export interface LegalSiteFile {
+  readonly file: string;
+  readonly content: string;
+}
+/**
+* Legal-site paths are contained only after the nearest existing ancestor is
+* canonicalized. A lexical `path.relative` check treats a symlinked `artifacts`
+* directory as inside the project while later writes follow the link.
+*/
+export declare function assertLegalProjectPath(label: string, resolved: string): void;
+/** Stage the site beside the destination, then publish with rename. */
+export declare function publishLegalSiteFiles(outDir: string, outputs: readonly LegalSiteFile[]): void;