@bleedingdev/modern-js-create 3.2.0-ultramodern.1 → 3.2.0-ultramodern.100

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

@@ -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,5 +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
+  sharp: true
+  workerd: true

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

@@ -0,0 +1,264 @@
+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 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]);
+    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;
+  }
+
+  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),
+    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 });
+installGit();
+initializeGitRepository();
+
+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);
+  }
+}
+
+installLefthook();