@bleedingdev/modern-js-create 3.2.0-ultramodern.12 → 3.2.0-ultramodern.120

package/template-workspace/README.md.handlebars

@@ -3,23 +3,78 @@
 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,
+private-first route metadata, localized URLs, public-route opt-ins, CSS prefix,
+Effect BFF handlers, local API contract, and typed client surface. Server
+handlers and Effect client/contract modules stay out of browser exposes.
+
+## Private-First Public Surfaces
+
+Generated app routes are private and non-indexable by default. Author route
+metadata in colocated `src/routes/**/route.meta.ts` files; the scaffold
+regenerates `src/routes/ultramodern-route-metadata.ts` as a compatibility
+manifest for config, i18n, public head, and public surface contracts. Private
+app, auth, tenant, dashboard, and internal routes publish no discovery output
+unless route metadata explicitly marks them `public && indexable`. The default
+scaffold therefore emits only a disallowing `robots.txt`; sitemap, web
+manifest, `llms.txt`, API catalog, security.txt, and JSON-LD output stay
+omitted until a safe public route or public docs/help/product surface exists.
+
+Public web artifacts are build/deploy outputs generated into `dist/public` and
+`.output/public`, not hand-authored source files under `config/public`. Dynamic
+public routes can expand sitemap entries through route-owned, Node-safe
+`route.sitemap.mjs` providers beside route metadata. The public-surface
+generator discovers those providers for dynamic public routes and still honors
+explicit `routes.publicSurface.contentSources` entries in the generated
+compatibility manifest.
+
+Run the scaffold validator before adding business code and after every
+`--vertical` mutation:
+
+```bash
+mise install
+pnpm install
+pnpm check
+pnpm build
+```
+
+Generated CI does not call the local aggregate. It runs format, lint,
+typecheck, skills, i18n boundary validation, contract validation, and build as
+separate matrix jobs so failures are isolated and parallelizable.
+
+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`.
+
+Agent skills are prepared during `pnpm install` as a developer convenience.
+External skill repository failures do not block postinstall; strict installation
+is available with `pnpm skills:install`. Use
+`ULTRAMODERN_SKIP_AGENT_SKILLS=1` for a dependency install that avoids external
+skill repositories completely.
+
+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 +82,53 @@ 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
+
+This workspace's apps no longer bake absolute `http://localhost:<port>` URLs
+into asset configuration. Two environment variables now have distinct roles in
+controlling where assets are served from and where SEO output links point.
+
+| Variable | Role | Feeds |
+| --- | --- | --- |
+| `ULTRAMODERN_PUBLIC_URL_<APP_ID>` | Per-app deployment and asset origin | `output.assetPrefix`, Module Federation remote URLs |
+| `MODERN_PUBLIC_SITE_URL` | Site-wide public origin for SEO output | Canonical, hreflang, sitemap `<loc>`, robots `Sitemap:` |
+
+Asset URLs use this precedence: `ULTRAMODERN_PUBLIC_URL_<APP_ID>` →
+`MODERN_PUBLIC_SITE_URL` → inferred workers.dev URL → origin-relative `/`.
+SEO and site origin prefer: `MODERN_PUBLIC_SITE_URL` →
+`ULTRAMODERN_PUBLIC_URL_<APP_ID>` → inferred workers.dev → `http://localhost:<port>`.
+
+Without public URLs configured, asset paths are origin-relative (`/`), and the
+dev server uses `dev.assetPrefix: '/'` — so apps work through tunnels and
+reverse proxies (ngrok, cloudflared) without triggering Chrome's Local Network
+Access prompt or mixed-content errors. Shell-only workspaces can set just
+`MODERN_PUBLIC_SITE_URL` for SEO output.
+
+## Cloudflare Proof
+
+Deploy the generated apps, then pass each deployed app's generated public URL
+env key into the proof step. The proof script reads the generated contract and
+checks the live Worker surface, including public-route sitemap/robots
+consistency, preview noindex behavior, unknown-route status, asset headers,
+byte budgets, and public sourcemap exposure. 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 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 |
+| 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,24 @@
+pre-commit:
+  commands:
+    format:
+      run: pnpm format
+      stage_fixed: true
+    lint-fix:
+      run: pnpm lint:fix
+      stage_fixed: true
+
+pre-push:
+  parallel: true
+  commands:
+    format:
+      run: pnpm format:check
+    lint:
+      run: pnpm lint
+    typecheck:
+      run: pnpm typecheck
+    skills:
+      run: pnpm skills:check
+    i18n-boundaries:
+      run: pnpm i18n:boundaries
+    contract:
+      run: pnpm contract:check

package/template-workspace/oxfmt.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
     '**/*.json',
     'dist',
     'node_modules',
+    'repos/**',
     '.modern',
     '.modernjs',
     '**/routeTree.gen.ts',

package/template-workspace/oxlint.config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
     '.agents',
     'dist',
     'node_modules',
+    'repos/**',
     '.modern',
     '.modernjs',
     '**/routeTree.gen.ts',

package/template-workspace/pnpm-workspace.yaml

@@ -1,17 +1,40 @@
 packages:
   - apps/*
-  - apps/remotes/*
-  - services/*
+  - verticals/*
   - packages/*
 
+minimumReleaseAge: 1440
+minimumReleaseAgeStrict: true
+minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
+  - '@tanstack/react-router'
+  - '@tanstack/router-core'
+  - '@typescript/native-preview'
+  - '@typescript/native-preview-*'
+  - '@types/react'
+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.15
+  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

@@ -7,26 +7,153 @@ 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 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);
+const cloneTimeoutMs = Number.parseInt(
+  process.env.ULTRAMODERN_AGENT_SKILLS_CLONE_TIMEOUT_MS ?? '60000',
+  10,
+);
 
-const readJson = (filePath) => JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+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'],
+    timeout: options.timeout,
+  });
+
+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,
+    maxRetries: 5,
+    recursive: true,
+    retryDelay: 100,
   });
 
 const cloneSource = (source, targetDir) => {
+  if (source.commit) {
+    run('git', ['init', targetDir], { timeout: 30000 });
+    run('git', ['remote', 'add', 'origin', source.repository], {
+      cwd: targetDir,
+      timeout: 30000,
+    });
+    run('git', ['fetch', '--depth', '1', '--quiet', 'origin', source.commit], {
+      cwd: targetDir,
+      timeout: cloneTimeoutMs,
+    });
+    run(
+      'git',
+      [
+        '-c',
+        'advice.detachedHead=false',
+        'checkout',
+        '--detach',
+        '--quiet',
+        'FETCH_HEAD',
+      ],
+      { cwd: targetDir, timeout: 30000 },
+    );
+    return;
+  }
+
   const repo = source.repository.replace(/^https:\/\/github.com\//u, '');
   try {
-    run('gh', ['repo', 'clone', repo, targetDir, '--', '--depth', '1'], {
-      stdio: 'inherit',
-    });
+    run(
+      'gh',
+      ['repo', 'clone', repo, targetDir, '--', '--depth', '1', '--quiet'],
+      { timeout: cloneTimeoutMs },
+    );
   } catch {
-    run('git', ['clone', '--depth', '1', source.repository, targetDir], {
-      stdio: 'inherit',
-    });
+    run(
+      'git',
+      ['clone', '--depth', '1', '--quiet', source.repository, targetDir],
+      { timeout: cloneTimeoutMs },
+    );
   }
 };
 
@@ -37,7 +164,9 @@ const resolveSkillDir = (sourceRoot, skillName) => {
     path.join(sourceRoot, 'skills', 'engineering', skillName),
     path.join(sourceRoot, 'skills', 'productivity', skillName),
   ];
-  return candidates.find((candidate) => fs.existsSync(path.join(candidate, 'SKILL.md')));
+  return candidates.find(candidate =>
+    fs.existsSync(path.join(candidate, 'SKILL.md')),
+  );
 };
 
 if (!fs.existsSync(lockPath)) {
@@ -47,36 +176,88 @@ if (!fs.existsSync(lockPath)) {
 
 const lock = readJson(lockPath);
 const installDir = path.join(root, lock.installDir ?? '.agents/skills');
-const privateSources = (lock.sources ?? []).filter(
-  (source) => source.install === 'clone-if-authorized',
+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 (skipRequested) {
+  const reason = 'agent skills bootstrap skipped by environment';
+  if (checkOnly) {
+    console.log(reason);
+    process.exit(0);
+  }
+  console.log(reason);
+  installLefthook();
+  process.exit(0);
+}
+
 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((skillName) => !fs.existsSync(path.join(installDir, skillName, 'SKILL.md'))),
+      .map(skill => skill.name)
+      .filter(
+        skillName =>
+          !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' || postinstall) {
+        console.warn(`Skipping ${source.repository}; ${error.message}`);
+        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}`);
+        throw new Error(
+          `Skill ${skill.name} not found in ${source.repository}`,
+        );
       }
       const targetSkillDir = path.join(installDir, skill.name);
       if (fs.existsSync(targetSkillDir)) {
@@ -84,12 +265,14 @@ for (const source of privateSources) {
           console.log(`Skipping existing ${skill.name}`);
           continue;
         }
-        fs.rmSync(targetSkillDir, { force: true, recursive: true });
+        removeTree(targetSkillDir);
       }
       fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
       console.log(`Installed ${skill.name}`);
     }
   } finally {
-    fs.rmSync(tempDir, { force: true, recursive: true });
+    removeTree(tempDir);
   }
 }
+
+installLefthook();