@kirill.konshin/lint 0.7.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +160 -113
  2. package/dist/config.d.ts +103 -0
  3. package/dist/config.js +112 -0
  4. package/dist/configs/base.d.ts +1 -1
  5. package/dist/configs/nx.d.ts +1 -1
  6. package/dist/configs/nx.js +3 -8
  7. package/dist/configs/react.d.ts +3 -3
  8. package/dist/configs/react.js +6 -16
  9. package/dist/configs/storybook.d.ts +3 -3
  10. package/dist/configs/storybook.js +4 -9
  11. package/dist/configs/tailwind.d.ts +6 -25
  12. package/dist/configs/tailwind.js +3 -64
  13. package/dist/configs/testing.d.ts +1 -1
  14. package/dist/configs/testing.js +3 -15
  15. package/dist/configs/turbo.d.ts +2 -2
  16. package/dist/configs/turbo.js +4 -6
  17. package/dist/configs/typescriptTypeAware.d.ts +1 -1
  18. package/dist/gates.d.ts +72 -0
  19. package/dist/gates.js +132 -0
  20. package/dist/index.d.ts +15 -51
  21. package/dist/index.js +16 -14
  22. package/dist/lib.d.ts +1 -1
  23. package/dist/lib.js +1 -1
  24. package/dist/lintPrepare.d.ts +75 -28
  25. package/dist/lintPrepare.js +243 -35
  26. package/dist/testColocation.js +1 -1
  27. package/dist/vitePlus.d.ts +8 -18
  28. package/dist/vitePlus.js +40 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/auth.md +3 -3
  32. package/rules/db.md +6 -9
  33. package/rules/expo.md +2 -0
  34. package/rules/github.md +1 -1
  35. package/rules/gitlab.md +1 -1
  36. package/rules/i18n.md +3 -0
  37. package/rules/monorepo-turbo-nx.md +38 -4
  38. package/rules/mui.md +8 -18
  39. package/rules/nextjs.md +13 -13
  40. package/rules/npm-yarn.md +28 -118
  41. package/rules/nx.md +1 -1
  42. package/rules/playwright.md +1 -1
  43. package/rules/react.md +7 -32
  44. package/rules/tailwind.md +9 -47
  45. package/rules/testing.md +2 -2
  46. package/rules/turbo.md +1 -1
  47. package/rules/typescript.md +6 -2
  48. package/rules/ui-kit.md +6 -0
  49. package/rules/vite.md +1 -1
  50. package/skills/lint-db/SKILL.md +23 -0
  51. package/skills/lint-electron/SKILL.md +9 -6
  52. package/skills/lint-github/SKILL.md +15 -8
  53. package/skills/lint-gitlab/SKILL.md +20 -5
  54. package/skills/lint-migrate/SKILL.md +18 -2
  55. package/skills/lint-mui/SKILL.md +28 -0
  56. package/skills/lint-nextjs/SKILL.md +53 -16
  57. package/skills/lint-npm-yarn/SKILL.md +126 -0
  58. package/skills/lint-repo/SKILL.md +12 -12
  59. package/skills/lint-tailwind/SKILL.md +53 -0
  60. package/skills/lint-webstorm/SKILL.md +3 -3
  61. package/skills/lint-worktree/SKILL.md +25 -9
  62. package/skills/spec-author/SKILL.md +2 -2
  63. package/skills/spec-steward/SKILL.md +1 -1
  64. package/skills/spec-steward/references/apply.md +1 -1
  65. package/skills/spec-steward/references/contract.md +2 -2
  66. package/skills/spec-steward/references/model.md +2 -2
  67. package/skills/spec-steward/references/review-format.md +4 -4
  68. package/skills/spec-steward/references/wiring.md +2 -2
  69. package/skills/spec-steward/references/worker.md +1 -1
  70. package/skills/spec-tools/SKILL.md +2 -2
  71. package/skills/spec-tools/references/rules/common.md +1 -1
  72. package/skills/spec-tools/references/rules/spec-steward.md +1 -1
  73. package/skills/spec-tools/scripts/cli.js +2 -2
  74. package/skills/spec-verify/SKILL.md +1 -1
@@ -3,16 +3,20 @@ type: always_apply
3
3
  description: Set of rules for projects with TypeScript, and partially applicable to plain JavaScript
4
4
  paths:
5
5
  - '**/*.js'
6
+ - '**/*.jsx'
6
7
  - '**/*.mjs'
7
8
  - '**/*.cjs'
8
9
  - '**/*.ts'
9
10
  - '**/*.tsx'
11
+ - '**/*.mts'
12
+ - '**/*.cts'
10
13
  ---
11
14
 
12
15
  - ALL projects must use TypeScript by default
13
- - JavaScript is acceptable for service scripts, but discouraged, use `ts-node`
16
+ - JavaScript is acceptable for service scripts, but discouraged; run TypeScript scripts with `node script.ts` (Node type stripping)
14
17
  - Do NOT upgrade to TypeScript 7 while tools load the TypeScript JS API (typescript-eslint, ctix, `@arethetypeswrong/core`, Storybook docgen, Next.js type checks, `spec-tools`): TS 7 ships only an unstable API; use its engine through Vite+ type-aware checks
15
- - With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlusConfig` has `typeAware` on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
18
+ - With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlus.typeAware` of `lint.config.ts` is on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
19
+ - In Next.js apps, server-only modules (auth/session, DB access, anything touching secrets, `'use server'` actions files) MUST start with `import 'server-only'` (the npm package, add as dependency) — ENFORCED BY AGENT: no ESLint rule checks this, add it when creating such modules and flag it when reviewing
16
20
  - ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
17
21
  - Prefer short-circuit evaluation and early exit
18
22
  - Use structured logging with context, consider adding function arguments to log:
package/rules/ui-kit.md CHANGED
@@ -1,6 +1,12 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: Rules for UI kits
4
+ paths:
5
+ - '**/*.tsx'
6
+ - '**/*.css'
7
+ - '**/*.sass'
8
+ - '**/*.scss'
9
+ - '**/*.less'
4
10
  ---
5
11
 
6
12
  - Follow UI kit docs and primitives; preserve semantics and accessibility
package/rules/vite.md CHANGED
@@ -8,7 +8,7 @@ paths:
8
8
 
9
9
  # Vite+ (vite-plus, vp)
10
10
 
11
- - Prefer [Vite+](https://viteplus.dev) (`vite-plus`, `vp` CLI): `defineConfig` from `vite-plus`, root config from `vitePlusConfig` (`@kirill.konshin/lint/vite-plus`), see the package README
11
+ - Prefer [Vite+](https://viteplus.dev) (`vite-plus`, `vp` CLI): `defineConfig` from `vite-plus`, root `vite.config.ts` is `defineConfig(vitePlusConfig())` (`@kirill.konshin/lint/vite-plus`), settings and project blocks in `lint.config.ts`, see the package README
12
12
  - Libraries build with `vp pack` (`pack` block, tsdown), apps with `vp build`, tests run with `vp test` and import from `vite-plus/test`
13
13
  - Keep `lint`/`fmt` in the root config only; per-package settings go to `lint.overrides`/`fmt.overrides`
14
14
 
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: lint-db
3
+ description: Database procedures for the db rule - LocalStorage / IndexedDB to server migrations, transactional importers, one-off data transfers, steps after a schema change, Neon Auth folded into Iron Session. Use when migrating or importing data, changing a schema, or adding Neon Auth.
4
+ ---
5
+
6
+ The binding rules are in [rules/db.md](../../rules/db.md). This skill holds the procedures.
7
+
8
+ # Migrations and Imports
9
+
10
+ - For LocalStorage or IndexedDB migrations, keep the behavior; improve the schema when normalization or consolidation is clearly safer.
11
+ - Make importers transactional, validated, idempotent and count-verifiable.
12
+ - Keep one-off data transfers out of the permanent migration machinery. Verify the source, the destination, the schema, the counts and the runtime connectivity.
13
+ - After a schema change: generate the migrations, confirm no drift, migrate a disposable database in the tests, then run typecheck, build and tests.
14
+
15
+ # Neon
16
+
17
+ Only when the user asks for Neon, or the project already uses it. Drivers, connection strings, branches and migrations: the `neon-postgres` skill and the `neon-postgres-branches` skill; the driver plumbing lives in `@kirill.konshin/db`.
18
+
19
+ Neon Auth: set it up per the `neon-auth` skill, then fold it into Iron Session ([rules/auth.md](../../rules/auth.md)):
20
+
21
+ 1. Link the Neon identity to the app user on the server.
22
+ 2. Store the app context in the sealed Iron Session.
23
+ 3. Clear the transient Neon session.
@@ -44,9 +44,11 @@ export default defineConfig({
44
44
 
45
45
  Scripts: `"start": "vp pack --watch"`, `"build:main": "vp pack"`.
46
46
 
47
+ This is the `vite.config.ts` of the Electron app's own workspace package. When the app is the workspace root, the root `vite.config.ts` stays `defineConfig(vitePlusConfig())`: put the `pack` block under the `vitePlus` key of `lint.config.ts` (`vitePlus: { pack: { … } }`).
48
+
47
49
  # Packaging a Next.js Standalone Server
48
50
 
49
- In a hoisted workspace (see npm-yarn rule) Next.js traces the server's dependencies into `.next/standalone/node_modules`, beside the app folder; package both, without Electron:
51
+ In a hoisted workspace (see [rules/npm-yarn.md](../../rules/npm-yarn.md#hoisting)) Next.js traces the server's dependencies into `.next/standalone/node_modules`, beside the app folder; package both, without Electron:
50
52
 
51
53
  ```yaml
52
54
  files:
@@ -60,20 +62,21 @@ files:
60
62
 
61
63
  ## Gitlab
62
64
 
65
+ Base the pipeline on the `lint-gitlab` skill (Corepack, install, cache). The Electron build job adds:
66
+
63
67
  ```yml
64
68
  variables:
65
69
  USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
66
70
 
67
71
  build:
68
- image: macos-12-xcode-13 # not exact version, but the point is to use macos-compatible image
72
+ image: <current GitLab macOS image> # a macOS runner builds and signs mac targets
69
73
  tags:
70
- - shared-macos-amd64
74
+ - <macOS runner tag>
71
75
  script:
72
- - yarn --immutable
73
76
  - yarn build
74
77
  - rm -rf electron/dist/mac # some cleanup to make artifacts leaner
75
- only:
76
- - master
78
+ rules:
79
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
77
80
  artifacts:
78
81
  paths:
79
82
  - electron/dist
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  name: lint-github
3
- description: Describes how to work with Github & example workflow as a reference which essential jobs and concepts usual Github Workflow should have
3
+ description: Reference GitHub Actions setup - composite setup and Nx-cache actions, install / lint / test / build / release jobs, Yarn and Nx Cloud caching, OIDC npm publishing. Use when writing, reviewing or debugging a `.github` workflow or action.
4
4
  ---
5
5
 
6
- Reference CI: two local composite actions and a workflow. Install and cache rules: npm-yarn.md "Install on CI" and github.md.
6
+ Reference CI: two local composite actions and a workflow. Install and cache rules: [rules/npm-yarn.md](../../rules/npm-yarn.md#install-on-ci) and [rules/github.md](../../rules/github.md).
7
7
 
8
8
  - The `install` job fills the Yarn cache (`setup` with `yarn-cache: warm`).
9
9
  - The checks run after it as parallel jobs. They only restore the cache (`yarn-cache: restore`).
10
10
  - The publish job needs all checks.
11
11
  - A workflow with one job, or with jobs that run one after another, has no `install` job. It uses the default `yarn-cache: save`.
12
- - Self-hosted runners with a shared cache volume: remove the `Use local Yarn cache` step and the Yarn cache steps from `setup` (npm-yarn.md "Install on CI").
12
+ - Self-hosted runners with a shared cache volume: remove the `Use local Yarn cache` step and the Yarn cache steps from `setup` (the `lint-npm-yarn` skill, "Install on CI").
13
13
 
14
14
  # With Nx Cloud (`nxCloudId` in `nx.json`)
15
15
 
@@ -182,8 +182,6 @@ runs:
182
182
  shell: bash
183
183
 
184
184
  # If project uses Turbo
185
- #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
186
- #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
187
185
  # One entry per commit when jobs run one after another; for parallel jobs add ${{ github.job }} to key and restore key (only the first job that saves a key keeps its outputs)
188
186
  - name: Cache Turbo
189
187
  if: inputs.yarn-cache != 'warm'
@@ -215,6 +213,16 @@ runs:
215
213
  path: .yarn/cache
216
214
  key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
217
215
 
216
+ # If project uses Vite+ tasks (`vp run`): experimental, measure first (npm-yarn.md "Install on CI"); after install,
217
+ # a rolling key, no sources or lockfiles in it - Vite Task fingerprints them
218
+ - name: Cache Vite+ tasks
219
+ if: inputs.yarn-cache != 'warm'
220
+ uses: actions/cache@v6
221
+ with:
222
+ path: node_modules/.vite/task-cache
223
+ key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}
224
+ restore-keys: vite-task-${{ runner.os }}-${{ runner.arch }}-
225
+
218
226
  # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
219
227
  - name: Prepare
220
228
  if: inputs.yarn-cache != 'warm'
@@ -329,9 +337,8 @@ jobs:
329
337
 
330
338
  needs: [lint, test, build]
331
339
 
332
- # If project publishes to NPM
333
- # https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
334
- if: github.repository == 'kirill-konshin/utils'
340
+ # If project publishes to NPM; forks skip the release
341
+ if: github.repository == '<owner>/<repo>'
335
342
  permissions:
336
343
  id-token: write # Required for OIDC trusted publishing
337
344
  contents: write
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-gitlab
3
- description: Describes how to work with Gitlab Pipelines & example pipeline as a reference which essential jobs and concepts usual Gitlab project should have
3
+ description: Reference GitLab CI pipeline - install / lint / test (coverage) / e2e / build jobs, Yarn, Nx and Vite+ task caches, Nx Cloud tokens, a shared cache volume. Use when writing, reviewing or debugging `.gitlab-ci.yml`.
4
4
  ---
5
5
 
6
6
  # With Nx Cloud (`nxCloudId` in `nx.json`)
@@ -56,6 +56,7 @@ cache:
56
56
  - '**/.tscache'
57
57
  - '**/.tsbuildinfo'
58
58
  - '**/.next/cache'
59
+ - node_modules/.vite/task-cache # Vite+ tasks (`vp run`): experimental, measure first (npm-yarn.md "Install on CI")
59
60
  policy: pull-push
60
61
 
61
62
  stages:
@@ -110,7 +111,21 @@ lint:
110
111
 
111
112
  test:
112
113
  stage: test
113
- image: mcr.microsoft.com/playwright:v1.50.0-noble # keep in sync with installed Playwright version
114
+ script:
115
+ - yarn vp test run --coverage # Vite+; without Vite+: yarn test --coverage; the cobertura reporter writes the report below
116
+ coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/' # line coverage % of the text reporter, shown in merge requests
117
+ artifacts:
118
+ when: always
119
+ paths:
120
+ - coverage
121
+ reports:
122
+ coverage_report:
123
+ coverage_format: cobertura
124
+ path: coverage/cobertura-coverage.xml
125
+
126
+ e2e:
127
+ stage: test
128
+ image: mcr.microsoft.com/playwright:v1.64.1-noble # keep in sync with the installed Playwright version
114
129
  artifacts:
115
130
  when: always
116
131
  paths:
@@ -126,8 +141,8 @@ build:
126
141
  stage: build
127
142
  script:
128
143
  - yarn build
129
- only:
130
- - master
144
+ rules:
145
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
131
146
  artifacts:
132
147
  paths:
133
148
  - web/build
@@ -135,7 +150,7 @@ build:
135
150
 
136
151
  # Shared Cache Volume
137
152
 
138
- Use this when all runners mount the same volume (npm-yarn.md "Install on CI"). The packages stay on the volume. No job uploads or downloads them.
153
+ Use this when all runners mount the same volume (the `lint-npm-yarn` skill, "Install on CI"). The packages stay on the volume. No job uploads or downloads them.
139
154
 
140
155
  Runner config (Kubernetes executor, a ReadWriteMany PVC):
141
156
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-migrate
3
- description: Upgrade a project that uses @kirill.konshin/lint to a newer minor version - one section per version step (0.6 -> 0.7 moves ESLint + Prettier + lint-staged + Husky to Vite+). Use when upgrading @kirill.konshin/lint, or when asked to move a repo to Vite+ / Oxlint / Oxfmt.
3
+ description: Upgrade a project that uses @kirill.konshin/lint to a newer minor version - one section per version step (0.6 -> 0.7 moves ESLint + Prettier + lint-staged + Husky to Vite+; 0.7 -> 0.8 moves all settings into one lint.config.ts and installs skills with the skills CLI). Use when upgrading @kirill.konshin/lint, or when asked to move a repo to Vite+ / Oxlint / Oxfmt.
4
4
  ---
5
5
 
6
6
  # Lint Migrate
@@ -11,9 +11,25 @@ Only what changes between versions; the target setup is the package README (`nod
11
11
  2. Apply each section from the installed version up to the target, in order; reconcile, never overwrite project settings
12
12
  3. Run the `lint-repo` skill: set up / update tooling (checks every file against the README), then its audit
13
13
 
14
+ # 0.7 -> 0.8
15
+
16
+ All settings move into one `lint.config.ts` in the workspace root (README "`lint.config.ts`"). `lint-prepare` installs the skills with the `skills` CLI (README "How it works"), not with its own links.
17
+
18
+ - **Prerequisites**: Node `^22.18` or later (Node loads `lint.config.ts` with type stripping); `"type": "module"` in the root `package.json` (check that root `.js` files are ESM, rename CommonJS ones to `.cjs`)
19
+ - **Write** `lint.config.ts` by hand from the options the configs pass today, also when every option is a default (`defineLintConfig({})`); import `defineLintConfig` (and `tsExts`, `scanWorkspace`) from `@kirill.konshin/lint/config`
20
+ - `vitePlusConfig(config, toggles)`: toggles → top-level keys; `typeAware` → `vitePlus.typeAware`; the `config` blocks (`lint`, `fmt`, `staged`, `test`, …) → the `vitePlus` key; then `vite.config.ts` is `export default defineConfig(vitePlusConfig());`
21
+ - `defineLintConfig(options)` (ESLint) options → top-level keys; `typeAware` and `defaultIgnore` → `eslint.typeAware`, `eslint.defaultIgnore`
22
+ - A root `package.json` `skills` field → the `skills` map, keyed by source: `{ "source": "a/b", "ref": "x", "skills": ["s"] }` → `'a/b': { ref: 'x', skills: { s: true } }`; remove the field
23
+ - Per-package differences in a monorepo stay in the configs, as overrides: one `lint.config.ts` only, never one per package
24
+ - **Rewrite**: `defineLintConfig` from `@kirill.konshin/lint` (ESLint) → `eslintConfig(overrides)`; `vitePlusConfig` returns a `Promise` — keep `defineConfig(vitePlusConfig(...))`, `defineConfig` accepts it; code that reads the result awaits it; the old `VitePlusOptions` (toggles) and `LintOptions` → `LintConfig`; the name `VitePlusOptions` now types the `vitePlus` key
25
+ - **Add** `skills-lock.json` to `.gitignore`; `vite-plus` to `devDependencies` when the project does not use Vite+ (a required peer now: it types `lint.config.ts`)
26
+ - **Expect**: `lint-prepare` replaces its old skill links on the first run; on a fresh clone it fetches the default remote skills from GitHub (on CI, with `CI` set, it does not); it removes remote skills of `skills-lock.json` that `lint.config.ts` does not list
27
+ - **Remove** a copy of a default skill that the project or `~/.claude/skills` keeps by hand (e.g. from `npx skills add`): a personal skill overrides the project one, a project folder blocks the sync of that name; turn off unwanted defaults in the `skills` map instead
28
+ - **Verify**: `vp check` (or ESLint) passes with the same findings; `.agents/skills` and `.claude/skills` list the package skills and the configured skills; `git status` shows none of them
29
+
14
30
  # 0.6 -> 0.7
15
31
 
16
- 0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
32
+ 0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
17
33
 
18
34
  - **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
19
35
  - **Set up** Vite+ by hand per the README "Vite+" section — not `vp migrate`: it copies every expanded ESLint rule, writes absolute paths and broken regexes, and rewrites dependencies; if it was run, replace its `lint` / `fmt` blocks with `vitePlusConfig`
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: lint-mui
3
+ description: Our MUI conventions on top of the vendor MUI skills - class-name usage in `sx`, safe-area insets in the theme, admin pages and login with `@kirill.konshin/mui/admin`. Use when writing or reviewing code that uses MUI, or building an admin interface.
4
+ ---
5
+
6
+ The binding rules are in [rules/mui.md](../../rules/mui.md): imports, no Tailwind, Toolpad. MUI API knowledge: the `material-ui-styling` skill, the `material-ui-theming` skill and the `material-ui-nextjs` skill; where they differ, the rules win.
7
+
8
+ # Class Names
9
+
10
+ The `*Classes` names survive minification; literal `.Mui-*` classes work too.
11
+
12
+ ```tsx
13
+ import { Box, Input, inputClasses } from '@mui/material';
14
+
15
+ <Box sx={{ [`& .${inputClasses.root}`]: {}, [`& .${inputClasses.disabled}`]: {} }}>
16
+ <Input />
17
+ </Box>;
18
+ ```
19
+
20
+ # Theme
21
+
22
+ - Define safe-area insets in the theme or globally; consume them through `sx`, never through repeated `env(...)`.
23
+
24
+ # Admin Pages and Login
25
+
26
+ - Use `@kirill.konshin/mui/admin`: `AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`. It holds the Toolpad boilerplate (`@toolpad/core` is archived: add no new direct Toolpad usage).
27
+ - `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` ([rules/auth.md](../../rules/auth.md)).
28
+ - Use the built-ins of the admin layout (navigation, dialogs, notifications) before custom JSX.
@@ -1,8 +1,10 @@
1
1
  ---
2
2
  name: lint-nextjs
3
- description: Describes key patterns how to work with Next.js
3
+ description: Our Next.js App Router conventions on top of the vendor Next.js skills - typed `LayoutProps` / `PageProps`, auth-guarded layouts, `params` / `searchParams` in server and client pages, page and component file placement, what `defineNextConfig` sets in `next.config.ts`. Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
4
4
  ---
5
5
 
6
+ The binding rules are in [rules/nextjs.md](../../rules/nextjs.md). Next.js API knowledge: the docs that `next` bundles (`node_modules/next/dist/docs/`), the `next-*` skills and the `vercel-react-best-practices` skill; MUI setup: the `material-ui-nextjs` skill.
7
+
6
8
  # Layouts
7
9
 
8
10
  Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
@@ -23,32 +25,36 @@ export default function Layout({ children, analytics }: LayoutProps<'/dashboard'
23
25
 
24
26
  ## Check auth in layouts pattern
25
27
 
26
- Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't create path segment, but will protect all routes under it.
28
+ Put the auth guard in the layout of a route group, `app/(auth)/layout.tsx`: the group adds no path segment and protects every route below it.
29
+
30
+ Layouts do not protect Route Handlers: check auth in each handler too.
27
31
 
28
- Route Handlers are not protected by layouts, so add auth check there too.
32
+ Use `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md)); the guard runs inside `<Suspense>`:
29
33
 
30
34
  ```tsx
31
- import React from 'react';
32
- import { redirect } from 'next/navigation';
33
- import { getToken } from '@/lib/auth';
35
+ import { type ReactNode, Suspense } from 'react';
36
+
37
+ import { auth } from '@/auth';
38
+
39
+ export default function Layout({ children }: LayoutProps<'/dashboard'>) {
40
+ return (
41
+ <Suspense>
42
+ <Protected>{children}</Protected>
43
+ </Suspense>
44
+ );
45
+ }
34
46
 
35
- export default async function Layout({ children }: LayoutProps<'/dashboard'>) {
36
- if (!(await getToken())) {
37
- redirect('/login');
38
- }
47
+ async function Protected({ children }: { children: ReactNode }) {
48
+ await auth.redirectNonAuthenticated(); // redirects to urls.login
39
49
  return <>{children}</>;
40
50
  }
41
51
  ```
42
52
 
43
53
  # Pages
44
54
 
45
- - https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routes
46
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#rendering-with-search-params
47
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-dynamic-segment
48
-
49
- Always use https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper.
55
+ Type pages with the [`PageProps` helper](https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper). `params` and `searchParams` are Promises.
50
56
 
51
- Always use the following pattern for all pages:
57
+ A server page awaits them:
52
58
 
53
59
  ```tsx
54
60
  export default async function Page({ params, searchParams }: PageProps<'/blog/[slug]'>) {
@@ -57,3 +63,34 @@ export default async function Page({ params, searchParams }: PageProps<'/blog/[s
57
63
  return <h1>Blog post: {slug}</h1>;
58
64
  }
59
65
  ```
66
+
67
+ A client page (`'use client'`) cannot be async: unwrap them with `use()`, or read them with `useParams()` / `useSearchParams()`:
68
+
69
+ ```tsx
70
+ 'use client';
71
+
72
+ import { use } from 'react';
73
+
74
+ export default function Page({ params }: PageProps<'/blog/[slug]'>) {
75
+ const { slug } = use(params);
76
+ return <h1>Blog post: {slug}</h1>;
77
+ }
78
+ ```
79
+
80
+ # Files
81
+
82
+ - A page holds its logic and its one-off components (not exported); it may be a client page. A page that only imports one component is a dummy page.
83
+ - Reusable components go in `src/components`.
84
+ - A large one-off component may sit in `src/app` next to its page, so the page stays small; `src/components` keeps no one-offs.
85
+ - Example: `actions.ts` with `'use server'` actions beside a `'use client'` page
86
+ - Admin pages: the `lint-mui` skill.
87
+
88
+ # `next.config.ts`
89
+
90
+ `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath: Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler) sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`, …). Extra entries cost nothing; a missing one costs dev startup time and bundle size.
91
+
92
+ ```ts
93
+ import { defineNextConfig } from '@kirill.konshin/next/config';
94
+
95
+ export default defineNextConfig((defaults) => ({ ...defaults, transpilePackages: ['my-lib'] }));
96
+ ```
@@ -0,0 +1,126 @@
1
+ ---
2
+ name: lint-npm-yarn
3
+ description: Yarn / npm / pnpm details for the npm-yarn rule - hoisting edge cases (Electron, pnpm, binary packagers), version pinning templates (`overrides`, `resolutions`, Vite+ pins), `.yarnrc.yml` template, CI install on a shared cache volume and speed-ups, Yalc linking procedure, first npm publish with OIDC. Use when changing package manager configuration, CI install, local package linking or publishing a new package.
4
+ ---
5
+
6
+ The binding rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md). This skill holds the details.
7
+
8
+ # Hoisting
9
+
10
+ - Hoist everything: the historical React Native/Expo/Electron reasons for hoisting limits are obsolete (Metro follows symlinks since RN 0.72, Expo SDK 54+ supports monorepos with any strategy, hoisting limits break Electron Forge and duplicate React instances)
11
+ - Electron + pnpm needs MORE hoisting, not less: set `node-linker=hoisted` (or `shamefully-hoist=true`) in `.npmrc`, otherwise packaged apps miss dependencies (electron-builder/electron-vite guidance)
12
+ - Electron + Next.js `output: 'standalone'` in a hoisted workspace: Next.js traces dependencies into `.next/standalone/node_modules`, beside the app folder `.next/standalone/<app>` — package that folder too (electron-builder `files`), never limit hoisting for it; see the `lint-electron` skill
13
+ - Binary packagers don't need hoisting limits either: bundle to a single file first, then package — node_modules layout becomes irrelevant; build Node SEA executables with `vp pack` (`exe`, Node ≥ 25.7) when Vite+ is used, else `@yao-pkg/pkg` (maintained fork of the deprecated `vercel/pkg`); a Next.js standalone server cannot be bundled into one file: ship its files as SEA assets and extract them on the first start
14
+ - Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
15
+ - npm / Yarn: default hoisting already exposes them
16
+ - pnpm: add to `.npmrc`: `public-hoist-pattern[]=next`, `public-hoist-pattern[]=tailwindcss`, `public-hoist-pattern[]=storybook`, `public-hoist-pattern[]=jest` (`*eslint*`/`*prettier*` are hoisted by default)
17
+ - If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`. Trace detection with `LINT_DEBUG=1 vp lint` (or `LINT_DEBUG=1 eslint .`)
18
+
19
+ # Consistent versions
20
+
21
+ Pin the shared packages at the root; they cause issues when versions drift ([npm `overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides), [why both fields](https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332)). `yarn.config.cjs`, and how `defineYarnConfig` reads these fields: the package README, "Yarn constraints".
22
+
23
+ Root `package.json` with Vite+ (the default): `vite` is an alias of the Vite+ core, `vitest` is the version Vite+ bundles (`npm view vite-plus dependencies.vitest`), and `@vitest/*` packages match it exactly:
24
+
25
+ ```json
26
+ {
27
+ "devDependencies": {
28
+ "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0",
29
+ "vite-plus": "^1.3.0"
30
+ },
31
+ "overrides": {
32
+ "@types/node": "$@types/node",
33
+ "@types/react": "$@types/react",
34
+ "@types/react-dom": "$@types/react-dom",
35
+ "next": "$next",
36
+ "eslint": "$eslint",
37
+ "typescript": "$typescript",
38
+ "vite": "$vite"
39
+ },
40
+ "resolutions": {
41
+ "@types/node": "^26",
42
+ "@types/react": "^19",
43
+ "@types/react-dom": "^19",
44
+ "eslint": "^10",
45
+ "next": "^16",
46
+ "typescript": "^6",
47
+ "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0",
48
+ "vitest": "5.0.5"
49
+ }
50
+ }
51
+ ```
52
+
53
+ Without Vite+: `"vite": "^8"` in `resolutions`, no `vitest` entry.
54
+
55
+ Other `package.json` files use the same ranges (`next` always has a version, see [rules/nextjs.md](../../rules/nextjs.md)):
56
+
57
+ ```jsonc
58
+ {
59
+ "devDependencies": {
60
+ "next": "^16.0.0",
61
+ "typescript": "^6.0.0",
62
+ },
63
+ }
64
+ ```
65
+
66
+ # `.yarnrc.yml`
67
+
68
+ ```yml
69
+ approvedGitRepositories:
70
+ - '**'
71
+
72
+ # print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
73
+ enableInlineBuilds: true
74
+
75
+ enableScripts: true
76
+
77
+ nodeLinker: node-modules
78
+
79
+ npmMinimalAgeGate: 0
80
+
81
+ # own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
82
+ npmPreapprovedPackages:
83
+ - '@kirill.konshin/*'
84
+ ```
85
+
86
+ # Install on CI
87
+
88
+ The basic rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md#install-on-ci). Platform steps: the `lint-github` skill and the `lint-gitlab` skill.
89
+
90
+ - Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
91
+ - Set `YARN_ENABLE_GLOBAL_CACHE=true` and put the Yarn global folder on the volume (`YARN_GLOBAL_FOLDER`). Do not use the CI cache for packages.
92
+ - Hardlinks do not cross filesystems. Yarn hardlinks package files from `<globalFolder>/index`. The `node-modules` linker then copies instead and downgrades `nmMode: hardlinks-global` to `hardlinks-local`. The `pnpm` linker has no fallback: it fails with "cross-device link".
93
+ - With Yarn's `nodeLinker: pnpm`, put `pnpmStoreFolder` on the same volume as the global folder, one folder per branch (`/cache/yarn/store/$CI_COMMIT_REF_SLUG`). The link step then takes seconds.
94
+ - Each Yarn `pnpm` install deletes all store entries that it does not use. The per-branch folder keeps installs on other branches away from your store.
95
+ - With pnpm, set `store-dir` on the volume.
96
+ - Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
97
+ - IF `yarn install` is still the CI bottleneck, measure it and evaluate alternatives. The principles of [Speed up NPM/Yarn install in Gitlab](https://www.konshin.org/publications/speed-up-npm-yarn-install-in-gitlab) ([Medium](https://medium.com/disdj/speed-up-npm-yarn-install-in-gitlab-1434437f9857)) still apply. Its tools are outdated.
98
+ - A faster linker: Yarn's `nodeLinker: pnpm` often links faster than `node-modules`, and pnpm is faster still. Both layouts are strict and not hoisted (see Hoisting). Undeclared dependencies fail, and Electron needs a hoisted layout. `@kirill.konshin/lint` is not verified with them.
99
+ - Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
100
+ - A CI image with the dependencies installed
101
+ - IF in doubt, keep `nodeLinker: node-modules`.
102
+
103
+ # Yalc (Local Package Linking)
104
+
105
+ Test unpublished `@kirill.konshin/*` packages in sibling projects (yalc is a root devDependency of the `kirill-konshin/utils` repository):
106
+
107
+ 1. `yarn nx run @kirill.konshin/<pkg>:build`
108
+ 2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
109
+ 3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from the `kirill-konshin/utils` repository)
110
+
111
+ Pitfalls (the `yalc link` / commit rules: [rules/npm-yarn.md](../../rules/npm-yarn.md#yalc)):
112
+
113
+ - `yalc link` is symlink mode: `node_modules/<pkg>` points at a local `.yalc/<pkg>` copy. While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` stay unchanged
114
+ - The real dependency (e.g. `"@kirill.konshin/auth": "^0.0.1"`) is committed separately; the consumer's `yarn.lock` can only be updated after the version is actually published to npm
115
+ - The consumer resolves the linked package's own dependencies from its node_modules — they must be installed there (usually already are as the consumer's own deps)
116
+ - A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
117
+ - Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
118
+ - Yarn 4.17+ quarantines packages published <24h ago (`npmMinimalAgeGate`) — consumers need `npmPreapprovedPackages: ["@kirill.konshin/*"]` in `.yarnrc.yml` to install own packages right after release (older Yarn errors on that key — upgrade the consumer via `packageManager` first)
119
+ - `.yarnrc.local.yml` is NOT a thing (open Yarn feature request, local overrides only via `YARN_*` env vars) and yalc runs NO registry (it is a file store in `~/.yalc`), so a registry override cannot replace linking — `yalc link` is the only mode that leaves all manifests untouched
120
+
121
+ # First Publish with OIDC
122
+
123
+ - Bootstrap a new npm package once from a locally authenticated session with `npm publish --access public --tag bootstrap`; complete npm's interactive 2FA challenge, or use `--otp=<code>` for TOTP.
124
+ - Configure its GitHub trusted publisher with the repository owner, repository name and release workflow file. For `@kirill.konshin/*` packages these are: organization/user `kirill-konshin`, repository `utils`, workflow `release.yml`, optional environment `npm-publish`. Check **Allow npm publish**.
125
+ - Under Publishing access, check **Require two-factor authentication and disallow bypass 2FA tokens (recommended)**; OIDC publishes remain allowed and should be used for every normal release.
126
+ - The first conventional `feat` release establishes the normal `latest` version.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-repo
3
- description: Set up/update this repo's lint/format/pre-commit tooling (@kirill.konshin/lint) - Vite+ (Oxlint, Oxfmt, vp staged/hooks) by default, ESLint + Prettier + lint-staged + Husky when Vite+ is not used, and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
3
+ description: Set up or update the lint, format and pre-commit tooling of a repository with `@kirill.konshin/lint` (Vite+ by default; ESLint + Prettier + lint-staged + Husky without Vite+), and audit the code against the packaged agent rules. Use when asked to set up, configure or upgrade lint / format / pre-commit tooling, or to check, audit or lint the code against the agent rules.
4
4
  ---
5
5
 
6
6
  # Lint Repo
@@ -18,34 +18,34 @@ Follow `node_modules/@kirill.konshin/lint/README.md`, reconciling (never blindly
18
18
 
19
19
  Vite+ is the default. Use the ESLint + Prettier flow only when the user declines Vite+.
20
20
 
21
- Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
21
+ Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
22
22
 
23
23
  ### Vite+
24
24
 
25
- Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as `lint-migrate` describes.
25
+ Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as the `lint-migrate` skill describes.
26
26
 
27
27
  1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint` only for Nx module-boundary rules); pin `vite`/`vitest` at the root (README "Yarn constraints").
28
- 2. **Config** — root `vite.config.ts`: `defineConfig(vitePlusConfig({ ...project blocks }, { ...toggles }))`; move project rule overrides into `lint.rules` / `lint.overrides`, ignores into `ignorePatterns`. Keep `.editorconfig`.
29
- 3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` (npm-yarn rule).
28
+ 2. **Config** — `lint.config.ts` in the workspace root, always (README "`lint.config.ts`"; `"type": "module"` in the root `package.json`): tool toggles, `skills`, `rules`, and under `vitePlus` the `typeAware` setting and the project blocks — rule overrides in `lint.rules` / `lint.overrides`, ignores in `lint.ignorePatterns`, `test`, `fmt`. Root `vite.config.ts` is exactly `export default defineConfig(vitePlusConfig());`. Keep `.editorconfig`.
29
+ 3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` ([rules/npm-yarn.md](../../rules/npm-yarn.md)).
30
30
  4. **Tests/builds** — tests import from `vite-plus/test`; libraries `vp pack`, apps `vp build`.
31
- 5. **CI** — `vp check` (no `--fix`), see `lint-github` / `lint-gitlab`.
32
- 6. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
31
+ 5. **CI** — `vp check` (no `--fix`), see the `lint-github` skill or the `lint-gitlab` skill.
32
+ 6. **IDEA** — apply the `lint-webstorm` skill if the repo has a JetBrains `.idea`.
33
33
  7. **Install** — run the package manager; then `vp check` and the tests.
34
34
 
35
35
  ### ESLint + Prettier
36
36
 
37
- 1. **Install** — add `eslint`, `prettier`, `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
38
- 2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` and `.prettierrc.mjs` (pass `defineLintConfig` options as needed — e.g. `defaultIgnore: { importMetaUrl: import.meta.url }`, `next: { rootDir }` — and keep project rule overrides).
37
+ 1. **Install** — add `eslint`, `prettier`, `vite-plus` (required peer: it types `lint.config.ts`), `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
38
+ 2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` (`eslintConfig()`) and `.prettierrc.mjs`; put settings into `lint.config.ts` in the workspace root, always present (e.g. `eslint: { defaultIgnore: { importMetaUrl: import.meta.url } }`, `next: { rootDir }`) and keep project rule overrides.
39
39
  3. **Lint-staged** — create/reconcile `.lintstagedrc.mjs`.
40
40
  4. **Husky** — `prepare/postinstall` (`prepare` by default, `postinstall` if Yarn 2+ is used AND root package.json is **private**) script; `.husky/pre-commit`, plus `eslint`/`prettier`/`lint`/`lint:staged` scripts. Drop a legacy `lint:all` if it duplicates `lint`.
41
- 5. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
41
+ 5. **IDEA** — apply the `lint-webstorm` skill if the repo has a JetBrains `.idea`.
42
42
  6. **Install** — run the package manager (`yarn` / `npm install` / `pnpm install`) so the new deps and Husky hooks land. Under Yarn 2+ check if root `package.json` has `prepare` script, and if it does, run it.
43
43
 
44
44
  Check the README's "Issues" section before debugging a lint crash.
45
45
 
46
46
  ## B. Audit code against rules
47
47
 
48
- Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
48
+ Rules: `.agents/rules/*.md` (created by `lint-prepare init`) → else `node_modules/@kirill.konshin/lint/rules/*.md`, except the rules the `rules` map of `lint.config.ts` turns off; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
49
49
 
50
50
  ### 1. Mechanical pass first
51
51
 
@@ -67,7 +67,7 @@ Go one-by-one / reply with instructions / skip all / fix all. Do nothing until a
67
67
 
68
68
  Per issue: **skip** / **skip + add override** / **fix** / **instructions**. For an override, offer only the applicable mechanism(s) and **name which one you'll write, showing the exact line/snippet first**:
69
69
 
70
- - **Lint override** (mechanical findings) — `// oxlint-disable-next-line <rule>` (Vite+) or `// eslint-disable-next-line <rule>` at the site, or a rule entry in `lint.overrides` of `vite.config.ts` / the `eslint.config.*` override block.
70
+ - **Lint override** (mechanical findings) — `// oxlint-disable-next-line <rule>` (Vite+) or `// eslint-disable-next-line <rule>` at the site, or a rule entry in `vitePlus.lint.overrides` of `lint.config.ts` / the `eslint.config.*` override block.
71
71
  - **AI override → AGENTS.md** (rule-audit findings) — a general rule appended to `AGENTS.md # Custom Rules` (run `lint-prepare init` to create the file if missing). Prefer a general statement over a per-file exception unless it's genuinely a one-off.
72
72
  - **both** — when the violation is covered by a lint rule _and_ an agent rule.
73
73