@bleedingdev/modern-js-create 3.2.0-ultramodern.9 → 3.2.0-ultramodern.90

package/template-workspace/README.md.handlebars

@@ -3,23 +3,48 @@
 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 ultramodern:check
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+pnpm dlx @bleedingdev/modern-js-create payments --vertical
 ```
 
-The topology and ownership metadata are generated under `topology/`.
+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 install
+pnpm check
+pnpm build
+```
+
+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
@@ -27,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/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

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

package/template-workspace/oxlint.config.ts

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

package/template-workspace/pnpm-workspace.yaml

@@ -1,17 +1,35 @@
 packages:
   - apps/*
-  - apps/remotes/*
-  - services/*
+  - verticals/*
   - packages/*
 
+minimumReleaseAge: 1440
+minimumReleaseAgeStrict: true
+minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
+trustPolicy: no-downgrade
+trustPolicyIgnoreAfter: 1440
+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.11
+  node-fetch: '^3.3.2'
+
 allowBuilds:
   '@swc/core': true
   core-js: true
   esbuild: true
+  lefthook: true
   msgpackr-extract: true
-
-onlyBuiltDependencies:
-  - '@swc/core'
-  - core-js
-  - esbuild
-  - msgpackr-extract
+  sharp: true
+  workerd: true

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

@@ -8,33 +8,151 @@ const lockPath = path.join(root, '.agents/skills-lock.json');
 const checkOnly = process.argv.includes('--check');
 const force = process.argv.includes('--force');
 
-function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-}
+const readJson = filePath => JSON.parse(fs.readFileSync(filePath, 'utf-8'));
 
-function run(command, args, options = {}) {
-  return execFileSync(command, args, {
+const run = (command, args, options = {}) =>
+  execFileSync(command, args, {
     cwd: options.cwd ?? root,
-    encoding: 'utf8',
+    encoding: 'utf-8',
     stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
   });
-}
 
-function cloneSource(source, targetDir) {
-  const repo = source.repository.replace(/^https:\/\/github.com\//, '');
+const commandExists = command => {
   try {
-    run('gh', ['repo', 'clone', repo, targetDir, '--', '--depth', '1'], {
-      stdio: 'inherit',
-    });
+    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', ['clone', '--depth', '1', source.repository, targetDir], {
-      stdio: 'inherit',
+    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,
+    maxRetries: 5,
+    recursive: true,
+    retryDelay: 100,
+  });
+
+const cloneSource = (source, targetDir) => {
+  if (source.commit) {
+    run('git', ['init', targetDir]);
+    run('git', ['remote', 'add', 'origin', source.repository], {
+      cwd: targetDir,
+    });
+    run('git', ['fetch', '--depth', '1', '--quiet', 'origin', source.commit], {
+      cwd: targetDir,
     });
+    run(
+      'git',
+      [
+        '-c',
+        'advice.detachedHead=false',
+        'checkout',
+        '--detach',
+        '--quiet',
+        'FETCH_HEAD',
+      ],
+      { cwd: targetDir },
+    );
+    return;
   }
-}
 
-function resolveSkillDir(sourceRoot, skillName) {
+  const repo = source.repository.replace(/^https:\/\/github.com\//u, '');
+  try {
+    run('gh', [
+      'repo',
+      'clone',
+      repo,
+      targetDir,
+      '--',
+      '--depth',
+      '1',
+      '--quiet',
+    ]);
+  } catch {
+    run('git', [
+      'clone',
+      '--depth',
+      '1',
+      '--quiet',
+      source.repository,
+      targetDir,
+    ]);
+  }
+};
+
+const resolveSkillDir = (sourceRoot, skillName) => {
   const candidates = [
     path.join(sourceRoot, skillName),
     path.join(sourceRoot, 'skills', skillName),
@@ -44,7 +162,7 @@ function resolveSkillDir(sourceRoot, skillName) {
   return candidates.find(candidate =>
     fs.existsSync(path.join(candidate, 'SKILL.md')),
   );
-}
+};
 
 if (!fs.existsSync(lockPath)) {
   console.error('Missing .agents/skills-lock.json');
@@ -53,12 +171,28 @@ if (!fs.existsSync(lockPath)) {
 
 const lock = readJson(lockPath);
 const installDir = path.join(root, lock.installDir ?? '.agents/skills');
-const privateSources = (lock.sources ?? []).filter(
+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 missing = privateSources.flatMap(source =>
+  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(
@@ -66,22 +200,44 @@ if (checkOnly) {
           !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
       ),
   );
-  if (missing.length > 0) {
+
+  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: ${missing.join(', ')}. Run pnpm skills:install if you have access.`,
+      `Private skills not installed: ${missingOptional.join(', ')}. Run pnpm skills:install if you have access.`,
     );
   } else {
-    console.log('Agent skills are installed.');
+    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 });
+installGit();
+initializeGitRepository();
 
-for (const source of privateSources) {
+for (const source of [...requiredCloneSources, ...optionalCloneSources]) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
   try {
-    cloneSource(source, tempDir);
+    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) {
@@ -95,12 +251,14 @@ for (const source of privateSources) {
           console.log(`Skipping existing ${skill.name}`);
           continue;
         }
-        fs.rmSync(targetSkillDir, { recursive: true, force: true });
+        removeTree(targetSkillDir);
       }
       fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
       console.log(`Installed ${skill.name}`);
     }
   } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true });
+    removeTree(tempDir);
   }
 }
+
+installLefthook();