@bleedingdev/modern-js-ultramodern-create 3.8.3-ultramodern.2

package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect.js

@@ -0,0 +1,405 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { RELEASE_COHORT_PROJECTION_PATH, readCreateReleaseCohort } from "../../ultramodern-release-cohort.js";
+import { createDevelopmentOverlay, createTopology, createUltramodernConfig } from "../../ultramodern-workspace/contracts.js";
+import { stampDeliveryUnitIdentity } from "../../ultramodern-workspace/delivery-unit-stamp.js";
+import { ULTRAMODERN_WORKSPACE_POLICY } from "../../ultramodern-workspace/policy.js";
+import { createAdditionalShellConfigEntry } from "../../ultramodern-workspace/shells.js";
+import { createWorkspaceValidationScript, migratedWorkspaceScriptArtifacts } from "../../ultramodern-workspace/workspace-scripts.js";
+import { additionalShellsFromToolingConfig, allWorkspaceAppsFromToolingConfig, normalizeCompactUltramodernConfig, synthesizeCompactUltramodernConfig, workspaceAppsFromToolingConfig } from "../config.js";
+import { reconcileCompactPackageSourceMetadata, reconcilePackageSourceMetadata, updateReferenceTopology, updateUltramodernConfig } from "./migrate-strict-effect/api-metadata.js";
+import { ensureGeneratedDeclarationPatches } from "./migrate-strict-effect/declaration-patches.js";
+import { workspaceUsesDependency } from "./migrate-strict-effect/dependency-usage.js";
+import { ensureGeneratedOxfmtIgnorePatterns, ensureGeneratedOxlintComponentStyle, removeGeneratedFileIfExists, removeStaleBackendFederationArtifacts, updateGeneratedBackendFederationContractFiles, updateGeneratedBuildIdentityModules, updateGeneratedModernConfigs, updateGeneratedTypeScriptSurfaces, updateGeneratedZeropsArtifacts } from "./migrate-strict-effect/generated-artifacts.js";
+import { migrateStrictEffectHelp } from "./migrate-strict-effect/help.js";
+import { runPnpmLockfileRefresh } from "./migrate-strict-effect/install.js";
+import { createMigrationIo, listWorkspacePackageFiles, readJsonFile, withStagedDryRunMigrationIo, writeJsonFile } from "./migrate-strict-effect/io.js";
+import { ensureBffEffectDependencies, updateGeneratedPackageScripts, updateGeneratedToolingDependencies, updateModernDependencies } from "./migrate-strict-effect/package-cohort.js";
+import { createMigrationPackageSource } from "./migrate-strict-effect/package-source.js";
+import { updateGeneratedPnpmWorkspacePolicy, validateGeneratedPnpmLockReleaseAgePolicy } from "./migrate-strict-effect/pnpm-policy.js";
+import { ensureGeneratedModuleFederationBridgeRouterOptOut, preflightModuleFederationBridgeRouter, removeRetiredReactRouterDependency } from "./migrate-strict-effect/react-router-retirement.js";
+import { updateGeneratedToolchainFiles, updateRootPackageToolchain } from "./migrate-strict-effect/toolchain-pins.js";
+import { hasFlag } from "./options.js";
+const retiredMetadataPaths = [
+    '.modernjs/ultramodern-generated-contract.json',
+    '.modernjs/ultramodern-package-source.json',
+    '.modernjs/ultramodern-workspace-template-manifest.json'
+];
+const rootPackageSourceOwnedKeys = [
+    ...ULTRAMODERN_WORKSPACE_POLICY.metadata.packageSource.ownedKeys,
+    'config'
+];
+function requireRecord(value, label) {
+    if (!value || 'object' != typeof value || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+    return value;
+}
+function synchronizeMigrationDeliveryUnitMetadata(io, raw, packageSource) {
+    const normalized = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+    const apps = workspaceAppsFromToolingConfig(normalized);
+    const appById = new Map(apps.map((app)=>[
+            app.id,
+            app
+        ]));
+    const scope = normalized.workspace.packageScope;
+    apps.filter((app)=>'shell' !== app.kind);
+    const primaryShell = apps.find((app)=>'shell' === app.kind);
+    const canonicalCompact = requireRecord(createUltramodernConfig(scope, packageSource.modernPackageVersion, packageSource, apps, normalized.features.tailwind, normalized.bridge, additionalShellsFromToolingConfig(normalized), primaryShell), 'Generated compact config');
+    const canonicalCompactApps = new Map((canonicalCompact.topology?.apps ?? []).map((entry)=>[
+            String(entry.id),
+            entry
+        ]));
+    for (const entry of raw.topology?.apps ?? []){
+        if (!entry || 'object' != typeof entry || Array.isArray(entry)) continue;
+        const app = appById.get(String(entry.id));
+        if (app) {
+            stampDeliveryUnitIdentity(entry, scope, app);
+            const canonicalEntry = canonicalCompactApps.get(app.id);
+            if (canonicalEntry) {
+                entry.moduleFederation = canonicalEntry.moduleFederation;
+                entry.backendFederation = canonicalEntry.backendFederation;
+                entry.api = canonicalEntry.api;
+            }
+        }
+    }
+    writeJsonFile(io, node_path.join(io.workspaceRoot, '.modernjs/ultramodern.json'), raw);
+    const topologyPath = node_path.join(io.workspaceRoot, 'topology/reference-topology.json');
+    if (!node_fs.existsSync(topologyPath)) return;
+    const topology = readJsonFile(topologyPath);
+    const synchronizedConfig = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+    const synchronizedApps = workspaceAppsFromToolingConfig(synchronizedConfig);
+    const synchronizedRemotes = synchronizedApps.filter((app)=>'shell' !== app.kind);
+    const synchronizedPrimaryShell = synchronizedApps.find((app)=>'shell' === app.kind);
+    const canonicalTopology = requireRecord(createTopology(scope, synchronizedRemotes, synchronizedPrimaryShell), 'Generated reference topology');
+    for (const key of [
+        'schemaVersion',
+        'id',
+        "description",
+        'preset',
+        'sharedPackages',
+        'validation'
+    ])topology[key] = canonicalTopology[key];
+    const canonicalTopologyApps = new Map([
+        canonicalTopology.shell,
+        ...canonicalTopology.verticals ?? []
+    ].map((entry)=>[
+            String(entry.id),
+            entry
+        ]));
+    for (const entry of [
+        topology.shell,
+        ...topology.verticals ?? []
+    ]){
+        if (!entry || 'object' != typeof entry || Array.isArray(entry)) continue;
+        const app = appById.get(String(entry.id));
+        if (app) {
+            stampDeliveryUnitIdentity(entry, scope, app);
+            const canonicalEntry = canonicalTopologyApps.get(app.id);
+            if (canonicalEntry) for (const key of [
+                'moduleFederation',
+                'backendFederation',
+                'api',
+                'cloudflare',
+                'ownership'
+            ])if (Object.hasOwn(canonicalEntry, key)) entry[key] = canonicalEntry[key];
+            else delete entry[key];
+        }
+    }
+    writeJsonFile(io, topologyPath, topology);
+}
+const compactPolicyKeys = [
+    'schemaVersion',
+    'profile',
+    'workspace',
+    'features',
+    'deploy',
+    'moduleFederation',
+    'backendFederation',
+    'agentSkills',
+    'tooling'
+];
+function synchronizeMigrationCompactPolicy(io, raw, packageSource) {
+    const migrated = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+    const apps = workspaceAppsFromToolingConfig(migrated);
+    apps.filter((app)=>'shell' !== app.kind);
+    const canonical = requireRecord(createUltramodernConfig(migrated.workspace.packageScope, packageSource.modernPackageVersion, packageSource, apps, migrated.features.tailwind, migrated.bridge, additionalShellsFromToolingConfig(migrated), apps.find((app)=>'shell' === app.kind)), 'Generated compact policy');
+    for (const key of compactPolicyKeys)raw[key] = canonical[key];
+    writeJsonFile(io, node_path.join(io.workspaceRoot, '.modernjs/ultramodern.json'), raw);
+}
+function reconcileRootPackageSourceMetadata(packageJson, packageSource) {
+    const modernjs = void 0 === packageJson.modernjs ? {} : requireRecord(packageJson.modernjs, 'package.json modernjs');
+    packageJson.modernjs = modernjs;
+    modernjs.packageSource = reconcilePackageSourceMetadata(modernjs.packageSource, {
+        canonical: {
+            strategy: packageSource.strategy,
+            config: './.modernjs/ultramodern.json'
+        },
+        label: 'package.json modernjs.packageSource',
+        ownedKeys: rootPackageSourceOwnedKeys
+    });
+}
+function requireString(value, label) {
+    if ('string' != typeof value || 0 === value.length) throw new Error(`${label} must be a non-empty string.`);
+    return value;
+}
+function assertUnique(values, label) {
+    if (new Set(values).size !== values.length) throw new Error(`${label} contains duplicate identities.`);
+}
+function deriveValidationContractInputs(workspaceRoot, migrated, migratedApps) {
+    const rootPackage = readJsonFile(node_path.join(workspaceRoot, 'package.json'));
+    const scope = requireString(rootPackage.name, 'Root package name');
+    if (migrated.workspace.packageScope !== scope) throw new Error(`Compact package scope ${migrated.workspace.packageScope} does not match root package ${scope}.`);
+    const topologyPath = node_path.join(workspaceRoot, 'topology/reference-topology.json');
+    if (!node_fs.existsSync(topologyPath)) throw new Error('Cannot render the migration validation contract without topology/reference-topology.json.');
+    const topology = readJsonFile(topologyPath);
+    const shell = requireRecord(topology.shell, 'Reference topology shell');
+    if (!Array.isArray(topology.verticals)) throw new Error('Reference topology verticals must be an array.');
+    const verticals = topology.verticals.map((value, index)=>requireRecord(value, `Reference topology verticals[${index}]`));
+    const expectedApps = [
+        {
+            id: requireString(shell.id, 'Reference topology shell.id'),
+            kind: 'shell',
+            packageName: requireString(shell.package, 'Reference topology shell.package'),
+            path: void 0,
+            hasApi: false
+        },
+        ...verticals.map((vertical, index)=>({
+                id: requireString(vertical.id, `Reference topology verticals[${index}].id`),
+                kind: 'vertical',
+                packageName: requireString(vertical.package, `Reference topology verticals[${index}].package`),
+                path: requireString(vertical.path, `Reference topology verticals[${index}].path`),
+                hasApi: void 0 !== vertical.api
+            }))
+    ];
+    assertUnique(expectedApps.map((app)=>app.id), 'Reference topology app cohort');
+    assertUnique(expectedApps.map((app)=>app.packageName), 'Reference topology package cohort');
+    const migratedById = new Map(migratedApps.map((app)=>[
+            app.id,
+            app
+        ]));
+    assertUnique(migratedApps.map((app)=>app.id), 'Compact topology app cohort');
+    const expectedIds = expectedApps.map((app)=>app.id).sort();
+    const migratedIds = migratedApps.map((app)=>app.id).sort();
+    if (JSON.stringify(expectedIds) !== JSON.stringify(migratedIds)) throw new Error(`Compact topology app cohort ${migratedIds.join(', ')} does not match reference topology ${expectedIds.join(', ')}.`);
+    const appPackageFiles = listWorkspacePackageFiles(workspaceRoot).filter((relativePath)=>relativePath.startsWith('apps/') || relativePath.startsWith('verticals/'));
+    const manifests = appPackageFiles.map((relativePath)=>({
+            relativePath,
+            packageJson: readJsonFile(node_path.join(workspaceRoot, relativePath))
+        }));
+    const manifestsByName = new Map();
+    for (const manifest of manifests){
+        const name = requireString(manifest.packageJson.name, `${manifest.relativePath} name`);
+        if (manifestsByName.has(name)) throw new Error(`Duplicate workspace app package name ${name}.`);
+        manifestsByName.set(name, manifest);
+    }
+    const tailwindStates = [];
+    for (const expected of expectedApps){
+        const app = migratedById.get(expected.id);
+        if (!app || app.kind !== expected.kind) throw new Error(`Compact topology app ${expected.id} does not match reference kind ${expected.kind}.`);
+        if (Boolean(app.api) !== expected.hasApi) throw new Error(`Compact topology app ${expected.id} API presence does not match reference topology.`);
+        const manifest = manifestsByName.get(expected.packageName);
+        if (!manifest) throw new Error(`Reference topology package ${expected.packageName} has no workspace manifest.`);
+        const expectedManifestPath = `${app.directory}/package.json`;
+        if (manifest.relativePath !== expectedManifestPath) throw new Error(`${expected.packageName} is at ${manifest.relativePath}, expected ${expectedManifestPath}.`);
+        if (expected.path && expected.path !== app.directory) throw new Error(`Compact topology app ${expected.id} path ${app.directory} does not match reference path ${expected.path}.`);
+        tailwindStates.push(Object.hasOwn(requireRecord(manifest.packageJson.devDependencies ?? {}, `${manifest.relativePath} devDependencies`), '@rsbuild/plugin-tailwindcss'));
+    }
+    if (1 !== new Set(tailwindStates).size) throw new Error('Generated app package manifests disagree on the Tailwind feature state.');
+    const enableTailwind = tailwindStates[0] ?? false;
+    if (migrated.features.tailwind !== enableTailwind) throw new Error(`Compact Tailwind state ${migrated.features.tailwind} does not match package manifests ${enableTailwind}.`);
+    return {
+        scope,
+        enableTailwind,
+        remotes: migratedApps.filter((app)=>'shell' !== app.kind),
+        primaryShell: migratedApps.find((app)=>'shell' === app.kind),
+        additionalShells: additionalShellsFromToolingConfig(migrated)
+    };
+}
+function reconcileAdditionalShellConfig(raw, migrated, migratedApps, io) {
+    const additionalShells = additionalShellsFromToolingConfig(migrated);
+    if (0 === additionalShells.length) return migrated;
+    const existingShells = new Map((Array.isArray(raw.shells) ? raw.shells : []).filter((entry)=>null !== entry && 'object' == typeof entry && !Array.isArray(entry) && 'id' in entry && 'string' == typeof entry.id).map((entry)=>[
+            entry.id,
+            entry
+        ]));
+    const remotes = migratedApps.filter((app)=>'shell' !== app.kind);
+    raw.shells = additionalShells.map((shell)=>({
+            ...existingShells.get(shell.id),
+            ...createAdditionalShellConfigEntry(migrated.workspace.packageScope, shell, remotes)
+        }));
+    writeJsonFile(io, node_path.join(io.workspaceRoot, '.modernjs/ultramodern.json'), raw);
+    return normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+}
+function synchronizeMigrationDevelopmentOverlay(io, migrated, migratedApps) {
+    const overlayPath = node_path.join(io.workspaceRoot, 'topology/local-overlays/development.json');
+    const existing = node_fs.existsSync(overlayPath) ? requireRecord(readJsonFile(overlayPath), 'Development topology overlay') : {};
+    const canonical = requireRecord(createDevelopmentOverlay(migrated.workspace.packageScope, migratedApps.filter((app)=>'shell' !== app.kind)), 'Generated development topology overlay');
+    canonical.ports = Object.fromEntries(migratedApps.map((app)=>[
+            app.id,
+            app.port
+        ]));
+    const frameworkOwnedKeys = new Set(Object.keys(canonical));
+    const reconciled = Object.fromEntries(Object.entries(existing).filter(([key])=>!frameworkOwnedKeys.has(key)));
+    Object.assign(reconciled, canonical);
+    writeJsonFile(io, overlayPath, reconciled);
+    return reconciled;
+}
+function migrateStrictEffect(args, context, io, dryRun, skipInstall) {
+    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.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);
+    preflightModuleFederationBridgeRouter(io.workspaceRoot, allWorkspaceAppsFromToolingConfig(current));
+    const packageSource = createMigrationPackageSource(args, current);
+    const result = (status)=>({
+            status,
+            version: packageSource.modernPackageVersion
+        });
+    const releaseCohort = 'install' === packageSource.strategy ? readCreateReleaseCohort() : void 0;
+    reconcileCompactPackageSourceMetadata(raw.packageSource, packageSource);
+    reconcileRootPackageSourceMetadata(readJsonFile(node_path.join(io.workspaceRoot, 'package.json')), packageSource);
+    updateGeneratedPnpmWorkspacePolicy(createMigrationIo(io.workspaceRoot, true), packageSource, {
+        releaseCohort
+    });
+    updateUltramodernConfig(io, raw, packageSource);
+    if (releaseCohort) io.write(node_path.join(io.workspaceRoot, RELEASE_COHORT_PROJECTION_PATH), `${JSON.stringify(releaseCohort, null, 2)}\n`);
+    updateReferenceTopology(io);
+    synchronizeMigrationDeliveryUnitMetadata(io, raw, packageSource);
+    synchronizeMigrationCompactPolicy(io, raw, packageSource);
+    let migrated = normalizeCompactUltramodernConfig(io.workspaceRoot, raw);
+    let migratedApps = workspaceAppsFromToolingConfig(migrated);
+    migrated = reconcileAdditionalShellConfig(raw, migrated, migratedApps, io);
+    migratedApps = workspaceAppsFromToolingConfig(migrated);
+    const allMigratedApps = allWorkspaceAppsFromToolingConfig(migrated);
+    const developmentOverlay = synchronizeMigrationDevelopmentOverlay(io, migrated, allMigratedApps);
+    const validationContractInputs = deriveValidationContractInputs(io.workspaceRoot, migrated, migratedApps);
+    const verticalApps = migrated.topology.apps.filter((app)=>'shell' !== app.kind);
+    const hasBackendSurface = verticalApps.some((app)=>app.api);
+    const shellOnly = 0 === verticalApps.length;
+    if (shellOnly) {
+        io.log('Shell-only workspace: skipping backend-federation and Zerops runtime stages.');
+        for (const relativePath of [
+            "scripts/generate-node-backend-federation.mts",
+            "scripts/generate-node-backend-federation.mjs",
+            "scripts/proof-node-backend-federation.mts",
+            "scripts/proof-node-backend-federation.mjs",
+            "scripts/materialize-zerops-runtime.mjs",
+            'zerops.yaml'
+        ])removeGeneratedFileIfExists(io, relativePath);
+    } else {
+        if (hasBackendSurface) {
+            removeStaleBackendFederationArtifacts(io, migrated);
+            updateGeneratedBackendFederationContractFiles(io, migrated);
+        } else for (const relativePath of [
+            "scripts/generate-node-backend-federation.mts",
+            "scripts/generate-node-backend-federation.mjs",
+            "scripts/proof-node-backend-federation.mts",
+            "scripts/proof-node-backend-federation.mjs"
+        ])removeGeneratedFileIfExists(io, relativePath);
+        updateGeneratedZeropsArtifacts(io, migrated);
+    }
+    for (const artifact of migratedWorkspaceScriptArtifacts({
+        shellOnly,
+        hasBackendSurface
+    }))if ("scripts/validate-ultramodern-workspace.mts" !== artifact.relativePath) {
+        if (artifact.legacyPath) io.remove(node_path.join(io.workspaceRoot, artifact.legacyPath));
+        io.writeGenerated(node_path.join(io.workspaceRoot, artifact.relativePath), artifact.content);
+    }
+    io.writeGenerated(node_path.join(io.workspaceRoot, "scripts/validate-ultramodern-workspace.mts"), createWorkspaceValidationScript(validationContractInputs.scope, validationContractInputs.enableTailwind, validationContractInputs.remotes, releaseCohort, validationContractInputs.additionalShells, validationContractInputs.primaryShell, raw, node_fs.existsSync(node_path.join(io.workspaceRoot, 'topology/ownership.json')) ? requireRecord(readJsonFile(node_path.join(io.workspaceRoot, 'topology/ownership.json')), 'Ownership topology') : void 0, developmentOverlay));
+    for (const relativePath of retiredMetadataPaths)io.remove(node_path.join(io.workspaceRoot, relativePath));
+    updateGeneratedBuildIdentityModules(io, migrated);
+    updateGeneratedTypeScriptSurfaces(io, migrated);
+    const canRetireLegacyOxfmtCliExclusion = ensureGeneratedOxfmtIgnorePatterns(io);
+    const rootScripts = readJsonFile(node_path.join(io.workspaceRoot, 'package.json')).scripts;
+    const hasLegacyOxfmtCliExclusion = rootScripts && 'object' == typeof rootScripts && !Array.isArray(rootScripts) && Object.values(rootScripts).some((script)=>'string' == typeof script && /\boxfmt(?: --check)? \. '!repos\/\*\*'(?:\s*&&|$)/u.test(script));
+    if (hasLegacyOxfmtCliExclusion && !canRetireLegacyOxfmtCliExclusion) throw new Error("Cannot replace the legacy Oxfmt '!repos/**' CLI exclusion until oxfmt.config.ts has a static ignorePatterns array containing 'repos/**'.");
+    for (const relativePackageFile of listWorkspacePackageFiles(io.workspaceRoot)){
+        const packageFile = node_path.join(io.workspaceRoot, relativePackageFile);
+        const packageJson = readJsonFile(packageFile);
+        if ('package.json' === relativePackageFile) {
+            reconcileRootPackageSourceMetadata(packageJson, packageSource);
+            updateRootPackageToolchain(packageJson);
+        }
+        updateModernDependencies(packageJson, packageSource);
+        const ownsGeneratedScripts = 'package.json' === relativePackageFile || allMigratedApps.some((app)=>`${app.directory}/package.json` === relativePackageFile);
+        updateGeneratedToolingDependencies(packageJson, {
+            ownsGeneratedScripts
+        });
+        ensureBffEffectDependencies(packageJson);
+        const retiredReactRouter = removeRetiredReactRouterDependency(packageJson, node_path.join(io.workspaceRoot, node_path.dirname(relativePackageFile)));
+        if ('preserved' === retiredReactRouter) io.log(`${relativePackageFile} keeps its react-router dependency: authored source imports React Router directly, so its generated Module Federation config keeps bridge.enableBridgeRouter: true.`);
+        else if ('removed' === retiredReactRouter) io.log(`${relativePackageFile} dropped its obsolete react-router dependency: no authored source imports React Router.`);
+        updateGeneratedPackageScripts(packageJson, {
+            relativePackageFile,
+            apps: allMigratedApps,
+            shellOnly,
+            canRetireLegacyOxfmtCliExclusion,
+            onPreserveScript: (scriptName)=>io.log(`${relativePackageFile} script ${JSON.stringify(scriptName)} was preserved: an existing command is mixed consumer/framework ownership.`)
+        });
+        writeJsonFile(io, packageFile, packageJson);
+    }
+    updateGeneratedModernConfigs(io, migrated);
+    ensureGeneratedModuleFederationBridgeRouterOptOut(io, allMigratedApps);
+    updateGeneratedPnpmWorkspacePolicy(io, packageSource, {
+        releaseCohort
+    });
+    updateGeneratedToolchainFiles(io);
+    const drizzleOrmPatch = ULTRAMODERN_WORKSPACE_POLICY.pnpm.patchedDependencies.conditional.find((patch)=>'drizzle-orm' === patch.packageName);
+    ensureGeneratedDeclarationPatches(io, {
+        includeDrizzleOrmPatch: void 0 !== drizzleOrmPatch && workspaceUsesDependency(io.workspaceRoot, drizzleOrmPatch.packageName, drizzleOrmPatch.version)
+    });
+    ensureGeneratedOxlintComponentStyle(io);
+    if (!skipInstall) return io.withStagedWorkspace((stagedWorkspaceRoot)=>{
+        node_fs.rmSync(node_path.join(stagedWorkspaceRoot, 'pnpm-lock.yaml'), {
+            force: true
+        });
+        const status = runPnpmLockfileRefresh({
+            ...context,
+            workspaceRoot: stagedWorkspaceRoot
+        });
+        if (0 !== status) return result(status);
+        return validateGeneratedPnpmLockReleaseAgePolicy(stagedWorkspaceRoot, packageSource, {
+            releaseCohort
+        }).then(()=>{
+            io.write(node_path.join(io.workspaceRoot, 'pnpm-lock.yaml'), node_fs.readFileSync(node_path.join(stagedWorkspaceRoot, 'pnpm-lock.yaml'), 'utf-8'));
+            return result(0);
+        });
+    });
+    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 result(0);
+}
+function runMigrateStrictEffect(args, context) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(migrateStrictEffectHelp);
+        return 0;
+    }
+    const dryRun = hasFlag(args, '--dry-run');
+    const skipInstall = dryRun || hasFlag(args, '--skip-install');
+    const runMigration = (io, migrationContext)=>io.transaction(()=>migrateStrictEffect(args, migrationContext, io, dryRun, skipInstall), {
+            commitWhen: (migrationResult)=>0 === migrationResult.status
+        });
+    const migration = dryRun ? withStagedDryRunMigrationIo(context.workspaceRoot, (io)=>{
+        const invocationRelativePath = node_path.relative(context.workspaceRoot, context.invocationCwd);
+        const invocationIsOutsideWorkspace = '..' === invocationRelativePath || invocationRelativePath.startsWith(`..${node_path.sep}`) || node_path.isAbsolute(invocationRelativePath);
+        return runMigration(io, {
+            workspaceRoot: io.workspaceRoot,
+            invocationCwd: invocationIsOutsideWorkspace ? context.invocationCwd : node_path.join(io.workspaceRoot, invocationRelativePath)
+        });
+    }) : runMigration(createMigrationIo(context.workspaceRoot, false), context);
+    const report = (migrationResult)=>{
+        if (0 === migrationResult.status && !dryRun) process.stdout.write(`UltraModern strict Effect metadata migrated to ${migrationResult.version}. Run pnpm api:check && pnpm contract:check next.\n`);
+        return migrationResult.status;
+    };
+    if (migration instanceof Promise) return migration.then(report);
+    return report(migration);
+}
+export { runMigrateStrictEffect };

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

@@ -0,0 +1,18 @@
+function readOption(args, name) {
+    const prefix = `${name}=`;
+    const inline = args.find((arg)=>arg.startsWith(prefix));
+    if (inline) {
+        const value = inline.slice(prefix.length);
+        if (!value) throw new Error(`${name} needs a value.`);
+        return value;
+    }
+    const index = args.indexOf(name);
+    if (-1 === index) return;
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} needs a value.`);
+    return value;
+}
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+export { hasFlag, readOption };

package/dist/esm/ultramodern-tooling/commands/routes-generate.js

@@ -0,0 +1,74 @@
+import node_path from "node:path";
+import { readUltramodernConfig, workspaceAppsFromToolingConfig } from "../config.js";
+import { runRenderedModule } from "./context.js";
+import { readOption } from "./options.js";
+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;
+    console.error(\`[ultramodern] TanStack route generation failed: \${target.label}\`);
+    // Print the full underlying failure, including the cause chain. The
+    // route-generate crash is often an opaque node error thrown deep inside
+    // app-tools/plugin (e.g. a path TypeError), so surfacing only
+    // \`error.message\` swallows the stack that points at the real culprit.
+    let current = error;
+    let depth = 0;
+    while (current) {
+      const label = depth === 0 ? '-' : '  caused by:';
+      const detail =
+        current instanceof Error
+          ? current.stack ?? \`\${current.name}: \${current.message}\`
+          : String(current);
+      console.error(\`\${label} \${detail}\`);
+      current = current instanceof Error ? current.cause : undefined;
+      depth += 1;
+    }
+  }
+}
+
+process.exit(failed ? 1 : 0);
+`;
+function runRoutesGenerate(args, context) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(`Usage:
+  ultramodern-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);
+}
+export { runRoutesGenerate };

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

@@ -0,0 +1,11 @@
+import { spawnNodeScript } from "./context.js";
+function runSkills(args, context) {
+    const [subcommand, ...rest] = args;
+    if ('install' === subcommand) return spawnNodeScript("template-workspace/scripts/bootstrap-agent-skills.mjs", rest, context);
+    if ('check' === subcommand) return spawnNodeScript("template-workspace/scripts/bootstrap-agent-skills.mjs", [
+        '--check',
+        ...rest
+    ], context);
+    throw new Error('Usage: ultramodern-create ultramodern skills <install|check>');
+}
+export { runSkills };

package/dist/esm/ultramodern-tooling/commands/sync-delivery-unit.js

@@ -0,0 +1 @@
+export { runSyncDeliveryUnit } from "../../ultramodern-workspace/delivery-unit-sync.js";

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

@@ -0,0 +1,15 @@
+import { readWorkspaceReleaseCohort } from "../../ultramodern-release-cohort.js";
+import { createWorkspaceValidationScript } from "../../ultramodern-workspace/workspace-scripts.js";
+import { additionalShellsFromToolingConfig, readUltramodernConfig, workspaceAppsFromToolingConfig } from "../config.js";
+import { runRenderedModule } from "./context.js";
+function runValidate(context) {
+    const config = readUltramodernConfig(context.workspaceRoot);
+    const apps = workspaceAppsFromToolingConfig(config);
+    const remotes = apps.filter((app)=>'shell' !== app.kind);
+    const primaryShell = apps.find((app)=>'shell' === app.kind);
+    const additionalShells = additionalShellsFromToolingConfig(config);
+    const releaseCohort = config.packageSource?.strategy === 'install' ? readWorkspaceReleaseCohort(context.workspaceRoot) : void 0;
+    const source = createWorkspaceValidationScript(config.workspace.packageScope, config.features.tailwind, remotes, releaseCohort, additionalShells, primaryShell);
+    return runRenderedModule(source, context);
+}
+export { runValidate };

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

@@ -0,0 +1,51 @@
+import node_path from "node:path";
+import { GENERATED_TOOLING_COMMANDS } from "../ultramodern-workspace/tooling-command-catalog.js";
+import { runCloudflareOutputVerify } from "./commands/cloudflare-output-verify.js";
+import { printHelp, runTemplateBackedToolingCommand } from "./commands/context.js";
+import { runMfTypes } from "./commands/mf-types.js";
+import { runMigrateStrictEffect } from "./commands/migrate-strict-effect.js";
+import { runRoutesGenerate } from "./commands/routes-generate.js";
+import { runSkills } from "./commands/skills.js";
+import { runSyncDeliveryUnit } from "./commands/sync-delivery-unit.js";
+import { runValidate } from "./commands/validate.js";
+async function runUltramodernToolingCli(args, workspaceRoot = process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd()) {
+    try {
+        const [command, ...rest] = args;
+        const context = {
+            workspaceRoot: node_path.resolve(workspaceRoot),
+            invocationCwd: process.cwd()
+        };
+        switch(command){
+            case void 0:
+            case '--help':
+            case '-h':
+                printHelp();
+                return 0;
+            case GENERATED_TOOLING_COMMANDS.validate.command:
+                return runValidate(context);
+            case GENERATED_TOOLING_COMMANDS.mfTypes.command:
+                return runMfTypes(rest, context);
+            case GENERATED_TOOLING_COMMANDS.migrateStrictEffect.command:
+                return await runMigrateStrictEffect(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) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[ultramodern] ${message}\n`);
+        return 1;
+    }
+}
+export { runUltramodernToolingCli };

package/dist/esm/ultramodern-tooling/config/constants.js

@@ -0,0 +1,4 @@
+const LEGACY_GENERATED_CONTRACT_PATH = '.modernjs/ultramodern-generated-contract.json';
+const LEGACY_PACKAGE_SOURCE_METADATA_PATH = '.modernjs/ultramodern-package-source.json';
+const LEGACY_DEVELOPMENT_OVERLAY_PATH = 'topology/local-overlays/development.json';
+export { LEGACY_DEVELOPMENT_OVERLAY_PATH, LEGACY_GENERATED_CONTRACT_PATH, LEGACY_PACKAGE_SOURCE_METADATA_PATH };

package/dist/esm/ultramodern-tooling/config/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./json.js";
+export * from "./load.js";
+export * from "./metadata.js";
+export * from "./normalize.js";
+export * from "./synthesize.js";
+export * from "./types.js";

package/dist/esm/ultramodern-tooling/config/json.js

@@ -0,0 +1,10 @@
+import node_fs from "node:fs";
+function readJsonObject(filePath) {
+    const value = JSON.parse(node_fs.readFileSync(filePath, 'utf-8'));
+    if (null === value || 'object' != typeof value || Array.isArray(value)) throw new Error(`UltraModern config must contain a JSON object: ${filePath}`);
+    return value;
+}
+function readOptionalJsonObject(filePath) {
+    return node_fs.existsSync(filePath) ? readJsonObject(filePath) : {};
+}
+export { readJsonObject, readOptionalJsonObject };

package/dist/esm/ultramodern-tooling/config/load.js

@@ -0,0 +1,13 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { ULTRAMODERN_CONFIG_PATH } from "../../ultramodern-workspace/descriptors.js";
+import { LEGACY_GENERATED_CONTRACT_PATH } from "./constants.js";
+import { readJsonObject } from "./json.js";
+import { normalizeCompactConfig } from "./normalize.js";
+function readUltramodernConfig(workspaceRoot = process.cwd()) {
+    const compactPath = node_path.join(workspaceRoot, ULTRAMODERN_CONFIG_PATH);
+    if (node_fs.existsSync(compactPath)) return normalizeCompactConfig(workspaceRoot, compactPath, readJsonObject(compactPath));
+    if (node_fs.existsSync(node_path.join(workspaceRoot, LEGACY_GENERATED_CONTRACT_PATH))) throw new Error(`Missing ${ULTRAMODERN_CONFIG_PATH}. Legacy UltraModern metadata detected — run \`ultramodern-create ultramodern migrate-strict-effect\` to synthesize it.`);
+    throw new Error(`Missing UltraModern config. Expected ${ULTRAMODERN_CONFIG_PATH}. Run \`ultramodern-create ultramodern migrate-strict-effect\` if you have legacy UltraModern metadata to migrate.`);
+}
+export { readUltramodernConfig };