@bleedingdev/modern-js-create 3.4.0-ultramodern.8 → 3.5.0-ultramodern.0

package/template-workspace/.github/workflows/ultramodern-workspace-gates.yml.handlebars

@@ -34,6 +34,8 @@ jobs:
             command: pnpm skills:check
           - name: I18n Boundaries
             command: pnpm i18n:boundaries
+          - name: API Boundaries
+            command: pnpm api:check
           - name: Contract
             command: pnpm contract:check
           - name: Build

package/template-workspace/.gitignore.handlebars

@@ -2,4 +2,7 @@ node_modules/
 dist/
 build/
 .modernjs/cache/
+.modern-js/
+**/.modern-js/
 .modernjs/agent-reference-repos-tmp/
+.codex/reports/

package/template-workspace/AGENTS.md.handlebars

@@ -1,7 +1,7 @@
 # UltraModern Agent Contract
 
 This workspace is generated as an agent-ready UltraModern.js SuperApp shell.
-Agents should treat the files under `.agents/skills` as local project
+Codex should treat the files under `.codex/skills` as local project
 instructions, not optional reading.
 
 ## Quality Gates
@@ -19,7 +19,7 @@ baseline; do not reintroduce Corepack or older pnpm aliases.
 - `pnpm check` is a local convenience aggregate for the primitive gates.
 - Generated CI runs primitive gates as separate matrix jobs instead of calling `pnpm check`.
 - Generated Codex stop hooks and subagent-stop hooks run `pnpm format && pnpm lint:fix && pnpm check`.
-- `postinstall` formats the generated tree and installs `lefthook`. It never clones repositories or installs system packages; agent skill repos and reference repos are explicit opt-in steps (`pnpm skills:install`, `pnpm agents:refs:install`). Generated `lefthook.yml` runs separate format and lint-fix commands on pre-commit; pre-push runs read-only primitive gates in parallel.
+- `postinstall` formats the generated tree, installs/updates pinned Codex skills, and installs `lefthook`. It never installs system packages. Clone-backed public skills are attempted by default; offline clone failures are advisory. Reference repos remain an explicit `pnpm agents:refs:install` step. Generated `lefthook.yml` runs separate format and lint-fix commands on pre-commit; pre-push runs read-only primitive gates in parallel.
 
 ## Localized Routes
 
@@ -48,7 +48,13 @@ Use these skills when the task touches the matching subsystem:
 - `rstest-best-practices`: Rstest configuration, test writing, mocking, snapshots, coverage, and CI test behavior.
 - `mf`: Module Federation docs, Modern.js integration, DTS/type checks, shared dependency checks, runtime errors, and observability troubleshooting.
 
-The public `module-federation/agent-skills` repository is installed only when you explicitly run `pnpm skills:install` (or set `ULTRAMODERN_AGENT_SKILLS=1` before `pnpm install`). Postinstall never clones repositories. `pnpm skills:install` remains strict for required public skills. `pnpm skills:check` fails when a vendored skill is missing and warns when clone-installed skills such as `mf` have not been fetched yet.
+Skill bodies are lockfile-pinned in `.codex/skills-lock.json` and installed
+into the repo-owned `.codex/skills` directory by default. The installer updates
+only pinned skill directories and preserves unrelated user skills already
+present under `.codex/skills`. Set `ULTRAMODERN_SKIP_CODEX_SKILLS=1` or
+`ULTRAMODERN_CODEX_SKILLS=0` to opt out during install. `pnpm skills:check` is
+advisory when local skill bodies are missing so offline CI can still run the
+normal gate.
 
 ## Private Skills
 
@@ -58,7 +64,7 @@ ScriptedAlchemy/TechsioCZ skills are private and are cloned only when the curren
 pnpm skills:install
 ```
 
-The installer copies only the pinned private skills from `.agents/skills-lock.json`: `plan-graph`, `dag`, `subagent-graph`, `helm`, and `debugger-mode`.
+The installer copies only the pinned private skills from `.codex/skills-lock.json`: `plan-graph`, `dag`, `subagent-graph`, `helm`, and `debugger-mode`.
 
 ## Agent Reference Repositories
 
@@ -85,4 +91,4 @@ Agents may read files under `repos/` to understand upstream patterns, APIs, and
 
 ## Skill Provenance
 
-The vendored Rstack skills, public Module Federation skill, and private TechsioCZ skill set are pinned in `.agents/skills-lock.json`. Do not update, remove, or replace them casually. If a skill needs updating, update the lock file and run the affected primitive gate plus `pnpm check`.
+The Rstack skills, public Module Federation skill, and private TechsioCZ skill set are pinned in `.codex/skills-lock.json`. Do not update, remove, or replace them casually. If a skill needs updating, update the lock file and run the affected primitive gate plus `pnpm check`.

package/template-workspace/README.md.handlebars

@@ -80,11 +80,14 @@ UltraModern.js source lookup using squashed git subtrees) are an explicit
 opt-in step: run `pnpm agents:refs:install` when you want them. `pnpm install`
 never clones repositories.
 
-Vendored agent skills ship with the scaffold. Clone-installed skills (such as
-the Module Federation `mf` skill) are fetched only when you explicitly run
-`pnpm skills:install`, or when `ULTRAMODERN_AGENT_SKILLS=1` is set during
-`pnpm install`. `pnpm skills:check` warns about missing clone-installed skills
-without failing the gate.
+Codex skill bodies are lockfile-pinned in `.codex/skills-lock.json` and
+repo-owned under `.codex/skills`. `pnpm install` runs the bootstrap by default:
+vendored pinned skills are copied locally, clone-backed public skills are
+fetched when network access is available, and offline clone failures remain
+advisory. Existing unrelated `.codex/skills/*` directories are preserved. Set
+`ULTRAMODERN_SKIP_CODEX_SKILLS=1` or `ULTRAMODERN_CODEX_SKILLS=0` to opt out.
+`pnpm skills:check` is advisory when local skill bodies are missing so offline
+CI can still run the normal gate.
 
 The topology and ownership metadata are generated under `topology/`. The
 workspace also ships `.github/workflows/ultramodern-workspace-gates.yml` and
@@ -93,12 +96,12 @@ actions, frozen installs, StepSecurity audit-mode runner hardening, dependency
 dashboard review, one-day release age, grouped updates, and manual approval for
 major upgrades.
 
-Package source metadata is generated at
-`.modernjs/ultramodern-package-source.json`. The default strategy keeps
-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.
+Package source provenance is recorded in `.modernjs/ultramodern.json`. The
+default strategy keeps 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.
 
 ## Public URL Environment Variables
 
@@ -151,7 +154,7 @@ pnpm cloudflare:proof -- --require-public-urls
 | 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 the matching primitive gate (`pnpm lint`, `pnpm typecheck`, `pnpm i18n:boundaries`, `pnpm contract:check`) before `pnpm build`; fix the owning failure 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 |
+| Missing public URL | Set the app public URL env key recorded in `.modernjs/ultramodern.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/oxfmt.config.ts

@@ -5,6 +5,7 @@ export default defineConfig({
   extends: [ultracite],
   ignorePatterns: [
     '.agents',
+    '.codex/skills',
     '.output',
     '**/*.json',
     'dist',

package/template-workspace/oxlint.config.ts

@@ -10,6 +10,7 @@ export default defineConfig({
   extends: [core, react],
   ignorePatterns: [
     '.agents',
+    '.codex/skills',
     '.output',
     'dist',
     'node_modules',

package/template-workspace/patches/@tanstack__router-core@1.171.13.patch

@@ -0,0 +1,51 @@
+diff --git a/dist/cjs/load-matches.cjs b/dist/cjs/load-matches.cjs
+index c09976a80c2c112b7dac6f941e643c81eeaf8d52..ec5156d89e9c5924a9ec0c19aad79711124f9ff4 100644
+--- a/dist/cjs/load-matches.cjs
++++ b/dist/cjs/load-matches.cjs
+@@ -442,0 +443 @@
++					if (!match) return;
+@@ -472,0 +474 @@
++			if (!match) return inner.matches[index];
+@@ -487,0 +490 @@
++	if (!match) return inner.matches[index];
+@@ -503 +506 @@
+-		return inner.router.getMatch(matchId);
++		return inner.router.getMatch(matchId) ?? inner.matches[index];
+diff --git a/dist/esm/load-matches.js b/dist/esm/load-matches.js
+index bcea2e0d88d037a01b93bf36dd6e643f98028e83..57484bf2825dab47030a1d4f905b9fb2e6067310 100644
+--- a/dist/esm/load-matches.js
++++ b/dist/esm/load-matches.js
+@@ -442,0 +443 @@
++					if (!match) return;
+@@ -472,0 +474 @@
++			if (!match) return inner.matches[index];
+@@ -487,0 +490 @@
++	if (!match) return inner.matches[index];
+@@ -503 +506 @@
+-		return inner.router.getMatch(matchId);
++		return inner.router.getMatch(matchId) ?? inner.matches[index];
+diff --git a/src/load-matches.ts b/src/load-matches.ts
+index f901a0c97ddf0618dd83229ac260277b46e2676d..76674e01e89ac2cbaba4d776c2be3bf0e3fdb432 100644
+--- a/src/load-matches.ts
++++ b/src/load-matches.ts
+@@ -838 +838,4 @@
+-          const match = inner.router.getMatch(matchId)!
++          const match = inner.router.getMatch(matchId)
++          if (!match) {
++            return
++          }
+@@ -906 +909,4 @@
+-      const match = inner.router.getMatch(matchId)!
++      const match = inner.router.getMatch(matchId)
++      if (!match) {
++        return inner.matches[index]!
++      }
+@@ -936 +942,4 @@
+-  const match = inner.router.getMatch(matchId)!
++  const match = inner.router.getMatch(matchId)
++  if (!match) {
++    return inner.matches[index]!
++  }
+@@ -955 +964 @@
+-    return inner.router.getMatch(matchId)!
++    return inner.router.getMatch(matchId) ?? inner.matches[index]!

package/template-workspace/pnpm-workspace.yaml.handlebars

@@ -41,6 +41,7 @@ peerDependencyRules:
 
 overrides:
   '@tanstack/react-router': {{tanstackRouterVersion}}
+  '@tanstack/router-core': {{tanstackRouterCoreVersion}}
   node-fetch: '{{nodeFetchVersion}}'
 
 allowBuilds:
@@ -51,3 +52,6 @@ allowBuilds:
   msgpackr-extract: true
   sharp: true
   workerd: true
+
+patchedDependencies:
+  '@tanstack/router-core@{{tanstackRouterCoreVersion}}': patches/@tanstack__router-core@{{tanstackRouterCoreVersion}}.patch

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

@@ -2,19 +2,22 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const root = process.cwd();
-const lockPath = path.join(root, '.agents/skills-lock.json');
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const templateWorkspaceDir = path.resolve(scriptDir, '..');
+const vendoredSkillsDir = path.join(templateWorkspaceDir, '.codex/skills');
+const lockPath = path.join(root, '.codex/skills-lock.json');
 const checkOnly = process.argv.includes('--check');
-const force = process.argv.includes('--force');
 const postinstall = process.argv.includes('--postinstall');
 const truthy = value => /^(1|true|yes|on)$/i.test(String(value ?? ''));
 const falsy = value => /^(0|false|no|off)$/i.test(String(value ?? ''));
 const skipRequested =
-  truthy(process.env.ULTRAMODERN_SKIP_AGENT_SKILLS) ||
-  falsy(process.env.ULTRAMODERN_AGENT_SKILLS);
+  truthy(process.env.ULTRAMODERN_SKIP_CODEX_SKILLS) ||
+  falsy(process.env.ULTRAMODERN_CODEX_SKILLS);
 const cloneTimeoutMs = Number.parseInt(
-  process.env.ULTRAMODERN_AGENT_SKILLS_CLONE_TIMEOUT_MS ?? '60000',
+  process.env.ULTRAMODERN_CODEX_SKILLS_CLONE_TIMEOUT_MS ?? '60000',
   10,
 );
 
@@ -60,7 +63,7 @@ const requireGit = () => {
   }
 
   throw new Error(
-    'Git is required to install agent skills. Install git yourself (for example "brew install git" or "sudo apt-get install git") and run pnpm skills:install again. This script never installs system packages on your behalf.',
+    'Git is required to install clone-backed Codex skills. Install git yourself (for example "brew install git" or "sudo apt-get install git") and run pnpm skills:install again. This script never installs system packages on your behalf.',
   );
 };
 
@@ -172,31 +175,42 @@ const resolveSkillDir = (sourceRoot, skillName) => {
 };
 
 if (!fs.existsSync(lockPath)) {
-  console.error('Missing .agents/skills-lock.json');
+  console.error('Missing .codex/skills-lock.json');
   process.exit(1);
 }
 
 const lock = readJson(lockPath);
-const installDir = path.join(root, lock.installDir ?? '.agents/skills');
+const installDir = path.join(root, lock.installDir ?? '.codex/skills');
 const sources = lock.sources ?? [];
-const requiredCloneSources = sources.filter(
-  source => source.install === 'clone',
-);
+const vendoredSources = sources.filter(source => source.install === 'vendored');
+const cloneSources = sources.filter(source => source.install === 'clone');
 const optionalCloneSources = sources.filter(
   source => source.install === 'clone-if-authorized',
 );
-const cloneSourceSkillNames = new Set(
-  [...requiredCloneSources, ...optionalCloneSources].flatMap(source =>
-    (source.baseline ?? []).map(skill => skill.name),
+const explicitSourceSkillNames = new Set(
+  [...vendoredSources, ...cloneSources, ...optionalCloneSources].flatMap(
+    source => (source.baseline ?? []).map(skill => skill.name),
   ),
 );
-const vendoredRequiredSkills = (lock.baseline ?? []).filter(
-  skill => !cloneSourceSkillNames.has(skill.name),
-);
-const cloneOptIn = truthy(process.env.ULTRAMODERN_AGENT_SKILLS);
+const skillsForSource = source =>
+  source.baseline ??
+  (source.install === 'vendored'
+    ? (lock.baseline ?? []).filter(
+        skill => !explicitSourceSkillNames.has(skill.name),
+      )
+    : []);
+const lockedSkillNames = (lock.baseline ?? []).map(skill => skill.name);
+const installedSkillNames = () =>
+  lockedSkillNames.filter(skillName =>
+    fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
+  );
+const missingSkillNames = () =>
+  lockedSkillNames.filter(
+    skillName => !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
+  );
 
 if (skipRequested) {
-  const reason = 'agent skills bootstrap skipped by environment';
+  const reason = 'Codex skills bootstrap skipped by environment';
   if (checkOnly) {
     console.log(reason);
     process.exit(0);
@@ -207,80 +221,76 @@ if (skipRequested) {
 }
 
 if (checkOnly) {
-  const missingVendored = vendoredRequiredSkills
-    .map(skill => skill.name)
-    .filter(
-      skillName => !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
-    );
-  const missingCloneInstalled = [
-    ...requiredCloneSources,
-    ...optionalCloneSources,
-  ].flatMap(source =>
-    (source.baseline ?? [])
-      .map(skill => skill.name)
-      .filter(
-        skillName =>
-          !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
-      ),
-  );
-
-  if (missingVendored.length > 0) {
-    console.error(
-      `Required agent skills not installed: ${missingVendored.join(', ')}. Run pnpm skills:install.`,
-    );
-    process.exit(1);
-  }
-
-  if (missingCloneInstalled.length > 0) {
+  const missing = missingSkillNames();
+  const installed = installedSkillNames();
+  if (missing.length > 0) {
     console.log(
-      `Advisory: clone-installed agent skills are not present: ${missingCloneInstalled.join(', ')}. This is expected in CI, nested generated workspaces, and postinstall-only installs; run pnpm skills:install when you need those skills.`,
+      `Advisory: pinned Codex skills are not installed: ${missing.join(', ')}. This is expected in offline postinstall runs and fresh check-only CI; run pnpm skills:install when you need local skill bodies.`,
     );
   } else {
-    console.log('All pinned agent skills are installed.');
+    console.log('All pinned Codex skills are installed.');
+  }
+  if (installed.length > 0) {
+    console.log(`Installed Codex skills: ${installed.join(', ')}.`);
   }
   process.exit(0);
 }
 
-if (postinstall && !cloneOptIn) {
-  console.log(
-    'Skipping agent skill repository clones during postinstall. Run pnpm skills:install (or set ULTRAMODERN_AGENT_SKILLS=1 before installing) to fetch them.',
-  );
-  installLefthook();
-  process.exit(0);
+fs.mkdirSync(installDir, { recursive: true });
+
+const installSkillFromDir = (sourceSkillDir, skillName) => {
+  const targetSkillDir = path.join(installDir, skillName);
+  if (path.resolve(sourceSkillDir) === path.resolve(targetSkillDir)) {
+    console.log(`Pinned Codex skill ${skillName} is already present`);
+    return;
+  }
+  if (fs.existsSync(targetSkillDir)) {
+    removeTree(targetSkillDir);
+  }
+  fs.mkdirSync(path.dirname(targetSkillDir), { recursive: true });
+  fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
+  console.log(`Installed Codex skill ${skillName}`);
+};
+
+for (const source of vendoredSources) {
+  for (const skill of skillsForSource(source)) {
+    const sourceSkillDir = resolveSkillDir(vendoredSkillsDir, skill.name);
+    if (!sourceSkillDir) {
+      throw new Error(
+        `Vendored Codex skill ${skill.name} not found in ${vendoredSkillsDir}`,
+      );
+    }
+    installSkillFromDir(sourceSkillDir, skill.name);
+  }
 }
 
-fs.mkdirSync(installDir, { recursive: true });
-requireGit();
+const cloneInstallSources = postinstall
+  ? cloneSources
+  : [...cloneSources, ...optionalCloneSources];
 
-for (const source of [...requiredCloneSources, ...optionalCloneSources]) {
+for (const source of cloneInstallSources) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
   try {
     try {
+      requireGit();
       cloneSource(source, tempDir);
     } catch (error) {
       if (source.install === 'clone-if-authorized' || postinstall) {
-        console.warn(`Skipping ${source.repository}; ${error.message}`);
+        console.warn(
+          `Advisory: unable to install Codex skills from ${source.repository}; ${error.message}. Offline postinstall may continue. Run pnpm skills:install later when network access is available.`,
+        );
         continue;
       }
       throw error;
     }
-    for (const skill of source.baseline ?? []) {
+    for (const skill of skillsForSource(source)) {
       const sourceSkillDir = resolveSkillDir(tempDir, skill.name);
       if (!sourceSkillDir) {
         throw new Error(
           `Skill ${skill.name} not found in ${source.repository}`,
         );
       }
-      const targetSkillDir = path.join(installDir, skill.name);
-      if (fs.existsSync(targetSkillDir)) {
-        if (!force) {
-          console.log(`Skipping existing ${skill.name}`);
-          continue;
-        }
-        removeTree(targetSkillDir);
-      }
-      fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
-      console.log(`Installed ${skill.name}`);
+      installSkillFromDir(sourceSkillDir, skill.name);
     }
   } finally {
     removeTree(tempDir);

package/templates/workspace-scripts/assert-mf-types.mjs.handlebars

@@ -2,19 +2,62 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const root = process.cwd();
-const generatedContractPath = path.join(
-  root,
-  '.modernjs/ultramodern-generated-contract.json',
-);
-const generatedContract = fs.existsSync(generatedContractPath)
-  ? JSON.parse(fs.readFileSync(generatedContractPath, 'utf-8'))
-  : undefined;
+const compactConfigPath = path.join(root, '.modernjs/ultramodern.json');
 const defaultAppDirs = {{defaultAppDirsJson}};
 
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function normalizeRelativePath(value) {
+  return String(value ?? '').replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+}
+
+function readGeneratedContractView() {
+  if (fs.existsSync(compactConfigPath)) {
+    const compactConfig = readJson(compactConfigPath);
+    return {
+      sourcePath: compactConfigPath,
+      apps: Array.isArray(compactConfig.topology?.apps)
+        ? compactConfig.topology.apps.map(app => {
+            const moduleFederation =
+              app.moduleFederation && typeof app.moduleFederation === 'object'
+                ? app.moduleFederation
+                : {};
+            return {
+              id: String(app.id),
+              path:
+                typeof app.path === 'string'
+                  ? normalizeRelativePath(app.path)
+                  : '.',
+              moduleFederation: {
+                exposes: Array.isArray(moduleFederation.exposes)
+                  ? moduleFederation.exposes.filter(
+                      expose => typeof expose === 'string',
+                    )
+                  : [],
+                dts: {
+                  compilerInstance:
+                    moduleFederation.dts?.compilerInstance ?? 'tsgo',
+                  tsConfigPath:
+                    moduleFederation.dts?.tsConfigPath ??
+                    './tsconfig.mf-types.json',
+                },
+              },
+            };
+          })
+        : [],
+    };
+  }
+  throw new Error('Missing UltraModern config. Expected .modernjs/ultramodern.json.');
+}
+
+const generatedContract = readGeneratedContractView();
+
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h')) {
   process.stdout.write(`Usage:
-  node scripts/assert-mf-types.mjs [app-dir...]
+  node scripts/assert-mf-types.mts [app-dir...]
 
 Checks that every Module Federation remote with exposed modules emitted a non-empty dist/@mf-types.zip archive and uses the workspace TypeScript compiler.
 `);