diff --git a/AGENTS.md b/AGENTS.md index fe0a623..2349857 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ A collection of Agent Skills for the Rspack ecosystem (Rspack, Rsbuild, Rslib, R ``` agent-skills/ ├── skills/ # Skills directory, contains all Skills +├── dev-skills/ # Developer-facing Skills for Rstack repository maintenance ├── packages/ # Source code projects for complex scripts ├── scripts/ # Project-level configurations and tools │ └── config/ # Common configurations (rslib, tsconfig, etc.) @@ -25,6 +26,8 @@ agent-skills/ - **skills/**: Contains all Skills, each Skill is an independent folder - Each Skill includes `SKILL.md` (required), `scripts/` (optional), `references/` (optional), `assets/` (optional) +- **dev-skills/**: Contains Skills used for Rstack repository maintenance + - These Skills are primarily for repository developers and maintainers, not end users - **packages/**: Contains source code for complex scripts that need compilation - Corresponds to Skills with the same name in the skills directory - Compiled by Rslib and output to the corresponding `skills/{skill-name}/scripts/` directory diff --git a/dev-skills/rstack-repo-maintain/SKILL.md b/dev-skills/rstack-repo-maintain/SKILL.md new file mode 100644 index 0000000..308a495 --- /dev/null +++ b/dev-skills/rstack-repo-maintain/SKILL.md @@ -0,0 +1,78 @@ +--- +name: rstack-repo-maintain +description: 'Audit and modernize RstackJS/Rspack ecosystem repositories to the current shared infrastructure baseline: Rslib ESM or dual builds, Rslint recommended rules, Rstest test tooling, Node 20+ support where appropriate, TypeScript 6 and tsgo where compatible, concise README/AGENTS docs, release workflow cleanup, unused dependency removal, and infra PR commit conventions. Use when updating rstackjs repositories, copying infra patterns from maintained exemplars, or reviewing package/tooling consistency.' +metadata: + internal: true +--- + +# Rstack Repo Maintain + +## Overview + +Modernize RstackJS repositories without blindly copying config. Use current repository state and recently maintained exemplar repos 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 whether a migration should be pure ESM, dual package, Node 20+, TypeScript 6, Rslint, Rstest, or tsgo. + +Default starting points: + +- Primary small-package baseline: `rstackjs/rslog`. +- Pure ESM and Node 20 plugin package baseline: `rstackjs/rsbuild-plugin-publint`. +- Concise AGENTS.md and tsgo/publint reference: `rstackjs/rslog`. +- Additional package validation reference: `rstackjs/rsbuild-plugin-arethetypeswrong`. +- Additional Rslib `dts.tsgo` implementation 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, `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. + +2. **Choose the migration target** + - 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** + - **Rslib**: use `rslib` for builds, keep config minimal, set appropriate `lib.syntax`, emit declarations, and align `package.json#exports` with real output. Add `rsbuild-plugin-publint` when the package should validate publish metadata during build. + - **Rslint**: use `@rslint/core`; use `ts.configs.recommended` for TypeScript packages. Add `js.configs.recommended` only when JavaScript source or config files are intentionally linted. + - **Prettier**: if the repo already carries Prettier or should check formatting, wire it into lint scripts with the repo's established style (`prettier --check .` / `prettier --write .` or `-c` / `-w`) and keep generated artifacts ignored by `.prettierignore`. + - **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. + - **Node/CI**: verify the effective Node support policy from code, dependencies, CI, and release workflows. Do not blindly add a Node 20 matrix or an extra CI build step when the maintained baseline intentionally keeps CI latest-only for speed or already builds in release. + - **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**: upgrade to TypeScript 6, remove stale/deprecated compiler options, prefer `target: "ES2023"` for Node 20+ packages, and keep module resolution consistent with runtime output. + - **tsgo**: enable Rslib declaration `dts: { tsgo: true }` only after checking compatibility with declaration bundling, package shape, and installed `@typescript/native-preview`. Pin native-preview to an exact version and validate emitted declarations plus package contents. + - **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 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): enable tsgo 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 to 0.6.1`, `chore(infra/tsgo): enable tsgo declaration build`, 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, typecheck if present, build, and tests. + - Run `npm pack --dry-run` or the repo's publish dry-run path for packages. + - Smoke test import/CLI paths that changed. + - 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. diff --git a/dev-skills/rstack-repo-maintain/references/repo-baselines.md b/dev-skills/rstack-repo-maintain/references/repo-baselines.md new file mode 100644 index 0000000..913052f --- /dev/null +++ b/dev-skills/rstack-repo-maintain/references/repo-baselines.md @@ -0,0 +1,159 @@ +# Rstack Repository Baselines + +Snapshot date: 2026-06-24. +Primary `rslog` baseline last verified from `origin/main` on 2026-06-24 at commit `25dc20d3402efc3c3104f776a97a81cf9829be67`. + +This reference is based on public GitHub PR and repository inspection under `rstackjs/*`. Re-check current main branches before applying these patterns. Secondary reference sections remain at the 2026-06-24 snapshot unless explicitly noted. + +## Primary Baseline: rstackjs/rslog + +Use `rslog` as the primary maintained baseline when modernizing a small Rstack package. + +Why it is the best first template: + +- It has the strongest maintenance signal among inspected candidates. +- It shows the full migration history from Rslib to pure ESM, Node 20+, Rslint, TypeScript 6, and CI cleanup. +- Its current package shape is simple enough to copy: `type: "module"`, explicit `exports["."].types` and default ESM entry, `files: ["dist"]`, `build: "rslib"`, `lint: "rslint && prettier --check ."`, `lint:write`, `test: "rstest"`, and `packageManager: "pnpm@11.6.0"`. +- Current `rslib.config.ts` uses `syntax: "es2023"`, `dts: { tsgo: true }`, and `pluginPublint()`. +- Current `rslint.config.ts` ignores generated `dist` output and keeps `ts.configs.recommended` with no rule overrides because the package is TypeScript-only. +- Current `rstest.config.ts` enables `globals: true`. +- Current `tsconfig.json` uses `rootDir: "./src"`, `outDir: "./dist"`, `target: "ES2023"`, `module: "nodenext"`, `moduleResolution: "nodenext"`, and `types: ["node", "@rstest/core/globals"]`. +- Current dependency pins include `@rslib/core@^0.22.1`, `@rslint/core@^0.6.1`, `@rstest/core@^0.10.4`, `typescript@^6.0.3`, `rsbuild-plugin-publint@^1.0.0`, and exact `@typescript/native-preview@7.0.0-dev.20260615.1`. +- Current `AGENTS.md` follows the concise rsbuild-style structure: Stack, Commands, Project structure, and Code style. +- Current `.prettierignore` is intentionally minimal: `dist` and `pnpm-lock.yaml`. +- CI intentionally keeps an Ubuntu-only Node `24.16.0` test workflow that runs lint and tests, with no separate build step in test CI. +- Release CI builds before `pnpm stage publish --no-git-checks`, uses OIDC, and keeps `contents: read` plus `id-token: write`. +- Current workflows pin `actions/checkout`, `actions/setup-node`, and `pnpm/action-setup` to commit hashes with version comments, set `package-manager-cache: false` in setup-node, and let `pnpm/action-setup` handle installation with `run_install: true`. + +Useful PRs: + +- [#23 chore(build): switch to Rslib](https://github.com/rstackjs/rslog/pull/23) +- [#33 chore: migrate to Rstest](https://github.com/rstackjs/rslog/pull/33) +- [#43 chore: remove unused @microsoft/api-extractor dependency](https://github.com/rstackjs/rslog/pull/43) +- [#59 feat!: transform to pure ESM package and requires Node 20+](https://github.com/rstackjs/rslog/pull/59) +- [#74 chore: add Rslint as linter](https://github.com/rstackjs/rslog/pull/74) +- [#76 chore: update TypeScript to v6 and adjust tsconfig settings](https://github.com/rstackjs/rslog/pull/76) +- [#77 chore: update tsconfig](https://github.com/rstackjs/rslog/pull/77) +- [#89 chore: optimize CI pnpm setup](https://github.com/rstackjs/rslog/pull/89) +- [#91 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rslog/pull/91) +- [#93 chore(infra): enable tsgo, publint, and prettier checks](https://github.com/rstackjs/rslog/pull/93) + +Review-tested decisions from #93: + +- Keep `AGENTS.md` short and close to `rsbuild/AGENTS.md`; avoid a long maintenance manual. +- Do not mention formatter tools the target repo does not use; use "existing format conventions" or the repo's actual formatter. +- Keep `js.configs.recommended` out of TypeScript-only packages. +- `@typescript/native-preview` is a deliberate tsgo toolchain dependency; pin it exactly and validate the generated declarations. +- `pnpm stage publish` is a pnpm 11 builtin, not a missing dependency. +- Prefer the current `pnpm/action-setup` + `run_install: true` workflow shape for small pnpm packages; avoid reintroducing ad hoc corepack/install steps unless the target repo needs them. +- In test CI, run lint and tests, but do not add a build job just to follow a generic checklist when release CI already performs the package build. +- Knip can be used locally for dependency review, but should not be added as a devDependency unless scripted. + +## Secondary Baseline: rstackjs/rsbuild-plugin-publint + +Use `rsbuild-plugin-publint` when a plugin package needs a compact pure ESM + Node 20 example. + +Current traits: + +- `type: "module"`. +- `exports["."].types` plus ESM default entry. +- `@rslib/core`, `@rslint/core`, TypeScript 6, and Rstest. +- `rslib.config.ts` uses `syntax: "es2023"` and `dts: true`. + +Useful PRs: + +- [#32 chore: upgrade TypeScript to 6.0.2](https://github.com/rstackjs/rsbuild-plugin-publint/pull/32) +- [#40 chore: migrate linting to Rslint and Prettier](https://github.com/rstackjs/rsbuild-plugin-publint/pull/40) +- [#49 feat: pure ESM package](https://github.com/rstackjs/rsbuild-plugin-publint/pull/49) +- [#50 feat!: replace picocolors with styleText and requires Node 20](https://github.com/rstackjs/rsbuild-plugin-publint/pull/50) +- [#54 chore: optimize CI pnpm setup](https://github.com/rstackjs/rsbuild-plugin-publint/pull/54) +- [#56 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rsbuild-plugin-publint/pull/56) + +Known gaps: + +- No `AGENTS.md` in current main at snapshot time. +- No Rslib `dts.tsgo` in current main at snapshot time. + +## Package Validation Reference: rstackjs/rsbuild-plugin-arethetypeswrong + +Use `rsbuild-plugin-arethetypeswrong` as an additional package validation and staged publishing reference. Use `rslog`, not this repo, as the current AGENTS.md shape. + +Current traits: + +- `type: "module"`. +- Rslib build, Rslint, TypeScript 6, and Rstest. +- `rslint.config.ts` enables both `js.configs.recommended` and `ts.configs.recommended`. +- Has `AGENTS.md` and README. +- Rslib config includes `rsbuild-plugin-publint` and bundled declarations. + +Useful PRs: + +- [#49 chore: switch to npm staged publishing](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/49) +- [#51 chore: build before stage publish](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/51) +- [#55 chore: optimize CI pnpm setup](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/55) +- [#58 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/58) + +Known gaps: + +- Rslib output syntax is `es2022`, not `es2023`, at snapshot time. +- No Rslib `dts.tsgo` in current main at snapshot time. + +## High-Activity Reference: rstackjs/prebundle + +Use `prebundle` as a high-activity reference when maintaining a CLI/build-tool style package with generated artifacts. + +Current traits: + +- High maintenance activity at snapshot time. +- Rslib build, Rslint, TypeScript 6, Rstest, README, and `AGENTS.md`. +- `rslint.config.ts` enables both `js.configs.recommended` and `ts.configs.recommended`. + +Useful PRs: + +- [#10 refactor: use Rslib to bundle](https://github.com/rstackjs/prebundle/pull/10) +- [#37 chore: enable npm trusted publishing](https://github.com/rstackjs/prebundle/pull/37) +- [#62 chore: upgrade TypeScript to ^6.0.2](https://github.com/rstackjs/prebundle/pull/62) +- [#72 chore: add Rslint linting](https://github.com/rstackjs/prebundle/pull/72) +- [#81 chore: optimize CI pnpm setup](https://github.com/rstackjs/prebundle/pull/81) +- [#83 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/prebundle/pull/83) + +Known gaps: + +- Rslib syntax is `es2021`, so do not copy it for Node 20+/ES2023 packages without checking why. + +## tsgo Reference: rstackjs/rsbuild-plugin-virtual-module + +Use `rsbuild-plugin-virtual-module` only as a concrete Rslib `tsgo` configuration reference. + +Current traits: + +- `rslib.config.ts` uses `dts: { tsgo: true }`. +- `@typescript/native-preview` is installed. +- Dual package output is still present. + +Relevant PR: + +- [#28 chore: update infrastructure for tsgo](https://github.com/rstackjs/rsbuild-plugin-virtual-module/pull/28) + +Important caveat: + +- Treat this repo as implementation evidence for Rslib tsgo, not as the primary small-package baseline. + +## Search Notes + +Searches used: + +- `type:pr org:rstackjs rslib` +- `type:pr org:rstackjs rslint` +- `type:pr org:rstackjs "typescript 6"` +- `type:pr org:rstackjs "Node 20"` +- `type:pr org:rstackjs AGENTS` +- `type:pr org:rstackjs README` +- `type:pr org:rstackjs "optimize CI"` +- `type:pr org:rstackjs knip` + +Findings: + +- No repo-owned scripted Knip baseline was found in the sampled search results. +- `rslog` now provides the reviewed tsgo + publint baseline for small packages; `rsbuild-plugin-virtual-module` remains useful only as an additional implementation reference. +- Some heavily maintained packages intentionally remain dual package or use lower output syntax; copy only after checking consumer compatibility.