From 64dc09536c8741c6929dd4dee0eaf8765a496b4b Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 30 Aug 2026 20:37:57 +0800 Subject: [PATCH 1/3] docs: add Lefthook migration guide --- .agents/skills/migrate-to-rstack-cli/SKILL.md | 4 ++-- .../migrate-to-rstack-cli/references/git-hooks.md | 10 +++++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.agents/skills/migrate-to-rstack-cli/SKILL.md b/.agents/skills/migrate-to-rstack-cli/SKILL.md index 01612d1..d884431 100644 --- a/.agents/skills/migrate-to-rstack-cli/SKILL.md +++ b/.agents/skills/migrate-to-rstack-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: migrate-to-rstack-cli -description: Use when migrating projects from standalone Rsbuild, Rslib, Rstest, Rslint, Rspress, Prettier, sort-package-json, lint-staged, husky, or simple-git-hooks tooling to the unified `rstack` package, `rs` commands, and `rstack.config.*`. +description: Use when migrating projects from standalone Rsbuild, Rslib, Rstest, Rslint, Rspress, Prettier, sort-package-json, lint-staged, husky, lefthook, or simple-git-hooks tooling to the unified `rstack` package, `rs` commands, and `rstack.config.*`. --- # Migrate to Rstack CLI @@ -18,7 +18,7 @@ Read every matching reference before editing. Load only the tools present in the - `prettier`, `package.json#prettier`, `.prettierrc*`, `prettier.config.*`, `.prettierignore`, `.editorconfig`, `sort-package-json`, Prettier plugins, or formatting scripts: [prettier.md](references/prettier.md) - `@rspress/core`, `rspress.config.*`, `rspress` commands, themes, or plugins: [rspress.md](references/rspress.md) - `lint-staged`, `nano-staged`, their configs: [lint-staged.md](references/lint-staged.md) -- `husky`, `.husky/`, `package.json#husky`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md) +- `husky`, `.husky/`, `package.json#husky`, `lefthook`, `lefthook*.{yml,yaml,json,jsonc,toml}`, `.lefthook*`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md) ## Workflow diff --git a/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md b/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md index 35e01c2..8df4242 100644 --- a/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md +++ b/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md @@ -1,6 +1,6 @@ # Git Hook Migration -Migrate [Husky](https://typicode.github.io/husky/) or [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks#readme) to [`rs hooks`](https://rstack.rs/guide/cli/hooks). If a hook calls lint-staged or nano-staged, also read [lint-staged.md](lint-staged.md). +Migrate [Husky](https://typicode.github.io/husky/), [Lefthook](https://lefthook.dev/), or [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks#readme) to [`rs hooks`](https://rstack.rs/guide/cli/hooks). If a hook works with staged files, also read [lint-staged.md](lint-staged.md). ## Shared Steps @@ -38,6 +38,14 @@ to: pnpm test ``` +## Lefthook + +1. Resolve the merged configuration, including main and local files, `LEFTHOOK_CONFIG`, `extends` or remote configs, lifecycle scripts, and direct `lefthook run` calls. Treat ignored local configs as user-owned. +2. Create one Rstack file per Git hook. Rstack runs it with POSIX `sh -e` and forwards arguments and standard input. Replace templates such as `{1}` with `"$1"`; move custom Lefthook groups to project scripts. +3. Move `pre-commit` tasks using `{staged_files}`, `stage_fixed`, `glob`, or `exclude` to `define.staged`, and run `rs staged` from `.rstack/hooks/pre-commit`; it passes matched files and stages successful fixes. Recreate the intended file set instead of copying globs: Lefthook's default `**` semantics differ from lint-staged. Preserve exclusions such as unsupported symlinks. +4. For `{push_files}`, `{all_files}`, custom `{files}`, or orchestration such as `parallel` and `piped`, call a project helper from the hook. It should consume all `pre-push` ref updates, apply the original conditions, preserve concurrency or ordering, and aggregate failures. For a configuration like Rstest's, run the format/spell check always, skip type checking only for Markdown-only pushes, and run the dependency check only for pushed package manifests. Do not substitute a fixed `HEAD^` diff. +5. Replace `lefthook install` with `rs hooks` and `LEFTHOOK=0` with `RSTACK_HOOKS=0`. After validation, remove Lefthook configs, dependencies, generated hooks, and pnpm build metadata such as `allowBuilds`, `onlyBuiltDependencies`, or `ignoredBuiltDependencies`. Remove local-config ignore rules only when no longer needed. + ## simple-git-hooks 1. Load the active configuration from `package.json#simple-git-hooks`, a `.simple-git-hooks.{js,cjs,mjs,json}` or `simple-git-hooks.{js,cjs,mjs,json}` file, or the custom path passed to its CLI. Use the configuration values instead of copying generated files from the Git hooks directory. From 0e80e26f3929044fe3a9795ae755dd7bac0f35f0 Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 30 Aug 2026 20:56:14 +0800 Subject: [PATCH 2/3] docs: simplify Lefthook migration routing --- .agents/skills/migrate-to-rstack-cli/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/migrate-to-rstack-cli/SKILL.md b/.agents/skills/migrate-to-rstack-cli/SKILL.md index d884431..11286a9 100644 --- a/.agents/skills/migrate-to-rstack-cli/SKILL.md +++ b/.agents/skills/migrate-to-rstack-cli/SKILL.md @@ -18,7 +18,7 @@ Read every matching reference before editing. Load only the tools present in the - `prettier`, `package.json#prettier`, `.prettierrc*`, `prettier.config.*`, `.prettierignore`, `.editorconfig`, `sort-package-json`, Prettier plugins, or formatting scripts: [prettier.md](references/prettier.md) - `@rspress/core`, `rspress.config.*`, `rspress` commands, themes, or plugins: [rspress.md](references/rspress.md) - `lint-staged`, `nano-staged`, their configs: [lint-staged.md](references/lint-staged.md) -- `husky`, `.husky/`, `package.json#husky`, `lefthook`, `lefthook*.{yml,yaml,json,jsonc,toml}`, `.lefthook*`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md) +- `husky`, `.husky/`, `package.json#husky`, `lefthook`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md) ## Workflow From 687355dc8e7cc24e9ee2138cc44eca663c75ea46 Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 30 Aug 2026 21:08:04 +0800 Subject: [PATCH 3/3] docs: preserve unrelated pnpm build policies --- .agents/skills/migrate-to-rstack-cli/references/git-hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md b/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md index 8df4242..e625154 100644 --- a/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md +++ b/.agents/skills/migrate-to-rstack-cli/references/git-hooks.md @@ -44,7 +44,7 @@ pnpm test 2. Create one Rstack file per Git hook. Rstack runs it with POSIX `sh -e` and forwards arguments and standard input. Replace templates such as `{1}` with `"$1"`; move custom Lefthook groups to project scripts. 3. Move `pre-commit` tasks using `{staged_files}`, `stage_fixed`, `glob`, or `exclude` to `define.staged`, and run `rs staged` from `.rstack/hooks/pre-commit`; it passes matched files and stages successful fixes. Recreate the intended file set instead of copying globs: Lefthook's default `**` semantics differ from lint-staged. Preserve exclusions such as unsupported symlinks. 4. For `{push_files}`, `{all_files}`, custom `{files}`, or orchestration such as `parallel` and `piped`, call a project helper from the hook. It should consume all `pre-push` ref updates, apply the original conditions, preserve concurrency or ordering, and aggregate failures. For a configuration like Rstest's, run the format/spell check always, skip type checking only for Markdown-only pushes, and run the dependency check only for pushed package manifests. Do not substitute a fixed `HEAD^` diff. -5. Replace `lefthook install` with `rs hooks` and `LEFTHOOK=0` with `RSTACK_HOOKS=0`. After validation, remove Lefthook configs, dependencies, generated hooks, and pnpm build metadata such as `allowBuilds`, `onlyBuiltDependencies`, or `ignoredBuiltDependencies`. Remove local-config ignore rules only when no longer needed. +5. Replace `lefthook install` with `rs hooks` and `LEFTHOOK=0` with `RSTACK_HOOKS=0`. After validation, remove Lefthook configs, dependencies, generated hooks, and its entries from pnpm build metadata such as `allowBuilds`, `onlyBuiltDependencies`, or `ignoredBuiltDependencies`. Preserve unrelated entries, and remove a setting only if it becomes empty. Remove local-config ignore rules only when no longer needed. ## simple-git-hooks