@bleedingdev/modern-js-create 3.2.0-ultramodern.5 → 3.2.0-ultramodern.7

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,56 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "https://github.com/rstackjs/agent-skills",
+    "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+    "license": "MIT",
+    "licensePath": ".agents/rstackjs-agent-skills-LICENSE"
+  },
+  "installDir": ".agents/skills",
+  "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,28 @@
+# 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.
+
+## 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.
+
+## 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 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 ultramodern:check`.

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

@@ -4,12 +4,23 @@ import path from 'node:path';
 const root = process.cwd();
 const packageScope = '{{packageScope}}';
 const tanstackVersion = '1.170.1';
+const rstackAgentSkillsCommit =
+  '61c948b42512e223bad44b83af4080eba48b2677';
 const modernPackages = [
   '@modern-js/app-tools',
   '@modern-js/plugin-bff',
   '@modern-js/plugin-tanstack',
   '@modern-js/runtime',
 ];
+const baselineAgentSkills = [
+  'rsbuild-best-practices',
+  'rspack-best-practices',
+  'rspack-tracing',
+  'rsdoctor-analysis',
+  'rslib-best-practices',
+  'rslib-modern-package',
+  'rstest-best-practices',
+];
 
 function readText(relativePath) {
   return fs.readFileSync(path.join(root, relativePath), 'utf-8');
@@ -30,9 +41,22 @@ function assertExists(relativePath) {
 }
 
 const requiredPaths = [
+  'AGENTS.md',
   'package.json',
   'pnpm-workspace.yaml',
   'tsconfig.base.json',
+  '.agents/skills-lock.json',
+  '.agents/rstackjs-agent-skills-LICENSE',
+  '.agents/skills/rsbuild-best-practices/SKILL.md',
+  '.agents/skills/rspack-best-practices/SKILL.md',
+  '.agents/skills/rspack-tracing/SKILL.md',
+  '.agents/skills/rspack-tracing/references/tracing-guide.md',
+  '.agents/skills/rspack-tracing/scripts/analyze_trace.js',
+  '.agents/skills/rsdoctor-analysis/SKILL.md',
+  '.agents/skills/rsdoctor-analysis/references/rsdoctor-data-types.md',
+  '.agents/skills/rslib-best-practices/SKILL.md',
+  '.agents/skills/rslib-modern-package/SKILL.md',
+  '.agents/skills/rstest-best-practices/SKILL.md',
   'topology/reference-topology.json',
   'topology/ownership.json',
   'topology/local-overlays/development.json',
@@ -65,6 +89,7 @@ for (const requiredPath of requiredPaths) {
 
 const rootPackage = readJson('package.json');
 const packageSource = readJson('.modernjs/ultramodern-package-source.json');
+const skillsLock = readJson('.agents/skills-lock.json');
 const expectedModernSpecifier =
   packageSource.strategy === 'install'
     ? packageSource.modernPackages?.specifier
@@ -83,6 +108,8 @@ function expectedModernDependency(packageName) {
 
 assert(rootPackage.private === true, 'Root package must be private');
 assert(rootPackage.modernjs?.preset === 'presetUltramodern', 'Root must declare presetUltramodern');
+assert(rootPackage.packageManager === 'pnpm@11.1.2', 'Root must pin pnpm 11.1.2');
+assert(rootPackage.engines?.pnpm === '>=11.0.0', 'Root must require pnpm >=11');
 assert(
   rootPackage.modernjs?.packageSource?.config ===
     './.modernjs/ultramodern-package-source.json',
@@ -117,6 +144,36 @@ assert(
   'Root must expose the ultramodern:check script',
 );
 
+const agentsInstructions = readText('AGENTS.md');
+assert(
+  agentsInstructions.includes('UltraModern Agent Contract') &&
+    agentsInstructions.includes('Required Skill Baseline'),
+  'Root AGENTS.md must document the UltraModern agent contract',
+);
+assert(
+  skillsLock.source?.repository === 'https://github.com/rstackjs/agent-skills',
+  'Agent skills lock must retain the Rstack skill source repository',
+);
+assert(
+  skillsLock.source?.commit === rstackAgentSkillsCommit,
+  'Agent skills lock must pin the expected Rstack skill commit',
+);
+assert(
+  skillsLock.installDir === '.agents/skills',
+  'Agent skills lock must use .agents/skills as installDir',
+);
+for (const skillName of baselineAgentSkills) {
+  assert(
+    skillsLock.baseline?.some(skill => skill.name === skillName),
+    `Agent skills lock must include ${skillName}`,
+  );
+  const skillContent = readText(`.agents/skills/${skillName}/SKILL.md`);
+  assert(
+    skillContent.includes(`name: ${skillName}`),
+    `${skillName} must contain matching skill metadata`,
+  );
+}
+
 const appPackagePaths = [
   'apps/shell-super-app/package.json',
   'apps/remotes/remote-commerce/package.json',
@@ -268,6 +325,16 @@ assert(
   manifest.packageSource?.strategy === packageSource.strategy,
   'Template manifest must retain the generated package source strategy',
 );
+assert(
+  manifest.agentSkills?.source?.commit === rstackAgentSkillsCommit,
+  'Template manifest must retain the Rstack agent skills commit',
+);
+assert(
+  baselineAgentSkills.every(skillName =>
+    manifest.agentSkills?.baseline?.includes(skillName),
+  ),
+  'Template manifest must list every baseline agent skill',
+);
 assert(
   manifest.validation?.expectedCommands?.includes('pnpm run ultramodern:check'),
   'Template manifest must document the validation command',