@kirill.konshin/lint 0.7.2 → 0.7.4

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 (39) hide show
  1. package/package.json +7 -3
  2. package/rules/auth.md +3 -3
  3. package/rules/db.md +5 -9
  4. package/rules/github.md +1 -1
  5. package/rules/gitlab.md +1 -1
  6. package/rules/i18n.md +3 -0
  7. package/rules/monorepo-turbo-nx.md +38 -4
  8. package/rules/mui.md +6 -18
  9. package/rules/nextjs.md +12 -12
  10. package/rules/npm-yarn.md +28 -118
  11. package/rules/nx.md +1 -1
  12. package/rules/playwright.md +1 -1
  13. package/rules/react.md +8 -9
  14. package/rules/tailwind.md +7 -46
  15. package/rules/testing.md +2 -2
  16. package/rules/turbo.md +1 -1
  17. package/rules/typescript.md +5 -1
  18. package/rules/ui-kit.md +6 -0
  19. package/skills/lint-db/SKILL.md +21 -0
  20. package/skills/lint-electron/SKILL.md +7 -6
  21. package/skills/lint-github/SKILL.md +5 -6
  22. package/skills/lint-gitlab/SKILL.md +4 -4
  23. package/skills/lint-migrate/SKILL.md +1 -1
  24. package/skills/lint-mui/SKILL.md +31 -0
  25. package/skills/lint-nextjs/SKILL.md +33 -8
  26. package/skills/lint-npm-yarn/SKILL.md +140 -0
  27. package/skills/lint-repo/SKILL.md +6 -6
  28. package/skills/lint-tailwind/SKILL.md +53 -0
  29. package/skills/lint-webstorm/SKILL.md +2 -2
  30. package/skills/lint-worktree/SKILL.md +2 -2
  31. package/skills/spec-author/SKILL.md +2 -2
  32. package/skills/spec-steward/references/apply.md +1 -1
  33. package/skills/spec-steward/references/contract.md +1 -1
  34. package/skills/spec-steward/references/model.md +2 -2
  35. package/skills/spec-steward/references/review-format.md +4 -4
  36. package/skills/spec-steward/references/wiring.md +1 -1
  37. package/skills/spec-steward/references/worker.md +1 -1
  38. package/skills/spec-tools/references/rules/common.md +1 -1
  39. package/skills/spec-tools/references/rules/spec-steward.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
18
  - 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`
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
@@ -0,0 +1,21 @@
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 (HTTP vs pooled driver, Drizzle migrations, Neon Auth with Iron Session). Use when migrating or importing data, changing a schema, or working with Neon.
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, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
11
+ - Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
12
+ - Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
13
+ - After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
14
+
15
+ # Neon
16
+
17
+ Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
18
+
19
+ - Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
20
+ - Use Neon Postgres with Drizzle and checked-in generated migrations.
21
+ - Fold Neon Auth into Iron Session ([rules/auth.md](../../rules/auth.md)): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
@@ -46,7 +46,7 @@ Scripts: `"start": "vp pack --watch"`, `"build:main": "vp pack"`.
46
46
 
47
47
  # Packaging a Next.js Standalone Server
48
48
 
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:
49
+ 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
50
 
51
51
  ```yaml
52
52
  files:
@@ -60,20 +60,21 @@ files:
60
60
 
61
61
  ## Gitlab
62
62
 
63
+ Base the pipeline on the `lint-gitlab` skill (Corepack, install, cache). The Electron build job adds:
64
+
63
65
  ```yml
64
66
  variables:
65
67
  USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
66
68
 
67
69
  build:
68
- image: macos-12-xcode-13 # not exact version, but the point is to use macos-compatible image
70
+ image: <current GitLab macOS image> # a macOS runner builds and signs mac targets
69
71
  tags:
70
- - shared-macos-amd64
72
+ - saas-macos-medium-m1
71
73
  script:
72
- - yarn --immutable
73
74
  - yarn build
74
75
  - rm -rf electron/dist/mac # some cleanup to make artifacts leaner
75
- only:
76
- - master
76
+ rules:
77
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
77
78
  artifacts:
78
79
  paths:
79
80
  - 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
 
@@ -329,9 +329,8 @@ jobs:
329
329
 
330
330
  needs: [lint, test, build]
331
331
 
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'
332
+ # If project publishes to NPM; forks skip the release
333
+ if: github.repository == '<owner>/<repo>'
335
334
  permissions:
336
335
  id-token: write # Required for OIDC trusted publishing
337
336
  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 / build jobs, Yarn and Nx 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`)
@@ -126,8 +126,8 @@ build:
126
126
  stage: build
127
127
  script:
128
128
  - yarn build
129
- only:
130
- - master
129
+ rules:
130
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
131
131
  artifacts:
132
132
  paths:
133
133
  - web/build
@@ -135,7 +135,7 @@ build:
135
135
 
136
136
  # Shared Cache Volume
137
137
 
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.
138
+ 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
139
 
140
140
  Runner config (Kubernetes executor, a ReadWriteMany PVC):
141
141
 
@@ -13,7 +13,7 @@ Only what changes between versions; the target setup is the package README (`nod
13
13
 
14
14
  # 0.6 -> 0.7
15
15
 
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.
16
+ 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
17
 
18
18
  - **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
19
19
  - **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,31 @@
1
+ ---
2
+ name: lint-mui
3
+ description: MUI and Toolpad conventions - barrel imports of `@mui/material` / `@mui/icons-material` (direct imports in libraries), stable `*Classes` class names in `sx`, safe-area insets in the theme, admin pages and login with `@toolpad/core` and `@kirill.konshin/mui/admin`, `optimizePackageImports` with Next.js. Use when writing or reviewing code that uses MUI or Toolpad, or building an admin interface.
4
+ ---
5
+
6
+ # Imports
7
+
8
+ - Always import components or icons this way: `import { Paper, Button } from '@mui/material';` and `import { Xxx } from '@mui/icons-material';`
9
+ - See [Next.js](#nextjs)
10
+ - Exception: if developing a library use direct imports with minimal bundle footprint (libraries may not be used with barrel handling)
11
+
12
+ # Class Names
13
+
14
+ - To use MUI default classes always use stable minifiable class names:
15
+ - Import: `import { inputClasses } from '@mui/material';` or `import { inputClasses } from '@mui/material/Input';` (see [Imports](#imports))
16
+ - Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
17
+
18
+ # Theme
19
+
20
+ - Define safe-area insets globally or in the theme; consume through `sx`, never repeated `env(...)`
21
+
22
+ # Admin Pages & Login
23
+
24
+ - ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see [rules/tailwind.md](../../rules/tailwind.md))
25
+ - ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
26
+ - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) over hand-rolled `NextAppProvider`/`DashboardLayout`/`SignInPage` boilerplate; `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md))
27
+ - Prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled equivalents
28
+
29
+ # Next.js
30
+
31
+ - With Next.js, `experimental.optimizePackageImports` MUST list the barrel-heavy MUI packages: `defineNextConfig` sets them, see the `lint-nextjs` skill
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-nextjs
3
- description: Describes key patterns how to work with Next.js
3
+ description: Next.js App Router patterns - typed `LayoutProps` / `PageProps`, auth-guarded layouts, async `params` / `searchParams`, page and component file placement, what `defineNextConfig` sets in `next.config.ts` (incl. MUI `optimizePackageImports`). Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
4
4
  ---
5
5
 
6
6
  # Layouts
@@ -27,15 +27,23 @@ Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't c
27
27
 
28
28
  Route Handlers are not protected by layouts, so add auth check there too.
29
29
 
30
+ Use `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md)); the guard runs inside `<Suspense>`:
31
+
30
32
  ```tsx
31
- import React from 'react';
32
- import { redirect } from 'next/navigation';
33
- import { getToken } from '@/lib/auth';
33
+ import { type ReactNode, Suspense } from 'react';
34
+
35
+ import { auth } from '@/auth';
36
+
37
+ export default function Layout({ children }: LayoutProps<'/dashboard'>) {
38
+ return (
39
+ <Suspense>
40
+ <Protected>{children}</Protected>
41
+ </Suspense>
42
+ );
43
+ }
34
44
 
35
- export default async function Layout({ children }: LayoutProps<'/dashboard'>) {
36
- if (!(await getToken())) {
37
- redirect('/login');
38
- }
45
+ async function Protected({ children }: { children: ReactNode }) {
46
+ await auth.redirectNonAuthenticated(); // redirects to urls.login
39
47
  return <>{children}</>;
40
48
  }
41
49
  ```
@@ -57,3 +65,20 @@ export default async function Page({ params, searchParams }: PageProps<'/blog/[s
57
65
  return <h1>Blog post: {slug}</h1>;
58
66
  }
59
67
  ```
68
+
69
+ # Files
70
+
71
+ - Do not make dummy pages that only import components, pages can be client, and should have most logic baked in, including one-off components (not exported)
72
+ - Reusable components should be in `src/components`
73
+ - As exception, separate component files are allowed to be in `src/app` next to relevant pages if one-off component is large so page itself becomes bloated, but `src/components` should not be polluted with one-offs, ask user if not sure
74
+ - Example: `actions.ts` for `'use server'` actions while page is `'use client'`
75
+ - Admin pages: use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
76
+
77
+ # `next.config.ts`
78
+
79
+ - Create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — 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 are ignored, missing ones cost dev startup and bundle size, see MUI below)
80
+
81
+ ## MUI
82
+
83
+ - When MUI is used with Next.js ALWAYS add barrel-heavy packages to `experimental.optimizePackageImports`: `@mui/material`, `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/x-data-grid`, `@toolpad/core`, plus the other usual suspects (`@fortawesome/*`, `@gravity-ui/icons`, `@gravity-ui/uikit`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`)
84
+ - Prefer `defineNextConfig` from `@kirill.konshin/next/config` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see `next.config.ts` above)
@@ -0,0 +1,140 @@
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`, Yarn constraints), `.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
+ - Yarn PnP: declare the tools at the workspace root as well
18
+ - If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
19
+
20
+ # Consistent versions
21
+
22
+ In monorepos pin versions of sub-packages to the root; these packages cause issues when versions drift.
23
+
24
+ https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332 https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
25
+
26
+ Root `package.json`:
27
+
28
+ ```json
29
+ {
30
+ "overrides": {
31
+ "@types/node": "$@types/node",
32
+ "@types/react": "$@types/react",
33
+ "@types/react-dom": "$@types/react-dom",
34
+ "next": "$next",
35
+ "eslint": "$eslint",
36
+ "typescript": "$typescript",
37
+ "vite": "$vite"
38
+ },
39
+ "resolutions": {
40
+ "@types/node": "^26",
41
+ "@types/react": "^19",
42
+ "@types/react-dom": "^19",
43
+ "eslint": "^10",
44
+ "next": "^16",
45
+ "typescript": "^6",
46
+ "vite": "^8"
47
+ }
48
+ }
49
+ ```
50
+
51
+ All other `package.json`:
52
+
53
+ ```jsonc
54
+ {
55
+ "devDependencies": {
56
+ "next": "^16.0.0", // except next, see nextjs.md
57
+ "typescript": "^6.0.0",
58
+ },
59
+ }
60
+ ```
61
+
62
+ Yarn does not apply npm `overrides`; `defineYarnConfig` reads them as constraints together with `resolutions`, keeps non-peer leaf ranges equal, and falls back to the listed default packages when `overrides` is absent.
63
+
64
+ Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
65
+
66
+ ```js
67
+ /** @type {import('@yarnpkg/types')} */
68
+ const { defineConfig } = require('@yarnpkg/types');
69
+ const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
70
+
71
+ module.exports = defineConfig(defineYarnConfig());
72
+ ```
73
+
74
+ Run `yarn constraints --fix` after dependency changes.
75
+
76
+ # `.yarnrc.yml`
77
+
78
+ Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
79
+
80
+ ```yml
81
+ approvedGitRepositories:
82
+ - '**'
83
+
84
+ # print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
85
+ enableInlineBuilds: true
86
+
87
+ enableScripts: true
88
+
89
+ nodeLinker: node-modules
90
+
91
+ npmMinimalAgeGate: 0
92
+
93
+ # own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
94
+ npmPreapprovedPackages:
95
+ - '@kirill.konshin/*'
96
+ ```
97
+
98
+ # Install on CI
99
+
100
+ 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.
101
+
102
+ - Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
103
+ - 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.
104
+ - 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".
105
+ - 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.
106
+ - 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.
107
+ - With pnpm, set `store-dir` on the volume.
108
+ - Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
109
+ - 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.
110
+ - 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.
111
+ - Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
112
+ - A CI image with the dependencies installed
113
+ - IF in doubt, keep `nodeLinker: node-modules`.
114
+
115
+ # Yalc (Local Package Linking)
116
+
117
+ Test unpublished `@kirill.konshin/*` packages in sibling projects (yalc is a root devDependency of the `kirill-konshin/utils` repository):
118
+
119
+ 1. `yarn nx run @kirill.konshin/<pkg>:build`
120
+ 2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
121
+ 3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from the `kirill-konshin/utils` repository)
122
+
123
+ Rules:
124
+
125
+ - ALWAYS use `yalc link` (symlink mode: `node_modules/<pkg>` → local `.yalc/<pkg>` copy), NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
126
+ - While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` MUST NOT be modified by the link — link artifacts break CI/other machines and must NEVER be committed; gitignore `.yalc/` and `yalc.lock` in the consumer
127
+ - 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
128
+ - 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)
129
+ - A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
130
+ - Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
131
+ - 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)
132
+ - `.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
133
+
134
+ # First Publish with OIDC
135
+
136
+ - Never bootstrap, publish, or push a release without explicit approval.
137
+ - 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.
138
+ - 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**.
139
+ - 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.
140
+ - The first conventional `feat` release establishes the normal `latest` version.
@@ -18,18 +18,18 @@ 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
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).
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
@@ -38,7 +38,7 @@ Write the config by hand. `vp migrate` is only an optional first pass: it copies
38
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).
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.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: lint-tailwind
3
+ description: Tailwind details for the tailwind rule - the safe-area `@utility` template and the eslint-plugin-tailwindcss / Oxlint setup (entry CSS detection, `cssConfigPath`, scoping, resolution errors). Use when adding safe-area utilities, or when Tailwind lint is set up, crashes or skips.
4
+ ---
5
+
6
+ The binding rules are in [rules/tailwind.md](../../rules/tailwind.md). This skill holds the details.
7
+
8
+ # Safe-Area Utilities
9
+
10
+ ```css
11
+ @utility top-safe {
12
+ top: 1.5rem;
13
+ top: max(1.5rem, env(safe-area-inset-top, 0px));
14
+ }
15
+
16
+ @utility right-safe {
17
+ right: 1.5rem;
18
+ right: max(1.5rem, env(safe-area-inset-right, 0px));
19
+ }
20
+
21
+ @utility bottom-safe {
22
+ bottom: 1.5rem;
23
+ bottom: max(1.5rem, env(safe-area-inset-bottom, 0px));
24
+ }
25
+
26
+ @utility left-safe {
27
+ left: 1.5rem;
28
+ left: max(1.5rem, env(safe-area-inset-left, 0px));
29
+ }
30
+ ```
31
+
32
+ # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
33
+
34
+ - With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; pass `tailwind: { cssConfigPath }` as `vitePlusConfig` options instead of `eslint.config.mjs`
35
+ - The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
36
+ - Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
37
+ - Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
38
+ - `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see the `lint-npm-yarn` skill, "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
39
+ - Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
40
+ - pass `cssConfigPath` to pick one (if others are not useful) OR
41
+ - create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
42
+ - When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
43
+ - ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
44
+
45
+ ```js
46
+ import { defineLintConfig } from '@kirill.konshin/lint';
47
+
48
+ export default defineLintConfig({
49
+ tailwind: {
50
+ cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
51
+ },
52
+ });
53
+ ```
@@ -5,7 +5,7 @@ description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project
5
5
 
6
6
  # Check
7
7
 
8
- Compare the project's `.idea` files with the templates below and the `webstorm` rule, list every discrepancy, ask before fixing:
8
+ Compare the project's `.idea` files with the templates below and [rules/webstorm.md](../../rules/webstorm.md), list every discrepancy, ask before fixing:
9
9
 
10
10
  - Template settings missing or different in the project's files
11
11
  - Excluded folders out of sync between `.gitignore`, `.idea/%projectName%.iml` (usually only one IML file) and `.idea/indexLayout.xml` - look only in these files, infer nothing else
@@ -149,7 +149,7 @@ When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.co
149
149
 
150
150
  # GitIgnore
151
151
 
152
- Excluded folders follow the baseline of the `webstorm` rule.
152
+ Excluded folders follow the baseline of [rules/webstorm.md](../../rules/webstorm.md).
153
153
 
154
154
  ## Configure `.idea/.gitignore`:
155
155
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-worktree
3
- description: Describes how to work with GIT Worktrees
3
+ description: Git worktrees in `.worktrees` and the JetBrains IDEA / WebStorm module-name clash they cause. Use when creating, attaching or removing a git worktree.
4
4
  ---
5
5
 
6
6
  - Prefer creating worktrees inside the main repo in `.worktrees` directory
@@ -25,4 +25,4 @@ description: Describes how to work with GIT Worktrees
25
25
  1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every file marked above.
26
26
  2. Restore them with `git checkout -- <files>`.
27
27
  3. Redo the rename afterwards.
28
- - A worktree created **inside** the main checkout (e.g. `.worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.worktrees" />`) and list it in `.gitignore`, so the excluded-folders baseline of the `webstorm` rule holds. Attaching such a worktree can replace the main checkout's own entry in its `.idea/modules.xml`: keep both — the main `.idea/%projectName%.iml` and the worktree's renamed one — then reload the project. A nested worktree shows as its own module node inside the tree, not as a separate top-level project; for a top-level entry, create the worktree outside the main checkout.
28
+ - A worktree created **inside** the main checkout (e.g. `.worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.worktrees" />`) and list it in `.gitignore`, so the excluded-folders baseline of [rules/webstorm.md](../../rules/webstorm.md) holds. Attaching such a worktree can replace the main checkout's own entry in its `.idea/modules.xml`: keep both — the main `.idea/%projectName%.iml` and the worktree's renamed one — then reload the project. A nested worktree shows as its own module node inside the tree, not as a separate top-level project; for a top-level entry, create the worktree outside the main checkout.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: spec-author
3
- description: Write or edit a capability specification in openspec/specs — the default direct-edit path
4
- allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(spec-steward:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(yarn spec-steward:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(npx spec-steward:*), Bash(git diff*), Bash(git log*), Read, Edit, Write, Glob, Grep
3
+ description: Write or edit a capability specification in openspec/specs — the default direct-edit path. Use when adding or changing a requirement or scenario, unless the user asks for the /opsx delta flow.
4
+ allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(node:*), Bash(git diff*), Bash(git log*), Read, Edit, Write, Glob, Grep
5
5
  ---
6
6
 
7
7
  Write or edit a capability specification in place. This is the **default** path for specification work; the `/opsx:*` commands drive the full delta flow and run only when the user asks for them.
@@ -6,7 +6,7 @@ The owner has answered a review file ([review-format.md](review-format.md)). Pro
6
6
  2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, changed as the comment tells.
7
7
  - Before you change a requirement, read the requirements that name it and that it names, and the code and tests involved. A fix must not break a sibling.
8
8
  - A rule that several repositories share changes identically in each. `steward align` shows the drift.
9
- - When a change moves guidance to a new place, put it where `rules/agent.md` tells, remove each copy, and reference it from its old place.
9
+ - When a change moves guidance to a new place, put it where [rules/agent.md](../../../rules/agent.md) tells, remove each copy, and reference it from its old place.
10
10
  - Add `applied: "R<round> — <what changed, with paths>"` to the item. A second application makes `applied` a list.
11
11
  3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's other instruction. Record what you did in `applied`.
12
12
  4. **Comment only.** Examine the item again, and change the proposal or the explanation in place. Move the owner's comment into `previousDecision: "R<n>: <comment>"` and set `decision` to `""`. A comment is never acceptance.
@@ -1,6 +1,6 @@
1
1
  # The spec-steward contract
2
2
 
3
- What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `steward.test.mjs` proves the cases below.
3
+ What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `spec-tools/src/steward/steward.test.ts` proves the cases below.
4
4
 
5
5
  Terms used throughout:
6
6
 
@@ -1,6 +1,6 @@
1
1
  # The specification model
2
2
 
3
- Where a piece of guidance lives is decided by `rules/agent.md`, shipped by `@kirill.konshin/lint`; in a repository it is `.agents/rules/agent.md`. Read it there; this file covers only what is specific to the specifications themselves. What the gate checks mechanically — citations, binding, markers, size lines, the scenario ratchet — is [contract.md](contract.md).
3
+ Where a piece of guidance lives is decided by [rules/agent.md](../../../rules/agent.md), shipped by `@kirill.konshin/lint`; in a repository it is `.agents/rules/agent.md`. Read it there; this file covers only what is specific to the specifications themselves. What the gate checks mechanically — citations, binding, markers, size lines, the scenario ratchet — is [contract.md](contract.md).
4
4
 
5
5
  ## A rule in `openspec/specs` is a contract
6
6
 
@@ -10,7 +10,7 @@ Normative force is carried by the RFC 2119 keywords — MUST, MUST NOT, REQUIRED
10
10
 
11
11
  A specification describes only real, existing behaviour. What is knowingly absent or incomplete is recorded as a [Known gap](#advisory-known-gap-or-neither), never written as though implemented and never left as unmarked silence.
12
12
 
13
- Apply the two litmus questions from `rules/agent.md`; then the decision test:
13
+ Apply the two litmus questions from [rules/agent.md](../../../rules/agent.md); then the decision test:
14
14
 
15
15
  > **Name the observable failure this rule prevents, and the cheapest evidence that would catch it.**
16
16
 
@@ -16,8 +16,8 @@ R-001:
16
16
  confidence: 85
17
17
  rule:
18
18
  text: |-
19
- The server SHALL promote accountId, rcAccountId, rcRequestId and rcUserId…
20
- location: 'SHOP openspec/specs/system-overview/logging/spec.md:47'
19
+ The server SHALL promote Xxx…
20
+ location: 'APP openspec/specs/system-overview/logging/spec.md:47'
21
21
  wrong: |
22
22
  The rule names the exact log fields. A field change breaks the rule with no effect in production.
23
23
  proposal: |
@@ -37,10 +37,10 @@ R-002:
37
37
  rules:
38
38
  - text: |-
39
39
  WHEN the dev server starts THEN it seeds the demo account
40
- location: 'SHOP openspec/specs/apps/runtime/spec.md:88'
40
+ location: 'APP openspec/specs/apps/runtime/spec.md:88'
41
41
  - text: |-
42
42
  The local database SHALL reset on each start
43
- location: 'SHOP openspec/specs/apps/db/spec.md:12'
43
+ location: 'APP openspec/specs/apps/db/spec.md:12'
44
44
  note: 'the reset is also in the README'
45
45
  wrong: |
46
46
  Both rules apply only on a developer machine. A violation has no effect in production.
@@ -12,7 +12,7 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
12
12
 
13
13
  These five points keep to the placement rules:
14
14
 
15
- - Nothing restates `rules/agent.md` or the repository's own rules.
15
+ - Nothing restates [rules/agent.md](../../../rules/agent.md) or the repository's own rules.
16
16
  - The OPSX `context` stays untouched: it already carries `AGENTS.md`.
17
17
  - The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
18
18