@bleedingdev/modern-js-create 3.2.0-ultramodern.7 → 3.2.0-ultramodern.71

package/template-workspace/AGENTS.md

@@ -1,6 +1,28 @@
 # UltraModern Agent Contract
 
-This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents should treat the files under `.agents/skills` as local project instructions, not optional reading.
+This workspace is generated as an agent-ready UltraModern.js SuperApp shell.
+Agents should treat the files under `.agents/skills` as local project
+instructions, not optional reading.
+
+## Quality Gates
+
+- `pnpm lint` runs Oxlint with the Ultracite preset.
+- `pnpm format` runs oxfmt.
+- `pnpm typecheck` runs effect-tsgo as the TypeScript checker.
+- `pnpm check` runs formatting, linting, effect-tsgo, private-skill availability checks, and the generated workspace contract.
+- Generated Codex stop hooks and subagent-stop hooks run `pnpm format && pnpm lint:fix && pnpm check`.
+- `postinstall` formats the generated tree, installs agent skills and reference repos, then installs `lefthook` when the workspace is inside a Git worktree. Generated `lefthook.yml` runs `pnpm format && pnpm lint:fix && pnpm check` on pre-commit; pre-push runs `pnpm check`.
+
+## Localized Routes
+
+Generated apps keep locale-prefixed entry routes under `src/routes/[lang]`,
+static language links, and canonical plus `hreflang` metadata. A new workspace
+starts shell-only; `create <domain> --vertical` adds route-owned metadata,
+localized resources, and Effect BFF surfaces for that domain. Runtime i18n is
+not enabled in the starter because the current React 19 + Module Federation
+streaming SSR stack must render predictably first. Production builds fail unless
+`MODERN_PUBLIC_SITE_URL` is set per deployed app, so canonical URLs always use
+the production origin.
 
 ## Required Skill Baseline
 
@@ -13,16 +35,42 @@ Use these skills when the task touches the matching subsystem:
 - `rslib-best-practices`: Shared packages, generated libraries, declaration output, and Rslib configuration.
 - `rslib-modern-package`: Package contracts for shared libraries, exports, side effects, dependency placement, README, and release readiness.
 - `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 during `pnpm install` and `pnpm skills:install`. `pnpm skills:check` fails when the required public `mf` skill is missing.
+
+## Private Skills
+
+ScriptedAlchemy/TechsioCZ skills are private and are cloned only when the current developer is authorized for `TechsioCZ/skills`.
+
+```bash
+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`.
+
+## Agent Reference Repositories
+
+The workspace installs read-only source references under `repos/` by default during `pnpm install` using `git subtree add --squash`. These repositories are reference material for coding agents, not application source:
+
+- `repos/effect` from `Effect-TS/effect`.
+- `repos/ultramodern.js` from `BleedingDev/ultramodern.js`.
+
+Agents may read files under `repos/` to understand upstream patterns, APIs, and project conventions. Do not edit files under `repos/`, import from them, or make production code depend on them. To skip this setup, run installs with `ULTRAMODERN_SKIP_AGENT_REPOS=1`.
 
 ## Project Priorities
 
 - Keep `presetUltramodern` as the single preset.
-- Prefer Effect for BFF/service code.
+- Keep the initial workspace shell-only unless a user explicitly asks for a
+  starter vertical.
+- Use `create <domain> --vertical` as the growth path for real business
+  MicroVerticals.
+- Prefer Effect for BFF code.
 - Prefer TanStack Router for app routing.
-- Keep design-system code as a normal Micro Frontend or shared package, not a special core path.
+- Keep UI-kit or design-system code as ordinary vertical or shared package code, not a special core path.
 - Keep generated packages explicit and publishable: stable `exports`, correct declarations, small public APIs, and clear ownership metadata.
 - Do not add migration tooling or codemods unless the project owner explicitly asks for migration work.
 
 ## Skill Provenance
 
-The vendored Rstack skills 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 `pnpm ultramodern:check`.
+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 `pnpm check`.

package/template-workspace/README.md.handlebars

@@ -3,23 +3,46 @@
 Generated UltraModern SuperApp workspace.
 
 This workspace keeps `presetUltramodern(...)` as the single public
-UltraModern.js 3.0 SuperApp surface and scaffolds the canonical Micro Vertical
-starter topology:
+UltraModern.js 3.0 SuperApp surface and starts with an explicit shell:
 
-- `apps/shell-super-app` owns shell route assembly and remote manifest wiring.
-- `apps/remotes/remote-commerce` owns the commerce vertical remote.
-- `apps/remotes/remote-identity` owns the identity vertical remote.
-- `apps/remotes/remote-design-system` owns the horizontal design-system remote.
-- `services/service-recommendations-effect` owns the Effect BFF service.
-- `packages/shared-*` provide placeholders for cross-workspace contracts.
+- `apps/shell-super-app` owns shell route assembly, Module Federation host
+  wiring, shared SSR/i18n runtime setup, and the boundary debugger.
+- `packages/shared-*` provide placeholders for cross-workspace contracts,
+  design tokens, and Effect API sharing.
+- `verticals/*` is intentionally empty until a real business domain is added.
 
-Run the scaffold validator before adding business code:
+Add a full-stack MicroVertical when the product needs one:
 
 ```bash
+pnpm create modern@latest transportation --vertical
+pnpm create modern@latest payments --vertical
+```
+
+Each added vertical owns its UI/routes, browser-safe Module Federation exposes,
+localized route metadata, CSS prefix, Effect BFF handlers, local API contract,
+and typed client surface. Server handlers and Effect client/contract modules
+stay out of browser exposes.
+
+Run the scaffold validator before adding business code and after every
+`--vertical` mutation:
+
+```bash
+mise install
 pnpm ultramodern:check
 ```
 
-The topology and ownership metadata are generated under `topology/`.
+By default, `pnpm install` also prepares read-only agent reference repositories
+under `repos/` for Effect and UltraModern.js source lookup using squashed git
+subtrees. Disable this setup with
+`ULTRAMODERN_SKIP_AGENT_REPOS=1 pnpm install`, or rerun it
+explicitly with `pnpm agents:refs:install`.
+
+The topology and ownership metadata are generated under `topology/`. The
+workspace also ships `.github/workflows/ultramodern-workspace-gates.yml` and
+`.github/renovate.json` with read-only workflow permissions, commit-pinned
+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

package/template-workspace/lefthook.yml

@@ -0,0 +1,10 @@
+pre-commit:
+  commands:
+    fix-and-check:
+      run: pnpm format && pnpm lint:fix && pnpm check
+      stage_fixed: true
+
+pre-push:
+  commands:
+    check:
+      run: pnpm check

package/template-workspace/oxfmt.config.ts

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

package/template-workspace/oxlint.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'oxlint';
+import core from 'ultracite/oxlint/core';
+import react from 'ultracite/oxlint/react';
+
+export default defineConfig({
+  env: {
+    browser: true,
+    node: true,
+  },
+  extends: [core, react],
+  ignorePatterns: [
+    '.agents',
+    'dist',
+    'node_modules',
+    'repos/**',
+    '.modern',
+    '.modernjs',
+    '**/routeTree.gen.ts',
+  ],
+});

package/template-workspace/pnpm-workspace.yaml

@@ -1,19 +1,29 @@
 packages:
   - apps/*
-  - apps/remotes/*
-  - services/*
+  - verticals/*
   - packages/*
 
+minimumReleaseAge: 0
+blockExoticSubdeps: true
+engineStrict: true
+pmOnFail: error
+verifyDepsBeforeRun: error
+strictDepBuilds: true
+
+peerDependencyRules:
+  allowedVersions:
+    react: '>=19.0.0'
+    typescript: '>=6.0.0'
+
+overrides:
+  '@tanstack/react-router': 1.170.8
+  node-fetch: '^3.3.2'
+
 allowBuilds:
-  '@biomejs/biome': true
   '@swc/core': true
   core-js: true
   esbuild: true
+  lefthook: true
   msgpackr-extract: true
-
-onlyBuiltDependencies:
-  - '@biomejs/biome'
-  - '@swc/core'
-  - core-js
-  - esbuild
-  - msgpackr-extract
+  sharp: true
+  workerd: true

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

@@ -0,0 +1,163 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const root = process.cwd();
+const lockPath = path.join(root, '.agents/skills-lock.json');
+const checkOnly = process.argv.includes('--check');
+const force = process.argv.includes('--force');
+
+const readJson = filePath => JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+const run = (command, args, options = {}) =>
+  execFileSync(command, args, {
+    cwd: options.cwd ?? root,
+    encoding: 'utf-8',
+    stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
+  });
+
+const removeTree = dir =>
+  fs.rmSync(dir, {
+    force: true,
+    maxRetries: 5,
+    recursive: true,
+    retryDelay: 100,
+  });
+
+const cloneSource = (source, targetDir) => {
+  const repo = source.repository.replace(/^https:\/\/github.com\//u, '');
+  try {
+    run('gh', ['repo', 'clone', repo, targetDir, '--', '--depth', '1'], {
+      stdio: 'inherit',
+    });
+  } catch {
+    run('git', ['clone', '--depth', '1', source.repository, targetDir], {
+      stdio: 'inherit',
+    });
+  }
+  if (source.commit) {
+    try {
+      run('git', ['checkout', source.commit], {
+        cwd: targetDir,
+        stdio: 'inherit',
+      });
+    } catch {
+      run('git', ['fetch', '--depth', '1', 'origin', source.commit], {
+        cwd: targetDir,
+        stdio: 'inherit',
+      });
+      run('git', ['checkout', source.commit], {
+        cwd: targetDir,
+        stdio: 'inherit',
+      });
+    }
+  }
+};
+
+const resolveSkillDir = (sourceRoot, skillName) => {
+  const candidates = [
+    path.join(sourceRoot, skillName),
+    path.join(sourceRoot, 'skills', skillName),
+    path.join(sourceRoot, 'skills', 'engineering', skillName),
+    path.join(sourceRoot, 'skills', 'productivity', skillName),
+  ];
+  return candidates.find(candidate =>
+    fs.existsSync(path.join(candidate, 'SKILL.md')),
+  );
+};
+
+if (!fs.existsSync(lockPath)) {
+  console.error('Missing .agents/skills-lock.json');
+  process.exit(1);
+}
+
+const lock = readJson(lockPath);
+const installDir = path.join(root, lock.installDir ?? '.agents/skills');
+const sources = lock.sources ?? [];
+const requiredCloneSources = sources.filter(
+  source => source.install === 'clone',
+);
+const optionalCloneSources = sources.filter(
+  source => source.install === 'clone-if-authorized',
+);
+const requiredSkills = [
+  ...(lock.baseline ?? []),
+  ...requiredCloneSources.flatMap(source => source.baseline ?? []),
+].filter(
+  (skill, index, skills) =>
+    skills.findIndex(candidate => candidate.name === skill.name) === index,
+);
+
+if (checkOnly) {
+  const missingRequired = requiredSkills
+    .map(skill => skill.name)
+    .filter(
+      skillName => !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
+    );
+  const missingOptional = optionalCloneSources.flatMap(source =>
+    (source.baseline ?? [])
+      .map(skill => skill.name)
+      .filter(
+        skillName =>
+          !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
+      ),
+  );
+
+  if (missingRequired.length > 0) {
+    console.error(
+      `Required agent skills not installed: ${missingRequired.join(', ')}. Run pnpm skills:install.`,
+    );
+    process.exit(1);
+  }
+
+  if (missingOptional.length > 0) {
+    console.warn(
+      `Private skills not installed: ${missingOptional.join(', ')}. Run pnpm skills:install if you have access.`,
+    );
+  } else {
+    console.log('Required and private agent skills are installed.');
+    process.exit(0);
+  }
+  console.log('Required agent skills are installed.');
+  process.exit(0);
+}
+
+fs.mkdirSync(installDir, { recursive: true });
+
+for (const source of [...requiredCloneSources, ...optionalCloneSources]) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
+  try {
+    try {
+      cloneSource(source, tempDir);
+    } catch (error) {
+      if (source.install === 'clone-if-authorized') {
+        console.warn(
+          `Skipping ${source.repository}; current developer may not have access.`,
+        );
+        continue;
+      }
+      throw error;
+    }
+    for (const skill of source.baseline ?? []) {
+      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}`);
+    }
+  } finally {
+    removeTree(tempDir);
+  }
+}