@bleedingdev/modern-js-create 3.2.0-ultramodern.6 → 3.2.0-ultramodern.8

package/template-workspace/.agents/skills/rspack-tracing/scripts/analyze_trace.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse duration string (e.g., "1.23ms", "456.78µs", "0.12s") to milliseconds
+function parseDuration(durationStr) {
+  if (!durationStr) return 0;
+
+  const match = durationStr.match(/^([\d.]+)(ms|µs|s|ns)$/);
+  if (!match) return 0;
+
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+
+  switch (unit) {
+    case 's':
+      return value * 1000;
+    case 'ms':
+      return value;
+    case 'µs':
+      return value / 1000;
+    case 'ns':
+      return value / 1000000;
+    default:
+      return value;
+  }
+}
+
+// Get trace file path
+const tracePath = process.argv[2] || path.join(__dirname, 'trace.json');
+
+if (!fs.existsSync(tracePath)) {
+  console.error(`Error: Trace file not found at ${tracePath}`);
+  console.error('Usage: node analyze_trace.js <path-to-trace.json>');
+  process.exit(1);
+}
+
+console.log(`Analyzing trace file: ${tracePath}\n`);
+
+try {
+  const fileContent = fs.readFileSync(tracePath, 'utf8');
+
+  // Parse line-delimited JSON
+  const events = fileContent
+    .trim()
+    .split('\n')
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (err) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (!events.length) {
+    console.error('No valid trace events found.');
+    process.exit(1);
+  }
+
+  console.log('=== Rspack Build Performance Analysis ===\n');
+  console.log(`Total events: ${events.length}\n`);
+
+  // Categorize events by target
+  const pluginStats = new Map();
+  const loaderStats = new Map();
+
+  events.forEach(event => {
+    const target = event.target;
+    const timeField = event.fields?.['time.busy'];
+
+    if (!timeField) return;
+
+    const duration = parseDuration(timeField);
+
+    if (target === 'Plugin Analysis') {
+      // Plugin performance
+      const pluginName = event.span?.name;
+      if (!pluginName) return;
+
+      if (!pluginStats.has(pluginName)) {
+        pluginStats.set(pluginName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = pluginStats.get(pluginName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    } else if (target === 'Loader Analysis') {
+      // Loader performance
+      let loaderName = event.span?.name;
+
+      // For pitch phase (span.name is null), use resource path
+      if (!loaderName) {
+        const resource = event.fields?.resource;
+        if (resource) {
+          // Extract filename from resource path
+          const cleanResource = resource.replace(/^"|"$/g, ''); // Remove quotes
+          const filename = cleanResource.split('/').pop();
+          loaderName = `Loader pitch for ${filename}`;
+        } else {
+          loaderName = 'Loader pitch (unknown resource)';
+        }
+      }
+
+      if (!loaderStats.has(loaderName)) {
+        loaderStats.set(loaderName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = loaderStats.get(loaderName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    }
+  });
+
+  // Display Plugin Analysis
+  if (pluginStats.size > 0) {
+    console.log('🔌 Plugin Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedPlugins = [...pluginStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedPlugins.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalPluginTime = [...pluginStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Plugin Time: ${totalPluginTime.toFixed(2)}ms\n`);
+  }
+
+  // Display Loader Analysis
+  if (loaderStats.size > 0) {
+    console.log('\n🔧 Loader Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedLoaders = [...loaderStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedLoaders.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalLoaderTime = [...loaderStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Loader Time: ${totalLoaderTime.toFixed(2)}ms\n`);
+  }
+} catch (err) {
+  console.error('Error processing trace file:', err);
+  process.exit(1);
+}

package/template-workspace/.agents/skills/rstest-best-practices/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rstest-best-practices
+description: Rstest best practices for config, CLI workflow, test writing, mocking, snapshot testing, DOM testing, coverage, multi-project setup, CI integration, performance and debugging. Use when writing, reviewing, or troubleshooting Rstest test projects.
+---
+
+# Rstest Best Practices
+
+Apply these rules when writing or reviewing Rstest test projects.
+
+## Configuration
+
+- Use `rstest.config.ts` and `defineConfig` from `@rstest/core`
+- Prefer explicit imports `import { test, expect, describe } from '@rstest/core'` over `globals: true`
+- For Rsbuild projects, use `@rstest/adapter-rsbuild` with `extends: withRsbuildConfig()` to reuse build config
+- For Rslib projects, use `@rstest/adapter-rslib` with `extends: withRslibConfig()` to reuse build config
+- Use `setupFiles` for shared test setup (e.g., custom matchers, cleanup hooks)
+- When using Rsbuild plugins (e.g., `@rsbuild/plugin-react`), add them via the `plugins` field
+- For deep-level or advanced build configuration needs, use `tools.rspack` or `tools.bundlerChain`
+
+## CLI
+
+- Use `rstest` or `rstest run` to run tests (`run` disables watch mode, suitable for CI)
+- Use `rstest --watch` or `rstest watch` for local development with file watching
+- Use `rstest list` to list all test files and test names
+- Use `rstest -u` to update snapshots
+- Use `--reporter=verbose` when debugging test failures for detailed output
+- Use `--config` (`-c`) to specify a custom config file path
+
+## Test writing
+
+- Import test APIs from `@rstest/core`: `test`, `describe`, `expect`, `beforeEach`, `afterEach`, etc.
+- Use `test` or `it` for test cases; use `describe` for grouping related tests
+- Use `.only` to focus on specific tests during development, but never commit `.only` to the codebase
+- Use `.skip` or `.todo` to mark incomplete or temporarily skipped tests
+- Prefer small, focused test cases that test a single behavior
+- For async error paths, prefer `await expect(fn()).rejects.toThrow(ErrorClass)` (or `.rejects.toMatchObject({ ... })`) over `try/catch` with `expect.fail` or `.catch(e => e)` patterns — the matcher form fails clearly if the promise unexpectedly resolves, keeps the assertion in one chain, and avoids forgetting to assert the throw at all
+- For async happy paths, use `await expect(fn()).resolves.toEqual(...)` for the same reason
+- Use `includeSource` for in-source testing of small utility functions (Rust-style `import.meta.rstest`)
+- For in-source tests, wrap test code in `if (import.meta.rstest) { ... }` and define `import.meta.rstest` as `false` in production build config
+
+## Test environment
+
+- Use `testEnvironment: 'node'` (default) for Node.js / server-side code
+- Use `testEnvironment: 'jsdom'` or `testEnvironment: 'happy-dom'` for DOM / browser API testing
+- Install `jsdom` or `happy-dom` as a dev dependency when using DOM environments
+- Prefer `happy-dom` for faster DOM testing; use `jsdom` when better browser API compatibility is needed
+- For real browser testing, use `@rstest/browser` with Playwright
+- Use inline project configs to run different test environments within one project (e.g., `node` and `jsdom` projects)
+
+## React / Vue testing
+
+- For React: use `@rsbuild/plugin-react` plugin and `@testing-library/react` for component testing
+- For Vue: use `@rsbuild/plugin-vue` plugin and `@testing-library/vue` for component testing
+- Create a `rstest.setup.ts` with `expect.extend(jestDomMatchers)` and `afterEach(() => cleanup())` for Testing Library
+- Add the setup file to `setupFiles` in config
+- For SSR testing, use `testEnvironment: 'node'` and test with `react-dom/server` or framework-specific SSR APIs
+
+## Mocking
+
+- Use `rs.mock('./module')` to mock modules
+- Use `rs.fn()` to create mock functions
+- Use `rs.spyOn(object, 'method')` to spy on methods
+- Prefer `clearMocks`, `resetMocks`, or `restoreMocks` config options to automatically clean up mocks between tests
+- Use factory functions in `rs.mock('./module', () => ({ ... }))` to provide mock implementations
+
+## Snapshot testing
+
+- Use `toMatchSnapshot()` for general snapshot testing
+- Use `toMatchInlineSnapshot()` for small, readable inline snapshots
+- Use `toMatchFileSnapshot()` for large or structured outputs (e.g., HTML, generated code)
+- Keep snapshots concise — only include relevant data, avoid timestamps and session IDs
+- Use `expect.addSnapshotSerializer()` to mask paths or sensitive data in snapshots
+- Use `path-serializer` to normalize file paths across platforms
+- Review snapshot changes carefully in code review
+
+## Coverage
+
+- Enable coverage with `--coverage` CLI flag or `coverage.enabled: true` in config
+- Install `@rstest/coverage-istanbul` for the Istanbul coverage provider
+- Use `coverage.include` to specify source files for coverage (e.g., `['src/**/*.{js,ts,tsx}']`)
+- Use `coverage.thresholds` to enforce minimum coverage requirements
+- Use `coverage.reporters` to generate reports in different formats (e.g., `text`, `lcov`, `html`)
+
+## Multi-project testing
+
+- Use `projects` field in root config to define multiple test projects
+- For monorepos, use glob patterns like `'packages/*'` to auto-discover sub-projects
+- Use `defineProject` helper in sub-project configs
+- Extract shared config and use `mergeRstestConfig` to compose project configs
+- Global options (`reporters`, `pool`, `isolate`, `coverage`, `bail`) must be set at the root level, not in projects
+
+## CI integration
+
+- Use `rstest run` (not `rstest watch`) in CI
+- Use `--shard` for parallel test execution across CI machines (e.g., `--shard 1/3`)
+- Use `--reporter=blob` with `rstest merge-reports` to combine sharded results
+- Use `--reporter=junit` with `outputPath` for CI report integration
+- The `github-actions` reporter is auto-enabled in GitHub Actions for inline error annotations
+- Use `--bail` to stop early on first failure when appropriate
+
+## Performance
+
+- Disable `isolate` (`--no-isolate`) when tests have no side effects for faster execution via module cache reuse
+- Use `pool.maxWorkers` to control parallelism based on available resources
+- Keep test build fast by avoiding unnecessary Rspack plugins in test config
+- Use test filtering (`rstest <pattern>` or `-t <name>`) to run only relevant tests during development
+- Leverage watch mode's incremental re-runs for fast local feedback
+
+## Debugging
+
+- Run with `DEBUG=rstest` to enable debug mode, which writes final configs and build outputs to disk
+- Read generated files in `dist/.rstest-temp/.rsbuild/` to confirm final Rstest/Rsbuild/Rspack config
+- Use VS Code's JavaScript Debug Terminal to run `rstest` with breakpoints
+- Use `--reporter=verbose` for detailed per-test output
+- Use `--printConsoleTrace` to trace console calls to their source
+- Add VS Code launch config for debugging specific test files with `@rstest/core/bin/rstest.js`
+
+## Profiling
+
+- Use Rsdoctor with `RSDOCTOR=true rstest run` to analyze test build performance
+- Use `samply` for native profiling of both main and worker processes
+- Use Node.js `--heap-prof` for memory profiling
+
+## Toolchain integration
+
+- Use the official VS Code extension (`rstack.rstest`) for in-editor test running and debugging
+- For Rslib libraries, use `@rstest/adapter-rslib` for config reuse
+- For Rsbuild apps, use `@rstest/adapter-rsbuild` for config reuse
+- Use `process.env.RSTEST` to detect test environment and apply test-specific config
+
+## Documentation
+
+- For the latest Rstest docs, read https://rstest.rs/llms.txt

package/template-workspace/.agents/skills-lock.json

@@ -0,0 +1,95 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "https://github.com/rstackjs/agent-skills",
+    "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+    "license": "MIT",
+    "licensePath": ".agents/rstackjs-agent-skills-LICENSE"
+  },
+  "installDir": ".agents/skills",
+  "sources": [
+    {
+      "id": "rstack-agent-skills",
+      "visibility": "public",
+      "repository": "https://github.com/rstackjs/agent-skills",
+      "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+      "license": "MIT",
+      "licensePath": ".agents/rstackjs-agent-skills-LICENSE",
+      "install": "vendored"
+    },
+    {
+      "id": "techsiocz-private",
+      "visibility": "private",
+      "repository": "https://github.com/TechsioCZ/skills",
+      "install": "clone-if-authorized",
+      "baseline": [
+        {
+          "name": "plan-graph",
+          "reason": "Build and validate DAGs from .plan.md files"
+        },
+        {
+          "name": "dag",
+          "reason": "Inspect current plan frontiers and blocked lanes"
+        },
+        {
+          "name": "subagent-graph",
+          "reason": "Design dependency-aware multi-agent launch graphs"
+        },
+        {
+          "name": "helm",
+          "reason": "Steer already-running multi-agent work"
+        },
+        {
+          "name": "debugger-mode",
+          "reason": "Run hypothesis-driven debugging with runtime evidence"
+        }
+      ]
+    }
+  ],
+  "baseline": [
+    {
+      "name": "rsbuild-best-practices",
+      "path": ".agents/skills/rsbuild-best-practices",
+      "reason": "Modern.js application build configuration and Rsbuild troubleshooting"
+    },
+    {
+      "name": "rspack-best-practices",
+      "path": ".agents/skills/rspack-best-practices",
+      "reason": "Rspack bundling, CSS, asset, profiling, and production behavior"
+    },
+    {
+      "name": "rspack-tracing",
+      "path": ".agents/skills/rspack-tracing",
+      "reason": "Trace-backed Rspack failure and performance debugging"
+    },
+    {
+      "name": "rsdoctor-analysis",
+      "path": ".agents/skills/rsdoctor-analysis",
+      "reason": "Evidence-backed bundle composition, duplication, and retained-module analysis"
+    },
+    {
+      "name": "rslib-best-practices",
+      "path": ".agents/skills/rslib-best-practices",
+      "reason": "Rslib shared package and design-system library authoring"
+    },
+    {
+      "name": "rslib-modern-package",
+      "path": ".agents/skills/rslib-modern-package",
+      "reason": "Modern package contracts, exports, declarations, side effects, and release readiness"
+    },
+    {
+      "name": "rstest-best-practices",
+      "path": ".agents/skills/rstest-best-practices",
+      "reason": "Rstest configuration, test writing, mocking, snapshots, coverage, and CI behavior"
+    }
+  ],
+  "excludedByDefault": [
+    "migrate-to-rsbuild",
+    "migrate-to-rslib",
+    "migrate-to-rslint",
+    "migrate-to-rstest",
+    "rsbuild-v2-upgrade",
+    "rspack-v2-upgrade",
+    "rspress-v2-upgrade"
+  ]
+}

package/template-workspace/AGENTS.md

@@ -0,0 +1,45 @@
+# 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.
+
+## 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.
+
+## Required Skill Baseline
+
+Use these skills when the task touches the matching subsystem:
+
+- `rsbuild-best-practices`: Modern.js app build configuration, Rsbuild options, assets, type checking, and build debugging.
+- `rspack-best-practices`: Rspack-level bundling, CSS, assets, profiling, and production build behavior.
+- `rspack-tracing`: Rspack build failures, slow builds, crash localization, and trace analysis.
+- `rsdoctor-analysis`: Evidence-based bundle analysis from `rsdoctor-data.json`, including duplicate packages, large chunks, and retained modules.
+- `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.
+
+## 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 allowlisted private skills from `.agents/skills-lock.json`: `plan-graph`, `dag`, `subagent-graph`, `helm`, and `debugger-mode`.
+
+## Project Priorities
+
+- Keep `presetUltramodern` as the single preset.
+- Prefer Effect for BFF/service 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 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 and private TechsioCZ skill allowlist 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/oxfmt.config.ts

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

package/template-workspace/oxlint.config.ts

@@ -0,0 +1,12 @@
+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: ["dist", "node_modules", ".modern", ".modernjs", "**/routeTree.gen.ts"],
+});

package/template-workspace/pnpm-workspace.yaml

@@ -5,14 +5,12 @@ packages:
   - packages/*
 
 allowBuilds:
-  '@biomejs/biome': true
   '@swc/core': true
   core-js: true
   esbuild: true
   msgpackr-extract: true
 
 onlyBuiltDependencies:
-  - '@biomejs/biome'
   - '@swc/core'
   - core-js
   - esbuild

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

@@ -0,0 +1,106 @@
+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');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd ?? root,
+    encoding: 'utf8',
+    stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function cloneSource(source, targetDir) {
+  const repo = source.repository.replace(/^https:\/\/github.com\//, '');
+  try {
+    run('gh', ['repo', 'clone', repo, targetDir, '--', '--depth', '1'], {
+      stdio: 'inherit',
+    });
+    return;
+  } catch {
+    run('git', ['clone', '--depth', '1', source.repository, targetDir], {
+      stdio: 'inherit',
+    });
+  }
+}
+
+function 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 privateSources = (lock.sources ?? []).filter(
+  source => source.install === 'clone-if-authorized',
+);
+
+if (checkOnly) {
+  const missing = privateSources.flatMap(source =>
+    (source.baseline ?? [])
+      .map(skill => skill.name)
+      .filter(
+        skillName =>
+          !fs.existsSync(path.join(installDir, skillName, 'SKILL.md')),
+      ),
+  );
+  if (missing.length > 0) {
+    console.warn(
+      `Private skills not installed: ${missing.join(', ')}. Run pnpm skills:install if you have access.`,
+    );
+  } else {
+    console.log('Agent skills are installed.');
+  }
+  process.exit(0);
+}
+
+fs.mkdirSync(installDir, { recursive: true });
+
+for (const source of privateSources) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
+  try {
+    cloneSource(source, tempDir);
+    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;
+        }
+        fs.rmSync(targetSkillDir, { recursive: true, force: true });
+      }
+      fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
+      console.log(`Installed ${skill.name}`);
+    }
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}