@mpgd/cli 0.48.0 → 0.49.0

package/dist/devvit-output-collisions.d.ts

@@ -0,0 +1,49 @@
+/**
+* One output path written by more than one source in a Devvit web build.
+*
+* `public` means a file from a public directory was silently replaced by a
+* Vite-emitted file of the same name (Vite copies `publicDir` first and then
+* writes the bundle over it). `case` means two output files differ only by
+* letter case. The build plugin checks bundle names before writing so this
+* also works on case-insensitive filesystems.
+*/
+export interface DevvitOutputCollision {
+  readonly kind: 'public' | 'case';
+  readonly path: string;
+  readonly sources: readonly string[];
+}
+/** Validate logical output names before the filesystem can collapse them. */
+export declare function assertDevvitOutputNames(bundleNames: readonly string[], publicNames: readonly string[], outDir: string): void;
+/** Shared Vite 7/8 guard for production and staging watch builds. */
+export declare function devvitOutputCollisionPlugin(): {
+  name: string;
+  apply: "build";
+  enforce: "post";
+  configResolved(config: {
+    publicDir: string;
+  }): void;
+  generateBundle: {
+    order: "post";
+    handler(this: {
+      environment: {
+        config: {
+          build: {
+            copyPublicDir: boolean;
+            outDir: string;
+          };
+        };
+      };
+    }, options: {
+      dir?: string | undefined;
+    }, bundle: Record<string, {
+      fileName: string;
+    }>): void;
+  };
+};
+/**
+* Finds output files of a Devvit client build that were overwritten or that
+* collide by case. `publicDirs` are the directories Vite copied verbatim.
+*/
+export declare function findDevvitOutputCollisions(outDir: string, publicDirs: readonly string[]): DevvitOutputCollision[];
+/** Throws a single readable error listing every collision. */
+export declare function assertNoDevvitOutputCollisions(outDir: string, publicDirs: readonly string[]): void;

package/dist/devvit-output-collisions.js

@@ -0,0 +1,120 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/** Validate logical output names before the filesystem can collapse them. */
+export function assertDevvitOutputNames(bundleNames, publicNames, outDir) {
+    const collisions = [];
+    const names = new Map();
+    for (const name of [...publicNames, ...bundleNames]) {
+        const previous = names.get(name.toLowerCase());
+        if (previous !== undefined) {
+            collisions.push({
+                kind: previous === name ? 'public' : 'case',
+                path: name,
+                sources: [previous, name],
+            });
+        }
+        names.set(name.toLowerCase(), name);
+    }
+    throwCollisions(collisions, outDir);
+}
+/** Shared Vite 7/8 guard for production and staging watch builds. */
+export function devvitOutputCollisionPlugin() {
+    let publicDir = '';
+    return {
+        name: 'mpgd-devvit-output-collisions',
+        apply: 'build',
+        enforce: 'post',
+        configResolved(config) {
+            publicDir = config.publicDir;
+        },
+        generateBundle: {
+            order: 'post',
+            handler(options, bundle) {
+                const publicNames = this.environment.config.build.copyPublicDir
+                    && publicDir !== '' && existsSync(publicDir) ? listFiles(publicDir) : [];
+                assertDevvitOutputNames(Object.values(bundle).map((output) => output.fileName), publicNames, options.dir ?? this.environment.config.build.outDir);
+            },
+        },
+    };
+}
+function listFiles(root) {
+    const out = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolute = join(directory, entry.name);
+            // Follow symlinks: a linked directory is traversed, a linked file listed.
+            const stats = entry.isSymbolicLink() ? statSync(absolute, { throwIfNoEntry: false }) : entry;
+            if (stats === undefined) {
+                continue;
+            }
+            if (stats.isDirectory()) {
+                pending.push(absolute);
+            }
+            else if (stats.isFile()) {
+                out.push(relative(root, absolute).split(sep).join('/'));
+            }
+        }
+    }
+    return out.sort();
+}
+/**
+ * Finds output files of a Devvit client build that were overwritten or that
+ * collide by case. `publicDirs` are the directories Vite copied verbatim.
+ */
+export function findDevvitOutputCollisions(outDir, publicDirs) {
+    if (!existsSync(outDir)) {
+        return [];
+    }
+    const outputs = listFiles(outDir);
+    const collisions = [];
+    for (const publicDir of publicDirs) {
+        if (!existsSync(publicDir)) {
+            continue;
+        }
+        for (const file of listFiles(publicDir)) {
+            const output = join(outDir, file);
+            if (!existsSync(output)) {
+                continue;
+            }
+            if (!readFileSync(output).equals(readFileSync(join(publicDir, file)))) {
+                collisions.push({
+                    kind: 'public',
+                    path: file,
+                    sources: [join(publicDir, file), 'vite bundle output'],
+                });
+            }
+        }
+    }
+    const byLowerCase = new Map();
+    for (const file of outputs) {
+        const key = file.toLowerCase();
+        byLowerCase.set(key, [...(byLowerCase.get(key) ?? []), file]);
+    }
+    for (const files of byLowerCase.values()) {
+        if (files.length > 1) {
+            collisions.push({ kind: 'case', path: files[0], sources: files });
+        }
+    }
+    return collisions;
+}
+/** Throws a single readable error listing every collision. */
+export function assertNoDevvitOutputCollisions(outDir, publicDirs) {
+    const collisions = findDevvitOutputCollisions(outDir, publicDirs);
+    throwCollisions(collisions, outDir);
+}
+function throwCollisions(collisions, outDir) {
+    if (collisions.length === 0) {
+        return;
+    }
+    const lines = collisions.map((collision) => collision.kind === 'public'
+        ? `  - ${collision.path}: public and bundle files use the same output name`
+        : `  - ${collision.sources.join(', ')}: names differ only by case`);
+    throw new Error([
+        `Devvit build output has ${collisions.length} conflicting file name(s) in ${outDir}:`,
+        ...lines,
+        'Rename the public file or the entry/chunk (Devvit client output uses unhashed [name].js names),'
+            + ' then rebuild.',
+    ].join('\n'));
+}

package/dist/index.js

@@ -25,6 +25,7 @@ import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageA
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
 import { defaultMpgdKitPath, initializeMicrosoftStoreStarter, listMicrosoftStoreInitializerTemplateFiles, prepareBaseGameTemplateFile, resolveMicrosoftStoreAdapterDependencyVersion, } from './microsoft-store-starter.js';
 import { applyKitUpgrade, planKitUpgrade } from './kit-upgrade.js';
+import { applyToolingMigration, planToolingMigration } from './tooling-migration.js';
 import { runMicrosoftStoreSubmissionPreflight } from './microsoft-store-submission.js';
 import { defaultOfflinePlaytestArtifactDir, defaultOfflinePlaytestMaximumBytes, defaultOfflinePlaytestOutputDir, runOfflinePlaytestPackaging, } from './offline-playtest.js';
 import { targetConfigExtensionsFileEnv, targetConfigMatrixFileEnv } from './target-config-env.js';
@@ -177,7 +178,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 === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade') && values.json === true) {
+            if ((ctx.name === 'verify-delivery' || ctx.name === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade' || ctx.name === 'migrate-tools') && values.json === true) {
                 return '';
             }
             const title = ctx.env.description || ctx.env.name || '';
@@ -188,7 +189,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 === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade') && values.json === true) {
+            if ((ctx.name === 'verify-delivery' || ctx.name === 'stage-target' || ctx.name === 'publish-s3' || ctx.name === 'upgrade' || ctx.name === 'migrate-tools') && values.json === true) {
                 process.stderr.write(`${messages}\n`);
                 return '';
             }
@@ -2576,6 +2577,58 @@ const kitCommand = defineI18n({
                 }
             },
         }),
+        'migrate-tools': defineI18n({
+            name: 'migrate-tools',
+            description: 'Plan or apply the TypeScript tools migration for an existing generated game.',
+            resource: commandResource({
+                base: {
+                    en: 'Plan or apply the TypeScript tools migration for an existing generated game.',
+                    ko: '기존 생성 게임의 TypeScript 도구 이전을 계획하거나 적용합니다.',
+                },
+                args: {
+                    game: { en: 'Existing generated game directory.', ko: '기존 생성 게임 디렉터리.' },
+                    apply: { en: 'Apply the reviewed local migration plan.', ko: '검토한 로컬 이전 계획을 적용합니다.' },
+                    json: { en: 'Print the complete plan as JSON.', ko: '전체 계획을 JSON으로 출력합니다.' },
+                },
+            }),
+            args: {
+                game: { type: 'string', required: false, default: '.', description: 'Game directory.' },
+                apply: { type: 'boolean', required: false, description: 'Apply the local plan.' },
+                json: { type: 'boolean', required: false, description: 'Print JSON.' },
+            },
+            run: (ctx) => {
+                const plan = planToolingMigration(readOptionalString(ctx.values.game) ?? '.', gameTemplateDir);
+                const result = ctx.values.apply === true && plan.blockers.length === 0
+                    ? applyToolingMigration(plan) : undefined;
+                if (ctx.values.json === true) {
+                    process.stdout.write(JSON.stringify({ plan, result: result ?? null }, null, 2) + '\n');
+                }
+                else {
+                    console.info('TypeScript tooling plan for ' + plan.gameRoot);
+                    for (const edit of plan.edits) {
+                        console.info('  ' + (edit.after === null ? 'Remove ' : 'Write ') + edit.file);
+                    }
+                    for (const note of plan.notes) {
+                        console.info('Note: ' + note);
+                    }
+                    for (const blocker of plan.blockers) {
+                        console.error('Blocked: ' + blocker);
+                    }
+                    if (result !== undefined) {
+                        console.info('Applied ' + result.length + ' file change(s).');
+                    }
+                    else if (!plan.edits.length && !plan.blockers.length) {
+                        console.info('TypeScript tooling is already current.');
+                    }
+                    else if (!plan.blockers.length) {
+                        console.info('Run again with --apply after reviewing the plan.');
+                    }
+                }
+                if (plan.blockers.length) {
+                    process.exitCode = 1;
+                }
+            },
+        }),
         doctor: defineI18n({
             name: 'doctor',
             description: 'Print CLI, kit, template, and target-wrapper status.',
@@ -2594,7 +2647,7 @@ const kitCommand = defineI18n({
         }),
     },
     run: () => {
-        console.info('Use "mpgd kit doctor" or "mpgd kit upgrade --game <directory> [--apply]".');
+        console.info('Use "mpgd kit doctor", "mpgd kit upgrade --game <directory> [--apply]", or "mpgd kit migrate-tools --game <directory> [--apply]".');
     },
 });
 function commandResource(description, args = {}) {
@@ -3042,6 +3095,9 @@ function createTemplateContext(input) {
         workspaceI18nBuildPrefix: input.workspace
             ? `pnpm --dir ${workspacePrefix} i18n:build && `
             : '',
+        devvitOutputPluginImport: input.workspace
+            ? toJavaScriptStringLiteral(`./${toTemplatePath(path.relative(path.join(input.appDir, 'apps/target-devvit'), path.resolve(kitPath ?? input.appDir, 'packages/cli/src/devvit-output-collisions')))}`)
+            : "'@mpgd/cli/devvit'",
         defaultKitPath: kitPath === undefined ? defaultMpgdKitPath : workspacePrefix,
         recommendedMatrixTargets: input.microsoftStore
             ? recommendedMatrixTargets
@@ -3133,6 +3189,7 @@ 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)

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "926ff936dc36d2112c042185974dc3c33102377d",
+  "kitGitSha": "88c1eb8846cc699d328d94d9c374b088c123e4c1",
   "kitDirty": false,
-  "packageVersion": "0.48.0"
+  "packageVersion": "0.49.0"
 }

package/dist/native-build-target.js

@@ -16525,6 +16525,12 @@ var releaseManifestEnvKeys = [
 ];
 var platformTargets = loadPlatformTargetsConfig();
 var configBaseDir = platformTargets.baseDir;
+var kitLinkCheck = resolve18("tools/workspace/relink-kit-workspace.mjs");
+if (existsSync24(kitLinkCheck)) {
+  spawnSync5(process.execPath, [kitLinkCheck, "--warn-unless-owner", configBaseDir], {
+    stdio: "inherit"
+  });
+}
 var config = platformTargets.config;
 var target = config.targets[targetName];
 if (target === void 0) {
@@ -16784,7 +16790,13 @@ try {
       const wrapperAppConfigPath = requireString2(target.wrapperApp, `${targetName}.wrapperApp`);
       const wrapperApp = targetPath(wrapperAppConfigPath);
       stageWrapperIcon(generatedIcons, wrapperApp);
-      run("pnpm", ["--dir", wrapperApp, "exec", "vite", "build", "--mode", profile], env);
+      run(process.execPath, [
+        resolve18("tools/run-ttsx.mjs"),
+        "--project",
+        resolve18("tsconfig.tools.json"),
+        resolve18("tools/target/build-devvit.ts"),
+        profile
+      ], env, wrapperApp);
       embedEffectiveTargetConfig(targetName, webDir, env);
       await stageTargetAssetPacks(webDir);
       stageWebIconEvidence(generatedIcons, webDir);

package/dist/tooling-migration.d.ts

@@ -0,0 +1,24 @@
+declare const managedPaths: readonly ['package.json', 'tsconfig.tools.json', 'tools/run-game-acceptance.mjs', 'tools/run-game-acceptance.ts', 'pnpm-lock.yaml'];
+type ManagedPath = typeof managedPaths[number];
+declare const snapshotPaths: readonly ["package.json", "tsconfig.tools.json", "tools/run-game-acceptance.mjs", "tools/run-game-acceptance.ts", "pnpm-lock.yaml", "pnpm-workspace.yaml", "tsconfig.json"];
+type SnapshotPath = typeof snapshotPaths[number];
+export interface ToolingMigrationEdit {
+  readonly file: ManagedPath;
+  readonly before: string | null;
+  readonly after: string | null;
+}
+export interface ToolingMigrationPlan {
+  readonly gameRoot: string;
+  readonly edits: readonly ToolingMigrationEdit[];
+  readonly snapshots: Readonly<Record<SnapshotPath, string | null>>;
+  readonly childManifests: Readonly<Record<string, string>>;
+  readonly updateLockfile: boolean;
+  readonly blockers: readonly string[];
+  readonly notes: readonly string[];
+}
+/** Plans only known generated-tool changes; custom scripts and source stay untouched. */
+export declare function planToolingMigration(gameDirectory: string, templateRoot?: string): ToolingMigrationPlan;
+/** Applies a fresh local plan, rolling back managed files and the game lockfile on failure. */
+export declare function applyToolingMigration(plan: ToolingMigrationPlan, updateLockfile?: typeof refreshLockfile): readonly string[];
+declare function refreshLockfile(gameRoot: string): void;
+export {};

package/dist/tooling-migration.js

@@ -0,0 +1,497 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { hostname } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'acorn';
+import { gte, minVersion, valid } from 'semver';
+import { resolveNativeCommandLaunch } from './command-launcher.js';
+const managedPaths = [
+    'package.json',
+    'tsconfig.tools.json',
+    'tools/run-game-acceptance.mjs',
+    'tools/run-game-acceptance.ts',
+    'pnpm-lock.yaml',
+];
+const snapshotPaths = [...managedPaths, 'pnpm-workspace.yaml', 'tsconfig.json'];
+const defaultTemplateRoot = fileURLToPath(new URL('../templates/phaser-game/', import.meta.url));
+/** Plans only known generated-tool changes; custom scripts and source stay untouched. */
+export function planToolingMigration(gameDirectory, templateRoot = defaultTemplateRoot) {
+    const gameRoot = realpathSync(path.resolve(gameDirectory));
+    const snapshots = Object.fromEntries(snapshotPaths.map((file) => [file, readOwnedFile(gameRoot, file)]));
+    const blockers = [];
+    const childManifests = readChildManifests(gameRoot);
+    const notes = [];
+    const edits = [];
+    const add = (file, after) => {
+        if (snapshots[file] !== after) {
+            edits.push({ file, before: snapshots[file], after });
+        }
+    };
+    const manifest = parseObject(snapshots['package.json'], 'package.json');
+    const template = parseObject(readFileSync(path.join(templateRoot, 'package.json'), 'utf8'), 'template package.json');
+    if (manifest.type !== 'module') {
+        blockers.push('Only generated ESM games (package.json type: module) can be migrated automatically.');
+    }
+    const scripts = objectField(manifest, 'scripts');
+    const templateScripts = objectField(template, 'scripts');
+    const oldCommands = {
+        accept: ['node ./tools/run-game-acceptance.mjs', 'node tools/run-game-acceptance.mjs'],
+        check: ['ttsc --noEmit -p tsconfig.json'],
+        lint: ['ttsc --noEmit -p tsconfig.json'],
+        format: ['ttsc format'],
+        fix: ['ttsc fix'],
+    };
+    for (const [name, old] of Object.entries(oldCommands)) {
+        const desired = templateScripts[name];
+        if (typeof desired !== 'string') {
+            throw new Error(`Template script ${name} is missing.`);
+        }
+        if (scripts[name] === undefined || scripts[name] === desired || old.includes(String(scripts[name]))) {
+            scripts[name] = desired;
+        }
+        else {
+            blockers.push(`Custom scripts.${name}: preserve it and migrate that command manually.`);
+        }
+    }
+    manifest.scripts = scripts;
+    const oldRunner = snapshots['tools/run-game-acceptance.mjs'];
+    const newRunner = snapshots['tools/run-game-acceptance.ts'];
+    if (oldRunner !== null && newRunner !== null) {
+        blockers.push('Both acceptance runners exist; resolve their contents before migrating.');
+    }
+    else if (oldRunner !== null) {
+        const templateRunner = readFileSync(path.join(templateRoot, 'tools/run-game-acceptance.ts'), 'utf8');
+        const rendered = migrateKnownRunner(oldRunner, templateRunner);
+        if (rendered === undefined) {
+            blockers.push('The JavaScript acceptance runner is customized; preserve it and migrate it manually.');
+        }
+        else {
+            add('tools/run-game-acceptance.ts', rendered);
+            add('tools/run-game-acceptance.mjs', null);
+        }
+    }
+    else if (newRunner === null) {
+        blockers.push('No generated acceptance runner was found.');
+    }
+    else if (migrateKnownRunner(newRunner, readFileSync(path.join(templateRoot, 'tools/run-game-acceptance.ts'), 'utf8')) === undefined) {
+        blockers.push('The TypeScript acceptance runner is customized; preserve it and migrate it manually.');
+    }
+    const toolsTemplate = parseObject(readFileSync(path.join(templateRoot, 'tsconfig.tools.json'), 'utf8'), 'template tools project');
+    const desiredTools = {
+        ...toolsTemplate,
+        compilerOptions: { ...objectField(toolsTemplate, 'compilerOptions'), strict: true },
+    };
+    const currentTools = snapshots['tsconfig.tools.json'];
+    if (currentTools === null) {
+        add('tsconfig.tools.json', stringify(desiredTools));
+    }
+    else {
+        const current = parseObject(currentTools, 'tsconfig.tools.json');
+        if (stable(current) === stable(toolsTemplate)) {
+            add('tsconfig.tools.json', stringify(desiredTools, currentTools));
+        }
+        else if (stable(current) !== stable(desiredTools)) {
+            blockers.push('Custom tsconfig.tools.json: preserve its options and migrate it manually.');
+        }
+    }
+    const dev = objectField(manifest, 'devDependencies');
+    const templateDev = objectField(template, 'devDependencies');
+    for (const section of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+        for (const name of ['ttsc', 'typescript', '@types/node']) {
+            if (objectField(manifest, section)[name] !== undefined) {
+                blockers.push(`Custom ${section}.${name}: keep toolchain declarations in devDependencies before migrating.`);
+            }
+        }
+    }
+    const compilerFloor = templateDev.ttsc;
+    if (typeof compilerFloor !== 'string' || !valid(compilerFloor)) {
+        throw new Error('Template ttsc must have an exact version.');
+    }
+    const currentCompiler = dev.ttsc;
+    if (!existsSync(path.join(gameRoot, 'tsconfig.json'))) {
+        blockers.push('Missing game tsconfig.json.');
+    }
+    let compilerVersion = compilerFloor;
+    if (typeof currentCompiler === 'string' && valid(currentCompiler)) {
+        if (gte(currentCompiler, compilerFloor)) {
+            compilerVersion = currentCompiler;
+        }
+    }
+    else if (currentCompiler !== undefined) {
+        blockers.push('Custom ttsc version specifier: align the shared toolchain manually first.');
+    }
+    let updateLockfile = false;
+    for (const name of ['ttsc', 'typescript', '@types/node']) {
+        const desired = name === 'ttsc' ? compilerVersion : templateDev[name];
+        if (typeof desired !== 'string') {
+            throw new Error(`Template dependency ${name} is missing.`);
+        }
+        const existing = versionFloor(dev[name]);
+        const minimum = minVersion(desired);
+        if (dev[name] !== undefined && existing === null) {
+            blockers.push(`Custom ${name} declaration: update it manually first.`);
+        }
+        if ((name === 'ttsc' || existing === null || (minimum !== null && !gte(existing, minimum))) && dev[name] !== desired) {
+            dev[name] = desired;
+            updateLockfile = true;
+        }
+    }
+    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const dependencies = section === 'devDependencies' ? dev : objectField(manifest, section);
+        for (const name of Object.keys(dependencies)) {
+            if (!name.startsWith('@ttsc/')) {
+                continue;
+            }
+            if (dependencies[name] !== compilerVersion) {
+                if (typeof dependencies[name] !== 'string' || !valid(dependencies[name]) || gte(dependencies[name], compilerVersion)) {
+                    blockers.push(`Custom or newer ${section}.${name}: align it with ttsc manually first.`);
+                }
+                else {
+                    dependencies[name] = compilerVersion;
+                    updateLockfile = true;
+                }
+            }
+        }
+        if (section === 'devDependencies' || manifest[section] !== undefined) {
+            manifest[section] = dependencies;
+        }
+    }
+    for (const [name, version] of Object.entries(objectField(manifest, 'peerDependencies'))) {
+        if (name.startsWith('@ttsc/') && version !== compilerVersion) {
+            blockers.push(`Custom peerDependencies.${name}: align the peer toolchain manually first.`);
+        }
+    }
+    for (const [file, source] of Object.entries(childManifests)) {
+        const child = parseObject(source, file);
+        for (const section of [
+            'dependencies',
+            'devDependencies',
+            'optionalDependencies',
+            'peerDependencies',
+        ]) {
+            for (const [name, version] of Object.entries(objectField(child, section))) {
+                if (name === 'ttsc' || name.startsWith('@ttsc/')) {
+                    if (version !== compilerVersion) {
+                        blockers.push(`${file}: align ${section}.${name} with ttsc ${compilerVersion} manually first.`);
+                    }
+                }
+                else if (name === 'typescript' || name === '@types/node') {
+                    const minimum = versionFloor(templateDev[name]);
+                    const current = versionFloor(version);
+                    if (minimum === null || current === null || !gte(current, minimum)) {
+                        blockers.push(`${file}: align ${section}.${name} with the template toolchain manually first.`);
+                    }
+                }
+            }
+        }
+    }
+    if (hasAncestorWorkspace(gameRoot)) {
+        blockers.push('This game belongs to a parent pnpm workspace. Automatic migration cannot verify its shared toolchain and lockfile; migrate the tools manually after aligning the owning workspace.');
+    }
+    if (updateLockfile) {
+        notes.push('Applying updates the game lockfile with pnpm install --lockfile-only --ignore-scripts.');
+    }
+    notes.push('Requires Node 24.11 or newer. Run pnpm check and pnpm accept --help after applying.');
+    if (stable(manifest) !== stable(parseObject(snapshots['package.json'], 'package.json'))) {
+        add('package.json', stringify(manifest, snapshots['package.json'] ?? undefined));
+    }
+    return { gameRoot, edits, snapshots, childManifests, updateLockfile, blockers, notes };
+}
+/** Applies a fresh local plan, rolling back managed files and the game lockfile on failure. */
+export function applyToolingMigration(plan, updateLockfile = refreshLockfile) {
+    if (plan.blockers.length) {
+        throw new Error(`Tooling migration blocked:\n${plan.blockers.join('\n')}`);
+    }
+    assertFreshPlan(plan);
+    for (const edit of plan.edits) {
+        if (!managedPaths.includes(edit.file) || edit.before !== plan.snapshots[edit.file]) {
+            throw new Error('Invalid tooling migration edit.');
+        }
+    }
+    if (!plan.edits.length) {
+        return [];
+    }
+    const lockPath = path.join(plan.gameRoot, '.mpgd-tooling-migration.lock');
+    const lock = JSON.stringify({
+        token: randomUUID(),
+        pid: process.pid,
+        host: hostname(),
+        startedAt: new Date().toISOString(),
+    });
+    try {
+        writeFileSync(lockPath, lock, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (isObject(error) && error.code === 'EEXIST') {
+            throw new Error(`Migration lock exists (EEXIST): ${lockPath}. If an earlier run was interrupted, verify its process and pnpm child have exited, inspect partial changes, then remove only this lock and run a fresh preview.`, { cause: error });
+        }
+        throw error;
+    }
+    let writesStarted = false;
+    let lockfileUpdateAttempted = false;
+    const written = [];
+    try {
+        // Another migration may have completed between the initial check and lock acquisition.
+        assertFreshPlan(plan);
+        writesStarted = true;
+        for (const edit of plan.edits) {
+            if (readOwnedFile(plan.gameRoot, edit.file) !== edit.before) {
+                throw new Error(`File changed during migration: ${edit.file}`);
+            }
+            writeOwnedFile(plan.gameRoot, edit.file, edit.after);
+            written.push(edit);
+        }
+        if (plan.updateLockfile) {
+            lockfileUpdateAttempted = true;
+            updateLockfile(plan.gameRoot);
+        }
+    }
+    catch (error) {
+        if (!writesStarted) {
+            throw error;
+        }
+        const failures = [];
+        for (const edit of [...written].reverse()) {
+            try {
+                if (readOwnedFile(plan.gameRoot, edit.file) !== edit.after) {
+                    throw new Error('A concurrent writer changed the migration output.');
+                }
+                writeOwnedFile(plan.gameRoot, edit.file, edit.before);
+            }
+            catch {
+                failures.push(edit.file);
+            }
+        }
+        if (lockfileUpdateAttempted) {
+            try {
+                // pnpm does not honor our migration lock. A changed lockfile might be
+                // another install's output; preserve it and require manual inspection.
+                if (readOwnedFile(plan.gameRoot, 'pnpm-lock.yaml') !== plan.snapshots['pnpm-lock.yaml']) {
+                    failures.push('pnpm-lock.yaml');
+                }
+            }
+            catch {
+                failures.push('pnpm-lock.yaml');
+            }
+        }
+        let rollbackStatus = lockfileUpdateAttempted
+            ? 'Managed files restored; lockfile unchanged.'
+            : 'Managed files restored; lockfile untouched.';
+        if (failures.length) {
+            rollbackStatus = `Rollback incomplete: ${failures.join(', ')}`;
+        }
+        throw new Error(`Tooling migration failed. ${rollbackStatus}`, { cause: error });
+    }
+    finally {
+        if (existsSync(lockPath) && readFileSync(lockPath, 'utf8') === lock) {
+            rmSync(lockPath);
+        }
+    }
+    return plan.edits.map((edit) => edit.file);
+}
+function assertFreshPlan(plan) {
+    if (realpathSync(plan.gameRoot) !== plan.gameRoot) {
+        throw new Error('Game root changed after planning.');
+    }
+    for (const file of snapshotPaths) {
+        if (readOwnedFile(plan.gameRoot, file) !== plan.snapshots[file]) {
+            throw new Error(`File changed after planning: ${file}`);
+        }
+    }
+    if (stable(readChildManifests(plan.gameRoot)) !== stable(plan.childManifests)) {
+        throw new Error('Child package manifests changed after planning.');
+    }
+    if (hasAncestorWorkspace(plan.gameRoot)) {
+        throw new Error('Parent workspace changed after planning.');
+    }
+}
+// Conservatively inspect game-owned nested packages, including custom workspace
+// layouts. Never traverse dependency installs, generated builds or linked trees.
+function readChildManifests(root) {
+    const manifests = {};
+    const ignored = new Set(['node_modules', 'dist', 'build', 'coverage']);
+    function visit(directory) {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || ignored.has(entry.name)) {
+                continue;
+            }
+            const full = path.join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                if (entry.name === 'package.json' || existsSync(path.join(full, 'package.json'))) {
+                    throw new Error(`Refusing linked child package: ${path.relative(root, full)}`);
+                }
+            }
+            else if (entry.isDirectory()) {
+                visit(full);
+            }
+            else if (directory !== root && entry.name === 'package.json') {
+                manifests[path.relative(root, full)] = readFileSync(full, 'utf8');
+            }
+        }
+    }
+    visit(root);
+    return manifests;
+}
+function parseObject(source, label) {
+    if (source === null) {
+        throw new Error(`Missing ${label}.`);
+    }
+    const parsed = JSON.parse(source);
+    if (!isObject(parsed)) {
+        throw new Error(`${label} must be a JSON object.`);
+    }
+    return parsed;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function objectField(value, key) {
+    if (value[key] === undefined) {
+        return {};
+    }
+    if (!isObject(value[key])) {
+        throw new Error(`${key} must be an object.`);
+    }
+    return value[key];
+}
+function stable(value) {
+    return JSON.stringify(value, (_key, entry) => isObject(entry)
+        ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)))
+        : entry);
+}
+function stringify(value, original = '') {
+    const indent = /^([\t ]+)"/m.exec(original)?.[1] ?? '  ';
+    const text = JSON.stringify(value, null, indent) + '\n';
+    return original.includes('\r\n') ? text.replace(/\n/g, '\r\n') : text;
+}
+function migrateKnownRunner(source, template) {
+    try {
+        let comments = 0;
+        const ast = parse(source, {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            onComment: () => {
+                comments++;
+            },
+        });
+        if (comments) {
+            return undefined;
+        } // Preserve user-authored comments rather than silently replacing them.
+        const defaults = [];
+        function walk(value) {
+            if (Array.isArray(value)) {
+                for (const entry of value) {
+                    walk(entry);
+                }
+            }
+            else if (isObject(value)) {
+                if (value.type === 'ConditionalExpression' && isObject(value.consequent) && typeof value.consequent.value === 'string') {
+                    defaults.push(value.consequent.value);
+                }
+                for (const entry of Object.values(value)) {
+                    walk(entry);
+                }
+            }
+        }
+        walk(ast);
+        if (defaults.length !== 1) {
+            return undefined;
+        }
+        const rendered = template.replace("'__DEFAULT_KIT_PATH__'", JSON.stringify(defaults[0]));
+        const canonical = (value) => JSON.stringify(value, (key, item) => ['start', 'end', 'raw'].includes(key) ? undefined : item);
+        return canonical(ast) === canonical(parse(rendered, { ecmaVersion: 'latest', sourceType: 'module' }))
+            ? rendered
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readOwnedFile(root, file) {
+    const full = ownedPath(root, file);
+    return existsSync(full) ? readFileSync(full, 'utf8') : null;
+}
+function ownedPath(root, file) {
+    if (!snapshotPaths.includes(file)) {
+        throw new Error('Path is not owned by tooling migration.');
+    }
+    let current = root;
+    for (const part of file.split('/')) {
+        current = path.join(current, part);
+        try {
+            if (lstatSync(current).isSymbolicLink()) {
+                throw new Error(`Refusing linked migration path: ${file}`);
+            }
+        }
+        catch (error) {
+            if (!isObject(error) || error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    return current;
+}
+function writeOwnedFile(root, file, source) {
+    const full = ownedPath(root, file);
+    if (source === null) {
+        rmSync(full, { force: true });
+        return;
+    }
+    const temporary = `${full}.mpgd-${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, source, {
+            flag: 'wx',
+            mode: existsSync(full) ? lstatSync(full).mode & 0o777 : 0o644,
+        });
+        renameSync(temporary, full);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function hasAncestorWorkspace(root) {
+    if (existsSync(path.join(root, 'pnpm-workspace.yaml'))) {
+        return false;
+    }
+    for (let parent = path.dirname(root);; parent = path.dirname(parent)) {
+        if (existsSync(path.join(parent, 'pnpm-workspace.yaml'))) {
+            return true;
+        }
+        if (path.dirname(parent) === parent) {
+            return false;
+        }
+    }
+}
+function refreshLockfile(gameRoot) {
+    const environment = { ...process.env };
+    for (const key of Object.keys(environment)) {
+        if (key.toLowerCase() === 'npm_config_workspace_dir') {
+            delete environment[key];
+        }
+    }
+    const launch = resolveNativeCommandLaunch({
+        command: 'pnpm',
+        args: ['install', '--lockfile-only', '--ignore-scripts', '--lockfile-dir', gameRoot],
+        environment,
+    });
+    const result = spawnSync(launch.command, [...launch.args], {
+        cwd: gameRoot,
+        env: environment,
+        encoding: 'utf8',
+        timeout: 120_000,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    if (result.error || result.status !== 0) {
+        throw new Error(`Could not refresh game lockfile: ${result.error?.message ?? result.stderr}`);
+    }
+}
+function versionFloor(value) {
+    try {
+        return typeof value === 'string' ? minVersion(value) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./devvit": {
+      "types": "./dist/devvit-output-collisions.d.ts",
+      "default": "./dist/devvit-output-collisions.js"
     }
   },
   "files": [
@@ -66,29 +70,29 @@
     "parse5": "7.3.0",
     "postcss": "8.5.28",
     "postcss-value-parser": "4.2.0",
-    "@mpgd/catalog": "0.10.0",
-    "@mpgd/phaser-assets": "0.9.0",
-    "@mpgd/platform": "0.23.0",
-    "@mpgd/target-config": "0.23.0"
+    "@mpgd/catalog": "0.10.1",
+    "@mpgd/phaser-assets": "0.9.1",
+    "@mpgd/platform": "0.23.1",
+    "@mpgd/target-config": "0.23.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/semver": "^7.8.0",
     "@types/yauzl": "3.4.0",
-    "ttsc": "0.30.4",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.17.0",
-    "@mpgd/adapter-browser": "0.11.0",
-    "@mpgd/adapter-capacitor": "0.10.0",
-    "@mpgd/adapter-devvit": "0.12.0",
-    "@mpgd/analytics": "0.4.9",
-    "@mpgd/adapter-verse8": "0.7.0",
-    "@mpgd/capacitor-play-billing": "0.3.0",
-    "@mpgd/bridge": "0.13.0",
-    "@mpgd/capacitor-storekit": "0.3.0",
-    "@mpgd/game-services": "0.24.0",
-    "@mpgd/game-runtime": "0.7.0",
-    "@mpgd/i18n": "0.6.14"
+    "@mpgd/adapter-ait": "0.17.1",
+    "@mpgd/adapter-browser": "0.11.1",
+    "@mpgd/adapter-capacitor": "0.10.1",
+    "@mpgd/adapter-devvit": "0.12.1",
+    "@mpgd/adapter-verse8": "0.7.1",
+    "@mpgd/analytics": "0.4.10",
+    "@mpgd/capacitor-play-billing": "0.3.1",
+    "@mpgd/bridge": "0.13.1",
+    "@mpgd/capacitor-storekit": "0.3.1",
+    "@mpgd/game-runtime": "0.7.1",
+    "@mpgd/game-services": "0.24.1",
+    "@mpgd/i18n": "0.6.15"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/lite-overlay/AGENTS.md

@@ -21,6 +21,11 @@ This is a Canvas2D game generated with the mpgd lite template.
 
 ## Tooling and checks
 
+- Author game code, tests, and development tools in TypeScript (`.ts`). Include every tool in
+  `tsconfig.tools.json` and run it with `ttsx --project tsconfig.tools.json`.
+- Use `.mjs`, `.cjs`, or authored `.js` only when a concrete consumer cannot run TypeScript
+  (for example a browser fixture or a JavaScript-only config loader). Document that constraint
+  beside the file. Convenience or avoiding type errors is not an exception.
 - Use `ttsx`, `ttsc`, and `@ttsc/lint`; do not add `tsx`, ESLint, or Prettier.
 - Run focused checks, then `pnpm check` and `pnpm build`.
 - Run `pnpm accept` for a target handoff; preserve its generated evidence.

package/templates/phaser-game/AGENTS.md

@@ -27,6 +27,11 @@ This repository is a standalone Phaser game generated with `@mpgd/create-game`.
 
 ## Tooling and checks
 
+- Author game code, tests, and development tools in TypeScript (`.ts`). Include every tool in
+  `tsconfig.tools.json` and run it with `ttsx --project tsconfig.tools.json`.
+- Use `.mjs`, `.cjs`, or authored `.js` only when a concrete consumer cannot run TypeScript
+  (for example a browser fixture or a JavaScript-only config loader). Document that constraint
+  beside the file. Convenience or avoiding type errors is not an exception.
 - Use `ttsx`, not `tsx`, for TypeScript scripts.
 - Use `ttsc` and `@ttsc/lint`; do not add ESLint or Prettier for TypeScript.
 - Run focused checks, then `pnpm check` and `pnpm build`.

package/templates/phaser-game/apps/target-ait/package.json

@@ -21,9 +21,9 @@
   },
   "devDependencies": {
     "@apps-in-toss/cli": "3.6.0",
-    "@ttsc/unplugin": "0.30.4",
+    "@ttsc/unplugin": "0.32.1",
     "@types/node": "^24.0.0",
-    "ttsc": "0.30.4",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vite": "8.1.3"
   }

package/templates/phaser-game/apps/target-cloudflare-pages/package.json

@@ -19,8 +19,8 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260707.1",
-    "@ttsc/unplugin": "0.30.4",
-    "ttsc": "0.30.4",
+    "@ttsc/unplugin": "0.32.1",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vite": "8.1.3",
     "wrangler": "^4.107.0"

package/templates/phaser-game/apps/target-devvit/package.json

@@ -26,10 +26,10 @@
   },
   "devDependencies": {
     "@devvit/start": "0.14.1",
-    "@ttsc/unplugin": "0.30.4",
+    "@ttsc/unplugin": "0.32.1",
     "@types/node": "^24.0.0",
     "devvit": "0.14.1",
-    "ttsc": "0.30.4",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vite": "7.3.6"
   }

package/templates/phaser-game/apps/target-devvit/vite.config.ts

@@ -2,6 +2,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { devvit } from '@devvit/start/vite';
+import { devvitOutputCollisionPlugin } from '@mpgd/cli/devvit';
 import { defineConfig, type PluginOption } from 'vite';
 
 import { createGameViteSharedConfig } from '../../vite.shared';
@@ -24,6 +25,7 @@ export default defineConfig(({ mode }) => {
     publicDir: resolve(gameRoot, 'public'),
     plugins: [
       ...(shared.plugins ?? []),
+      devvitOutputCollisionPlugin(),
       devvit({
         client: {
           build: {

package/templates/phaser-game/package.json

@@ -8,7 +8,7 @@
     "dev": "__WORKSPACE_I18N_BUILD_PREFIX__vite --host 0.0.0.0",
     "dev:ait": "APP_TARGET=ait MPGD_CONFIG_TARGET=ait MPGD_PLATFORM_TARGETS_FILE=./mpgd.targets.json APP_VERSION=0.0.0-dev BUILD_ID=ait-sandbox sh -c '__WORKSPACE_I18N_BUILD_PREFIX__vite --host 0.0.0.0'",
     "build": "__WORKSPACE_I18N_BUILD_PREFIX__vite build",
-    "accept": "node ./tools/run-game-acceptance.mjs",
+    "accept": "ttsx --project tsconfig.tools.json tools/run-game-acceptance.ts --",
     "icons:generate": "pnpm exec mpgd game icons generate . --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
     "icons:generate:devvit": "pnpm exec mpgd game icons generate . --targets reddit --profile development --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
     "icons:generate:devvit:production": "pnpm exec mpgd game icons generate . --targets reddit --profile production --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
@@ -49,10 +49,10 @@
     "pages:dev": "pnpm legal:build && pnpm --dir apps/target-cloudflare-pages run dev",
     "pages:preview": "pnpm legal:build && pnpm --dir apps/target-cloudflare-pages run preview",
     "pages:types": "pnpm --dir apps/target-cloudflare-pages run types",
-    "check": "ttsc --noEmit -p tsconfig.json",
-    "lint": "ttsc --noEmit -p tsconfig.json",
-    "format": "ttsc format",
-    "fix": "ttsc fix"
+    "check": "ttsc --noEmit -p tsconfig.json && ttsc --noEmit -p tsconfig.tools.json",
+    "lint": "ttsc --noEmit -p tsconfig.json && ttsc --noEmit -p tsconfig.tools.json",
+    "format": "ttsc format -p tsconfig.json && ttsc format -p tsconfig.tools.json",
+    "fix": "ttsc fix -p tsconfig.json && ttsc fix -p tsconfig.tools.json"
   },
   "dependencies": {
     "@ait-co/polyfill": "^0.1.19",
@@ -81,9 +81,9 @@
     "@ait-co/console-cli": "^0.1.49",
     "@cloudflare/workers-types": "^5.20260707.1",
     "@mpgd/cli": "__MPGD_DEPENDENCY_VERSION_CLI__",
-    "@ttsc/unplugin": "0.30.4",
+    "@ttsc/unplugin": "0.32.1",
     "@types/node": "^24.0.0",
-    "ttsc": "0.30.4",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vite": "8.1.3",
     "wrangler": "^4.107.0"

package/templates/phaser-game/tools/{run-game-acceptance.mjs → run-game-acceptance.ts}

@@ -12,11 +12,4 @@ const kitPath = path.resolve(
     : configuredKitPath,
 );
 
-await runMpgdCli([
-  'game',
-  'accept',
-  gameRoot,
-  '--kit-path',
-  kitPath,
-  ...process.argv.slice(2),
-]);
+await runMpgdCli(['game', 'accept', gameRoot, '--kit-path', kitPath, ...process.argv.slice(2)]);

package/templates/phaser-game/tsconfig.tools.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ],
+    "noEmit": true
+  },
+  "include": [
+    "tools/**/*.ts"
+  ]
+}