@bleedingdev/modern-js-create 3.5.0-ultramodern.28 → 3.5.0-ultramodern.29

package/dist/esm-node/ultramodern-tooling/commands.js

@@ -7,28 +7,30 @@ import { fileURLToPath } from "node:url";
 import { resolveCreatePackageRoot } from "../create-package-root.js";
 import { BLEEDINGDEV_PACKAGE_NAME_PREFIX, BLEEDINGDEV_PACKAGE_SCOPE, ULTRAMODERN_SINGLE_APP_MODERN_PACKAGES, ULTRAMODERN_WORKSPACE_MODERN_PACKAGES, WORKSPACE_PACKAGE_VERSION, modernPackageSpecifier } from "../ultramodern-package-source.js";
 import { createAppEnvDts } from "../ultramodern-workspace/app-files.js";
+import { createBackendFederationContractFile } from "../ultramodern-workspace/backend-federation.js";
+import { runSyncDeliveryUnit } from "../ultramodern-workspace/delivery-unit-sync.js";
 import { validateModuleFederationTypes } from "../ultramodern-workspace/mf-validation.js";
-import { createAppModernConfig } from "../ultramodern-workspace/module-federation.js";
+import { createAppModernConfig, createUltramodernBuildModule, createUltramodernBuildReexportModule } from "../ultramodern-workspace/module-federation.js";
 import { createAppMfTypesTsConfig, createAppTsConfig, createSharedPackageTsConfig, createTsConfigBase } from "../ultramodern-workspace/package-json.js";
+import { GENERATED_TOOLING_COMMANDS, generatedToolingCommandList, generatedToolingCommands } from "../ultramodern-workspace/tooling-command-catalog.js";
 import { DRIZZLE_ORM_VERSION, EFFECT_TSGO_VERSION, EFFECT_VERSION, EFFECT_VITEST_VERSION, MODULE_FEDERATION_VERSION, OXFMT_VERSION, OXLINT_VERSION, TYPESCRIPT_NATIVE_PREVIEW_VERSION, WRANGLER_VERSION, ZEPHYR_AGENT_VERSION, ZEPHYR_RSPACK_PLUGIN_VERSION } from "../ultramodern-workspace/versions.js";
-import { createWorkspaceValidationScript } from "../ultramodern-workspace/workspace-scripts.js";
-import { readUltramodernConfig, workspaceAppsFromToolingConfig } from "./config.js";
+import { createWorkspaceAppPackageScripts, createWorkspaceRootPackageScripts } from "../ultramodern-workspace/workspace-script-plan.js";
+import { createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, writeGeneratedToolWrapperScripts } from "../ultramodern-workspace/workspace-scripts.js";
+import { createZeropsYaml } from "../ultramodern-workspace/zerops.js";
+import { normalizeCompactUltramodernConfig, readUltramodernConfig, synthesizeCompactUltramodernConfig, workspaceAppsFromToolingConfig } from "./config.js";
 const commands_dirname = node_path.dirname(fileURLToPath(import.meta.url));
 const createPackageRoot = resolveCreatePackageRoot(commands_dirname);
 function printHelp() {
+    const commands = [
+        ...generatedToolingCommandList().map((command)=>`  ${command}`),
+        '  skills install',
+        '  skills check'
+    ].join('\n');
     process.stdout.write(`Usage:
   modern-js-create ultramodern <command> [args]
 
 Commands:
-  validate
-  typecheck
-  mf-types
-  migrate-strict-effect
-  public-surface
-  cloudflare-proof
-  performance-readiness
-  skills install
-  skills check
+${commands}
 `);
 }
 function spawnNodeScript(relativeScriptPath, args, context, options = {}) {
@@ -47,6 +49,13 @@ function spawnNodeScript(relativeScriptPath, args, context, options = {}) {
     if (result.error) throw result.error;
     return result.status ?? 1;
 }
+function runTemplateBackedToolingCommand(command, args, context) {
+    const toolingCommand = generatedToolingCommands.find((candidate)=>candidate.command === command);
+    if (!toolingCommand?.templatePath) return;
+    return spawnNodeScript(toolingCommand.templatePath, args, context, {
+        cwd: 'invocation' === toolingCommand.cwd ? context.invocationCwd : context.workspaceRoot
+    });
+}
 function runRenderedModule(source, context) {
     const tempDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), 'ultramodern-tool-'));
     const tempFile = node_path.join(tempDir, 'command.mjs');
@@ -93,11 +102,45 @@ const modernPackageNames = new Set([
     ...ULTRAMODERN_SINGLE_APP_MODERN_PACKAGES,
     ...ULTRAMODERN_WORKSPACE_MODERN_PACKAGES
 ]);
+function createMigrationIo(workspaceRoot, dryRun) {
+    const plan = [];
+    const rel = (p)=>(node_path.relative(workspaceRoot, p) || node_path.basename(p)).split(node_path.sep).join('/');
+    return {
+        workspaceRoot,
+        dryRun,
+        plan,
+        write (filePath, content) {
+            if (node_fs.existsSync(filePath) && node_fs.readFileSync(filePath, 'utf-8') === content) return false;
+            if (dryRun) {
+                plan.push(`[dry-run] would write ${rel(filePath)}`);
+                return true;
+            }
+            node_fs.mkdirSync(node_path.dirname(filePath), {
+                recursive: true
+            });
+            node_fs.writeFileSync(filePath, content, 'utf-8');
+            return true;
+        },
+        remove (filePath) {
+            if (!node_fs.existsSync(filePath)) return false;
+            if (dryRun) {
+                plan.push(`[dry-run] would delete ${rel(filePath)}`);
+                return true;
+            }
+            node_fs.rmSync(filePath);
+            return true;
+        },
+        log (message) {
+            if (dryRun) plan.push(`[dry-run] ${message}`);
+            else process.stdout.write(`[ultramodern] ${message}\n`);
+        }
+    };
+}
 function readJsonFile(filePath) {
     return JSON.parse(node_fs.readFileSync(filePath, 'utf-8'));
 }
-function writeJsonFile(filePath, value) {
-    node_fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+function writeJsonFile(io, filePath, value) {
+    return io.write(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 function readOption(args, name) {
     const prefix = `${name}=`;
@@ -130,7 +173,7 @@ function listWorkspacePackageFiles(workspaceRoot) {
             withFileTypes: true
         })){
             if (!entry.isDirectory()) continue;
-            const packageFile = node_path.join(directory, entry.name, 'package.json');
+            const packageFile = `${directory}/${entry.name}/package.json`;
             if (node_fs.existsSync(node_path.join(workspaceRoot, packageFile))) packageFiles.push(packageFile);
         }
     }
@@ -220,15 +263,36 @@ const cloudflareModernDeployCommand = 'ULTRAMODERN_ZEPHYR=false MODERNJS_DEPLOY=
 const cloudflareModernDeploySkipBuildCommand = `${cloudflareModernDeployCommand} --skip-build`;
 const cloudflareWranglerDeployCommand = 'wrangler deploy --config .output/wrangler.json';
 const cloudflareWranglerDeployInvalidSkipBuildCommand = `${cloudflareWranglerDeployCommand} --skip-build`;
-function updateGeneratedPackageScripts(packageJson) {
+function removeStaleBackendFederationCommandSegments(command) {
+    return command.replace(/\s+&&\s+node\s+\S*scripts\/generate-node-backend-federation\.m[ct]s(?:\s+--app\s+\S+)?(?:\s+--target\s+\S+)?(?=\s+&&|$)/gu, '');
+}
+function updateGeneratedPackageScripts(packageJson, options = {}) {
     const scripts = packageJson.scripts;
     if (!scripts || 'object' != typeof scripts || Array.isArray(scripts)) return false;
     let changed = false;
+    const apps = options.apps ?? [];
+    const app = apps.find((candidate)=>`${candidate.directory}/package.json` === options.relativePackageFile);
+    const expectedScripts = 'package.json' === options.relativePackageFile ? createWorkspaceRootPackageScripts(apps.filter((candidate)=>'shell' !== candidate.kind)) : app ? createWorkspaceAppPackageScripts(app) : void 0;
+    if (expectedScripts) {
+        for (const [name, value] of Object.entries(expectedScripts))if (scripts[name] !== value) {
+            scripts[name] = value;
+            changed = true;
+        }
+    }
+    const build = scripts.build;
+    if ('string' == typeof build) {
+        const nextBuild = removeStaleBackendFederationCommandSegments(build);
+        if (nextBuild !== build) {
+            scripts.build = nextBuild;
+            changed = true;
+        }
+    }
     const cloudflareBuild = scripts['cloudflare:build'];
     if ('string' == typeof cloudflareBuild) {
-        let nextCloudflareBuild = cloudflareBuild;
+        let nextCloudflareBuild = removeStaleBackendFederationCommandSegments(cloudflareBuild);
         if (nextCloudflareBuild.includes(cloudflareModernDeployCommand) && !nextCloudflareBuild.includes(cloudflareModernDeploySkipBuildCommand)) nextCloudflareBuild = nextCloudflareBuild.replace(cloudflareModernDeployCommand, cloudflareModernDeploySkipBuildCommand);
         nextCloudflareBuild = nextCloudflareBuild.replace(/ && node \S*scripts\/generate-public-surface-assets\.m[ct]s --app [^&]+ --target dist(?= && ULTRAMODERN_ZEPHYR=false MODERNJS_DEPLOY=cloudflare modern deploy --skip-build)/u, '');
+        nextCloudflareBuild = nextCloudflareBuild.replace(/ && node \S*scripts\/verify-cloudflare-output\.m[ct]s(?: --app [^&]+)?/u, '');
         if (nextCloudflareBuild !== cloudflareBuild) {
             scripts['cloudflare:build'] = nextCloudflareBuild;
             changed = true;
@@ -242,9 +306,18 @@ function updateGeneratedPackageScripts(packageJson) {
     return changed;
 }
 function normalizeStrictEffectApiMetadata(value) {
-    const api = value.api;
-    if (!api || 'object' != typeof api || Array.isArray(api)) return false;
     let changed = false;
+    const backendFederation = value.backendFederation;
+    if (backendFederation && 'object' == typeof backendFederation && !Array.isArray(backendFederation) && Object.hasOwn(backendFederation, 'entry')) {
+        delete backendFederation.entry;
+        changed = true;
+    }
+    const api = value.api;
+    if (!api || 'object' != typeof api || Array.isArray(api)) return changed;
+    if (void 0 !== api.backendFederation) {
+        delete api.backendFederation;
+        changed = true;
+    }
     const oldEffect = api.effect;
     if (oldEffect && 'object' == typeof oldEffect && !Array.isArray(oldEffect)) {
         if (void 0 === api.stem && 'string' == typeof oldEffect.stem) {
@@ -306,6 +379,38 @@ function normalizeStrictEffectApiMetadata(value) {
     }
     return changed;
 }
+function removeGeneratedFileIfExists(io, relativePath) {
+    return io.remove(node_path.join(io.workspaceRoot, relativePath));
+}
+function removeStaleBackendFederationArtifacts(io, config) {
+    let changed = false;
+    for (const relativePath of [
+        "scripts/generate-node-backend-federation.mts",
+        "scripts/proof-node-backend-federation.mts",
+        "scripts/verify-cloudflare-output.mts"
+    ])changed = removeGeneratedFileIfExists(io, relativePath) || changed;
+    for (const app of workspaceAppsFromToolingConfig(config))changed = removeGeneratedFileIfExists(io, node_path.join(app.directory, 'api/backend-federation.ts')) || changed;
+    return changed;
+}
+function updateGeneratedZeropsArtifacts(io, config) {
+    const apps = workspaceAppsFromToolingConfig(config);
+    let changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, 'zerops.yaml'), `${createZeropsYaml(config.workspace.packageScope, apps)}\n`);
+    changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, "scripts/materialize-zerops-runtime.mjs"), createZeropsRuntimeMaterializationScript()) || changed;
+    return changed;
+}
+function updateGeneratedBuildIdentityModules(io, config) {
+    let changed = false;
+    for (const app of workspaceAppsFromToolingConfig(config)){
+        changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'src/ultramodern-build.ts'), createUltramodernBuildReexportModule()) || changed;
+        changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'shared/ultramodern-build.ts'), createUltramodernBuildModule(config.workspace.packageScope, app)) || changed;
+    }
+    return changed;
+}
+function updateGeneratedBackendFederationContractFiles(io, config) {
+    let changed = false;
+    for (const app of workspaceAppsFromToolingConfig(config))if (app.api) changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'api/backend-federation.ts'), createBackendFederationContractFile(app)) || changed;
+    return changed;
+}
 function replaceYamlLine(source, pattern, replacement) {
     const updated = source.replace(pattern, replacement);
     return {
@@ -338,22 +443,35 @@ function ensureYamlListItem(source, key, item) {
         changed: true
     };
 }
-function ensureYamlMapEntry(source, key, entryKey, value) {
-    const entryLine = `  '${entryKey}': ${value}`;
-    const packageName = entryKey.includes('@') ? entryKey.slice(0, entryKey.lastIndexOf('@')) : entryKey;
-    const escapedPackageName = packageName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    const currentEntryPattern = new RegExp(`^ {2}'${escapedPackageName}@[^']+': .+$`, 'mu');
-    const currentEntry = source.match(currentEntryPattern);
-    if (currentEntry) {
-        if (currentEntry[0] === entryLine) return {
-            source,
-            changed: false
-        };
-        return {
-            source: source.replace(currentEntryPattern, entryLine),
-            changed: true
-        };
+function yamlEntryPattern(entryKey, scalar = false) {
+    const bareKey = entryKey.replace(/^['"]|['"]$/gu, '');
+    if (scalar) {
+        const esc = bareKey.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+        return new RegExp(`^ {2}(?:'${esc}'|"${esc}"|${esc}): .+$`, 'gmu');
     }
+    const packageName = bareKey.includes('@') ? bareKey.slice(0, bareKey.lastIndexOf('@')) : bareKey;
+    const esc = packageName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`^ {2}(?:'${esc}@[^']+'|"${esc}@[^"]+"|${esc}@[^:'"\\s]+): .+$`, 'gmu');
+}
+function upsertYamlEntry(source, key, entryLine, pattern) {
+    const linePattern = new RegExp(pattern.source, 'u');
+    const lines = source.split('\n');
+    let seen = false;
+    let changed = false;
+    const out = [];
+    for (const line of lines)if (linePattern.test(line)) {
+        if (seen) {
+            changed = true;
+            continue;
+        }
+        seen = true;
+        if (line !== entryLine) changed = true;
+        out.push(entryLine);
+    } else out.push(line);
+    if (seen) return {
+        source: out.join('\n'),
+        changed
+    };
     const headerPattern = new RegExp(`^${key}:\\n(?:(?:  .+\\n)*)`, 'mu');
     const header = source.match(headerPattern);
     if (header) {
@@ -371,62 +489,43 @@ function ensureYamlMapEntry(source, key, entryKey, value) {
         changed: true
     };
 }
+function ensureYamlMapEntry(source, key, entryKey, value) {
+    return upsertYamlEntry(source, key, `  '${entryKey}': ${value}`, yamlEntryPattern(entryKey));
+}
 function ensureYamlScalarMapEntry(source, key, entryKey, value) {
-    const entryLine = `  ${entryKey}: ${value}`;
-    const escapedEntryKey = entryKey.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    const currentEntryPattern = new RegExp(`^ {2}${escapedEntryKey}: .+$`, 'mu');
-    const currentEntry = source.match(currentEntryPattern);
-    if (currentEntry) {
-        if (currentEntry[0] === entryLine) return {
-            source,
-            changed: false
-        };
-        return {
-            source: source.replace(currentEntryPattern, entryLine),
-            changed: true
-        };
-    }
-    const headerPattern = new RegExp(`^${key}:\\n(?:(?:  .+\\n)*)`, 'mu');
-    const header = source.match(headerPattern);
-    if (header) return {
-        source: source.replace(headerPattern, `${header[0]}${entryLine}\n`),
-        changed: true
-    };
-    return {
-        source: `${source.trimEnd()}\n${key}:\n${entryLine}\n`,
-        changed: true
-    };
+    return upsertYamlEntry(source, key, `  ${entryKey}: ${value}`, yamlEntryPattern(entryKey, true));
 }
 function removeYamlMapEntry(source, entryKey) {
-    const packageName = entryKey.includes('@') ? entryKey.slice(0, entryKey.lastIndexOf('@')) : entryKey;
-    const escapedPackageName = packageName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    const currentEntryPattern = new RegExp(`^ {2}'${escapedPackageName}@[^']+': .+\\n?`, 'mu');
-    if (!currentEntryPattern.test(source)) return {
+    const linePattern = new RegExp(yamlEntryPattern(entryKey).source, 'u');
+    const lines = source.split('\n');
+    let changed = false;
+    const out = [];
+    for (const line of lines){
+        if (linePattern.test(line)) {
+            changed = true;
+            continue;
+        }
+        out.push(line);
+    }
+    return changed ? {
+        source: out.join('\n'),
+        changed
+    } : {
         source,
-        changed: false
-    };
-    return {
-        source: source.replace(currentEntryPattern, ''),
-        changed: true
+        changed
     };
 }
-function ensureGeneratedPatchFile(workspaceRoot, relativePatchPath, sourcePatchPath) {
-    const targetPath = node_path.join(workspaceRoot, relativePatchPath);
+function ensureGeneratedPatchFile(io, relativePatchPath, sourcePatchPath) {
+    const targetPath = node_path.join(io.workspaceRoot, relativePatchPath);
     const patch = node_fs.readFileSync(sourcePatchPath, 'utf-8');
-    if (node_fs.existsSync(targetPath) && node_fs.readFileSync(targetPath, 'utf-8') === patch) return false;
-    node_fs.mkdirSync(node_path.dirname(targetPath), {
-        recursive: true
-    });
-    node_fs.writeFileSync(targetPath, patch, 'utf-8');
-    return true;
+    return io.write(targetPath, patch);
 }
-function removeGeneratedPatchFileIfUnchanged(workspaceRoot, relativePatchPath, sourcePatchPath) {
-    const targetPath = node_path.join(workspaceRoot, relativePatchPath);
+function removeGeneratedPatchFileIfUnchanged(io, relativePatchPath, sourcePatchPath) {
+    const targetPath = node_path.join(io.workspaceRoot, relativePatchPath);
     if (!node_fs.existsSync(targetPath)) return false;
     const patch = node_fs.readFileSync(sourcePatchPath, 'utf-8');
     if (node_fs.readFileSync(targetPath, 'utf-8') !== patch) return false;
-    node_fs.rmSync(targetPath);
-    return true;
+    return io.remove(targetPath);
 }
 function workspaceUsesDependency(workspaceRoot, packageName) {
     const packageJsonPaths = [
@@ -463,20 +562,20 @@ function workspaceUsesDependency(workspaceRoot, packageName) {
     }
     return false;
 }
-function ensureGeneratedDeclarationPatches(workspaceRoot, options) {
+function ensureGeneratedDeclarationPatches(io, options) {
     let changed = false;
-    changed = ensureGeneratedPatchFile(workspaceRoot, moduleFederationModernJsPatchPath, moduleFederationModernJsPatchSourcePath) || changed;
-    changed = ensureGeneratedPatchFile(workspaceRoot, moduleFederationBridgeReactPatchPath, moduleFederationBridgeReactPatchSourcePath) || changed;
-    changed = ensureGeneratedPatchFile(workspaceRoot, effectDeclarationPatchPath, effectDeclarationPatchSourcePath) || changed;
-    changed = options.includeDrizzleOrmPatch ? ensureGeneratedPatchFile(workspaceRoot, drizzleOrmDeclarationPatchPath, drizzleOrmDeclarationPatchSourcePath) || changed : removeGeneratedPatchFileIfUnchanged(workspaceRoot, drizzleOrmDeclarationPatchPath, drizzleOrmDeclarationPatchSourcePath) || changed;
+    changed = ensureGeneratedPatchFile(io, moduleFederationModernJsPatchPath, moduleFederationModernJsPatchSourcePath) || changed;
+    changed = ensureGeneratedPatchFile(io, moduleFederationBridgeReactPatchPath, moduleFederationBridgeReactPatchSourcePath) || changed;
+    changed = ensureGeneratedPatchFile(io, effectDeclarationPatchPath, effectDeclarationPatchSourcePath) || changed;
+    changed = options.includeDrizzleOrmPatch ? ensureGeneratedPatchFile(io, drizzleOrmDeclarationPatchPath, drizzleOrmDeclarationPatchSourcePath) || changed : removeGeneratedPatchFileIfUnchanged(io, drizzleOrmDeclarationPatchPath, drizzleOrmDeclarationPatchSourcePath) || changed;
     return changed;
 }
-function updateGeneratedPnpmWorkspacePolicy(workspaceRoot) {
-    const workspaceFile = node_path.join(workspaceRoot, 'pnpm-workspace.yaml');
+function updateGeneratedPnpmWorkspacePolicy(io) {
+    const workspaceFile = node_path.join(io.workspaceRoot, 'pnpm-workspace.yaml');
     if (!node_fs.existsSync(workspaceFile)) return false;
     let source = node_fs.readFileSync(workspaceFile, 'utf-8');
     let changed = false;
-    const usesDrizzleOrm = workspaceUsesDependency(workspaceRoot, 'drizzle-orm');
+    const usesDrizzleOrm = workspaceUsesDependency(io.workspaceRoot, 'drizzle-orm');
     const replacements = [
         [
             /^ {4}'@effect\/vitest>effect': .+$/mu,
@@ -536,12 +635,11 @@ function updateGeneratedPnpmWorkspacePolicy(workspaceRoot) {
     const drizzleOrmPatch = usesDrizzleOrm ? ensureYamlMapEntry(source, 'patchedDependencies', `drizzle-orm@${DRIZZLE_ORM_VERSION}`, drizzleOrmDeclarationPatchPath) : removeYamlMapEntry(source, `drizzle-orm@${DRIZZLE_ORM_VERSION}`);
     source = drizzleOrmPatch.source;
     changed = drizzleOrmPatch.changed || changed;
-    if (changed) node_fs.writeFileSync(workspaceFile, source, 'utf-8');
+    if (changed) io.write(workspaceFile, source);
     return changed;
 }
-function updateUltramodernConfig(workspaceRoot, packageSource) {
-    const configPath = node_path.join(workspaceRoot, '.modernjs/ultramodern.json');
-    const config = readJsonFile(configPath);
+function updateUltramodernConfig(io, config, packageSource) {
+    const configPath = node_path.join(io.workspaceRoot, '.modernjs/ultramodern.json');
     config.packageSource = {
         strategy: packageSource.strategy,
         modernPackageVersion: packageSource.modernPackageVersion,
@@ -556,73 +654,145 @@ function updateUltramodernConfig(workspaceRoot, packageSource) {
         } : {}
     };
     for (const app of config.topology?.apps ?? [])if (app && 'object' == typeof app && !Array.isArray(app)) normalizeStrictEffectApiMetadata(app);
-    writeJsonFile(configPath, config);
+    writeJsonFile(io, configPath, config);
 }
-function writeJsonIfChanged(filePath, value) {
-    const next = `${JSON.stringify(value, null, 2)}\n`;
-    if (node_fs.existsSync(filePath) && node_fs.readFileSync(filePath, 'utf-8') === next) return false;
-    node_fs.mkdirSync(node_path.dirname(filePath), {
-        recursive: true
-    });
-    node_fs.writeFileSync(filePath, next, 'utf-8');
-    return true;
+function writeJsonIfChanged(io, filePath, value) {
+    return io.write(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
-function writeTextIfChanged(filePath, value) {
-    if (node_fs.existsSync(filePath) && node_fs.readFileSync(filePath, 'utf-8') === value) return false;
-    node_fs.mkdirSync(node_path.dirname(filePath), {
-        recursive: true
-    });
-    node_fs.writeFileSync(filePath, value, 'utf-8');
-    return true;
+function writeTextIfChanged(io, filePath, value) {
+    return io.write(filePath, value);
 }
-function ensureGeneratedIgnoreRules(workspaceRoot) {
-    const gitignorePath = node_path.join(workspaceRoot, '.gitignore');
+function ensureGeneratedIgnoreRules(io) {
+    const gitignorePath = node_path.join(io.workspaceRoot, '.gitignore');
     const existing = node_fs.existsSync(gitignorePath) ? node_fs.readFileSync(gitignorePath, 'utf-8') : '';
     const lines = 0 === existing.trimEnd().length ? [] : existing.trimEnd().split(/\r?\n/u);
     let changed = false;
     for (const rule of [
         '.mf/',
         '**/.mf/',
-        'dist-cloudflare/'
+        'dist-cloudflare/',
+        '.output/',
+        '**/.output/',
+        '.modern-js/',
+        '**/.modern-js/'
     ])if (!lines.includes(rule)) {
         lines.push(rule);
         changed = true;
     }
     if (!changed) return false;
-    const next = `${lines.join('\n')}\n`;
-    node_fs.writeFileSync(gitignorePath, next, 'utf-8');
-    return true;
+    return io.write(gitignorePath, `${lines.join('\n')}\n`);
 }
-function updateGeneratedTypeScriptSurfaces(workspaceRoot, config) {
+function updateGeneratedTypeScriptSurfaces(io, config) {
     let changed = false;
     const apps = workspaceAppsFromToolingConfig(config);
     const remotes = apps.filter((app)=>'shell' !== app.kind);
-    changed = writeJsonIfChanged(node_path.join(workspaceRoot, 'tsconfig.base.json'), createTsConfigBase()) || changed;
-    changed = ensureGeneratedIgnoreRules(workspaceRoot) || changed;
+    changed = writeJsonIfChanged(io, node_path.join(io.workspaceRoot, 'tsconfig.base.json'), createTsConfigBase()) || changed;
+    changed = ensureGeneratedIgnoreRules(io) || changed;
     for (const sharedPackage of [
         'packages/shared-contracts',
         'packages/shared-design-tokens'
-    ])changed = writeJsonIfChanged(node_path.join(workspaceRoot, sharedPackage, 'tsconfig.json'), createSharedPackageTsConfig(sharedPackage)) || changed;
+    ])changed = writeJsonIfChanged(io, node_path.join(io.workspaceRoot, sharedPackage, 'tsconfig.json'), createSharedPackageTsConfig(sharedPackage)) || changed;
     for (const app of apps){
-        changed = writeJsonIfChanged(node_path.join(workspaceRoot, app.directory, 'tsconfig.json'), createAppTsConfig(app, remotes)) || changed;
-        changed = writeJsonIfChanged(node_path.join(workspaceRoot, app.directory, 'tsconfig.mf-types.json'), createAppMfTypesTsConfig(app)) || changed;
-        changed = writeTextIfChanged(node_path.join(workspaceRoot, app.directory, 'src/modern-app-env.d.ts'), createAppEnvDts(app, remotes)) || changed;
+        changed = writeJsonIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'tsconfig.json'), createAppTsConfig(app, remotes)) || changed;
+        changed = writeJsonIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'tsconfig.mf-types.json'), createAppMfTypesTsConfig(app)) || changed;
+        changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'src/modern-app-env.d.ts'), createAppEnvDts(app, remotes)) || changed;
     }
     return changed;
 }
-function updateGeneratedModernConfigs(workspaceRoot, config) {
+function updateGeneratedModernConfigs(io, config) {
     let changed = false;
     const apps = workspaceAppsFromToolingConfig(config);
-    for (const app of apps)changed = writeTextIfChanged(node_path.join(workspaceRoot, app.directory, 'modern.config.ts'), createAppModernConfig(config.workspace.packageScope, app)) || changed;
+    const remotes = apps.filter((app)=>'shell' !== app.kind);
+    for (const app of apps)changed = writeTextIfChanged(io, node_path.join(io.workspaceRoot, app.directory, 'modern.config.ts'), createAppModernConfig(config.workspace.packageScope, app, remotes)) || changed;
     return changed;
 }
-function updateReferenceTopology(workspaceRoot) {
-    const topologyPath = node_path.join(workspaceRoot, 'topology/reference-topology.json');
+function ensureGeneratedOxfmtIgnorePatterns(io) {
+    const configPath = node_path.join(io.workspaceRoot, 'oxfmt.config.ts');
+    if (!node_fs.existsSync(configPath)) return false;
+    const source = node_fs.readFileSync(configPath, 'utf-8');
+    const requiredPatterns = [
+        '.modernjs',
+        '.output',
+        '**/modern-tanstack/**',
+        '**/routeTree.gen.*'
+    ];
+    const warnUnparseable = ()=>{
+        const message = `Could not update oxfmt.config.ts ignorePatterns automatically; add these entries manually: ${requiredPatterns.join(', ')}.`;
+        if (io.dryRun) io.log(message);
+        else process.stderr.write(`[ultramodern] ${message}\n`);
+    };
+    const anchor = source.indexOf('ignorePatterns:');
+    if (-1 === anchor) {
+        warnUnparseable();
+        return false;
+    }
+    const openBracket = source.indexOf('[', anchor);
+    if (-1 === openBracket) {
+        warnUnparseable();
+        return false;
+    }
+    let depth = 0;
+    let closeBracket = -1;
+    let stringQuote;
+    for(let index = openBracket; index < source.length; index += 1){
+        const char = source[index];
+        if (stringQuote) {
+            if ('\\' === char) index += 1;
+            else if (char === stringQuote) stringQuote = void 0;
+            continue;
+        }
+        if ("'" === char || '"' === char || '`' === char) stringQuote = char;
+        else if ('[' === char) depth += 1;
+        else if (']' === char) {
+            depth -= 1;
+            if (0 === depth) {
+                closeBracket = index;
+                break;
+            }
+        }
+    }
+    if (-1 === closeBracket) {
+        warnUnparseable();
+        return false;
+    }
+    const body = source.slice(openBracket + 1, closeBracket);
+    if (body.includes('...')) {
+        warnUnparseable();
+        return false;
+    }
+    const literalPattern = /(['"`])((?:\\.|(?!\1).)*)\1/g;
+    const existing = new Set();
+    for (const match of body.matchAll(literalPattern))existing.add(match[2]);
+    const missing = requiredPatterns.filter((pattern)=>!existing.has(pattern));
+    if (0 === missing.length) return false;
+    const bodyLines = body.split('\n');
+    let indent = '  ';
+    let quote = "'";
+    for(let index = bodyLines.length - 1; index >= 0; index -= 1){
+        const literal = bodyLines[index].match(/^(\s*)(['"`])/u);
+        if (literal) {
+            indent = literal[1];
+            quote = literal[2];
+            break;
+        }
+    }
+    const head = source.slice(0, closeBracket);
+    const rest = source.slice(closeBracket);
+    const tailMatch = head.match(/(\r?\n[ \t]*)$/u);
+    const tail = tailMatch ? tailMatch[1] : '\n';
+    let bodyContent = tailMatch ? head.slice(0, head.length - tail.length) : head;
+    if (!/[[,]\s*$/u.test(bodyContent)) bodyContent = `${bodyContent},`;
+    const insertionLines = missing.map((pattern)=>`${indent}${quote}${pattern}${quote},`).join('\n');
+    const nextSource = `${bodyContent}\n${insertionLines}${tail}${rest}`;
+    return io.write(configPath, nextSource);
+}
+function updateReferenceTopology(io) {
+    const topologyPath = node_path.join(io.workspaceRoot, 'topology/reference-topology.json');
     if (!node_fs.existsSync(topologyPath)) return false;
     const topology = readJsonFile(topologyPath);
     let changed = false;
     for (const vertical of topology.verticals ?? [])if (vertical && 'object' == typeof vertical && !Array.isArray(vertical)) changed = normalizeStrictEffectApiMetadata(vertical) || changed;
-    if (changed) writeJsonFile(topologyPath, topology);
+    if (changed) writeJsonFile(io, topologyPath, topology);
     return changed;
 }
 function createMigrationPackageSource(args, current) {
@@ -675,25 +845,56 @@ function runPnpmLockfileRefresh(context) {
 function runMigrateStrictEffect(args, context) {
     if (args.includes('--help') || args.includes('-h')) {
         process.stdout.write(`Usage:
-  modern-js-create ultramodern migrate-strict-effect --version <version> [--skip-install]
+  modern-js-create ultramodern migrate-strict-effect --version <version> [--dry-run] [--skip-install]
 
 Updates generated UltraModern package-source metadata, Modern package aliases,
 framework-owned toolchain pins, direct Effect API topology metadata, strict
 Effect pnpm overrides/trust policy, framework-owned TypeScript config
 surfaces, and the pnpm lockfile. Source code still has to pass pnpm api:check
 and pnpm contract:check.
+
+When the compact config is absent but legacy UltraModern 3.2 metadata is
+present, the compact config is synthesized from it first. Shell-only
+workspaces skip the backend-federation and Zerops runtime stages. Pass
+--dry-run to print the planned filesystem changes without writing anything
+(implies --skip-install).
 `);
         return 0;
     }
-    const current = readUltramodernConfig(context.workspaceRoot);
+    const dryRun = hasFlag(args, '--dry-run');
+    const skipInstall = dryRun || hasFlag(args, '--skip-install');
+    const io = createMigrationIo(context.workspaceRoot, dryRun);
+    const compactPath = node_path.join(io.workspaceRoot, '.modernjs/ultramodern.json');
+    let raw;
+    if (node_fs.existsSync(compactPath)) raw = readJsonFile(compactPath);
+    else {
+        const synthesized = synthesizeCompactUltramodernConfig(io.workspaceRoot);
+        if (!synthesized) throw new Error("Missing .modernjs/ultramodern.json and no legacy UltraModern metadata (.modernjs/ultramodern-generated-contract.json) was found to synthesize it from.");
+        raw = synthesized.compact;
+        io.write(compactPath, `${JSON.stringify(raw, null, 2)}\n`);
+        io.log(`Synthesized .modernjs/ultramodern.json from legacy metadata: ${synthesized.sources.join(', ')}.`);
+        if (synthesized.missing.length > 0) io.log(`Legacy metadata not found (using defaults): ${synthesized.missing.join(', ')}.`);
+    }
+    const current = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
     const packageSource = createMigrationPackageSource(args, current);
-    updateUltramodernConfig(context.workspaceRoot, packageSource);
-    updateReferenceTopology(context.workspaceRoot);
-    const migrated = readUltramodernConfig(context.workspaceRoot);
-    updateGeneratedTypeScriptSurfaces(context.workspaceRoot, migrated);
-    updateGeneratedModernConfigs(context.workspaceRoot, migrated);
-    for (const relativePackageFile of listWorkspacePackageFiles(context.workspaceRoot)){
-        const packageFile = node_path.join(context.workspaceRoot, relativePackageFile);
+    updateUltramodernConfig(io, raw, packageSource);
+    updateReferenceTopology(io);
+    const migrated = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+    const migratedApps = workspaceAppsFromToolingConfig(migrated);
+    const shellOnly = !migrated.topology.apps.some((app)=>app.api);
+    if (shellOnly) io.log('Shell-only workspace: skipping backend-federation and Zerops runtime stages.');
+    else {
+        removeStaleBackendFederationArtifacts(io, migrated);
+        updateGeneratedZeropsArtifacts(io, migrated);
+        updateGeneratedBackendFederationContractFiles(io, migrated);
+    }
+    if (dryRun) io.log("would refresh generated tool wrapper scripts under scripts/");
+    else writeGeneratedToolWrapperScripts(io.workspaceRoot);
+    updateGeneratedBuildIdentityModules(io, migrated);
+    updateGeneratedTypeScriptSurfaces(io, migrated);
+    updateGeneratedModernConfigs(io, migrated);
+    for (const relativePackageFile of listWorkspacePackageFiles(io.workspaceRoot)){
+        const packageFile = node_path.join(io.workspaceRoot, relativePackageFile);
         const packageJson = readJsonFile(packageFile);
         if ('package.json' === relativePackageFile) {
             packageJson.modernjs ??= {};
@@ -702,21 +903,28 @@ and pnpm contract:check.
                 config: './.modernjs/ultramodern.json'
             };
         }
-        const modernDependenciesChanged = updateModernDependencies(packageJson, packageSource);
-        const toolingDependenciesChanged = updateGeneratedToolingDependencies(packageJson);
-        const generatedScriptsChanged = updateGeneratedPackageScripts(packageJson);
-        const changed = modernDependenciesChanged || toolingDependenciesChanged || generatedScriptsChanged;
-        if (changed) writeJsonFile(packageFile, packageJson);
-        else if ('package.json' === relativePackageFile) writeJsonFile(packageFile, packageJson);
-    }
-    updateGeneratedPnpmWorkspacePolicy(context.workspaceRoot);
-    ensureGeneratedDeclarationPatches(context.workspaceRoot, {
-        includeDrizzleOrmPatch: workspaceUsesDependency(context.workspaceRoot, 'drizzle-orm')
+        updateModernDependencies(packageJson, packageSource);
+        updateGeneratedToolingDependencies(packageJson);
+        updateGeneratedPackageScripts(packageJson, {
+            relativePackageFile,
+            apps: migratedApps
+        });
+        writeJsonFile(io, packageFile, packageJson);
+    }
+    updateGeneratedPnpmWorkspacePolicy(io);
+    ensureGeneratedDeclarationPatches(io, {
+        includeDrizzleOrmPatch: workspaceUsesDependency(io.workspaceRoot, 'drizzle-orm')
     });
-    if (!hasFlag(args, '--skip-install')) {
+    ensureGeneratedOxfmtIgnorePatterns(io);
+    if (!skipInstall) {
         const status = runPnpmLockfileRefresh(context);
         if (0 !== status) return status;
     }
+    if (dryRun) {
+        for (const line of io.plan)process.stdout.write(`${line}\n`);
+        process.stdout.write(`[dry-run] migrate-strict-effect would migrate UltraModern strict Effect metadata to ${packageSource.modernPackageVersion}.\n`);
+        return 0;
+    }
     process.stdout.write(`UltraModern strict Effect metadata migrated to ${packageSource.modernPackageVersion}. Run pnpm api:check && pnpm contract:check next.\n`);
     return 0;
 }
@@ -729,6 +937,140 @@ function runSkills(args, context) {
     ], context);
     throw new Error('Usage: modern-js-create ultramodern skills <install|check>');
 }
+const resolveCloudflareOutputVerifyTargets = (args, context)=>{
+    const outputDirectory = readOption(args, '--output');
+    const appId = readOption(args, '--app');
+    if (outputDirectory && appId) throw new Error('Use either --app or --output, not both.');
+    const targets = outputDirectory ? [
+        {
+            label: outputDirectory,
+            outputDirectory: node_path.resolve(context.invocationCwd, outputDirectory)
+        }
+    ] : workspaceAppsFromToolingConfig(readUltramodernConfig(context.workspaceRoot)).filter((app)=>!appId || app.id === appId).map((app)=>({
+            label: app.id,
+            outputDirectory: node_path.join(context.workspaceRoot, app.directory, '.output')
+        }));
+    if (0 === targets.length) throw new Error(`No generated UltraModern app matched ${appId}.`);
+    return targets;
+};
+const renderCloudflareOutputVerifyModule = ({ workspaceRoot, targets, scanRoots, importWorker })=>`
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const workspaceRoot = ${JSON.stringify(workspaceRoot)};
+const targets = ${JSON.stringify(targets, null, 2)};
+const scanRoots = ${JSON.stringify(scanRoots)};
+const verifierRequire = createRequire(path.join(workspaceRoot, 'package.json'));
+const {
+  verifyCloudflareOutput,
+  verifyCloudflareOutputMutationPolicy,
+} = verifierRequire('@modern-js/app-tools/cloudflare-output-verifier');
+
+let failed = false;
+for (const target of targets) {
+  const result = await verifyCloudflareOutput({
+    outputDirectory: target.outputDirectory,
+    importWorker: ${JSON.stringify(importWorker)},
+  });
+  if (result.ok) {
+    console.log(\`[ultramodern] Cloudflare output verified: \${target.label}\`);
+  } else {
+    failed = true;
+    console.error(\`[ultramodern] Cloudflare output failed: \${target.label}\`);
+    for (const issue of result.issues) {
+      console.error(\`- \${issue.code}: \${issue.message}\${issue.path ? \` (\${issue.path})\` : ''}\`);
+    }
+  }
+}
+
+if (scanRoots.length > 0) {
+  const policyResult = await verifyCloudflareOutputMutationPolicy({ scanRoots });
+  if (!policyResult.ok) {
+    failed = true;
+    console.error('[ultramodern] generated-output mutation policy failed');
+    for (const issue of policyResult.issues) {
+      console.error(\`- \${issue.code}: \${issue.message}\${issue.path ? \` (\${issue.path})\` : ''}\`);
+    }
+  }
+}
+
+process.exit(failed ? 1 : 0);
+`;
+function runCloudflareOutputVerify(args, context) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(`Usage:
+  modern-js-create ultramodern cloudflare-output-verify [--app <id> | --output <dir>] [--no-import-worker] [--no-source-scan]
+
+Verifies generated Cloudflare output against the UltraModern worker contract.
+Without --app or --output, every generated workspace app is verified.
+`);
+        return 0;
+    }
+    const source = renderCloudflareOutputVerifyModule({
+        workspaceRoot: context.workspaceRoot,
+        targets: resolveCloudflareOutputVerifyTargets(args, context),
+        scanRoots: hasFlag(args, '--no-source-scan') ? [] : [
+            context.workspaceRoot
+        ],
+        importWorker: !hasFlag(args, '--no-import-worker')
+    });
+    return runRenderedModule(source, context);
+}
+const resolveRoutesGenerateTargets = (args, context)=>{
+    const appId = readOption(args, '--app');
+    const targets = workspaceAppsFromToolingConfig(readUltramodernConfig(context.workspaceRoot)).filter((app)=>!appId || app.id === appId).map((app)=>({
+            label: app.id,
+            appDirectory: node_path.join(context.workspaceRoot, app.directory)
+        }));
+    if (0 === targets.length) throw new Error(`No generated UltraModern app matched ${appId ?? '<any>'}.`);
+    return targets;
+};
+const renderRoutesGenerateModule = ({ workspaceRoot, targets })=>`
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const workspaceRoot = ${JSON.stringify(workspaceRoot)};
+const targets = ${JSON.stringify(targets, null, 2)};
+const appRequire = createRequire(path.join(workspaceRoot, 'package.json'));
+const pluginUrl = pathToFileURL(
+  appRequire.resolve('@modern-js/plugin-tanstack'),
+).href;
+const { generateTanstackRouteArtifacts } = await import(pluginUrl);
+
+let failed = false;
+// Sequential — the app-tools cli singleton is not re-entrant.
+for (const target of targets) {
+  try {
+    await generateTanstackRouteArtifacts({ appDirectory: target.appDirectory });
+    console.log(\`[ultramodern] TanStack route artifacts generated: \${target.label}\`);
+  } catch (error) {
+    failed = true;
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(\`[ultramodern] TanStack route generation failed: \${target.label}\`);
+    console.error(\`- \${message}\`);
+  }
+}
+
+process.exit(failed ? 1 : 0);
+`;
+function runRoutesGenerate(args, context) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(`Usage:
+  modern-js-create ultramodern routes-generate [--app <id>]
+
+Regenerates TanStack route artifacts (router.gen.ts, register.gen.d.ts) for
+generated UltraModern apps without running dev or build. Without --app, every
+generated workspace app is regenerated.
+`);
+        return 0;
+    }
+    const source = renderRoutesGenerateModule({
+        workspaceRoot: context.workspaceRoot,
+        targets: resolveRoutesGenerateTargets(args, context)
+    });
+    return runRenderedModule(source, context);
+}
 async function runUltramodernToolingCli(args, workspaceRoot = process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd()) {
     try {
         const [command, ...rest] = args;
@@ -742,25 +1084,25 @@ async function runUltramodernToolingCli(args, workspaceRoot = process.env.ULTRAM
             case '-h':
                 printHelp();
                 return 0;
-            case 'validate':
+            case GENERATED_TOOLING_COMMANDS.validate.command:
                 return runValidate(context);
-            case 'typecheck':
-                return spawnNodeScript("templates/workspace-scripts/ultramodern-typecheck.mjs", rest, context, {
-                    cwd: context.invocationCwd
-                });
-            case 'mf-types':
+            case GENERATED_TOOLING_COMMANDS.mfTypes.command:
                 return runMfTypes(rest, context);
-            case 'migrate-strict-effect':
+            case GENERATED_TOOLING_COMMANDS.migrateStrictEffect.command:
                 return runMigrateStrictEffect(rest, context);
-            case 'public-surface':
-                return spawnNodeScript("templates/workspace-scripts/generate-public-surface-assets.mjs", rest, context);
-            case 'cloudflare-proof':
-                return spawnNodeScript("templates/workspace-scripts/proof-cloudflare-version.mjs", rest, context);
-            case 'performance-readiness':
-                return spawnNodeScript("templates/workspace-scripts/ultramodern-performance-readiness.mjs", rest, context);
+            case GENERATED_TOOLING_COMMANDS.cloudflareOutputVerify.command:
+                return runCloudflareOutputVerify(rest, context);
+            case GENERATED_TOOLING_COMMANDS.routesGenerate.command:
+                return runRoutesGenerate(rest, context);
+            case 'sync-delivery-unit':
+                return runSyncDeliveryUnit(rest, context);
             case 'skills':
                 return runSkills(rest, context);
             default:
+                {
+                    const templateBackedStatus = runTemplateBackedToolingCommand(command ?? '', rest, context);
+                    if (void 0 !== templateBackedStatus) return templateBackedStatus;
+                }
                 throw new Error(`Unknown UltraModern command: ${command}`);
         }
     } catch (error) {