@kirill.konshin/lint 0.7.3 → 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 +1 -1
  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
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "Vite+ (Oxlint + Oxfmt), ESLint + Prettier + lint-staged configs and AI agent rules/skills for monorepos",
4
- "version": "0.7.3",
4
+ "version": "0.7.4",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
package/rules/auth.md CHANGED
@@ -10,8 +10,8 @@ paths:
10
10
  - Follow the canonical patterns from the [package README](https://github.com/kirill-konshin/utils/blob/main/packages/auth/README.md) (session module, layout guard, login page, actions, route handlers, proxy) and its migration table when refactoring existing hand-rolled auth
11
11
  - ONE auth instance per app in `src/auth.ts`: `createPasswordAuth` (password-protected admin) or `createAuth` (token/OAuth)
12
12
  - `isValid` defaults to checking the lib-owned `AUTHENTICATED` marker field (set by `login()`, default session shape `PasswordSession`, nothing to configure) — token/OAuth apps pass their own session type + `isValid` (e.g. access token present & not expired)
13
- - Pass Next's `Route` as the routes generic (`createPasswordAuth<Route>` / `createAuth<Session, Route>`) so `urls` and the return-URL helpers are type-checked (`typedRoutes` is set by `defineNextConfig`, see nextjs.md)
14
- - Auth module MUST start with `import 'server-only'` and MUST NOT be module-level `'use server'` (that would expose session getters as callable server actions) — export `loginAction`/`logoutAction` from the SAME module as thin async wrappers with function-level `'use server'`, NO separate `actions.ts`; plain re-exports (`export const loginAction = auth.loginFormAction`) are NOT registered as actions; ENFORCED BY AGENT: no ESLint rule checks this, add on creation, flag on review (see nextjs.md)
13
+ - Pass Next's `Route` as the routes generic (`createPasswordAuth<Route>` / `createAuth<Session, Route>`) so `urls` and the return-URL helpers are type-checked (`typedRoutes` is set by `defineNextConfig`, see [nextjs.md](nextjs.md))
14
+ - Auth module MUST start with `import 'server-only'` and MUST NOT be module-level `'use server'` (that would expose session getters as callable server actions) — export `loginAction`/`logoutAction` from the SAME module as thin async wrappers with function-level `'use server'`, NO separate `actions.ts`; plain re-exports (`export const loginAction = auth.loginFormAction`) are NOT registered as actions; ENFORCED BY AGENT: no ESLint rule checks this, add on creation, flag on review (see [nextjs.md](nextjs.md))
15
15
  - Client Components MUST NOT import the auth module (`server-only` + function-level actions are not client-importable) — Server Components pass `loginAction`/`logoutAction` down as props
16
16
  - Cookie name MUST be unique per app (`<app>_session`), NEVER generic `session`
17
17
  - Cookie secret `SESSION_SECRET` (≥32 chars) and login password `ADMIN_PASSWORD` are SEPARATE env vars, never reuse one for the other
@@ -19,7 +19,7 @@ paths:
19
19
  - Guard pages/layouts with `redirectNonAuthenticated()` (redirects to login), Server Actions and Route Handlers with `throwNonAuthenticated()` or `authenticatedRouteHandler()` (401), the whole `/api` surface with `proxyGuard()` in `proxy.ts`, login page with `redirectIfAuthenticated()`
20
20
  - Declare API visibility as `urls.public` / `urls.protected` globs and keep them exhaustive — `proxyGuard()` throws on overlap and warns (treating as public) on unknown paths; `allow` is only for request-level tweaks
21
21
  - Session lifetime via `ttl` (seconds) ONLY, NEVER set `cookieOptions.maxAge` (iron-session derives it)
22
- - Logout via `auth.logout()` (destroy + redirect) — re-export directly (`export const logoutAction = auth.logout`), a `FormData` argument from `<form action>` is ignored
22
+ - Logout via `auth.logout()` (destroy + redirect) — export `logoutAction` as a function-level `'use server'` wrapper, like `loginAction`; a `FormData` argument from `<form action>` is ignored
23
23
  - Preserve the return URL through the `state` search param / hidden form field on login redirects; ALWAYS extract it with `auth.getState()` (accepts `await searchParams`, `URLSearchParams`, `FormData`, `NextRequest`, raw string; allows internal paths only, never the login page, falls back to `urls.afterLogin`), NEVER hand-parse `state`
24
24
  - NEVER store the return URL in the session — concurrent tabs share the cookie and would clash; thread it ONLY via search params, form fields and the `x-pathname` header
25
25
  - `proxy.ts` is two lines: `export const config = { matcher: [...] };` (a LITERAL — Next.js parses it statically) + `export const proxy = auth.proxyGuard({ matcher: config.matcher });` — the guard verifies the matcher covers all `urls.public`/`urls.protected` globs (it may be broader) and THROWS on uncovered ones
package/rules/db.md CHANGED
@@ -3,6 +3,8 @@ type: always_apply
3
3
  description: Database persistence and migration rules
4
4
  ---
5
5
 
6
+ Migration and import procedures, Neon: the `lint-db` skill.
7
+
6
8
  # IndexedDB
7
9
 
8
10
  - Use Dexie for browser-owned IndexedDB data.
@@ -20,15 +22,9 @@ description: Database persistence and migration rules
20
22
  - Use `DATABASE_URL` at runtime; prefer `DATABASE_URL_UNPOOLED` for migrations and maintenance when available.
21
23
  - Close owned pools in `finally`; do not leak clients or hide ownership of long-lived connections.
22
24
  - Enforce user and tenant scope on every read and mutation; authentication alone is not authorization.
23
- - For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
24
- - Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
25
- - Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
26
- - After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
25
+ - Never delete server data only because a mutable export became smaller
26
+ - Data migrations, importers and schema changes: follow the `lint-db` skill
27
27
 
28
28
  # Neon
29
29
 
30
- Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
31
-
32
- - Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
33
- - Use Neon Postgres with Drizzle and checked-in generated migrations.
34
- - Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
30
+ - Only if the user asks for Neon, or the project already uses it: follow the `lint-db` skill
package/rules/github.md CHANGED
@@ -8,7 +8,7 @@ paths:
8
8
  ---
9
9
 
10
10
  - Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node -> restore Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
11
- - Yarn cache: follow npm-yarn.md "Install on CI". Use the key `${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}` and the restore key `${{ runner.os }}-yarn-`.
11
+ - Yarn cache: follow [npm-yarn.md](npm-yarn.md#install-on-ci). Use the key `${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}` and the restore key `${{ runner.os }}-yarn-`.
12
12
  - With an `install` job, only this job saves the Yarn cache. The other jobs `need` it and restore with `actions/cache/restore`. See the `lint-github` skill.
13
13
  - Key build caches per commit when jobs run one after another: key `${{ runner.os }}-<tool>-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-`. A later job gets an exact hit and does not save again.
14
14
  - Key build caches per job and commit when jobs run in parallel: key `${{ runner.os }}-<tool>-${{ github.job }}-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-${{ github.job }}-`. Only the first job that saves a key keeps its outputs. A downstream job restores the producing job's key and does not save.
package/rules/gitlab.md CHANGED
@@ -10,7 +10,7 @@ paths:
10
10
  - Always collect coverage from tests
11
11
  - Always publish important build stats as artifacts
12
12
  - Agentic review MUST verify this effective CI order: checkout and cache restore -> enable Corepack -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
13
- - Yarn cache: follow npm-yarn.md "Install on CI". Key it per branch, with the default branch as the fallback key.
13
+ - Yarn cache: follow [npm-yarn.md](npm-yarn.md#install-on-ci). Key it per branch, with the default branch as the fallback key.
14
14
  - The fallback to the default-branch cache works only when "Use separate caches for protected branches" is cleared (Settings > CI/CD > General pipelines). Otherwise GitLab adds `-protected` or `-non_protected` to all keys, and other branches never find the default-branch cache. GitLab: clear it only when all users with the Developer role are highly trusted.
15
15
  - With an `install` job, only this job has Yarn cache `policy: pull-push`. The other jobs use `policy: pull`. See the `lint-gitlab` skill.
16
16
  - Use the fastzip archiver for cache and artifacts. It is the default from GitLab Runner 19.4. On older runners, set `FF_USE_FASTZIP: 'true'`.
package/rules/i18n.md CHANGED
@@ -1,6 +1,9 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: General recommendations for I18N
4
+ paths:
5
+ - '**/*.tsx'
6
+ - '**/*.ts'
4
7
  ---
5
8
 
6
9
  - When displaying date and time use `Intl.DateTimeFormat`.
@@ -1,11 +1,12 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for MONOREPO projects which use Turbo or NX
3
+ description: Set of rules for MONOREPO projects which use Turbo, NX or Vite+
4
4
  paths:
5
5
  - '**/turbo.json'
6
6
  - '**/nx.json'
7
7
  - '**/package.json'
8
8
  - '**/project.json'
9
+ - '**/vite.config.ts'
9
10
  ---
10
11
 
11
12
  - Existing projects may use what they use
@@ -14,7 +15,25 @@ paths:
14
15
  - Tasks to launch inner tasks (main `build` that launches `build` in each sub-package)
15
16
  - Inner `package.json` MUST only define atomic orchestrator-agnostic tasks
16
17
  - Repo-wide defaults (parallelism, worker counts, cache and tool settings) live in env files (`.env`) or tool configs (`nx.json`, `turbo.json`, `vite.config.ts`), NEVER in `package.json` scripts — scripts stay as simple as possible; CI-specific behavior is set on the CI command (flags or env) where it is needed
17
- - Prefer NX for new projects
18
+
19
+ # Orchestrator Choice
20
+
21
+ - IF NX Release publishes the packages, use NX for cache and task management
22
+ - ELSE use Vite+ (`vp run`) — the default
23
+ - IF Turbo is already used, keep it and offer to migrate: to NX if NX Release publishes, else to Vite+
24
+
25
+ # Vite+ Task Runner
26
+
27
+ https://viteplus.dev/guide/cache
28
+
29
+ - Only `vp run` caches; a direct `vp build` / `vp test` does not
30
+ - Define cacheable tasks in `vite.config.ts` `run.tasks` (cached by default); `package.json` scripts are cached only with `--cache` or `run.cache.scripts: true`
31
+ - `clean`, `wait`, `start` / `dev` tasks: `cache: false`
32
+ - Tasks run in a clean environment: list env vars that change outputs in `cache.env`, pass-through ones in `cache.untrackedEnv`
33
+ - Verify each task: the second `vp run <task>` MUST print `cache hit`; else fix `cache.input` / `cache.output`
34
+ - Cache lives in `node_modules/.vite/task-cache`; clear with `vp cache clean`; CI reuse: see [npm-yarn.md](npm-yarn.md#install-on-ci)
35
+ - No `affected` command: PR runs are fast only when CI restores the task cache
36
+ - Concurrency defaults to 4 tasks: `--concurrency-limit` or `VP_RUN_CONCURRENCY_LIMIT`; `--parallel` is unlimited
18
37
 
19
38
  # Test Ownership
20
39
 
@@ -22,7 +41,7 @@ paths:
22
41
  - The test tool at the root (Vitest `test.projects`, Jest `projects`) is the local / IDE full-speed run: one worker pool over every package, all cores, no cache
23
42
  - Inside an orchestrator task a test runner takes half of the cores, as the orchestrator runs several tasks at once (Nx: detect with `NX_TASK_TARGET_PROJECT`)
24
43
  - Type checking (`vp check`, `tsc`) resolves workspace packages through their built declarations: CI lint jobs run after the build job (`needs: build`) and build the packages first through the orchestrator (cache hits), and so does a fresh clone before `lint`
25
- - Suites that need running apps (e2e, integration): the orchestrator starts them — the test target `dependsOn` the continuous `start` / `dev` / `serve` plus a `wait` probe, `cache: false` — or Docker Compose does; the test tool never starts them (Playwright `webServer`), see playwright.md and testing.md
44
+ - Suites that need running apps (e2e, integration): the orchestrator starts them — the test target `dependsOn` the continuous `start` / `dev` / `serve` plus a `wait` probe, `cache: false` — or Docker Compose does; the test tool never starts them (Playwright `webServer`), see [playwright.md](playwright.md) and [testing.md](testing.md)
26
45
 
27
46
  # Task Consistency
28
47
 
@@ -65,4 +84,19 @@ The `start` task uses `"dependsOn": ["^wait"]` (upstream):
65
84
  4. Once the file exists, `B`'s `wait-on` unblocks and exits, and `A`'s `start` can proceed
66
85
  5. If file existed before, `A` starts immediately, the only issue could be `A`'s double-build if `B`'s `start` will eventually modify the file, causing `A`'s watcher to rebuild
67
86
 
68
- For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in turbo.md.
87
+ For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in [turbo.md](turbo.md).
88
+
89
+ ## Vite+
90
+
91
+ Vite Task has no `persistent` / `continuous` tasks (verified on 1.3.0):
92
+
93
+ - `vp run -r start` waits for upstream `start` to exit, so downstream `start` never starts, `^wait` or not (https://github.com/voidzero-dev/vite-task/issues/258)
94
+ - `--parallel` ignores every `dependsOn`, `^wait` included
95
+ - `dependsOn` a persistent task is not supported (https://github.com/voidzero-dev/vite-task/issues/416)
96
+
97
+ Chain the upstream probe inside the downstream command instead:
98
+
99
+ - Root: `"start": "vp run -r --parallel start"`
100
+ - Downstream package `A`: `"start": "vp run --filter 'A^...' wait && <watcher>"` — write the package name, `.^...` does not resolve
101
+ - Upstream package `B` defines `wait` as above
102
+ - Stopping only the `vp` process orphans its tasks; stop the whole process group (https://github.com/voidzero-dev/vite-plus/issues/3090)
package/rules/mui.md CHANGED
@@ -1,24 +1,12 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: Set of rules for projects with MUI
4
+ paths:
5
+ - '**/*.tsx'
6
+ - '**/*.ts'
4
7
  ---
5
8
 
6
- - Always import components or icons this way: `import { Paper, Button } from '@mui/material';` and `import { Xxx } from '@mui/icons-material';`
7
- - See barrel handling section
8
- - Exception: if developing a library use direct imports with minimal bundle footprint (libraries may not be used with barrel handling)
9
- - To use MUI default classes always use stable minifiable class names:
10
- - Import: `import { inputClasses } from '@mui/material';` or `import { inputClasses } from '@mui/material/Input';` (see rule about imports)
11
- - Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
12
- - Define safe-area insets globally or in the theme; consume through `sx`, never repeated `env(...)`
9
+ Details and admin pages: the `lint-mui` skill.
13
10
 
14
- # Admin Pages & Login
15
-
16
- - ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see tailwind.md)
17
- - ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
18
- - 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 auth.md)
19
- - Prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled equivalents
20
-
21
- # Next.js
22
-
23
- - 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`)
24
- - 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 nextjs.md)
11
+ - Import from the barrels (`@mui/material`, `@mui/icons-material`) in apps; use direct imports (`@mui/material/Button`) in libraries
12
+ - Target MUI default classes only through the stable `*Classes` names (e.g. `inputClasses.root`), never through literal class strings
package/rules/nextjs.md CHANGED
@@ -1,30 +1,30 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: Set of rules for projects which use Next.js
4
+ paths:
5
+ - '**/next.config.*'
6
+ - '**/app/**'
7
+ - '**/proxy.ts'
4
8
  ---
5
9
 
6
10
  _EVERY_ Next.js page, layout, route handler or component must adhere to policy unless explicitly prohibited in comment before the component definition.
7
11
 
8
- Use `lint-nextjs` skill when working with Next.js projet.
12
+ Use the `lint-nextjs` skill when working with a Next.js project.
9
13
 
10
14
  # General Guidelines
11
15
 
12
16
  - Prefer Route Handlers for redirects
13
17
  - Never use Pages Router
14
18
  - Always use App Router
15
- - Use `iron-session` for authentication via `@kirill.konshin/auth`, see auth.md
16
- - 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
19
+ - Use `iron-session` for authentication via `@kirill.konshin/auth`, see [auth.md](auth.md)
20
+ - Server-only modules MUST start with `import 'server-only'`: see [typescript.md](typescript.md)
17
21
  - `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
18
- - ALWAYS 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.md)
22
+ - ALWAYS 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); what it sets: the `lint-nextjs` skill
19
23
  - Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it)
20
- - 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)
21
- - Reusable components should be in `src/components`
22
- - 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
23
- - Example: `actions.ts` for `'use server'` actions while page is `'use client'`
24
+ - Page and component file placement: the `lint-nextjs` skill
24
25
 
25
26
  # Admin Pages & Login
26
27
 
27
- - ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see mui.md
28
- - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see mui.md
29
- - Use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
30
- - Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
28
+ - ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see the `lint-mui` skill
29
+ - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see the `lint-mui` skill
30
+ - Tailwind is ONLY for user-facing sites, NEVER for admin (see [tailwind.md](tailwind.md))
package/rules/npm-yarn.md CHANGED
@@ -1,8 +1,21 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: NPM & Yarn patterns
4
+ paths:
5
+ - '**/package.json'
6
+ - '**/.yarnrc.yml'
7
+ - '**/yarn.config.cjs'
8
+ - '**/.npmrc'
9
+ - '**/pnpm-workspace.yaml'
10
+ - '**/.github/**/*.yml'
11
+ - '**/.github/**/*.yaml'
12
+ - '**/.gitlab-ci.yml'
13
+ - '**/.gitlab/**/*.yml'
14
+ - '**/.gitlab/**/*.yaml'
4
15
  ---
5
16
 
17
+ Templates, procedures and details: the `lint-npm-yarn` skill.
18
+
6
19
  - Prefer using Corepack for all new projects.
7
20
  - Prefer Yarn v4+ for all new projects.
8
21
 
@@ -27,138 +40,35 @@ description: NPM & Yarn patterns
27
40
 
28
41
  # Hoisting
29
42
 
30
- - Hoist everything: keep the package manager's DEFAULT hoisting — do not set `installConfig.hoistingLimits`/`nmHoistingLimits` or Yarn 1 `nohoist`; the historical React Native/Expo/Electron reasons 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)
31
- - 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)
32
- - 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
33
- - 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
34
- - Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
35
- - npm / Yarn: default hoisting already exposes them
36
- - 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)
37
- - Yarn PnP: declare the tools at the workspace root as well
38
- - 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
43
+ - Hoist everything: keep the DEFAULT hoisting of the package manager. Do not set `installConfig.hoistingLimits`, `nmHoistingLimits` or Yarn 1 `nohoist`.
44
+ - Shared root configs (e.g. `@kirill.konshin/lint`) must resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root.
45
+ - Electron, pnpm, binary packagers, "not resolvable from the workspace root": see the `lint-npm-yarn` skill.
39
46
 
40
47
  # Consistent versions
41
48
 
42
- In monorepos pin versions of sub-packages to the root; these packages cause issues when versions drift.
43
-
44
- https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332 https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
45
-
46
- Root `package.json`:
47
-
48
- ```json
49
- {
50
- "overrides": {
51
- "@types/node": "$@types/node",
52
- "@types/react": "$@types/react",
53
- "@types/react-dom": "$@types/react-dom",
54
- "next": "$next",
55
- "eslint": "$eslint",
56
- "typescript": "$typescript",
57
- "vite": "$vite"
58
- },
59
- "resolutions": {
60
- "@types/node": "^26",
61
- "@types/react": "^19",
62
- "@types/react-dom": "^19",
63
- "eslint": "^10",
64
- "next": "^16",
65
- "typescript": "^6",
66
- "vite": "^8"
67
- }
68
- }
69
- ```
70
-
71
- All other `package.json`:
72
-
73
- ```jsonc
74
- {
75
- "devDependencies": {
76
- "next": "^16.0.0", // except next, see nextjs.md
77
- "typescript": "^6.0.0",
78
- },
79
- }
80
- ```
81
-
82
- 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.
83
-
84
- Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
85
-
86
- ```js
87
- /** @type {import('@yarnpkg/types')} */
88
- const { defineConfig } = require('@yarnpkg/types');
89
- const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
90
-
91
- module.exports = defineConfig(defineYarnConfig());
92
- ```
93
-
94
- Run `yarn constraints --fix` after dependency changes.
95
-
96
- # `.yarnrc.yml`
97
-
98
- Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
99
-
100
- ```yml
101
- approvedGitRepositories:
102
- - '**'
103
-
104
- # print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
105
- enableInlineBuilds: true
106
-
107
- enableScripts: true
108
-
109
- nodeLinker: node-modules
110
-
111
- npmMinimalAgeGate: 0
112
-
113
- # own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
114
- npmPreapprovedPackages:
115
- - '@kirill.konshin/*'
116
- ```
49
+ - In monorepos, pin the versions of shared packages at the root (`overrides` + `resolutions`). Drift in these versions causes issues.
50
+ - Every package with `"packageManager": "yarn@..."` MUST install `@yarnpkg/types` and use `defineYarnConfig` from `@kirill.konshin/lint/yarn` in `yarn.config.cjs`.
51
+ - Run `yarn constraints --fix` after dependency changes.
52
+ - Do not specify `yarnPath` in `.yarnrc.yml`. Use `packageManager` in `package.json` and Corepack.
117
53
 
118
54
  # Install on CI
119
55
 
120
- The single source for CI install rules. Platform steps: github.md, gitlab.md.
56
+ The single source for CI install rules. Platform steps: [github.md](github.md), [gitlab.md](gitlab.md). Shared cache volume and speed-up options: the `lint-npm-yarn` skill.
121
57
 
122
58
  - On CI, set `YARN_ENABLE_GLOBAL_CACHE=false`. Yarn then keeps all packages in `.yarn/cache`, and CI caches this folder.
123
59
  - Cache only `.yarn/cache`. NEVER cache `node_modules`: it has too many files to pack and unpack quickly.
60
+ - Exception: the Vite+ task cache `node_modules/.vite/task-cache` (experimental, https://viteplus.dev/guide/github-actions-cache). Measure first. Restore it after install. Use a rolling key `vite-task-<os>-<arch>-<run id>` with a `vite-task-<os>-<arch>-` restore prefix. Do not put sources or lockfiles in the key: Vite Task fingerprints them.
124
61
  - IF parallel jobs follow the install, add an `install` job. This job fills the Yarn cache and saves it. The other jobs only read it.
125
62
  - IF the pipeline has one job, or its jobs run one after another, do not add an `install` job.
126
- - Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
127
- - 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.
128
- - 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".
129
- - 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.
130
- - 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.
131
- - With pnpm, set `store-dir` on the volume.
132
- - Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
133
- - 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.
134
- - 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.
135
- - Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
136
- - A CI image with the dependencies installed
137
63
  - IF in doubt, keep `nodeLinker: node-modules`.
138
64
 
139
- # Yalc (Local Package Linking)
140
-
141
- Test unpublished packages in sibling projects (yalc is a root devDependency here):
142
-
143
- 1. `yarn nx run @kirill.konshin/<pkg>:build`
144
- 2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
145
- 3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from this repo)
146
-
147
- Rules:
65
+ # Yalc
148
66
 
149
- - ALWAYS use `yalc link` (symlink mode: `node_modules/<pkg>` → local `.yalc/<pkg>` copy), NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
150
- - 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
151
- - 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
152
- - 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)
153
- - A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
154
- - Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
155
- - 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)
156
- - `.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
67
+ - ALWAYS use `yalc link`, NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
68
+ - NEVER commit link artifacts; gitignore `.yalc/` and `yalc.lock` in the consumer
69
+ - Procedure and pitfalls: the `lint-npm-yarn` skill
157
70
 
158
- # First Publish with OIDC
71
+ # Publishing
159
72
 
160
73
  - Never bootstrap, publish, or push a release without explicit approval.
161
- - 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.
162
- - Configure its GitHub trusted publisher for organization/user `kirill-konshin`, repository `utils`, workflow `release.yml`, optional environment `npm-publish`, and check **Allow npm publish**.
163
- - 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.
164
- - The first conventional `feat` release establishes the normal `latest` version.
74
+ - First publish of a new package with OIDC: the `lint-npm-yarn` skill.
package/rules/nx.md CHANGED
@@ -11,7 +11,7 @@ paths:
11
11
 
12
12
  - If NX is used root `package.json` must have `nx show projects > /dev/null` in the `prepare`/`postinstall` script, so the project graph cache exists for tools that read it outside `nx` — e.g. `@nx/eslint-plugin` rules in a bare `eslint` run silently skip without it. With `prepare`, Yarn 2+ skips it on install — run `yarn prepare` explicitly (after cloning + as a CI step); with `postinstall` (private root) Yarn runs it on install, so no extra step
13
13
  - With Nx Cloud (`nxCloudId` in `nx.json`) the remote cache replaces CI caching of `.nx/cache` — do NOT cache `.nx` in CI. Set Workspace visibility → Organization members only in the Nx Cloud workspace settings (no anonymous access; fork PRs run without the cache); developers run `npx nx login` once (personal read-write token in the home folder, no env var); CI passes `NX_CLOUD_ACCESS_TOKEN` from repository secrets (environment secrets reach only jobs that declare the environment): a read-write CI access token only on protected branches (`main`, release), a read-only CI access token everywhere else
14
- - Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see `github.md` / `gitlab.md`). One cache entry holds one DB, so restoring several entries does not merge their outputs.
14
+ - Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see [github.md](github.md) / [gitlab.md](gitlab.md)). One cache entry holds one DB, so restoring several entries does not merge their outputs.
15
15
  - NX Release (v23+) with conventional commits silently demotes bumps for `0.x` packages (breaking → minor, `feat` → patch) while the log still claims `Applied semver relative bump "minor"`;
16
16
  - set `release.version.adjustSemverBumpsForZeroMajorVersion: false` in `nx.json` if `feat:` must bump minor before `1.0.0`
17
17
  - Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with NO `--parallel` flags: parallelism lives in the root `.env` (`NX_PARALLEL=50%` — Nx loads it before every command and parses percentages; `nx.json` `parallel` takes only a number, a string there dispatches nothing); continuous tasks (`start`) always all run, each in its own slot; test runners limit their own workers (Vitest `maxWorkers: '50%'`);
@@ -6,7 +6,7 @@ paths:
6
6
  - '**/e2e/**'
7
7
  ---
8
8
 
9
- - The apps under test are started outside Playwright, never by its `webServer`: the e2e target `dependsOn` the continuous `start` / `dev` / `serve` targets plus their `wait` probes (`wait-on`), or Docker Compose runs the stack and the suite as a service; see monorepo-turbo-nx.md
9
+ - The apps under test are started outside Playwright, never by its `webServer`: the e2e target `dependsOn` the continuous `start` / `dev` / `serve` targets plus their `wait` probes (`wait-on`), or Docker Compose runs the stack and the suite as a service; see [monorepo-turbo-nx.md](monorepo-turbo-nx.md)
10
10
  - The suite reaches the apps through `baseURL` (and other URLs) from the environment, so the same specs run locally, in Compose and against a deployment
11
11
  - E2E targets against running apps are `cache: false`; reports and traces (`test-results`, `playwright-report`) are their outputs and CI artifacts
12
12
  - How Playwright splits the work:
package/rules/react.md CHANGED
@@ -13,12 +13,11 @@ paths:
13
13
  - `ReactElement<...>` if object-specific
14
14
  - If extending functionality of existing component use it's Props:
15
15
  - `type DerivedProps = CmpProps & {...}` if `Cmp` provides `CmpProps` (preferred)
16
- - `type DerivedProps = ComponentProps<typeof Cmp> & {...}` if `Cmp` does provide `CmpProps`
17
- - ALWAYS prefer using memoized components
18
- - Memoize everything
16
+ - `type DerivedProps = ComponentProps<typeof Cmp> & {...}` if `Cmp` does not provide `CmpProps`
17
+ - Memoize components and callbacks unless React Compiler is enabled in the project
19
18
  - Prefer `memo<Props>(...)`
20
19
  - Use `FC<Props> = memo(...)` if `--isolatedDeclarations` flag is on
21
- - ALWAYS use `useCallback` if React Compiler is not enabled in project
20
+ - Wrap callbacks in `useCallback`
22
21
  - Prefer to set defaults while destructuring props: `function Cmp({ children = 'xxx' })` where applicable
23
22
 
24
23
  ```tsx
@@ -42,14 +41,14 @@ const containerDefaultProps = SOME_GLOBAL_SETTING ? { ... } : {};
42
41
  ```tsx
43
42
  'use client';
44
43
 
45
- import { createContext, useContext, useMemo, useState, ReactNode } from 'react';
44
+ import { createContext, useContext, useMemo, useState, Dispatch, ReactNode, SetStateAction } from 'react';
46
45
 
47
46
  // Always type Context explicitly
48
47
  // Never export context itself
49
48
  const ExampleContext = createContext<{
50
- setEnabled: (prev: boolean) => boolean;
51
- enabled: false;
52
- }>(null);
49
+ enabled: boolean;
50
+ setEnabled: Dispatch<SetStateAction<boolean>>;
51
+ } | null>(null);
53
52
 
54
53
  // Export provider
55
54
  export function ExampleContextProvider({ children }: { children: ReactNode }) {
@@ -59,7 +58,7 @@ export function ExampleContextProvider({ children }: { children: ReactNode }) {
59
58
  // memoize context value
60
59
  const value = useMemo(() => ({ enabled, setEnabled }), [enabled, setEnabled]);
61
60
 
62
- return <ExampleContext.Provider value={control}>{children}</ExampleContext.Provider>;
61
+ return <ExampleContext.Provider value={value}>{children}</ExampleContext.Provider>;
63
62
  }
64
63
 
65
64
  // Export hook for consumers
package/rules/tailwind.md CHANGED
@@ -1,59 +1,20 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: Set of rules for projects which use Tailwind
4
+ paths:
5
+ - '**/*.css'
6
+ - '**/*.tsx'
4
7
  ---
5
8
 
6
- - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see mui.md)
9
+ The `@utility` template and the lint-plugin setup: the `lint-tailwind` skill.
10
+
11
+ - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see the `lint-mui` skill)
7
12
  - Always use latest version of Tailwind
8
13
  - Default UI library for use with Tailwind is Hero UI v3+
9
14
  - Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
10
15
  - Define safe-area insets as named Tailwind utilities; never repeat arbitrary `env(...)` or safe-area calculations in components
11
16
  - Safe-area positioning utilities must declare an unconditional design-system gutter first, then enhance it with the maximum of that gutter and the device-reported inset on every edge; use at least `1.5rem` for floating controls because insets can be zero and custom-property resolution can fail on real devices
12
-
13
- ```css
14
- @utility top-safe {
15
- top: 1.5rem;
16
- top: max(1.5rem, env(safe-area-inset-top, 0px));
17
- }
18
-
19
- @utility right-safe {
20
- right: 1.5rem;
21
- right: max(1.5rem, env(safe-area-inset-right, 0px));
22
- }
23
-
24
- @utility bottom-safe {
25
- bottom: 1.5rem;
26
- bottom: max(1.5rem, env(safe-area-inset-bottom, 0px));
27
- }
28
-
29
- @utility left-safe {
30
- left: 1.5rem;
31
- left: max(1.5rem, env(safe-area-inset-left, 0px));
32
- }
33
- ```
34
-
35
- # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
36
-
37
- - 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`
38
- - The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
39
- - 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
40
- - Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
41
- - `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see npm-yarn.md "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
42
- - Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
43
- - pass `cssConfigPath` to pick one (if others are not useful) OR
44
- - create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
45
- - 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
46
- - ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
47
-
48
- ```js
49
- import { defineLintConfig } from '@kirill.konshin/lint';
50
-
51
- export default defineLintConfig({
52
- tailwind: {
53
- cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
54
- },
55
- });
56
- ```
17
+ - Lint (eslint-plugin-tailwindcss, also as an Oxlint JS plugin with Vite+) MUST resolve the Tailwind entry CSS, else it crashes; setup: the `lint-tailwind` skill
57
18
 
58
19
  # Hero UI
59
20
 
package/rules/testing.md CHANGED
@@ -12,8 +12,8 @@ paths:
12
12
  ---
13
13
 
14
14
  - If project use `vite` or `vite-plus` use `vitest` (`vp test`, imports from `vite-plus/test`), otherwise `jest`
15
- - With Nx / Turbo, CI runs tests through the orchestrator and its cache (full and affected); the test tool at the root over all projects (`vp test` with `test.projects`, `maxWorkers: '100%'`) is the local full-speed run (see monorepo-turbo-nx.md)
16
- - If project needs browser-based testing use `playwright`; it splits work over worker processes, test files and `--shard`s (see playwright.md)
15
+ - With Nx / Turbo, CI runs tests through the orchestrator and its cache (full and affected); the test tool at the root over all projects (`vp test` with `test.projects`, `maxWorkers: '100%'`) is the local full-speed run (see [monorepo-turbo-nx.md](monorepo-turbo-nx.md))
16
+ - If project needs browser-based testing use `playwright`; it splits work over worker processes, test files and `--shard`s (see [playwright.md](playwright.md))
17
17
  - Suites that need a real server (integration, e2e — Vitest / Jest too): a separate test config and target (e.g. `test:integration` with `vitest.integration.config.ts` over `*.spec.ts`), started by the orchestrator — `dependsOn` the continuous `dev` / `start` plus a `wait` probe, `cache: false` — with a JUnit report; a CI job against an external environment may be allowed to fail, and is not created where its credentials are missing
18
18
  - Naming
19
19
  - `*.test.ts` for unit tests
package/rules/turbo.md CHANGED
@@ -64,7 +64,7 @@ When an app needs a sibling service running in dev (`web` needs `api`), combine:
64
64
 
65
65
  - `"with": ["api#start"]` — launches the service alongside, so `turbo run start --filter=web` brings up both (convenience instead of whole-repo `start`)
66
66
  - `"dependsOn": ["api#wait"]` — blocks `web#start` until the readiness probe exits
67
- - Name the probe task `wait` (NOT `dev:ready` as in the Turbo guide) — same task the `^wait` pattern uses (see monorepo-turbo-nx.md)
67
+ - Name the probe task `wait` (NOT `dev:ready` as in the Turbo guide) — same task the `^wait` pattern uses (see [monorepo-turbo-nx.md](monorepo-turbo-nx.md))
68
68
  - NEVER put persistent tasks in `dependsOn` — they never exit, so dependents never unblock; depend on the finite `wait` probe
69
69
  - `wait` lives in the service package so it self-identifies readiness: `"wait": "wait-on http://localhost:3001/health"` (URL, TCP port, file, socket)
70
70
  - Task overrides replace, they don't merge — keep `^wait` when overriding `start`
@@ -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: