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

package/dist/cjs/ultramodern-tooling/commands.cjs

@@ -312,19 +312,71 @@ const cloudflareWranglerDeployInvalidSkipBuildCommand = `${cloudflareWranglerDep
 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, '');
 }
+const SHELL_ONLY_OMITTED_ROOT_SCRIPTS = [
+    'node:backend-federation:generate',
+    'node:proof',
+    'zerops:materialize'
+];
+const splitScriptSegments = (command)=>command.split('&&').map((segment)=>segment.trim()).filter((segment)=>segment.length > 0);
+const scriptSegmentTarget = (segment)=>segment.replace(/^pnpm\s+/u, '').split(/\s+/u)[0] ?? segment;
+const FRAMEWORK_CHECK_TARGETS = new Set([
+    'format:check',
+    'lint',
+    'typecheck',
+    'skills:check',
+    'i18n:boundaries',
+    'api:check',
+    'contract:check',
+    'node:backend-federation:generate',
+    'node:proof',
+    'performance:readiness',
+    'bridge:check'
+]);
+function mergeAggregateCheckScript(consumer, framework) {
+    const frameworkSegments = splitScriptSegments(framework);
+    const consumerExtras = splitScriptSegments(consumer).filter((segment)=>!FRAMEWORK_CHECK_TARGETS.has(scriptSegmentTarget(segment)));
+    return [
+        ...consumerExtras,
+        ...frameworkSegments
+    ].join(' && ');
+}
+function rewriteMigratedScriptReferences(scripts) {
+    let changed = false;
+    const pattern = new RegExp(`(scripts/(?:${workspace_scripts_cjs_namespaceObject.migratedWorkspaceScriptBasenames.join('|')}))\\.mjs`, 'gu');
+    for (const [name, value] of Object.entries(scripts)){
+        if ('string' != typeof value) continue;
+        const next = value.replace(pattern, '$1.mts');
+        if (next !== value) {
+            scripts[name] = next;
+            changed = true;
+        }
+    }
+    return changed;
+}
 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 shellOnly = options.shellOnly ?? false;
     const app = apps.find((candidate)=>`${candidate.directory}/package.json` === options.relativePackageFile);
-    const expectedScripts = 'package.json' === options.relativePackageFile ? (0, workspace_script_plan_cjs_namespaceObject.createWorkspaceRootPackageScripts)(apps.filter((candidate)=>'shell' !== candidate.kind)) : app ? (0, workspace_script_plan_cjs_namespaceObject.createWorkspaceAppPackageScripts)(app) : void 0;
-    if (expectedScripts) {
-        for (const [name, value] of Object.entries(expectedScripts))if (scripts[name] !== value) {
-            scripts[name] = value;
+    const isRootPackage = 'package.json' === options.relativePackageFile;
+    const expectedScripts = isRootPackage ? (0, workspace_script_plan_cjs_namespaceObject.createWorkspaceRootPackageScripts)(apps.filter((candidate)=>'shell' !== candidate.kind)) : app ? (0, workspace_script_plan_cjs_namespaceObject.createWorkspaceAppPackageScripts)(app) : void 0;
+    if (expectedScripts) for (const [name, value] of Object.entries(expectedScripts)){
+        if (isRootPackage && shellOnly && SHELL_ONLY_OMITTED_ROOT_SCRIPTS.includes(name)) {
+            if (name in scripts) {
+                delete scripts[name];
+                changed = true;
+            }
+            continue;
+        }
+        const nextValue = 'check' === name && 'string' == typeof scripts[name] ? mergeAggregateCheckScript(scripts[name], value) : value;
+        if (scripts[name] !== nextValue) {
+            scripts[name] = nextValue;
             changed = true;
         }
     }
+    if (rewriteMigratedScriptReferences(scripts)) changed = true;
     const build = scripts.build;
     if ('string' == typeof build) {
         const nextBuild = removeStaleBackendFederationCommandSegments(build);
@@ -699,6 +751,7 @@ function updateUltramodernConfig(io, config, packageSource) {
             aliasPackageNamePrefix: packageSource.aliasPackageNamePrefix
         } : {}
     };
+    if (config.generator && 'object' == typeof config.generator && !Array.isArray(config.generator) && 'string' == typeof config.generator.version) config.generator.version = packageSource.modernPackageVersion;
     for (const app of config.topology?.apps ?? [])if (app && 'object' == typeof app && !Array.isArray(app)) normalizeStrictEffectApiMetadata(app);
     writeJsonFile(io, configPath, config);
 }
@@ -928,14 +981,27 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
     const migrated = (0, external_config_cjs_namespaceObject.normalizeCompactUltramodernConfig)(io.workspaceRoot, raw);
     const migratedApps = (0, external_config_cjs_namespaceObject.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 {
+    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 {
         removeStaleBackendFederationArtifacts(io, migrated);
         updateGeneratedZeropsArtifacts(io, migrated);
         updateGeneratedBackendFederationContractFiles(io, migrated);
     }
-    if (dryRun) io.log("would refresh generated tool wrapper scripts under scripts/");
-    else (0, workspace_scripts_cjs_namespaceObject.writeGeneratedToolWrapperScripts)(io.workspaceRoot);
+    for (const artifact of (0, workspace_scripts_cjs_namespaceObject.migratedWorkspaceScriptArtifacts)({
+        shellOnly
+    })){
+        if (artifact.legacyPath) io.remove(external_node_path_default().join(io.workspaceRoot, artifact.legacyPath));
+        io.write(external_node_path_default().join(io.workspaceRoot, artifact.relativePath), artifact.content);
+    }
     updateGeneratedBuildIdentityModules(io, migrated);
     updateGeneratedTypeScriptSurfaces(io, migrated);
     updateGeneratedModernConfigs(io, migrated);
@@ -953,7 +1019,8 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
         updateGeneratedToolingDependencies(packageJson);
         updateGeneratedPackageScripts(packageJson, {
             relativePackageFile,
-            apps: migratedApps
+            apps: migratedApps,
+            shellOnly
         });
         writeJsonFile(io, packageFile, packageJson);
     }
@@ -1092,9 +1159,23 @@ for (const target of targets) {
     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}\`);
+    // 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;
+    }
   }
 }
 

package/dist/cjs/ultramodern-workspace/module-federation.cjs

@@ -104,6 +104,15 @@ const zephyrEnabled = process.env['ULTRAMODERN_ZEPHYR'] !== 'false';
 const cloudflareDeployEnabled =
   process.env['MODERNJS_DEPLOY'] === 'cloudflare';
 
+const parsedZephyrTimeoutMs = Number.parseInt(
+  process.env['ULTRAMODERN_ZEPHYR_TIMEOUT_MS'] ?? '',
+  10,
+);
+const zephyrTimeoutMs =
+  Number.isFinite(parsedZephyrTimeoutMs) && parsedZephyrTimeoutMs > 0
+    ? parsedZephyrTimeoutMs
+    : 45000;
+
 const zephyrWarn = (error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);
   console.warn(
@@ -126,10 +135,27 @@ const zephyrRspackPlugin = () => ({
     }
     api.modifyRspackConfig(config => {
       try {
-        return Promise.resolve(withZephyrRspack()(config)).catch(error => {
-          zephyrWarn(error);
-          return config;
+        // Zephyr can not only throw/reject but also hang on a stalled network
+        // call, wedging the whole build. Race it against a watchdog so a hang
+        // degrades to an unmodified config instead of blocking indefinitely.
+        const zephyrConfig = Promise.resolve(withZephyrRspack()(config)).catch(
+          error => {
+            zephyrWarn(error);
+            return config;
+          },
+        );
+        const watchdog = new Promise<ZephyrRspackConfig>(resolve => {
+          const timer = setTimeout(() => {
+            zephyrWarn(
+              \`timed out after \${zephyrTimeoutMs}ms (override with ULTRAMODERN_ZEPHYR_TIMEOUT_MS)\`,
+            );
+            resolve(config);
+          }, zephyrTimeoutMs);
+          if (typeof timer.unref === 'function') {
+            timer.unref();
+          }
         });
+        return Promise.race([zephyrConfig, watchdog]);
       } catch (error) {
         zephyrWarn(error);
         return config;

package/dist/cjs/ultramodern-workspace/workspace-script-plan.cjs

@@ -138,7 +138,7 @@ function createWorkspaceRootScriptPlan(remotes = [], options = {}) {
         zeropsMaterialize: "node ./scripts/materialize-zerops-runtime.mjs",
         contractCheck: rootToolingWrapperCommand('validate'),
         typecheck: options.typecheck ?? `${rootToolingWrapperCommand('typecheck')} --project tsconfig.json`,
-        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript} && pnpm performance:readiness${bridgeCheck}`
+        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check${hasRemotes ? ` && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript}` : ''} && pnpm performance:readiness${bridgeCheck}`
     };
 }
 function createWorkspaceRootPackageScripts(remotes = [], options = {}) {

package/dist/cjs/ultramodern-workspace/workspace-scripts.cjs

@@ -37,12 +37,15 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    createAgentReferenceReposSetupScript: ()=>createAgentReferenceReposSetupScript,
     createNodeBackendFederationProofScript: ()=>createNodeBackendFederationProofScript,
     createPerformanceReadinessConfigScript: ()=>createPerformanceReadinessConfigScript,
     createWorkspaceApiBoundaryValidationScript: ()=>createWorkspaceApiBoundaryValidationScript,
     createWorkspaceI18nBoundaryValidationScript: ()=>createWorkspaceI18nBoundaryValidationScript,
     createWorkspaceValidationScript: ()=>createWorkspaceValidationScript,
     createZeropsRuntimeMaterializationScript: ()=>createZeropsRuntimeMaterializationScript,
+    migratedWorkspaceScriptArtifacts: ()=>migratedWorkspaceScriptArtifacts,
+    migratedWorkspaceScriptBasenames: ()=>migratedWorkspaceScriptBasenames,
     writeGeneratedToolWrapperScripts: ()=>writeGeneratedToolWrapperScripts,
     writeGeneratedWorkspaceScripts: ()=>writeGeneratedWorkspaceScripts
 });
@@ -53,9 +56,10 @@ var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_no
 const external_fs_io_cjs_namespaceObject = require("./fs-io.cjs");
 const external_tooling_command_catalog_cjs_namespaceObject = require("./tooling-command-catalog.cjs");
 const external_workspace_validation_contract_cjs_namespaceObject = require("./workspace-validation-contract.cjs");
+const singleQuoted = (value)=>`'${value.replace(/'/gu, "\\'")}'`;
 function createToolWrapperScript(command, extraArgs = []) {
-    const commandJson = JSON.stringify(command);
-    const extraArgsJson = JSON.stringify(extraArgs);
+    const commandLiteral = singleQuoted(command);
+    const extraArgsLiteral = `[${extraArgs.map(singleQuoted).join(', ')}]`;
     return `#!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -66,7 +70,7 @@ const forwardedArgs = process.argv.slice(2);
 const workspaceRoot =
   process.env.ULTRAMODERN_WORKSPACE_ROOT ??
   path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const ultramodernArgs = ['ultramodern', ${commandJson}, ...${extraArgsJson}, ...forwardedArgs];
+const ultramodernArgs = ['ultramodern', ${commandLiteral}, ...${extraArgsLiteral}, ...forwardedArgs];
 const result = createBin
   ? spawnSync(process.execPath, [createBin, ...ultramodernArgs], {
       env: { ...process.env, ULTRAMODERN_WORKSPACE_ROOT: workspaceRoot },
@@ -191,21 +195,75 @@ function writeGeneratedWorkspaceScripts(targetDir, _scope, _enableTailwind, _rem
     writeWorkspaceOwnedMtsScript(targetDir, 'bootstrap-agent-skills', createSkillsToolWrapperScript());
     migrateCopiedWorkspaceScriptToMts(targetDir, 'setup-agent-reference-repos');
 }
+function createAgentReferenceReposSetupScript() {
+    return external_node_fs_default().readFileSync(external_node_path_default().join(external_fs_io_cjs_namespaceObject.workspaceTemplateDir, "scripts/setup-agent-reference-repos.mjs"), 'utf-8');
+}
+const BACKEND_FEDERATION_WRAPPER_IDS = new Set([
+    'backendFederationGenerate',
+    'backendFederationProof'
+]);
+function migratedWorkspaceScriptArtifacts(options) {
+    const artifacts = [
+        {
+            relativePath: "scripts/check-ultramodern-i18n-boundaries.mts",
+            content: createWorkspaceI18nBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-i18n-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/check-ultramodern-api-boundaries.mts",
+            content: createWorkspaceApiBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-api-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/ultramodern-performance-readiness.config.mjs",
+            content: createPerformanceReadinessConfigScript()
+        },
+        {
+            relativePath: "scripts/bootstrap-agent-skills.mts",
+            content: createSkillsToolWrapperScript(),
+            legacyPath: "scripts/bootstrap-agent-skills.mjs"
+        },
+        {
+            relativePath: "scripts/setup-agent-reference-repos.mts",
+            content: createAgentReferenceReposSetupScript(),
+            legacyPath: "scripts/setup-agent-reference-repos.mjs"
+        }
+    ];
+    for (const command of external_tooling_command_catalog_cjs_namespaceObject.generatedToolingCommands)if (!(options.shellOnly && BACKEND_FEDERATION_WRAPPER_IDS.has(command.id))) artifacts.push({
+        relativePath: command.wrapperPath,
+        content: createToolWrapperScript(command.command),
+        legacyPath: command.wrapperPath.replace(/\.mts$/u, '.mjs')
+    });
+    return artifacts;
+}
+const migratedWorkspaceScriptBasenames = [
+    'check-ultramodern-i18n-boundaries',
+    'check-ultramodern-api-boundaries',
+    'bootstrap-agent-skills',
+    'setup-agent-reference-repos',
+    ...external_tooling_command_catalog_cjs_namespaceObject.generatedToolingCommands.map((command)=>command.wrapperName)
+];
+exports.createAgentReferenceReposSetupScript = __webpack_exports__.createAgentReferenceReposSetupScript;
 exports.createNodeBackendFederationProofScript = __webpack_exports__.createNodeBackendFederationProofScript;
 exports.createPerformanceReadinessConfigScript = __webpack_exports__.createPerformanceReadinessConfigScript;
 exports.createWorkspaceApiBoundaryValidationScript = __webpack_exports__.createWorkspaceApiBoundaryValidationScript;
 exports.createWorkspaceI18nBoundaryValidationScript = __webpack_exports__.createWorkspaceI18nBoundaryValidationScript;
 exports.createWorkspaceValidationScript = __webpack_exports__.createWorkspaceValidationScript;
 exports.createZeropsRuntimeMaterializationScript = __webpack_exports__.createZeropsRuntimeMaterializationScript;
+exports.migratedWorkspaceScriptArtifacts = __webpack_exports__.migratedWorkspaceScriptArtifacts;
+exports.migratedWorkspaceScriptBasenames = __webpack_exports__.migratedWorkspaceScriptBasenames;
 exports.writeGeneratedToolWrapperScripts = __webpack_exports__.writeGeneratedToolWrapperScripts;
 exports.writeGeneratedWorkspaceScripts = __webpack_exports__.writeGeneratedWorkspaceScripts;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createAgentReferenceReposSetupScript",
     "createNodeBackendFederationProofScript",
     "createPerformanceReadinessConfigScript",
     "createWorkspaceApiBoundaryValidationScript",
     "createWorkspaceI18nBoundaryValidationScript",
     "createWorkspaceValidationScript",
     "createZeropsRuntimeMaterializationScript",
+    "migratedWorkspaceScriptArtifacts",
+    "migratedWorkspaceScriptBasenames",
     "writeGeneratedToolWrapperScripts",
     "writeGeneratedWorkspaceScripts"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];

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

@@ -14,7 +14,7 @@ import { createAppMfTypesTsConfig, createAppTsConfig, createSharedPackageTsConfi
 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 { createWorkspaceAppPackageScripts, createWorkspaceRootPackageScripts } from "../ultramodern-workspace/workspace-script-plan.js";
-import { createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, writeGeneratedToolWrapperScripts } from "../ultramodern-workspace/workspace-scripts.js";
+import { createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, migratedWorkspaceScriptArtifacts, migratedWorkspaceScriptBasenames } 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));
@@ -265,19 +265,71 @@ const cloudflareWranglerDeployInvalidSkipBuildCommand = `${cloudflareWranglerDep
 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, '');
 }
+const SHELL_ONLY_OMITTED_ROOT_SCRIPTS = [
+    'node:backend-federation:generate',
+    'node:proof',
+    'zerops:materialize'
+];
+const splitScriptSegments = (command)=>command.split('&&').map((segment)=>segment.trim()).filter((segment)=>segment.length > 0);
+const scriptSegmentTarget = (segment)=>segment.replace(/^pnpm\s+/u, '').split(/\s+/u)[0] ?? segment;
+const FRAMEWORK_CHECK_TARGETS = new Set([
+    'format:check',
+    'lint',
+    'typecheck',
+    'skills:check',
+    'i18n:boundaries',
+    'api:check',
+    'contract:check',
+    'node:backend-federation:generate',
+    'node:proof',
+    'performance:readiness',
+    'bridge:check'
+]);
+function mergeAggregateCheckScript(consumer, framework) {
+    const frameworkSegments = splitScriptSegments(framework);
+    const consumerExtras = splitScriptSegments(consumer).filter((segment)=>!FRAMEWORK_CHECK_TARGETS.has(scriptSegmentTarget(segment)));
+    return [
+        ...consumerExtras,
+        ...frameworkSegments
+    ].join(' && ');
+}
+function rewriteMigratedScriptReferences(scripts) {
+    let changed = false;
+    const pattern = new RegExp(`(scripts/(?:${migratedWorkspaceScriptBasenames.join('|')}))\\.mjs`, 'gu');
+    for (const [name, value] of Object.entries(scripts)){
+        if ('string' != typeof value) continue;
+        const next = value.replace(pattern, '$1.mts');
+        if (next !== value) {
+            scripts[name] = next;
+            changed = true;
+        }
+    }
+    return changed;
+}
 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 shellOnly = options.shellOnly ?? false;
     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;
+    const isRootPackage = 'package.json' === options.relativePackageFile;
+    const expectedScripts = isRootPackage ? createWorkspaceRootPackageScripts(apps.filter((candidate)=>'shell' !== candidate.kind)) : app ? createWorkspaceAppPackageScripts(app) : void 0;
+    if (expectedScripts) for (const [name, value] of Object.entries(expectedScripts)){
+        if (isRootPackage && shellOnly && SHELL_ONLY_OMITTED_ROOT_SCRIPTS.includes(name)) {
+            if (name in scripts) {
+                delete scripts[name];
+                changed = true;
+            }
+            continue;
+        }
+        const nextValue = 'check' === name && 'string' == typeof scripts[name] ? mergeAggregateCheckScript(scripts[name], value) : value;
+        if (scripts[name] !== nextValue) {
+            scripts[name] = nextValue;
             changed = true;
         }
     }
+    if (rewriteMigratedScriptReferences(scripts)) changed = true;
     const build = scripts.build;
     if ('string' == typeof build) {
         const nextBuild = removeStaleBackendFederationCommandSegments(build);
@@ -652,6 +704,7 @@ function updateUltramodernConfig(io, config, packageSource) {
             aliasPackageNamePrefix: packageSource.aliasPackageNamePrefix
         } : {}
     };
+    if (config.generator && 'object' == typeof config.generator && !Array.isArray(config.generator) && 'string' == typeof config.generator.version) config.generator.version = packageSource.modernPackageVersion;
     for (const app of config.topology?.apps ?? [])if (app && 'object' == typeof app && !Array.isArray(app)) normalizeStrictEffectApiMetadata(app);
     writeJsonFile(io, configPath, config);
 }
@@ -881,14 +934,27 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
     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 {
+    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 {
         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);
+    for (const artifact of migratedWorkspaceScriptArtifacts({
+        shellOnly
+    })){
+        if (artifact.legacyPath) io.remove(node_path.join(io.workspaceRoot, artifact.legacyPath));
+        io.write(node_path.join(io.workspaceRoot, artifact.relativePath), artifact.content);
+    }
     updateGeneratedBuildIdentityModules(io, migrated);
     updateGeneratedTypeScriptSurfaces(io, migrated);
     updateGeneratedModernConfigs(io, migrated);
@@ -906,7 +972,8 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
         updateGeneratedToolingDependencies(packageJson);
         updateGeneratedPackageScripts(packageJson, {
             relativePackageFile,
-            apps: migratedApps
+            apps: migratedApps,
+            shellOnly
         });
         writeJsonFile(io, packageFile, packageJson);
     }
@@ -1045,9 +1112,23 @@ for (const target of targets) {
     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}\`);
+    // 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;
+    }
   }
 }
 

package/dist/esm/ultramodern-workspace/module-federation.js

@@ -62,6 +62,15 @@ const zephyrEnabled = process.env['ULTRAMODERN_ZEPHYR'] !== 'false';
 const cloudflareDeployEnabled =
   process.env['MODERNJS_DEPLOY'] === 'cloudflare';
 
+const parsedZephyrTimeoutMs = Number.parseInt(
+  process.env['ULTRAMODERN_ZEPHYR_TIMEOUT_MS'] ?? '',
+  10,
+);
+const zephyrTimeoutMs =
+  Number.isFinite(parsedZephyrTimeoutMs) && parsedZephyrTimeoutMs > 0
+    ? parsedZephyrTimeoutMs
+    : 45000;
+
 const zephyrWarn = (error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);
   console.warn(
@@ -84,10 +93,27 @@ const zephyrRspackPlugin = () => ({
     }
     api.modifyRspackConfig(config => {
       try {
-        return Promise.resolve(withZephyrRspack()(config)).catch(error => {
-          zephyrWarn(error);
-          return config;
+        // Zephyr can not only throw/reject but also hang on a stalled network
+        // call, wedging the whole build. Race it against a watchdog so a hang
+        // degrades to an unmodified config instead of blocking indefinitely.
+        const zephyrConfig = Promise.resolve(withZephyrRspack()(config)).catch(
+          error => {
+            zephyrWarn(error);
+            return config;
+          },
+        );
+        const watchdog = new Promise<ZephyrRspackConfig>(resolve => {
+          const timer = setTimeout(() => {
+            zephyrWarn(
+              \`timed out after \${zephyrTimeoutMs}ms (override with ULTRAMODERN_ZEPHYR_TIMEOUT_MS)\`,
+            );
+            resolve(config);
+          }, zephyrTimeoutMs);
+          if (typeof timer.unref === 'function') {
+            timer.unref();
+          }
         });
+        return Promise.race([zephyrConfig, watchdog]);
       } catch (error) {
         zephyrWarn(error);
         return config;

package/dist/esm/ultramodern-workspace/workspace-script-plan.js

@@ -97,7 +97,7 @@ function createWorkspaceRootScriptPlan(remotes = [], options = {}) {
         zeropsMaterialize: "node ./scripts/materialize-zerops-runtime.mjs",
         contractCheck: rootToolingWrapperCommand('validate'),
         typecheck: options.typecheck ?? `${rootToolingWrapperCommand('typecheck')} --project tsconfig.json`,
-        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript} && pnpm performance:readiness${bridgeCheck}`
+        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check${hasRemotes ? ` && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript}` : ''} && pnpm performance:readiness${bridgeCheck}`
     };
 }
 function createWorkspaceRootPackageScripts(remotes = [], options = {}) {

package/dist/esm/ultramodern-workspace/workspace-scripts.js

@@ -1,11 +1,12 @@
 import node_fs from "node:fs";
 import node_path from "node:path";
-import { readFileTemplate, renderFileTemplate, writeFileReplacing } from "./fs-io.js";
+import { readFileTemplate, renderFileTemplate, workspaceTemplateDir, writeFileReplacing } from "./fs-io.js";
 import { GENERATED_TOOLING_COMMANDS, generatedToolingCommands } from "./tooling-command-catalog.js";
 import { createWorkspaceValidationContract } from "./workspace-validation-contract.js";
+const singleQuoted = (value)=>`'${value.replace(/'/gu, "\\'")}'`;
 function createToolWrapperScript(command, extraArgs = []) {
-    const commandJson = JSON.stringify(command);
-    const extraArgsJson = JSON.stringify(extraArgs);
+    const commandLiteral = singleQuoted(command);
+    const extraArgsLiteral = `[${extraArgs.map(singleQuoted).join(', ')}]`;
     return `#!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -16,7 +17,7 @@ const forwardedArgs = process.argv.slice(2);
 const workspaceRoot =
   process.env.ULTRAMODERN_WORKSPACE_ROOT ??
   path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const ultramodernArgs = ['ultramodern', ${commandJson}, ...${extraArgsJson}, ...forwardedArgs];
+const ultramodernArgs = ['ultramodern', ${commandLiteral}, ...${extraArgsLiteral}, ...forwardedArgs];
 const result = createBin
   ? spawnSync(process.execPath, [createBin, ...ultramodernArgs], {
       env: { ...process.env, ULTRAMODERN_WORKSPACE_ROOT: workspaceRoot },
@@ -141,4 +142,52 @@ function writeGeneratedWorkspaceScripts(targetDir, _scope, _enableTailwind, _rem
     writeWorkspaceOwnedMtsScript(targetDir, 'bootstrap-agent-skills', createSkillsToolWrapperScript());
     migrateCopiedWorkspaceScriptToMts(targetDir, 'setup-agent-reference-repos');
 }
-export { createNodeBackendFederationProofScript, createPerformanceReadinessConfigScript, createWorkspaceApiBoundaryValidationScript, createWorkspaceI18nBoundaryValidationScript, createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, writeGeneratedToolWrapperScripts, writeGeneratedWorkspaceScripts };
+function createAgentReferenceReposSetupScript() {
+    return node_fs.readFileSync(node_path.join(workspaceTemplateDir, "scripts/setup-agent-reference-repos.mjs"), 'utf-8');
+}
+const BACKEND_FEDERATION_WRAPPER_IDS = new Set([
+    'backendFederationGenerate',
+    'backendFederationProof'
+]);
+function migratedWorkspaceScriptArtifacts(options) {
+    const artifacts = [
+        {
+            relativePath: "scripts/check-ultramodern-i18n-boundaries.mts",
+            content: createWorkspaceI18nBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-i18n-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/check-ultramodern-api-boundaries.mts",
+            content: createWorkspaceApiBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-api-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/ultramodern-performance-readiness.config.mjs",
+            content: createPerformanceReadinessConfigScript()
+        },
+        {
+            relativePath: "scripts/bootstrap-agent-skills.mts",
+            content: createSkillsToolWrapperScript(),
+            legacyPath: "scripts/bootstrap-agent-skills.mjs"
+        },
+        {
+            relativePath: "scripts/setup-agent-reference-repos.mts",
+            content: createAgentReferenceReposSetupScript(),
+            legacyPath: "scripts/setup-agent-reference-repos.mjs"
+        }
+    ];
+    for (const command of generatedToolingCommands)if (!(options.shellOnly && BACKEND_FEDERATION_WRAPPER_IDS.has(command.id))) artifacts.push({
+        relativePath: command.wrapperPath,
+        content: createToolWrapperScript(command.command),
+        legacyPath: command.wrapperPath.replace(/\.mts$/u, '.mjs')
+    });
+    return artifacts;
+}
+const migratedWorkspaceScriptBasenames = [
+    'check-ultramodern-i18n-boundaries',
+    'check-ultramodern-api-boundaries',
+    'bootstrap-agent-skills',
+    'setup-agent-reference-repos',
+    ...generatedToolingCommands.map((command)=>command.wrapperName)
+];
+export { createAgentReferenceReposSetupScript, createNodeBackendFederationProofScript, createPerformanceReadinessConfigScript, createWorkspaceApiBoundaryValidationScript, createWorkspaceI18nBoundaryValidationScript, createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, migratedWorkspaceScriptArtifacts, migratedWorkspaceScriptBasenames, writeGeneratedToolWrapperScripts, writeGeneratedWorkspaceScripts };

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

@@ -15,7 +15,7 @@ import { createAppMfTypesTsConfig, createAppTsConfig, createSharedPackageTsConfi
 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 { createWorkspaceAppPackageScripts, createWorkspaceRootPackageScripts } from "../ultramodern-workspace/workspace-script-plan.js";
-import { createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, writeGeneratedToolWrapperScripts } from "../ultramodern-workspace/workspace-scripts.js";
+import { createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, migratedWorkspaceScriptArtifacts, migratedWorkspaceScriptBasenames } 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));
@@ -266,19 +266,71 @@ const cloudflareWranglerDeployInvalidSkipBuildCommand = `${cloudflareWranglerDep
 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, '');
 }
+const SHELL_ONLY_OMITTED_ROOT_SCRIPTS = [
+    'node:backend-federation:generate',
+    'node:proof',
+    'zerops:materialize'
+];
+const splitScriptSegments = (command)=>command.split('&&').map((segment)=>segment.trim()).filter((segment)=>segment.length > 0);
+const scriptSegmentTarget = (segment)=>segment.replace(/^pnpm\s+/u, '').split(/\s+/u)[0] ?? segment;
+const FRAMEWORK_CHECK_TARGETS = new Set([
+    'format:check',
+    'lint',
+    'typecheck',
+    'skills:check',
+    'i18n:boundaries',
+    'api:check',
+    'contract:check',
+    'node:backend-federation:generate',
+    'node:proof',
+    'performance:readiness',
+    'bridge:check'
+]);
+function mergeAggregateCheckScript(consumer, framework) {
+    const frameworkSegments = splitScriptSegments(framework);
+    const consumerExtras = splitScriptSegments(consumer).filter((segment)=>!FRAMEWORK_CHECK_TARGETS.has(scriptSegmentTarget(segment)));
+    return [
+        ...consumerExtras,
+        ...frameworkSegments
+    ].join(' && ');
+}
+function rewriteMigratedScriptReferences(scripts) {
+    let changed = false;
+    const pattern = new RegExp(`(scripts/(?:${migratedWorkspaceScriptBasenames.join('|')}))\\.mjs`, 'gu');
+    for (const [name, value] of Object.entries(scripts)){
+        if ('string' != typeof value) continue;
+        const next = value.replace(pattern, '$1.mts');
+        if (next !== value) {
+            scripts[name] = next;
+            changed = true;
+        }
+    }
+    return changed;
+}
 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 shellOnly = options.shellOnly ?? false;
     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;
+    const isRootPackage = 'package.json' === options.relativePackageFile;
+    const expectedScripts = isRootPackage ? createWorkspaceRootPackageScripts(apps.filter((candidate)=>'shell' !== candidate.kind)) : app ? createWorkspaceAppPackageScripts(app) : void 0;
+    if (expectedScripts) for (const [name, value] of Object.entries(expectedScripts)){
+        if (isRootPackage && shellOnly && SHELL_ONLY_OMITTED_ROOT_SCRIPTS.includes(name)) {
+            if (name in scripts) {
+                delete scripts[name];
+                changed = true;
+            }
+            continue;
+        }
+        const nextValue = 'check' === name && 'string' == typeof scripts[name] ? mergeAggregateCheckScript(scripts[name], value) : value;
+        if (scripts[name] !== nextValue) {
+            scripts[name] = nextValue;
             changed = true;
         }
     }
+    if (rewriteMigratedScriptReferences(scripts)) changed = true;
     const build = scripts.build;
     if ('string' == typeof build) {
         const nextBuild = removeStaleBackendFederationCommandSegments(build);
@@ -653,6 +705,7 @@ function updateUltramodernConfig(io, config, packageSource) {
             aliasPackageNamePrefix: packageSource.aliasPackageNamePrefix
         } : {}
     };
+    if (config.generator && 'object' == typeof config.generator && !Array.isArray(config.generator) && 'string' == typeof config.generator.version) config.generator.version = packageSource.modernPackageVersion;
     for (const app of config.topology?.apps ?? [])if (app && 'object' == typeof app && !Array.isArray(app)) normalizeStrictEffectApiMetadata(app);
     writeJsonFile(io, configPath, config);
 }
@@ -882,14 +935,27 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
     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 {
+    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 {
         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);
+    for (const artifact of migratedWorkspaceScriptArtifacts({
+        shellOnly
+    })){
+        if (artifact.legacyPath) io.remove(node_path.join(io.workspaceRoot, artifact.legacyPath));
+        io.write(node_path.join(io.workspaceRoot, artifact.relativePath), artifact.content);
+    }
     updateGeneratedBuildIdentityModules(io, migrated);
     updateGeneratedTypeScriptSurfaces(io, migrated);
     updateGeneratedModernConfigs(io, migrated);
@@ -907,7 +973,8 @@ workspaces skip the backend-federation and Zerops runtime stages. Pass
         updateGeneratedToolingDependencies(packageJson);
         updateGeneratedPackageScripts(packageJson, {
             relativePackageFile,
-            apps: migratedApps
+            apps: migratedApps,
+            shellOnly
         });
         writeJsonFile(io, packageFile, packageJson);
     }
@@ -1046,9 +1113,23 @@ for (const target of targets) {
     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}\`);
+    // 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;
+    }
   }
 }
 

package/dist/esm-node/ultramodern-workspace/module-federation.js

@@ -63,6 +63,15 @@ const zephyrEnabled = process.env['ULTRAMODERN_ZEPHYR'] !== 'false';
 const cloudflareDeployEnabled =
   process.env['MODERNJS_DEPLOY'] === 'cloudflare';
 
+const parsedZephyrTimeoutMs = Number.parseInt(
+  process.env['ULTRAMODERN_ZEPHYR_TIMEOUT_MS'] ?? '',
+  10,
+);
+const zephyrTimeoutMs =
+  Number.isFinite(parsedZephyrTimeoutMs) && parsedZephyrTimeoutMs > 0
+    ? parsedZephyrTimeoutMs
+    : 45000;
+
 const zephyrWarn = (error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);
   console.warn(
@@ -85,10 +94,27 @@ const zephyrRspackPlugin = () => ({
     }
     api.modifyRspackConfig(config => {
       try {
-        return Promise.resolve(withZephyrRspack()(config)).catch(error => {
-          zephyrWarn(error);
-          return config;
+        // Zephyr can not only throw/reject but also hang on a stalled network
+        // call, wedging the whole build. Race it against a watchdog so a hang
+        // degrades to an unmodified config instead of blocking indefinitely.
+        const zephyrConfig = Promise.resolve(withZephyrRspack()(config)).catch(
+          error => {
+            zephyrWarn(error);
+            return config;
+          },
+        );
+        const watchdog = new Promise<ZephyrRspackConfig>(resolve => {
+          const timer = setTimeout(() => {
+            zephyrWarn(
+              \`timed out after \${zephyrTimeoutMs}ms (override with ULTRAMODERN_ZEPHYR_TIMEOUT_MS)\`,
+            );
+            resolve(config);
+          }, zephyrTimeoutMs);
+          if (typeof timer.unref === 'function') {
+            timer.unref();
+          }
         });
+        return Promise.race([zephyrConfig, watchdog]);
       } catch (error) {
         zephyrWarn(error);
         return config;

package/dist/esm-node/ultramodern-workspace/workspace-script-plan.js

@@ -98,7 +98,7 @@ function createWorkspaceRootScriptPlan(remotes = [], options = {}) {
         zeropsMaterialize: "node ./scripts/materialize-zerops-runtime.mjs",
         contractCheck: rootToolingWrapperCommand('validate'),
         typecheck: options.typecheck ?? `${rootToolingWrapperCommand('typecheck')} --project tsconfig.json`,
-        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript} && pnpm performance:readiness${bridgeCheck}`
+        check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check${hasRemotes ? ` && pnpm ${backendFederationGenerateScript} && pnpm ${nodeProofScript}` : ''} && pnpm performance:readiness${bridgeCheck}`
     };
 }
 function createWorkspaceRootPackageScripts(remotes = [], options = {}) {

package/dist/esm-node/ultramodern-workspace/workspace-scripts.js

@@ -1,12 +1,13 @@
 import "node:module";
 import node_fs from "node:fs";
 import node_path from "node:path";
-import { readFileTemplate, renderFileTemplate, writeFileReplacing } from "./fs-io.js";
+import { readFileTemplate, renderFileTemplate, workspaceTemplateDir, writeFileReplacing } from "./fs-io.js";
 import { GENERATED_TOOLING_COMMANDS, generatedToolingCommands } from "./tooling-command-catalog.js";
 import { createWorkspaceValidationContract } from "./workspace-validation-contract.js";
+const singleQuoted = (value)=>`'${value.replace(/'/gu, "\\'")}'`;
 function createToolWrapperScript(command, extraArgs = []) {
-    const commandJson = JSON.stringify(command);
-    const extraArgsJson = JSON.stringify(extraArgs);
+    const commandLiteral = singleQuoted(command);
+    const extraArgsLiteral = `[${extraArgs.map(singleQuoted).join(', ')}]`;
     return `#!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -17,7 +18,7 @@ const forwardedArgs = process.argv.slice(2);
 const workspaceRoot =
   process.env.ULTRAMODERN_WORKSPACE_ROOT ??
   path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const ultramodernArgs = ['ultramodern', ${commandJson}, ...${extraArgsJson}, ...forwardedArgs];
+const ultramodernArgs = ['ultramodern', ${commandLiteral}, ...${extraArgsLiteral}, ...forwardedArgs];
 const result = createBin
   ? spawnSync(process.execPath, [createBin, ...ultramodernArgs], {
       env: { ...process.env, ULTRAMODERN_WORKSPACE_ROOT: workspaceRoot },
@@ -142,4 +143,52 @@ function writeGeneratedWorkspaceScripts(targetDir, _scope, _enableTailwind, _rem
     writeWorkspaceOwnedMtsScript(targetDir, 'bootstrap-agent-skills', createSkillsToolWrapperScript());
     migrateCopiedWorkspaceScriptToMts(targetDir, 'setup-agent-reference-repos');
 }
-export { createNodeBackendFederationProofScript, createPerformanceReadinessConfigScript, createWorkspaceApiBoundaryValidationScript, createWorkspaceI18nBoundaryValidationScript, createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, writeGeneratedToolWrapperScripts, writeGeneratedWorkspaceScripts };
+function createAgentReferenceReposSetupScript() {
+    return node_fs.readFileSync(node_path.join(workspaceTemplateDir, "scripts/setup-agent-reference-repos.mjs"), 'utf-8');
+}
+const BACKEND_FEDERATION_WRAPPER_IDS = new Set([
+    'backendFederationGenerate',
+    'backendFederationProof'
+]);
+function migratedWorkspaceScriptArtifacts(options) {
+    const artifacts = [
+        {
+            relativePath: "scripts/check-ultramodern-i18n-boundaries.mts",
+            content: createWorkspaceI18nBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-i18n-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/check-ultramodern-api-boundaries.mts",
+            content: createWorkspaceApiBoundaryValidationScript(),
+            legacyPath: "scripts/check-ultramodern-api-boundaries.mjs"
+        },
+        {
+            relativePath: "scripts/ultramodern-performance-readiness.config.mjs",
+            content: createPerformanceReadinessConfigScript()
+        },
+        {
+            relativePath: "scripts/bootstrap-agent-skills.mts",
+            content: createSkillsToolWrapperScript(),
+            legacyPath: "scripts/bootstrap-agent-skills.mjs"
+        },
+        {
+            relativePath: "scripts/setup-agent-reference-repos.mts",
+            content: createAgentReferenceReposSetupScript(),
+            legacyPath: "scripts/setup-agent-reference-repos.mjs"
+        }
+    ];
+    for (const command of generatedToolingCommands)if (!(options.shellOnly && BACKEND_FEDERATION_WRAPPER_IDS.has(command.id))) artifacts.push({
+        relativePath: command.wrapperPath,
+        content: createToolWrapperScript(command.command),
+        legacyPath: command.wrapperPath.replace(/\.mts$/u, '.mjs')
+    });
+    return artifacts;
+}
+const migratedWorkspaceScriptBasenames = [
+    'check-ultramodern-i18n-boundaries',
+    'check-ultramodern-api-boundaries',
+    'bootstrap-agent-skills',
+    'setup-agent-reference-repos',
+    ...generatedToolingCommands.map((command)=>command.wrapperName)
+];
+export { createAgentReferenceReposSetupScript, createNodeBackendFederationProofScript, createPerformanceReadinessConfigScript, createWorkspaceApiBoundaryValidationScript, createWorkspaceI18nBoundaryValidationScript, createWorkspaceValidationScript, createZeropsRuntimeMaterializationScript, migratedWorkspaceScriptArtifacts, migratedWorkspaceScriptBasenames, writeGeneratedToolWrapperScripts, writeGeneratedWorkspaceScripts };

package/dist/types/ultramodern-workspace/workspace-scripts.d.ts

@@ -7,3 +7,13 @@ export declare function createPerformanceReadinessConfigScript(): string;
 export declare function createNodeBackendFederationProofScript(): string;
 export declare function createZeropsRuntimeMaterializationScript(): string;
 export declare function writeGeneratedWorkspaceScripts(targetDir: string, _scope: string, _enableTailwind: boolean, _remotes?: WorkspaceApp[]): void;
+export declare function createAgentReferenceReposSetupScript(): string;
+export interface MigratedWorkspaceScriptArtifact {
+    relativePath: string;
+    content: string;
+    legacyPath?: string;
+}
+export declare function migratedWorkspaceScriptArtifacts(options: {
+    shellOnly: boolean;
+}): MigratedWorkspaceScriptArtifact[];
+export declare const migratedWorkspaceScriptBasenames: readonly string[];

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.5.0-ultramodern.29",
+  "version": "3.5.0-ultramodern.30",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/esm-node/index.js",
   "bin": {
@@ -77,7 +77,7 @@
     "@modern-js/codesmith": "2.6.9",
     "oxfmt": "0.56.0",
     "ultracite": "7.8.3",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.29"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.30"
   },
   "devDependencies": {
     "@rslib/core": "0.23.1",
@@ -99,6 +99,6 @@
     "test": "rm -rf dist && rslib build -c rslibconfig.mts && rstest --passWithNoTests"
   },
   "ultramodern": {
-    "frameworkVersion": "3.5.0-ultramodern.29"
+    "frameworkVersion": "3.5.0-ultramodern.30"
   }
 }

package/templates/workspace-scripts/validate-ultramodern-workspace.mjs.handlebars

@@ -8,6 +8,10 @@ const packageScope = '{{packageScope}}';
 const expectedNodeVersion = '{{nodeVersion}}';
 const tailwindEnabled = {{tailwindEnabledJson}};
 const fullStackVerticals = {{fullStackVerticalsJson}};
+// Backend-federation and Zerops runtime surfaces only exist when the workspace
+// exposes API-bearing verticals. Shell-only workspaces skip their
+// materialization during migrate, so the contract must not require them.
+const hasBackendSurfaces = fullStackVerticals.length > 0;
 const shellNamespace = {{shellNamespaceJson}};
 const oldRemotePaths = {{oldRemotePathsJson}};
 const expectedBuildScript = {{expectedBuildScriptJson}};
@@ -1688,11 +1692,11 @@ const requiredPaths = [
   'scripts/bootstrap-agent-skills.mts',
   'scripts/check-ultramodern-api-boundaries.mts',
   'scripts/check-ultramodern-i18n-boundaries.mts',
-  'scripts/generate-node-backend-federation.mts',
+  ...(hasBackendSurfaces ? ['scripts/generate-node-backend-federation.mts'] : []),
   'scripts/generate-public-surface-assets.mts',
   'scripts/generate-tanstack-routes.mts',
   'scripts/proof-cloudflare-version.mts',
-  'scripts/proof-node-backend-federation.mts',
+  ...(hasBackendSurfaces ? ['scripts/proof-node-backend-federation.mts'] : []),
   'scripts/setup-agent-reference-repos.mts',
   'scripts/ultramodern-performance-readiness.config.mjs',
   'scripts/ultramodern-performance-readiness.mts',
@@ -1923,54 +1927,70 @@ assert(rootPackage.scripts?.['contract:check'] === 'node ./scripts/validate-ultr
 assert(rootPackage.scripts?.['api:check'] === 'node ./scripts/check-ultramodern-api-boundaries.mts', 'Root must expose api:check');
 assert(rootPackage.scripts?.['i18n:boundaries'] === 'node ./scripts/check-ultramodern-i18n-boundaries.mts', 'Root must expose i18n:boundaries');
 assert(rootPackage.scripts?.['performance:readiness'] === 'node ./scripts/ultramodern-performance-readiness.mts', 'Root must expose default-on performance readiness diagnostics');
-assert(rootPackage.scripts?.['node:backend-federation:generate'] === 'node ./scripts/generate-node-backend-federation.mts', 'Root must expose local Node backend federation artifact generation');
-assert(rootPackage.scripts?.['zerops:materialize'] === 'node ./scripts/materialize-zerops-runtime.mjs', 'Root must expose Zerops runtime materialization script');
+if (hasBackendSurfaces) {
+  assert(rootPackage.scripts?.['node:backend-federation:generate'] === 'node ./scripts/generate-node-backend-federation.mts', 'Root must expose local Node backend federation artifact generation');
+  assert(rootPackage.scripts?.['zerops:materialize'] === 'node ./scripts/materialize-zerops-runtime.mjs', 'Root must expose Zerops runtime materialization script');
+  assert(
+    rootPackage.scripts?.['node:proof'] ===
+      'node ./scripts/proof-node-backend-federation.mts',
+    'Root must expose node:proof for backend federation Effect modules',
+  );
+}
 assertNotExists('scripts/generate-node-backend-federation.mjs');
 assertNotExists('scripts/proof-node-backend-federation.mjs');
 assertNotExists('scripts/verify-cloudflare-output.mjs');
 assertNotExists('scripts/generate-tanstack-routes.mjs');
 assert(
-  rootPackage.scripts?.['node:proof'] ===
-    'node ./scripts/proof-node-backend-federation.mts',
-  'Root must expose node:proof for backend federation Effect modules',
-);
-assert(
-  bridgeConfig
-    ? rootPackage.scripts?.check?.includes('pnpm api:check') &&
-        rootPackage.scripts.check.includes('pnpm node:proof') &&
-        rootPackage.scripts.check.endsWith('&& pnpm performance:readiness && pnpm bridge:check')
-    : rootPackage.scripts?.check?.includes('pnpm api:check') &&
-        rootPackage.scripts.check.includes('pnpm node:proof') &&
-        rootPackage.scripts.check.endsWith('&& pnpm performance:readiness'),
-  'Root check must run Node backend federation proof, default-on performance readiness diagnostics, and bridge gates when configured',
-);
-const zeropsYaml = readText('zerops.yaml');
-assert(zeropsYaml.includes('zerops:'), 'Zerops manifest must include zerops services');
-assert(zeropsYaml.includes('setup: shell-super-app'), 'Zerops manifest must include shell service');
-assert(zeropsYaml.includes('base: nodejs@26'), 'Zerops manifest must use generated Node runtime major');
-assert(zeropsYaml.includes('deployFiles:'), 'Zerops manifest must deploy package-pruned runtime directories');
-assert(
-  zeropsYaml.includes('start: cd .zerops/runtime/shell-super-app && npm run serve'),
-  'Zerops shell service must start from materialized runtime package',
-);
-assert(
-  zeropsYaml.includes('SHELL_SUPER_APP_PORT:') &&
-    zeropsYaml.includes('ULTRAMODERN_ZEROPS_SERVICE:'),
-  'Zerops manifest must expose service identity and ports',
+  rootPackage.scripts?.check?.includes('pnpm api:check') &&
+    (hasBackendSurfaces
+      ? rootPackage.scripts.check.includes('pnpm node:proof')
+      : !rootPackage.scripts.check.includes('pnpm node:proof')) &&
+    rootPackage.scripts.check.endsWith(
+      bridgeConfig
+        ? '&& pnpm performance:readiness && pnpm bridge:check'
+        : '&& pnpm performance:readiness',
+    ),
+  'Root check must run Node backend federation proof when backend surfaces exist, default-on performance readiness diagnostics, and bridge gates when configured',
 );
-for (const vertical of fullStackVerticals) {
-  assert(zeropsYaml.includes(`setup: ${vertical.id}`), `${vertical.id} must have a Zerops service`);
+if (hasBackendSurfaces) {
+  const zeropsYaml = readText('zerops.yaml');
+  assert(zeropsYaml.includes('zerops:'), 'Zerops manifest must include zerops services');
+  assert(zeropsYaml.includes('setup: shell-super-app'), 'Zerops manifest must include shell service');
+  assert(zeropsYaml.includes('base: nodejs@26'), 'Zerops manifest must use generated Node runtime major');
+  assert(zeropsYaml.includes('deployFiles:'), 'Zerops manifest must deploy package-pruned runtime directories');
   assert(
-    zeropsYaml.includes(`~/.local/bin/mise exec -- pnpm run zerops:materialize -- --app ${vertical.id} --package ${vertical.packageName} --package-dir ${vertical.path}`),
-    `${vertical.id} Zerops service must materialize its runtime package`,
+    zeropsYaml.includes('start: cd .zerops/runtime/shell-super-app && npm run serve'),
+    'Zerops shell service must start from materialized runtime package',
   );
   assert(
-    zeropsYaml.includes(`path: ${vertical.apiPrefix}/${vertical.stem}/readiness`),
-    `${vertical.id} BFF readiness path must use generated API prefix`,
+    zeropsYaml.includes('SHELL_SUPER_APP_PORT:') &&
+      zeropsYaml.includes('ULTRAMODERN_ZEROPS_SERVICE:'),
+    'Zerops manifest must expose service identity and ports',
   );
+  for (const vertical of fullStackVerticals) {
+    assert(zeropsYaml.includes(`setup: ${vertical.id}`), `${vertical.id} must have a Zerops service`);
+    assert(
+      zeropsYaml.includes(`~/.local/bin/mise exec -- pnpm run zerops:materialize -- --app ${vertical.id} --package ${vertical.packageName} --package-dir ${vertical.path}`),
+      `${vertical.id} Zerops service must materialize its runtime package`,
+    );
+    assert(
+      zeropsYaml.includes(`path: ${vertical.apiPrefix}/${vertical.stem}/readiness`),
+      `${vertical.id} BFF readiness path must use generated API prefix`,
+    );
+  }
+  const zeropsMaterializer = readText('scripts/materialize-zerops-runtime.mjs');
+  assert(zeropsMaterializer.includes("MODERNJS_DEPLOY: 'node'"), 'Zerops materializer must use Modern.js Node deploy target');
+  assert(/'deploy',\s*'--skip-build'/.test(zeropsMaterializer), 'Zerops materializer must pass --skip-build directly to Modern deploy');
+  assert(zeropsMaterializer.includes('normalizeRuntimePackageDependencies'), 'Zerops materializer must normalize generated Modern package aliases before installing dependencies');
+  assert(zeropsMaterializer.includes('officialPackageName'), 'Zerops materializer must add official Modern.js npm aliases for generated runtime imports');
+  assert(zeropsMaterializer.includes('installRuntimeDependencies'), 'Zerops materializer must install dependencies outside the workspace copy runtime node_modules');
+  assert(zeropsMaterializer.includes('copyWorkspacePackage'), 'Zerops materializer must preserve generated local workspace package dependencies');
+  assert(zeropsMaterializer.includes('makeWorkspacePackageRuntimeSafe'), 'Zerops materializer must rewrite copied workspace packages to runtime-safe JavaScript exports');
+  assert(zeropsMaterializer.includes("serve: runtimePackage.scripts?.serve ?? 'node index.js'"), 'Zerops materializer must preserve runtime serve script fallback');
+  assert(zeropsMaterializer.includes("'install', '--omit=dev'"), 'Zerops materializer must omit dev dependencies from runtime installs');
+  assert(zeropsMaterializer.includes("'--legacy-peer-deps'"), 'Zerops materializer must tolerate generated-workspace peer dependency ranges in npm runtime install');
 }
 const performanceReadinessConfig = readText('scripts/ultramodern-performance-readiness.config.mjs');
-const zeropsMaterializer = readText('scripts/materialize-zerops-runtime.mjs');
 const assertToolWrapper = (scriptPath, command) => {
   const source = readText(scriptPath);
   assert(source.includes('modern-js-create'), `${scriptPath} must delegate to modern-js-create`);
@@ -1981,16 +2001,6 @@ const assertToolWrapper = (scriptPath, command) => {
 assert(performanceReadinessConfig.includes('UltramodernPerformanceReadinessDiagnosticsConfig'), 'Performance readiness config must carry the typed opt-out surface');
 assert(performanceReadinessConfig.includes('enabled: true'), 'Performance readiness diagnostics must be default-on');
 assert(performanceReadinessConfig.includes("failOn: 'framework-invariant'"), 'Performance readiness diagnostics must only fail framework invariants by default');
-assert(zeropsMaterializer.includes("MODERNJS_DEPLOY: 'node'"), 'Zerops materializer must use Modern.js Node deploy target');
-assert(/'deploy',\s*'--skip-build'/.test(zeropsMaterializer), 'Zerops materializer must pass --skip-build directly to Modern deploy');
-assert(zeropsMaterializer.includes('normalizeRuntimePackageDependencies'), 'Zerops materializer must normalize generated Modern package aliases before installing dependencies');
-assert(zeropsMaterializer.includes('officialPackageName'), 'Zerops materializer must add official Modern.js npm aliases for generated runtime imports');
-assert(zeropsMaterializer.includes('installRuntimeDependencies'), 'Zerops materializer must install dependencies outside the workspace copy runtime node_modules');
-assert(zeropsMaterializer.includes('copyWorkspacePackage'), 'Zerops materializer must preserve generated local workspace package dependencies');
-assert(zeropsMaterializer.includes('makeWorkspacePackageRuntimeSafe'), 'Zerops materializer must rewrite copied workspace packages to runtime-safe JavaScript exports');
-assert(zeropsMaterializer.includes("serve: runtimePackage.scripts?.serve ?? 'node index.js'"), 'Zerops materializer must preserve runtime serve script fallback');
-assert(zeropsMaterializer.includes("'install', '--omit=dev'"), 'Zerops materializer must omit dev dependencies from runtime installs');
-assert(zeropsMaterializer.includes("'--legacy-peer-deps'"), 'Zerops materializer must tolerate generated-workspace peer dependency ranges in npm runtime install');
 assertToolWrapper('scripts/validate-ultramodern-workspace.mts', 'validate');
 assertToolWrapper('scripts/ultramodern-performance-readiness.mts', 'performance-readiness');
 const i18nBoundaryScript = readText('scripts/check-ultramodern-i18n-boundaries.mts');
@@ -2010,10 +2020,12 @@ assert(rootPackage.scripts?.postinstall === "oxfmt . '!repos/**' && node ./scrip
 assert(rootPackage.scripts?.['agents:refs:install'] === 'node ./scripts/setup-agent-reference-repos.mts', 'Root must expose agents:refs:install as the explicit reference repo installer');
 const agentSkillsBootstrap = readText('scripts/bootstrap-agent-skills.mts');
 assertToolWrapper('scripts/assert-mf-types.mts', 'mf-types');
-assertToolWrapper('scripts/generate-node-backend-federation.mts', 'backend-federation-generate');
+if (hasBackendSurfaces) {
+  assertToolWrapper('scripts/generate-node-backend-federation.mts', 'backend-federation-generate');
+  assertToolWrapper('scripts/proof-node-backend-federation.mts', 'backend-federation-proof');
+}
 assertToolWrapper('scripts/generate-public-surface-assets.mts', 'public-surface');
 assertToolWrapper('scripts/generate-tanstack-routes.mts', 'routes-generate');
-assertToolWrapper('scripts/proof-node-backend-federation.mts', 'backend-federation-proof');
 assertToolWrapper('scripts/proof-cloudflare-version.mts', 'cloudflare-proof');
 assertToolWrapper('scripts/verify-cloudflare-output.mts', 'cloudflare-output-verify');
 assertToolWrapper('scripts/migrate-strict-effect.mts', 'migrate-strict-effect');