@bleedingdev/modern-js-create 3.2.0-ultramodern.82 → 3.2.0-ultramodern.84

package/README.md

@@ -27,24 +27,20 @@ To initialize the empty directory you are already in, pass `.` explicitly:
 pnpm dlx @bleedingdev/modern-js-create .
 ```
 
-Create a full SuperApp workspace only when you need independently owned
-verticals:
+The default is the full UltraModern single-app setup. Create a SuperApp
+workspace explicitly when you need independently owned verticals:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
 ```
 
-The workspace is a full-stack reference, not a visual-only commerce boundary
-demo. It generates:
+The workspace starts shell-only so the first commit has no fake business
+domains to delete. It generates:
 
 - `apps/shell-super-app` as the Module Federation host and topology owner.
-- `verticals/explore` for discovery UI plus
-  `/explore-api/effect/explore/*`.
-- `verticals/decide` for product selection UI plus
-  `/decide-api/effect/decide/*`.
-- `verticals/checkout` for cart and checkout UI plus
-  `/checkout-api/effect/checkout/*`.
-- `packages/shared-design-tokens` as the shared CSS token owner.
+- `verticals/*` empty until you add a real domain with `--vertical`.
+- `packages/shared-*` placeholders for shared contracts, tokens, and API
+  support.
 - `.modernjs/ultramodern-generated-contract.json` with MF, Effect, i18n,
   federated CSS, Cloudflare, and Zephyr dependency metadata.
 
@@ -54,13 +50,14 @@ Validate the generated workspace before making application changes:
 cd my-super-app
 mise install
 pnpm install
-pnpm ultramodern:check
+pnpm check
 pnpm build
 ```
 
 ### Router Template
 
-TanStack Router is generated by default. To force the compatibility router:
+TanStack Router is generated by default. Choose React Router only as an explicit
+compatibility lane:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create my-app --router react-router
@@ -127,10 +124,10 @@ Use this decision table before adding a vertical:
 | Design tokens, primitives, generated clients, or domain-neutral utilities | Yes | Use an ordinary workspace package, not a vertical |
 | Feature composites or workflow state shared across verticals | No | Revisit ownership; do not hide it in shared code |
 
-The lower-level `--router`, `--workspace`, and `--sub` flags remain available
-for manual package scaffolding, but UltraModern vertical additions should use
-`--vertical` so paths, topology, Effect BFF contracts, and local overlays stay
-consistent.
+The lower-level `--router react-router`, `--workspace`, and `--sub` flags remain
+available for compatibility and local package scaffolding, but UltraModern
+vertical additions should use `--vertical` so paths, topology, Effect BFF
+contracts, and local overlays stay consistent.
 
 See
 `docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`
@@ -141,14 +138,13 @@ UltraModern.js entrypoint. The lower-level `--ultramodern-*` flags remain
 available for release engineering and local package-source testing, but users
 should not need them for normal app creation.
 
-### Tractor Architecture Contracts
+### SuperApp Architecture Contracts
 
-The generated shell owns route assembly and policy. The generated Explore,
-Decide, and Checkout verticals own their own route subtree, MF exposes, Effect BFF
-contract, generated client, `localisedUrls`, locale JSON, CSS layer, and
-Cloudflare Worker output. The shell consumes vertical UI through MF manifests
-and vertical APIs through generated Effect clients exported by the vertical
-packages.
+The generated shell owns route assembly and policy. Each vertical added with
+`--vertical` owns its route subtree, MF exposes, Effect BFF contract, generated
+client, `localisedUrls`, locale JSON, CSS layer, and Cloudflare Worker output.
+The shell consumes vertical UI through MF manifests and vertical APIs through
+generated Effect clients exported by the vertical packages.
 
 Route localization is route-owned. Each app writes
 `src/routes/ultramodern-route-metadata` and passes
@@ -176,7 +172,7 @@ manifest markers in lockstep for the same vertical version.
 
 ### Cloudflare And Zephyr Proof
 
-Each generated app has:
+Each generated workspace app has:
 
 - `cloudflare:build`, `cloudflare:deploy`, `cloudflare:preview`, and
   `cloudflare:proof` scripts.
@@ -184,20 +180,33 @@ Each generated app has:
 - `zephyr:dependencies` for any consumed verticals.
 - `zephyr-rspack-plugin` wired through the generated Modern.js Rspack bridge.
 
-Public URL proof is intentionally separate from local build validation:
+Deploy first, then pass each deployed app's generated public URL env key into
+the proof step. Shell-only workspaces only need the shell URL; added verticals
+use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with hyphens converted
+to underscores and uppercased:
 
 ```bash
-ULTRAMODERN_PUBLIC_URL_EXPLORE=https://explore.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_DECIDE=https://decide.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_CHECKOUT=https://checkout.example.workers.dev \
+pnpm cloudflare:deploy
 ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
 pnpm cloudflare:proof -- --require-public-urls
 ```
 
-Live Zephyr switching proof requires Zephyr credentials and public runtime,
-manifest, and API URLs for v1 and v2 of Explore, Decide, and Checkout. Without
-public URLs and credentials, use dry-run evidence only; do not claim live
-Zephyr selection has been proven.
+Without public URLs and credentials, use local `pnpm check` and `pnpm build`
+evidence only; do not claim live Cloudflare or Zephyr selection has been
+proven.
+
+### Troubleshooting
+
+| Symptom | Current check | Owner |
+| --- | --- | --- |
+| Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
+| Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
+| Build failure | Run `pnpm check` before `pnpm build`; fix reported format, lint, type, skill, i18n, or generated-contract failures first. | Owning package or generated contract |
+| Missing public URL | Set the env key from `.modernjs/ultramodern-generated-contract.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
+| Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
+| Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |
+| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |
 
 ### Local Monorepo Testing
 
@@ -208,14 +217,14 @@ workspace protocol dependencies:
 pnpm dlx @bleedingdev/modern-js-create my-app --workspace
 ```
 
-For package-source validation of the full Tractor workspace, generate with the
+For package-source validation of the full SuperApp workspace, generate with the
 workspace package source, then run the generated contract gate:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create tractor-super-app --ultramodern-workspace --ultramodern-package-source workspace
-cd tractor-super-app
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace --ultramodern-package-source workspace
+cd my-super-app
 pnpm install
-pnpm ultramodern:check
+pnpm check
 ```
 
 ## Documentation

package/dist/index.js

@@ -465,12 +465,12 @@ const EN_LOCALE = {
         optionHelp: '  -h, --help     Display this help message',
         optionVersion: '  -v, --version  Display version information',
         optionLang: '  -l, --lang     Set the language (zh or en)',
-        optionRouter: '  -r, --router   Select router framework (react-router or tanstack)',
+        optionRouter: '  -r, --router   Select router framework (tanstack default; react-router is compatibility mode)',
         optionBff: '      --bff      Keep Effect BFF enabled (default for UltraModern apps)',
         optionBffRuntime: '      --bff-runtime Select BFF runtime (hono or effect)',
         optionTailwind: '      --no-tailwind Disable default Tailwind CSS v4 scaffold',
         optionWorkspace: '      --workspace Use workspace protocol for @modern-js dependencies (for local monorepo testing)',
-        optionUltramodernWorkspace: '      --ultramodern-workspace Generate an UltraModern SuperApp workspace (explicit opt-in; default is a simple app)',
+        optionUltramodernWorkspace: '      --ultramodern-workspace Generate an UltraModern SuperApp workspace (default is a full UltraModern single app)',
         optionUltramodernPackageSource: '      --ultramodern-package-source Select UltraModern package source (workspace or install; BleedingDev defaults to install aliases)',
         optionUltramodernPackageScope: '      --ultramodern-package-scope Publish scope for npm alias installs (for example bleedingdev)',
         optionUltramodernPackageNamePrefix: '      --ultramodern-package-name-prefix Prefix for npm alias package names (default: modern-js-)',
@@ -487,7 +487,7 @@ const EN_LOCALE = {
         example8: '  pnpm dlx @bleedingdev/modern-js-create my-app --workspace',
         example9: '  pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace',
         example10: '  pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind',
-        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router',
+        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router # compatibility mode',
         example12: '  pnpm dlx @bleedingdev/modern-js-create catalog --vertical',
         moreInfo: '📚 Learn more: https://modernjs.dev'
     },
@@ -523,12 +523,12 @@ const ZH_LOCALE = {
         optionHelp: '  -h, --help     显示帮助信息',
         optionVersion: '  -v, --version  显示版本信息',
         optionLang: '  -l, --lang     设置语言 (zh 或 en)',
-        optionRouter: '  -r, --router   选择路由框架 (react-router 或 tanstack)',
+        optionRouter: '  -r, --router   选择路由框架（默认 tanstack；react-router 为兼容模式）',
         optionBff: '      --bff      保持启用 Effect BFF（UltraModern 应用默认值）',
         optionBffRuntime: '      --bff-runtime 选择 BFF 运行时（hono 或 effect）',
         optionTailwind: '      --no-tailwind 禁用默认 Tailwind CSS v4 模板',
         optionWorkspace: '      --workspace 对 @modern-js 依赖使用 workspace 协议（用于本地 monorepo 联调）',
-        optionUltramodernWorkspace: '      --ultramodern-workspace 生成 UltraModern SuperApp 工作区（显式选择；默认创建简单应用）',
+        optionUltramodernWorkspace: '      --ultramodern-workspace 生成 UltraModern SuperApp 工作区（默认创建完整 UltraModern 单应用）',
         optionUltramodernPackageSource: '      --ultramodern-package-source 选择 UltraModern 依赖来源（workspace 或 install；BleedingDev 默认使用 install alias）',
         optionUltramodernPackageScope: '      --ultramodern-package-scope npm alias 安装使用的发布 scope（例如 bleedingdev）',
         optionUltramodernPackageNamePrefix: '      --ultramodern-package-name-prefix npm alias 包名前缀（默认：modern-js-）',
@@ -545,7 +545,7 @@ const ZH_LOCALE = {
         example8: '  pnpm dlx @bleedingdev/modern-js-create my-app --workspace',
         example9: '  pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace',
         example10: '  pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind',
-        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router',
+        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router # 兼容模式',
         example12: '  pnpm dlx @bleedingdev/modern-js-create catalog --vertical',
         moreInfo: '📚 更多信息: https://modernjs.dev'
     },
@@ -619,6 +619,19 @@ function sortJsonValue(value) {
     return value;
 }
 const ULTRAMODERN_WORKSPACE_FLAG = '--ultramodern-workspace';
+const FIRST_VERTICAL_PORT = 4101;
+const TAILWIND_PREFIX_DIGIT_WORDS = [
+    'zero',
+    'one',
+    'two',
+    'three',
+    'four',
+    'five',
+    'six',
+    'seven',
+    'eight',
+    'nine'
+];
 function isRecord(value) {
     return null !== value && 'object' == typeof value && !Array.isArray(value);
 }
@@ -1115,6 +1128,7 @@ function createTsConfigBase() {
             verbatimModuleSyntax: true,
             strict: true,
             noEmit: true,
+            allowImportingTsExtensions: true,
             allowJs: true,
             esModuleInterop: true,
             noUncheckedIndexedAccess: true,
@@ -1228,6 +1242,7 @@ function createAppModernConfig(scope, app) {
     const bffImport = appHasEffectApi(app) ? "import { bffPlugin } from '@modern-js/plugin-bff';\n" : '';
     const bffConfig = appHasEffectApi(app) ? `      bff: {
         effect: {
+          entry: './api/effect/index',
           openapi: {
             path: '/openapi.json',
           },
@@ -1532,6 +1547,9 @@ const reactDomVersion = (require('react-dom/package.json') as { version: string
 
 ${createModuleFederationRemoteUrlHelpers(shellHost, remotes)}
 export default createModuleFederationConfig({
+  bridge: {
+    enableBridgeRouter: false,
+  },
   dev: {
     disableDynamicRemoteTypeHints: true,
   },
@@ -1587,6 +1605,9 @@ const reactDomVersion = (require('react-dom/package.json') as { version: string
 
 ${createModuleFederationRemoteUrlHelpers(app, remotes)}
 export default createModuleFederationConfig({
+  bridge: {
+    enableBridgeRouter: false,
+  },
   dev: {
     disableDynamicRemoteTypeHints: true,
   },
@@ -1910,9 +1931,9 @@ function createCssTokenImport(scope) {
     return `@import '${ultramodern_workspace_packageName(scope, 'shared-design-tokens')}/tokens.css';\n`;
 }
 function createTailwindPrefix(raw) {
-    const prefix = raw.toLowerCase().replace(/[^a-z]/gu, '');
-    if (!prefix) throw new Error(`Cannot derive a Tailwind prefix from ${raw}`);
-    return prefix;
+    const normalized = raw.toLowerCase().replace(/[^a-z0-9]/gu, '');
+    if (!normalized) throw new Error(`Cannot derive a Tailwind prefix from ${raw}`);
+    return normalized.replace(/[0-9]/gu, (digit)=>TAILWIND_PREFIX_DIGIT_WORDS[Number(digit)]);
 }
 function tailwindPrefixForApp(app) {
     if ('shell' === app.kind) return 'shell';
@@ -2350,24 +2371,16 @@ function createShellRemoteComponents(scope, remotes = []) {
         const componentName = `${toPascalCase(remote.id)}Widget`;
         return `const ${componentName} = createHydratedRemote(${componentName}Server, '${remoteDependencyAlias(remote)}/Widget');`;
     }).join('\n');
-    const showcaseItems = widgetRemotes.map((remote)=>{
-        const componentName = `${toPascalCase(remote.id)}Widget`;
-        return `          <${componentName} key="${remote.id}" />`;
-    }).join('\n');
-    const remoteCount = String(widgetRemotes.length);
-    return `import { createLazyComponent } from '@module-federation/bridge-react';
+    const federationImports = widgetRemotes.length > 0 ? `import { createLazyComponent } from '@module-federation/bridge-react';
 import { getInstance, loadRemote } from '@module-federation/modern-js-v3/runtime';
 import { Suspense, useEffect, useMemo, useState } from 'react';
 import type { ComponentType } from 'react';
-import { I18nLink, useModernI18n } from '@modern-js/plugin-i18n/runtime';
 ${serverImports}
-
-interface RemoteComponentModule {
+` : '';
+    const federationHelpers = widgetRemotes.length > 0 ? `interface RemoteComponentModule {
   default: ComponentType;
 }
 
-const widgetCount = Number('${remoteCount}');
-
 const loadRemoteComponent = (specifier: string) =>
   loadRemote<RemoteComponentModule>(specifier) as Promise<RemoteComponentModule>;
 
@@ -2414,10 +2427,20 @@ const createHydratedRemote =
       </Suspense>
     );
   };
+` : '';
+    const showcaseItems = widgetRemotes.map((remote)=>{
+        const componentName = `${toPascalCase(remote.id)}Widget`;
+        return `          <${componentName} key="${remote.id}" />`;
+    }).join('\n');
+    const remoteCount = String(widgetRemotes.length);
+    return `${federationImports}import { I18nLink, useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+	const widgetCount = Number('${remoteCount}');
 
-${hydratedExports}
+	${federationHelpers}
+	${hydratedExports}
 
-export const Header = () => {
+	export const Header = () => {
   const { i18nInstance } = useModernI18n();
   const t = i18nInstance['t'].bind(i18nInstance);
 
@@ -3442,7 +3465,7 @@ function createEffectServiceEntry(scope, service, contractImportPath = ultramode
   HttpApiBuilder,
   Layer,
 } from '@modern-js/plugin-bff/effect-edge';
-import { ultramodernApiMarker } from '../../src/ultramodern-build';
+import { ultramodernApiMarker } from '../../src/ultramodern-build.ts';
 import {
   ${apiExport},
   ${groupName}OperationContexts,
@@ -4685,6 +4708,7 @@ function createWorkspaceValidationScript(scope, enableTailwind, remotes = []) {
             mfName: remote.mfName,
             apiPrefix: remote.effectApi.prefix,
             tailwindPrefix: tailwindPrefixForApp(remote),
+            zephyrAlias: remoteDependencyAlias(remote),
             packageName: ultramodern_workspace_packageName(scope, remote.packageSuffix),
             exposes: Object.keys(remote.exposes ?? {}),
             componentPaths: Object.keys(remote.exposes ?? {}).map((expose)=>remoteComponentOutputPath(remote, expose)).filter((componentPath)=>Boolean(componentPath)),
@@ -4873,7 +4897,7 @@ assert(generatedContract.cssFederation?.sharedDesignTokens?.ssr?.firstPaintRequi
 const shellPackage = readJson('apps/shell-super-app/package.json');
 const expectedZephyrDependencies = Object.fromEntries(
   fullStackVerticals.map(vertical => [
-    vertical.domain,
+    vertical.zephyrAlias,
     \`\${vertical.packageName}@workspace:*\`,
   ]),
 );
@@ -4917,7 +4941,7 @@ for (const vertical of fullStackVerticals) {
     fullStackVerticals
       .filter(candidate => vertical.verticalRefs.includes(candidate.id))
       .map(candidate => [
-        candidate.domain,
+        candidate.zephyrAlias,
         \`\${candidate.packageName}@workspace:*\`,
       ]),
   );
@@ -4960,7 +4984,7 @@ for (const vertical of fullStackVerticals) {
   assert(contractEntry?.styling?.federation?.owner?.id === vertical.id, \`\${vertical.id} CSS federation owner is missing\`);
   assert(contractEntry?.styling?.federation?.role === 'vertical-css', \`\${vertical.id} must own only vertical CSS\`);
   assert(contractEntry?.styling?.federation?.rootSelector === \`[data-app-id="\${vertical.id}"]\`, \`\${vertical.id} CSS root selector is incorrect\`);
-  assert(contractEntry?.styling?.federation?.classPrefix === \`\${vertical.domain}:\`, \`\${vertical.id} CSS class prefix is incorrect\`);
+  assert(contractEntry?.styling?.federation?.classPrefix === \`\${vertical.tailwindPrefix}:\`, \`\${vertical.id} CSS class prefix is incorrect\`);
   assert(contractEntry?.styling?.federation?.layers?.owned?.includes(\`ultramodern-vertical-\${vertical.domain}\`), \`\${vertical.id} vertical CSS layer is missing\`);
   assert(!contractEntry?.styling?.federation?.layers?.owned?.includes('ultramodern-shell-base'), \`\${vertical.id} must not own shell base CSS\`);
   assert(contractEntry?.styling?.federation?.entrypoints?.federationEntry === 'src/federation-entry.tsx', \`\${vertical.id} CSS contract must include federation entry\`);
@@ -5364,7 +5388,7 @@ function writeApp(targetDir, scope, app, packageSource, enableTailwind, remotes
     }
     if (appHasEffectApi(resolvedApp)) {
         writeFile(targetDir, `${resolvedApp.directory}/shared/effect/api.ts`, createEffectSharedApi(resolvedApp));
-        writeFile(targetDir, `${resolvedApp.directory}/api/effect/index.ts`, createEffectServiceEntry(scope, resolvedApp, '../../shared/effect/api'));
+        writeFile(targetDir, `${resolvedApp.directory}/api/effect/index.ts`, createEffectServiceEntry(scope, resolvedApp, '../../shared/effect/api.ts'));
         writeFile(targetDir, `${resolvedApp.directory}/src/effect/${resolvedApp.effectApi.stem}-client.ts`, createEffectClient(resolvedApp, '../../shared/effect/api'));
     }
     if ('vertical' === resolvedApp.kind) {
@@ -5454,7 +5478,7 @@ function assertValidVerticalName(name) {
 }
 function nextAvailablePort(ports) {
     const numericPorts = Object.values(ports).filter((value)=>'number' == typeof value && Number.isFinite(value));
-    return Math.max(3030, ...numericPorts) + 1;
+    return Math.max(FIRST_VERTICAL_PORT - 1, ...numericPorts) + 1;
 }
 function assertCanCreate(workspaceRoot, relativePath) {
     if (node_fs.existsSync(node_path.join(workspaceRoot, relativePath))) throw new Error(`Refusing to overwrite existing path: ${relativePath}`);

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.82",
+  "version": "3.2.0-ultramodern.84",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {
@@ -41,7 +41,7 @@
     "@types/node": "^25.9.1",
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "tsx": "^4.22.3",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.82"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.84"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -54,6 +54,6 @@
     "start": "node ./dist/index.js"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.82"
+    "frameworkVersion": "3.2.0-ultramodern.84"
   }
 }

package/template/AGENTS.md

@@ -10,7 +10,7 @@ This project is generated for Codex-first UltraModern.js work.
 - `pnpm i18n:check` rejects hardcoded user-visible JSX text.
 - `pnpm ultramodern:check` verifies the generated contract.
 - Generated Codex stop hooks and subagent-stop hooks run `pnpm format && pnpm lint:fix && pnpm ultramodern:check`.
-- `postinstall` installs `lefthook` when the app is inside a Git worktree. Generated `lefthook.yml` runs `pnpm format && pnpm lint:fix && pnpm ultramodern:check` on pre-commit; pre-push runs `pnpm ultramodern:check`.
+- `postinstall` formats the generated tree, installs private orchestration skills when available, initializes a Git repository when needed, and installs `lefthook`. Generated `lefthook.yml` runs `pnpm format && pnpm lint:fix && pnpm ultramodern:check` on pre-commit; pre-push runs `pnpm ultramodern:check`.
 
 ## Internationalization
 

package/template/oxfmt.config.ts

@@ -3,6 +3,13 @@ import ultracite from 'ultracite/oxfmt';
 
 export default defineConfig({
   extends: [ultracite],
-  ignorePatterns: ['dist', 'node_modules', '.modern', '.modernjs', '**/routeTree.gen.ts'],
+  ignorePatterns: [
+    '.agents',
+    'dist',
+    'node_modules',
+    '.modern',
+    '.modernjs',
+    '**/routeTree.gen.ts',
+  ],
   singleQuote: true,
 });

package/template/oxlint.config.ts

@@ -8,5 +8,12 @@ export default defineConfig({
     node: true,
   },
   extends: [core, react],
-  ignorePatterns: ['dist', 'node_modules', '.modern', '.modernjs', '**/routeTree.gen.ts'],
+  ignorePatterns: [
+    '.agents',
+    'dist',
+    'node_modules',
+    '.modern',
+    '.modernjs',
+    '**/routeTree.gen.ts',
+  ],
 });

package/template/package.json.handlebars

@@ -15,7 +15,7 @@
 {{#unless isSubproject}}
     "skills:install": "node ./scripts/bootstrap-agent-skills.mjs",
     "skills:check": "node ./scripts/bootstrap-agent-skills.mjs --check",
-    "postinstall": "node ./scripts/bootstrap-agent-skills.mjs && (git rev-parse --is-inside-work-tree >/dev/null 2>&1 && lefthook install || true)",
+    "postinstall": "oxfmt . && node ./scripts/bootstrap-agent-skills.mjs",
 {{/unless}}
     "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck && pnpm i18n:check && pnpm test{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
     "format": "oxfmt .",
@@ -41,7 +41,7 @@
     "@modern-js/app-tools": "{{appToolsVersion}}",
 {{#if enableBff}}    "@modern-js/plugin-bff": "{{pluginBffVersion}}",
 {{/if}}    "@modern-js/tsconfig": "{{tsconfigVersion}}",
-    "@rstest/core": "0.10.2",
+    "@rstest/core": "0.10.3",
 {{#if enableTailwind}}
     "@tailwindcss/postcss": "^{{tailwindPostcssVersion}}",
 {{/if}}

package/template/pnpm-workspace.yaml

@@ -1,6 +1,8 @@
 minimumReleaseAge: 1440
 minimumReleaseAgeStrict: true
 minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
 trustPolicy: no-downgrade
 trustPolicyIgnoreAfter: 1440
 blockExoticSubdeps: true
@@ -17,3 +19,11 @@ allowBuilds:
   msgpackr-extract: true
   sharp: true
   workerd: true
+onlyBuiltDependencies:
+  - '@swc/core'
+  - core-js
+  - esbuild
+  - lefthook
+  - msgpackr-extract
+  - sharp
+  - workerd

package/template/rstest.config.mts

@@ -1,7 +1,5 @@
-import { withModernConfig } from '@modern-js/adapter-rstest';
 import { defineConfig } from '@rstest/core';
 
 export default defineConfig({
-  extends: withModernConfig(),
-  testEnvironment: 'happy-dom',
+  testEnvironment: 'node',
 });

package/template/scripts/bootstrap-agent-skills.mjs

@@ -17,6 +17,76 @@ const run = (command, args, options = {}) =>
     stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
   });
 
+const commandExists = (command) => {
+  try {
+    run(command, ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const runShell = (script) =>
+  run('sh', ['-lc', script], {
+    stdio: 'inherit',
+  });
+
+const installGit = () => {
+  if (commandExists('git')) {
+    return;
+  }
+
+  if (commandExists('brew')) {
+    run('brew', ['install', 'git'], { stdio: 'inherit' });
+  } else if (process.platform === 'linux' && commandExists('apt-get')) {
+    const sudo = typeof process.getuid === 'function' && process.getuid() === 0 ? '' : 'sudo ';
+    runShell(`${sudo}apt-get update && ${sudo}apt-get install -y git`);
+  } else if (process.platform === 'linux' && commandExists('dnf')) {
+    const sudo = typeof process.getuid === 'function' && process.getuid() === 0 ? '' : 'sudo ';
+    runShell(`${sudo}dnf install -y git`);
+  } else if (process.platform === 'linux' && commandExists('yum')) {
+    const sudo = typeof process.getuid === 'function' && process.getuid() === 0 ? '' : 'sudo ';
+    runShell(`${sudo}yum install -y git`);
+  } else if (process.platform === 'linux' && commandExists('apk')) {
+    runShell('apk add --no-cache git');
+  }
+
+  if (!commandExists('git')) {
+    throw new Error(
+      'Git is required for UltraModern setup. Install git and run pnpm skills:install again.',
+    );
+  }
+};
+
+const isInsideGitWorkTree = () => {
+  try {
+    return run('git', ['rev-parse', '--is-inside-work-tree']).trim() === 'true';
+  } catch {
+    return false;
+  }
+};
+
+const initializeGitRepository = () => {
+  if (isInsideGitWorkTree()) {
+    return;
+  }
+
+  try {
+    run('git', ['init', '-b', 'main'], { stdio: 'inherit' });
+  } catch {
+    run('git', ['init'], { stdio: 'inherit' });
+    run('git', ['branch', '-M', 'main'], { stdio: 'inherit' });
+  }
+};
+
+const installLefthook = () => {
+  try {
+    run('lefthook', ['install'], { stdio: 'inherit' });
+  } catch (error) {
+    console.warn(`Unable to install lefthook hooks: ${error.message}`);
+  }
+};
+
 const removeTree = (dir) =>
   fs.rmSync(dir, {
     force: true,
@@ -98,6 +168,7 @@ if (checkOnly) {
 }
 
 fs.mkdirSync(installDir, { recursive: true });
+installGit();
 
 for (const source of [...requiredCloneSources, ...optionalCloneSources]) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
@@ -133,3 +204,6 @@ for (const source of [...requiredCloneSources, ...optionalCloneSources]) {
     removeTree(tempDir);
   }
 }
+
+initializeGitRepository();
+installLefthook();

package/template/scripts/check-i18n-strings.mjs

@@ -30,6 +30,13 @@ const collectFiles = (directory) => {
 };
 
 const lineNumberForIndex = (content, index) => content.slice(0, index).split('\n').length;
+const isCodeElementText = (content, index) => {
+  const tagStart = content.lastIndexOf('<', index);
+  if (tagStart === -1) {
+    return false;
+  }
+  return /^<code(?:\s|>)/u.test(content.slice(tagStart, index));
+};
 const isIgnoredLine = (content, index) => {
   const lineStart = content.lastIndexOf('\n', index) + 1;
   const lineEnd = content.indexOf('\n', index);
@@ -58,7 +65,11 @@ for (const filePath of scanRoots.flatMap(collectFiles)) {
 
   for (const match of content.matchAll(jsxTextPattern)) {
     const text = match[1].replaceAll(/\s+/gu, ' ').trim();
-    if (text && !isIgnoredLine(content, match.index ?? 0)) {
+    if (
+      text &&
+      !isIgnoredLine(content, match.index ?? 0) &&
+      !isCodeElementText(content, match.index ?? 0)
+    ) {
       violations.push({
         filePath,
         line: lineNumberForIndex(content, match.index ?? 0),

package/template/scripts/validate-ultramodern.mjs.handlebars

@@ -9,21 +9,19 @@ const packageSourcePath = path.resolve(
   '.modernjs/ultramodern-package-source.json',
 );
 const readPnpmConfig = (key) => {
-  const env = { ...process.env };
-  for (const envKey of Object.keys(env)) {
-    if (/^(?:npm|pnpm)_config_/i.test(envKey)) {
-      delete env[envKey];
-    }
-  }
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([envKey]) => !/^(?:npm|pnpm)_config_/iu.test(envKey),
+    ),
+  );
   const output = execFileSync('pnpm', ['config', 'get', key, '--json'], {
     cwd: process.cwd(),
-    env,
     encoding: 'utf-8',
+    env,
     stdio: ['ignore', 'pipe', 'pipe'],
   }).trim();
   return output ? JSON.parse(output) : undefined;
 };
-const isSubproject = {{isSubproject}};
 const enableTailwind = {{enableTailwind}};
 const expectedPnpmVersion = '{{pnpmVersion}}';
 const activePnpmVersion = execFileSync('pnpm', ['--version'], {
@@ -131,14 +129,13 @@ if (fs.existsSync(path.resolve(process.cwd(), 'src/routes/page.tsx'))) {
   process.exit(1);
 }
 
-if (!enableTailwind) {
-  if (
-    fs.existsSync(path.resolve(process.cwd(), 'postcss.config.mjs')) ||
-    fs.existsSync(path.resolve(process.cwd(), 'tailwind.config.ts'))
-  ) {
-    console.error('Tailwind config files must not be written when Tailwind is disabled');
-    process.exit(1);
-  }
+if (
+  !enableTailwind &&
+  (fs.existsSync(path.resolve(process.cwd(), 'postcss.config.mjs')) ||
+    fs.existsSync(path.resolve(process.cwd(), 'tailwind.config.ts')))
+) {
+  console.error('Tailwind config files must not be written when Tailwind is disabled');
+  process.exit(1);
 }
 
 {{#unless isSubproject}}
@@ -259,17 +256,19 @@ const skillsLock = JSON.parse(
 );
 {{/unless}}
 const requiredScripts = {
-  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
-  test: 'rstest run',
 {{#unless isSubproject}}
   format: 'oxfmt .',
   'format:check': 'oxfmt --check .',
+{{/unless}}
+  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
+{{#unless isSubproject}}
   lint: 'oxlint .',
   'lint:fix': 'oxlint . --fix',
+  postinstall: 'oxfmt . && node ./scripts/bootstrap-agent-skills.mjs',
   'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
   'skills:install': 'node ./scripts/bootstrap-agent-skills.mjs',
-  postinstall: 'node ./scripts/bootstrap-agent-skills.mjs && (git rev-parse --is-inside-work-tree >/dev/null 2>&1 && lefthook install || true)',
 {{/unless}}
+  test: 'rstest run',
 };
 
 for (const [scriptName, scriptCommand] of Object.entries(requiredScripts)) {
@@ -330,8 +329,11 @@ if (readPnpmConfig('minimumReleaseAgeIgnoreMissingTime') !== false) {
   console.error('pnpm minimumReleaseAgeIgnoreMissingTime must be false');
   process.exit(1);
 }
-if (readPnpmConfig('minimumReleaseAgeExclude') !== undefined) {
-  console.error('pnpm minimumReleaseAgeExclude must stay unset');
+if (
+  JSON.stringify(readPnpmConfig('minimumReleaseAgeExclude')) !==
+  JSON.stringify(['@bleedingdev/modern-js-*'])
+) {
+  console.error('pnpm minimumReleaseAgeExclude must allow just-published BleedingDev Modern cohorts only');
   process.exit(1);
 }
 if (readPnpmConfig('trustPolicy') !== 'no-downgrade') {
@@ -366,8 +368,11 @@ if (
   console.error('pnpm allowBuilds must approve only the generated app build dependencies');
   process.exit(1);
 }
-if (readPnpmConfig('onlyBuiltDependencies') !== undefined) {
-  console.error('pnpm onlyBuiltDependencies must not be set');
+if (
+  JSON.stringify(readPnpmConfig('onlyBuiltDependencies')) !==
+  JSON.stringify(['@swc/core', 'core-js', 'esbuild', 'lefthook', 'msgpackr-extract', 'sharp', 'workerd'])
+) {
+  console.error('pnpm onlyBuiltDependencies must approve only the generated app build dependencies');
   process.exit(1);
 }
 
@@ -420,6 +425,15 @@ if (typeof expectedModernSpecifier !== 'string' || expectedModernSpecifier.lengt
   console.error('Package source metadata must provide a Modern package specifier');
   process.exit(1);
 }
+if (
+  packageSource.strategy === 'install' &&
+  expectedModernSpecifier !== templateManifest.template?.version
+) {
+  console.error(
+    `Package source Modern specifier ${expectedModernSpecifier} must match template version ${templateManifest.template?.version}`,
+  );
+  process.exit(1);
+}
 
 const expectedModernDependency = (packageName) => {
   const alias = packageSource.modernPackages?.aliases?.[packageName];

package/template/src/routes/[lang]/page.tsx.handlebars

@@ -121,16 +121,12 @@ const Index = () => {
           <p className="name">{t('home.name')}</p>
         </div>
         <p className="description{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
-          {t('home.description.intro')} <code className="code">presetUltramodern(...)</code>{' '}
-          {/* i18n-ignore technical token */}
+          {t('home.description.intro')}{' '}
+          <code className="code">presetUltramodern(...)</code>{' '}
           {t('home.description.afterPreset')}{' '}
-          <code className="code">modern.config.ts</code>
-          {/* i18n-ignore technical token */}
-          {' '}
+          <code className="code">modern.config.ts</code>{' '}
           {t('home.description.afterConfig')}{' '}
-          <code className="code">pnpm run ultramodern:check</code>
-          {/* i18n-ignore technical token */}
-          {' '}
+          <code className="code">pnpm run ultramodern:check</code>{' '}
           {t('home.description.end')}
         </p>
 {{#if useEffectBff}}

package/template/tailwind.config.ts.handlebars

@@ -2,9 +2,9 @@
 
 export default {
   content: ['./src/**/*.{js,ts,jsx,tsx}'],
+  plugins: [],
   theme: {
     extend: {},
   },
-  plugins: [],
 } satisfies Config;
 {{/if}}

package/template-workspace/README.md.handlebars

@@ -28,7 +28,9 @@ Run the scaffold validator before adding business code and after every
 
 ```bash
 mise install
-pnpm ultramodern:check
+pnpm install
+pnpm check
+pnpm build
 ```
 
 By default, `pnpm install` also prepares read-only agent reference repositories
@@ -50,3 +52,28 @@ UltraModern.js runtime and tooling packages on `workspace:*` for monorepo
 development. To create a workspace that can install those packages outside the
 monorepo, generate with `--ultramodern-package-source install`; generated shared
 packages still use `workspace:*` because they are part of this workspace.
+
+## Cloudflare Proof
+
+Deploy the generated apps, then pass each deployed app's generated public URL
+env key into the proof step. A shell-only workspace only needs the shell URL;
+added verticals use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with
+hyphens converted to underscores and uppercased.
+
+```bash
+pnpm cloudflare:deploy
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+pnpm cloudflare:proof -- --require-public-urls
+```
+
+## Troubleshooting
+
+| Symptom | Current check | Owner |
+| --- | --- | --- |
+| Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
+| Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
+| Build failure | Run `pnpm check` before `pnpm build`; fix reported format, lint, type, skill, i18n, or generated-contract failures first. | Owning package or generated contract |
+| Missing public URL | Set the env key from `.modernjs/ultramodern-generated-contract.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
+| Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
+| Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |
+| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |

package/template-workspace/pnpm-workspace.yaml

@@ -3,7 +3,13 @@ packages:
   - verticals/*
   - packages/*
 
-minimumReleaseAge: 0
+minimumReleaseAge: 1440
+minimumReleaseAgeStrict: true
+minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
+trustPolicy: no-downgrade
+trustPolicyIgnoreAfter: 1440
 blockExoticSubdeps: true
 engineStrict: true
 pmOnFail: error