rstack-repo-maintain

--- name: rstack-repo-maintain description: 'Audit and modernize RstackJS/Rspack ecosystem repositories against current infrastructure baselines. Choose between the Rsbuild-style Rstack CLI monorepo lane and the standalone Rslib/Rslint/Rstest package lane; maintain package.json metadata, exports, dependency placement and version freshness; align ESM or dual output, Node/pnpm/TypeScript versions, formatter, CI action pins, release validation, docs, dependencies, and infra PR conventions. Use when updating rstackjs repositories, refreshing infrastructure or package manifest baselines, copying patterns from Rsbuild or maintained exemplars, or reviewing package and tooling consistency.' metadata: internal: true ---

<!-- cspell:words oxfmt -->

# Rstack Repo Maintain

## Overview

Modernize RstackJS repositories without blindly copying config. Use the target's compatibility surface plus current exemplar repositories to make small, verifiable infrastructure upgrades.

## Baseline Evidence

Read `references/repo-baselines.md` when choosing a template repo, explaining where the baseline came from, or deciding between pure ESM and dual output, standalone tools and Rstack CLI, runtime floors, TypeScript majors, formatters, package validation, or CI patterns.

Read `references/package-json-baseline.md` when auditing or changing `package.json`, checking whether dependencies are current, choosing an `@rsbuild/core` peer range, or validating published package contents.

Default starting points:

- Large monorepo and integrated-tooling baseline: `web-infra-dev/rsbuild`. Use its Rstack CLI, pnpm catalog, supply-chain, `oxfmt`, and CI patterns selectively; do not treat it as a drop-in small-package template. - Primary standalone small-package baseline: `rstackjs/rslog`. - Pure ESM and Node 20 plugin package baseline: `rstackjs/rsbuild-plugin-publint`. - Concise AGENTS.md and publint reference: `rstackjs/rslog`, after checking that its prose still matches its configs. - Additional package validation reference: `rstackjs/rsbuild-plugin-arethetypeswrong`. - Generated-artifact CLI reference: `rstackjs/prebundle`. - Dual-package compatibility reference: `rstackjs/rsbuild-plugin-virtual-module`.

Always re-check the target repo and exemplar repo before editing. The reference file is a dated snapshot, not a permanent source of truth.

## Workflow

1. **Inventory the target repo** - Read `package.json`, lockfile, `pnpm-workspace.yaml`, `.node-version`, `.rstack/**`, `rstack.config.*`, `rslib.config.*`, `rslint.config.*`, `rstest.config.*`, `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `tsconfig*.json`, `.github/workflows/*`, `README.md`, `AGENTS.md`, release config, and source entry points. - Identify package kind: library, Rsbuild/Rspack plugin, CLI, app template, test fixture, or docs package. - List current build, lint, typecheck, test, release, and package manager commands before changing them. - For published packages, map `files`, `bin`, `types`, and every `exports` target to the source or generated artifact that provides it.

2. **Choose the migration target** - Use the standalone lane for focused packages that are already clear with direct Rslib, Rslint, and Rstest configs. - Consider the Rstack CLI lane for multi-package repositories that benefit from shared build/test config, unified type-aware linting, staged-file handling, and hook setup. Require each migrated command to have an equivalent Rstack CLI path; do not add the CLI merely to match Rsbuild. - Prefer pure ESM for modern libraries and plugins when consumers can support it. - Use dual package output only as a deliberate transition when existing CommonJS consumers or public exports require it. - Treat runtime support, package exports, CLI bins, side effects, and documented deep imports as compatibility constraints.

3. **Update the infrastructure in small layers** - **Package manifest**: follow `references/package-json-baseline.md`. Select the matching core/CLI, plugin, or library profile; check metadata and published entry points; separate npm release freshness from compatibility ranges; and update the manifest and lockfile together. Use `@rsbuild/core` as live evidence, not as a field-for-field template for every package. - **Build tooling**: in the standalone lane, use Rslib, keep config minimal, set appropriate `lib.syntax`, emit declarations, and align `package.json#exports` with real output. In the integrated lane, use `rstack.config.ts`, `define.lib`, and shared `rstack/lib` config only when that reduces duplicated configuration. Add `rsbuild-plugin-publint` when the package should validate publish metadata during build. When upgrading `@rslib/core` from 0.x to `1.0.0-beta` or another v1 prerelease, follow the official [Rslib v0-to-v1 upgrade guide](https://v1.rslib.rs/zh/guide/upgrade/v0-to-v1) and audit every listed breaking default instead of treating it as a routine dependency bump. - **Linting**: in the standalone lane, use `@rslint/core` and `ts.configs.recommended`; add `js.configs.recommended` only when JavaScript source or config files are intentionally linted. In the integrated lane, use the repository's supported `rs lint` command and preserve type-check coverage. - **Formatting**: preserve the repository's formatter unless the migration explicitly includes formatter replacement. Current Rsbuild uses `oxfmt`, while maintained standalone packages may use Prettier or dprint. Keep generated artifacts and lock files ignored where appropriate. - **Test tooling**: prefer Rstest for JavaScript/TypeScript unit tests in Rstack repositories. When a repo still uses Vitest or Jest, use the `migrate-to-rstest` skill, map scripts and configs to `@rstest/core`, keep Playwright or other browser E2E tooling separate, and remove legacy runner deps/configs only after the migrated scope is green. - **Runtime and package manager**: verify Node support from code, dependencies, package `engines`, `.node-version`, CI, and release workflows. Update `packageManager`, pnpm engine constraints, lockfile, and CI together. Do not copy Rsbuild's Node 22 minimum into a Node 20-compatible package without a concrete runtime reason. - **pnpm policy**: for monorepos, consider catalogs, `catalogMode`, unused-catalog cleanup, peer-install policy, build-script allowlists, `minimumReleaseAge`, and strict dependency-build settings. Adopt each option only after checking install behavior, native dependencies, trusted release exceptions, and the repository's pnpm version. - **GitHub Actions**: keep `.github/workflows/*` aligned with the chosen baseline repo. Pin third-party actions to commit hashes, not floating tags, and update action pins by copying or refreshing the baseline pattern instead of inventing new pins. - **TypeScript**: choose the major supported by the target toolchain instead of applying one global version. Remove stale compiler options, prefer `target: "ES2023"` for compatible Node packages, and keep module resolution consistent with runtime output. For TypeScript 7 packages, remove the old direct `@typescript/native-preview` dependency and manual tsgo selection from Rslib config. Current Rslib automatically uses tsgo when the installed TypeScript version is 7 or later, so keep declaration generation enabled and validate emitted declarations without adding preview-specific wiring. - **Docs**: keep `README.md` focused on purpose, install, usage, options, supported runtimes, release/license links. Add a concise `AGENTS.md` in the rsbuild-style shape: Stack, Commands, Project structure, and Code style. - **Dependency cleanup**: run a repo-appropriate unused dependency check such as Knip when feasible, then remove only dependencies proven unused or misplaced. Do not add Knip as a dependency unless the repo starts using it in scripts; treat `pnpm stage` and intentional legacy tsgo tool dependencies as known false positives when applicable.

4. **Preserve behavior while modernizing** - Do not touch business logic unless the infra change requires it. - Keep compatibility breaks explicit in commit/PR notes: ESM-only output, removed exports, changed CLI behavior, or dependency placement changes. - If a repo needs multiple risky changes, split them into reviewable PR-sized batches.

5. **Prepare the infra PR** - Create the infrastructure update branch from the latest `origin/main` unless the user asks for a different base. - Use a specific PR title starting with `chore(infra):`, for example `chore(infra): adopt Rstack CLI and package validation` or `chore(infra): align build and lint tooling`. - Keep each tool update or tool configuration as its own commit unit. Use commit titles such as `chore(deps): update rslint`, `chore(infra/build): align declaration output`, or `chore(infra/ci): pin workflow actions`. - Do not mix unrelated tool changes, generated lockfile updates, and source fixes in a single commit unless the tool update requires them to stay atomic.

6. **Validate before cleanup** - Run install with the repo package manager. - Run lint, format check, typecheck if present, build, and tests. - For pnpm packages, prefer `pnpm pack --dry-run` when the repository's pnpm version supports it. Otherwise, use `pnpm pack --pack-destination <temporary-directory>` and remove the temporary archive after inspection; use `npm pack` only when npm is the target repository's package manager. Skip the separate pack command only when package inclusion rules have been inspected, every published entry is provably included, and an enforcing `pluginPublint` in `rslib.config.ts` has completed in a successful non-watch build. Do not take this shortcut when inclusion is uncertain, the plugin is disabled, conditional activation was not satisfied, `throwOn: 'never'` is set, only a watch build ran, or the task explicitly requires tarball inspection. Never run `pnpm pack` without `--dry-run`, `--pack-destination`, or another explicit output path in the target working tree because it writes a `.tgz` there. - Smoke test import/CLI paths that changed. - When migrating to Rstack CLI, compare generated package artifacts and test discovery with the pre-migration commands. - Remove obsolete configs and dependencies only after the new path is green.

## Output

When reporting back, include:

- Target baseline and why it was chosen. - Files changed, grouped by build/lint/TypeScript/CI/docs/dependencies. - Breaking changes or compatibility risks. - Commands run and their result. - Any deliberate deviations from the Rstack baseline.