@bleedingdev/modern-js-create 3.2.0-ultramodern.18 → 3.2.0-ultramodern.19

package/dist/index.js

@@ -556,6 +556,7 @@ const ultramodern_workspace_dirname = node_path.dirname(fileURLToPath(import.met
 const workspaceTemplateDir = node_path.resolve(ultramodern_workspace_dirname, '..', 'template-workspace');
 const TANSTACK_ROUTER_VERSION = '1.170.1';
 const MODULE_FEDERATION_VERSION = '2.4.0';
+const ZEPHYR_MODERNJS_PLUGIN_VERSION = '1.1.1';
 const EFFECT_TSGO_VERSION = '0.7.3';
 const TYPESCRIPT_NATIVE_PREVIEW_VERSION = '7.0.0-dev.20260518.1';
 const OXLINT_VERSION = '1.65.0';
@@ -926,6 +927,7 @@ function appDependencies(scope, packageSource) {
         '@module-federation/modern-js-v3': MODULE_FEDERATION_VERSION,
         '@module-federation/runtime': MODULE_FEDERATION_VERSION,
         '@tanstack/react-router': TANSTACK_ROUTER_VERSION,
+        'zephyr-modernjs-plugin': ZEPHYR_MODERNJS_PLUGIN_VERSION,
         [ultramodern_workspace_packageName(scope, 'shared-contracts')]: WORKSPACE_PACKAGE_VERSION,
         [ultramodern_workspace_packageName(scope, 'shared-design-tokens')]: WORKSPACE_PACKAGE_VERSION,
         i18next: I18NEXT_VERSION,
@@ -967,7 +969,10 @@ function createRootPackageJson(scope, packageSource) {
             typecheck: `pnpm -r --filter "@${scope}/*" typecheck`,
             'skills:install': "node ./scripts/bootstrap-agent-skills.mjs",
             'skills:check': "node ./scripts/bootstrap-agent-skills.mjs --check",
+            'agents:refs:install': "node ./scripts/setup-agent-reference-repos.mjs",
+            'agents:refs:check': "node ./scripts/setup-agent-reference-repos.mjs --check",
             'ultramodern:check': "node ./scripts/validate-ultramodern-workspace.mjs",
+            postinstall: "node ./scripts/setup-agent-reference-repos.mjs",
             check: 'pnpm format:check && pnpm lint && pnpm typecheck && pnpm i18n:check && pnpm skills:check && pnpm ultramodern:check'
         },
         engines: {
@@ -1136,6 +1141,7 @@ import { appTools, defineConfig, presetUltramodern } from '@modern-js/app-tools'
 import { i18nPlugin } from '@modern-js/plugin-i18n';
 import { tanstackRouterPlugin } from '@modern-js/plugin-tanstack';
 import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+import { withZephyr } from 'zephyr-modernjs-plugin';
 
 const appId = '${app.id}';
 const port = Number(process.env['${app.portEnv}'] ?? ${app.port});
@@ -1157,11 +1163,19 @@ export default defineConfig(
     {
       output: {
         disableTsChecker: true,
+        distPath: {
+          html: './',
+        },
         polyfill: 'off',
         splitRouteChunks: false,
       },
+      html: {
+        outputStructure: 'flat',
+      },
       plugins: [
-        appTools(),
+        appTools({
+          bundler: 'rspack',
+        }),
         i18nPlugin({
           localeDetection: {
             fallbackLanguage: 'en',
@@ -1171,6 +1185,7 @@ export default defineConfig(
         }),
         tanstackRouterPlugin(),
         moduleFederationPlugin(),
+        withZephyr(),
       ],
       server: {
         port,
@@ -1180,6 +1195,7 @@ export default defineConfig(
         },
       },
       source: {
+        mainEntryName: 'index',
         globalVars: {
           ULTRAMODERN_SITE_URL: siteUrl,
         },
@@ -1856,6 +1872,7 @@ function createTemplateManifest(modernVersion, packageSource) {
             allowedPaths: [
                 '.agents/**',
                 '.github/**',
+                '.gitignore',
                 '.modernjs/**',
                 'AGENTS.md',
                 'README.md',

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.18",
+  "version": "3.2.0-ultramodern.19",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {

package/template-workspace/.agents/agent-reference-repos.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "defaultEnabled": true,
+  "installDir": "repos",
+  "repositories": [
+    {
+      "id": "effect",
+      "name": "Effect",
+      "url": "https://github.com/Effect-TS/effect.git",
+      "ref": "main",
+      "path": "repos/effect",
+      "readOnly": true
+    },
+    {
+      "id": "ultramodern-js",
+      "name": "UltraModern.js",
+      "url": "https://github.com/BleedingDev/ultramodern.js.git",
+      "ref": "main-ultramodern",
+      "path": "repos/ultramodern.js",
+      "readOnly": true
+    }
+  ]
+}

package/template-workspace/AGENTS.md

@@ -38,6 +38,15 @@ pnpm skills:install
 
 The installer copies only the allowlisted 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 snapshots under `repos/` by default during `pnpm install`. 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.

package/template-workspace/README.md.handlebars

@@ -19,6 +19,11 @@ Run the scaffold validator before adding business code:
 pnpm ultramodern:check
 ```
 
+By default, `pnpm install` also prepares read-only agent reference repositories
+under `repos/` for Effect and UltraModern.js source lookup. 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

package/template-workspace/scripts/setup-agent-reference-repos.mjs

@@ -0,0 +1,217 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const args = new Set(process.argv.slice(2));
+const checkOnly = args.has('--check');
+const configPath = path.join(root, '.agents', 'agent-reference-repos.json');
+const manifestPath = path.join(root, '.modernjs', 'agent-reference-repos.json');
+const tempRoot = path.join(root, '.modernjs', 'agent-reference-repos-tmp');
+
+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_REPOS) ||
+  falsy(process.env.ULTRAMODERN_AGENT_REPOS);
+const required = truthy(process.env.ULTRAMODERN_AGENT_REPOS_REQUIRED);
+const refresh = truthy(process.env.ULTRAMODERN_AGENT_REPOS_REFRESH);
+
+const log = message => console.log(`[agent-reference-repos] ${message}`);
+const warn = message => console.warn(`[agent-reference-repos] ${message}`);
+
+function fail(message) {
+  if (required || checkOnly) {
+    throw new Error(message);
+  }
+  warn(message);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: options.cwd ?? root,
+    encoding: 'utf-8',
+    stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeout ?? 120000,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim();
+    throw new Error(
+      `${command} ${commandArgs.join(' ')} failed${
+        stderr ? `: ${stderr}` : ''
+      }`,
+    );
+  }
+  return result.stdout?.trim() ?? '';
+}
+
+function assertSafeRepoPath(relativePath) {
+  if (
+    typeof relativePath !== 'string' ||
+    relativePath.length === 0 ||
+    path.isAbsolute(relativePath) ||
+    relativePath.split(/[\\/]+/).includes('..') ||
+    !relativePath.startsWith('repos/')
+  ) {
+    throw new Error(`Unsafe reference repository path: ${relativePath}`);
+  }
+}
+
+function hasGit() {
+  const result = spawnSync('git', ['--version'], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return result.status === 0;
+}
+
+function existingReference(targetPath, repo) {
+  const markerPath = path.join(targetPath, '.ultramodern-reference-repo.json');
+  if (!fs.existsSync(markerPath)) {
+    return undefined;
+  }
+  try {
+    const marker = readJson(markerPath);
+    if (marker.url === repo.url && marker.ref === repo.ref) {
+      return marker;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function materializeRepository(repo) {
+  assertSafeRepoPath(repo.path);
+  const targetPath = path.join(root, repo.path);
+  const existing = existingReference(targetPath, repo);
+
+  if (existing && !refresh) {
+    log(`${repo.id} already present at ${repo.path} (${existing.commit})`);
+    return { ...existing, status: 'present' };
+  }
+
+  if (fs.existsSync(targetPath)) {
+    if (!refresh) {
+      fail(`${repo.path} exists but is not a managed reference repo`);
+      return undefined;
+    }
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+
+  if (checkOnly) {
+    fail(`${repo.path} is missing`);
+    return undefined;
+  }
+
+  fs.mkdirSync(tempRoot, { recursive: true });
+  const tempPath = fs.mkdtempSync(path.join(tempRoot, `${repo.id}-`));
+
+  try {
+    log(`cloning ${repo.name} from ${repo.url}#${repo.ref}`);
+    run(
+      'git',
+      [
+        'clone',
+        '--depth',
+        '1',
+        '--single-branch',
+        '--branch',
+        repo.ref,
+        '--filter=blob:none',
+        repo.url,
+        tempPath,
+      ],
+      { timeout: 300000 },
+    );
+    const commit = run('git', ['-C', tempPath, 'rev-parse', 'HEAD']);
+    fs.rmSync(path.join(tempPath, '.git'), { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.renameSync(tempPath, targetPath);
+
+    const marker = {
+      schemaVersion: 1,
+      id: repo.id,
+      name: repo.name,
+      url: repo.url,
+      ref: repo.ref,
+      commit,
+      path: repo.path,
+      readOnly: repo.readOnly !== false,
+      installedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(
+      path.join(targetPath, '.ultramodern-reference-repo.json'),
+      `${JSON.stringify(marker, null, 2)}\n`,
+    );
+    log(`${repo.id} installed at ${repo.path} (${commit})`);
+    return { ...marker, status: 'installed' };
+  } catch (error) {
+    fs.rmSync(tempPath, { recursive: true, force: true });
+    fail(`Could not install ${repo.id}: ${error.message}`);
+    return undefined;
+  }
+}
+
+function main() {
+  if (!fs.existsSync(configPath)) {
+    fail('Missing .agents/agent-reference-repos.json');
+    return;
+  }
+
+  const config = readJson(configPath);
+  const enabled = config.defaultEnabled !== false && !skipRequested;
+
+  if (!enabled) {
+    log('setup skipped; set ULTRAMODERN_SKIP_AGENT_REPOS=0 to enable it again');
+    return;
+  }
+
+  if (!hasGit()) {
+    fail('git is required to install agent reference repositories');
+    return;
+  }
+
+  const installed = [];
+  for (const repo of config.repositories ?? []) {
+    const result = materializeRepository(repo);
+    if (result) {
+      installed.push(result);
+    }
+  }
+
+  if (!checkOnly) {
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(
+      manifestPath,
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          generatedAt: new Date().toISOString(),
+          installDir: config.installDir ?? 'repos',
+          repositories: installed,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`[agent-reference-repos] ${error.message}`);
+  process.exitCode = 1;
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}

package/template-workspace/scripts/validate-ultramodern-workspace.mjs.handlebars

@@ -36,6 +36,7 @@ const assertExists = (relativePath) => {
 
 const requiredPaths = [
   'AGENTS.md',
+  '.gitignore',
   'package.json',
   'pnpm-workspace.yaml',
   'tsconfig.base.json',
@@ -44,6 +45,7 @@ const requiredPaths = [
   '.github/renovate.json',
   '.github/workflows/ultramodern-workspace-gates.yml',
   '.agents/skills-lock.json',
+  '.agents/agent-reference-repos.json',
   '.agents/rstackjs-agent-skills-LICENSE',
   '.agents/skills/rsbuild-best-practices/SKILL.md',
   '.agents/skills/rspack-best-practices/SKILL.md',
@@ -61,6 +63,7 @@ const requiredPaths = [
   '.modernjs/ultramodern-workspace-template-manifest.json',
   '.modernjs/ultramodern-package-source.json',
   'scripts/bootstrap-agent-skills.mjs',
+  'scripts/setup-agent-reference-repos.mjs',
   'scripts/check-i18n-strings.mjs',
   'apps/shell-super-app/package.json',
   'apps/shell-super-app/config/public/locales/en/translation.json',
@@ -122,6 +125,7 @@ for (const appDirectory of [
 const rootPackage = readJson('package.json');
 const packageSource = readJson('.modernjs/ultramodern-package-source.json');
 const skillsLock = readJson('.agents/skills-lock.json');
+const agentReferenceRepos = readJson('.agents/agent-reference-repos.json');
 const pnpmWorkspace = readText('pnpm-workspace.yaml');
 const workflowContent = readText('.github/workflows/ultramodern-workspace-gates.yml');
 const renovateConfig = readJson('.github/renovate.json');
@@ -237,6 +241,9 @@ const requiredRootScripts = {
   'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
   lint: 'oxlint .',
   'lint:fix': 'oxlint . --fix',
+  'agents:refs:check': 'node ./scripts/setup-agent-reference-repos.mjs --check',
+  'agents:refs:install': 'node ./scripts/setup-agent-reference-repos.mjs',
+  postinstall: 'node ./scripts/setup-agent-reference-repos.mjs',
   'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
   'skills:install': 'node ./scripts/bootstrap-agent-skills.mjs',
   typecheck: `pnpm -r --filter "@${packageScope}/*" typecheck`,
@@ -274,6 +281,34 @@ assert(
   skillsLock.installDir === '.agents/skills',
   'Agent skills lock must use .agents/skills as installDir',
 );
+assert(
+  agentReferenceRepos.defaultEnabled === true,
+  'Agent reference repositories must be enabled by default',
+);
+assert(
+  agentReferenceRepos.repositories?.some(
+    (repo) =>
+      repo.id === 'effect' &&
+      repo.url === 'https://github.com/Effect-TS/effect.git' &&
+      repo.path === 'repos/effect',
+  ),
+  'Agent reference repositories must include Effect',
+);
+assert(
+  agentReferenceRepos.repositories?.some(
+    (repo) =>
+      repo.id === 'ultramodern-js' &&
+      repo.url === 'https://github.com/BleedingDev/ultramodern.js.git' &&
+      repo.path === 'repos/ultramodern.js',
+  ),
+  'Agent reference repositories must include UltraModern.js',
+);
+assert(
+  readText('scripts/setup-agent-reference-repos.mjs').includes(
+    'ULTRAMODERN_SKIP_AGENT_REPOS',
+  ),
+  'Agent reference repository setup must expose an opt-out environment variable',
+);
 for (const skillName of baselineAgentSkills) {
   assert(
     skillsLock.baseline?.some((skill) => skill.name === skillName),
@@ -357,6 +392,10 @@ for (const packagePath of appPackagePaths) {
     packageJson.dependencies?.['@module-federation/modern-js-v3'] === '2.4.0',
     `${packagePath} must include the Module Federation plugin`,
   );
+  assert(
+    packageJson.dependencies?.['zephyr-modernjs-plugin'] === '1.1.1',
+    `${packagePath} must include the official Zephyr Modern.js plugin`,
+  );
   assert(
     packageJson.modernjs?.preset === 'presetUltramodern',
     `${packagePath} must keep presetUltramodern metadata`,
@@ -383,6 +422,27 @@ for (const configPath of [
     config.includes('moduleFederationPlugin()'),
     `${configPath} must enable Module Federation`,
   );
+  assert(
+    config.includes("from 'zephyr-modernjs-plugin'"),
+    `${configPath} must import the official Zephyr Modern.js plugin`,
+  );
+  assert(config.includes('withZephyr()'), `${configPath} must enable Zephyr through plugins`);
+  assert(
+    config.includes("bundler: 'rspack'"),
+    `${configPath} must keep appTools on the rspack bundler for Zephyr`,
+  );
+  assert(
+    config.includes("html: './'"),
+    `${configPath} must keep Modern.js output.distPath.html compatible with Zephyr`,
+  );
+  assert(
+    config.includes("outputStructure: 'flat'"),
+    `${configPath} must keep Modern.js HTML output flat for Zephyr`,
+  );
+  assert(
+    config.includes("mainEntryName: 'index'"),
+    `${configPath} must keep Modern.js source.mainEntryName compatible with Zephyr`,
+  );
 }
 
 for (const routePath of [