@kirill.konshin/lint 0.3.2 → 0.3.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.
package/README.md CHANGED
@@ -155,6 +155,7 @@ end_of_line = lf
155
155
  charset = utf-8
156
156
  trim_trailing_whitespace = true
157
157
  insert_final_newline = false
158
+ max_line_length = 120
158
159
 
159
160
  [*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}]
160
161
  indent_size = 4
@@ -215,10 +216,11 @@ By default, always use the `prepare` script, as [Husky recommends](https://typic
215
216
 
216
217
  ```bash
217
218
  #!/bin/zsh
218
- source ~/.zshrc # for VSCode terminal
219
219
  yarn lint:staged
220
220
  ```
221
221
 
222
+ Note `source ~/.zshrc # for VSCode terminal` may be added for VSCode terminal that is not aware of ZSH. Do not add unless specifically asked, and remove if present.
223
+
222
224
  ## AI Agent Rules
223
225
 
224
226
  The package also ships a standardized set of coding conventions (`rules/*.md`) and skills for AI coding assistants, wired into a repo by the `lint-prepare` CLI.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
- "version": "0.3.2",
4
+ "version": "0.3.4",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
@@ -70,6 +70,7 @@
70
70
  "prettier": "^3",
71
71
  "storybook": "^10.5.2",
72
72
  "tailwindcss": "*",
73
+ "typescript": "^6",
73
74
  "vite": "*",
74
75
  "vitest": "*"
75
76
  },
package/rules/auth.md ADDED
@@ -0,0 +1,29 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects with Auth & Next.js
4
+ paths:
5
+ - '**/*.tsx'
6
+ - '**/*.ts'
7
+ ---
8
+
9
+ - ALWAYS use [`@kirill.konshin/auth`](https://github.com/kirill-konshin/utils/tree/main/packages/auth) ([npm](https://www.npmjs.com/package/@kirill.konshin/auth)) for authentication in Next.js apps, NEVER hand-roll `iron-session` wrappers
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
+ - ONE auth instance per app in `src/auth.ts`: `createPasswordAuth` (password-protected admin) or `createAuth` (token/OAuth)
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)
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
+ - Cookie name MUST be unique per app (`<app>_session`), NEVER generic `session`
17
+ - Cookie secret `SESSION_SECRET` (≥32 chars) and login password `ADMIN_PASSWORD` are SEPARATE env vars, never reuse one for the other
18
+ - NEVER compare passwords with `===`, use `verifyPassword` / `timingSafeEqualStrings` (timing-safe)
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
+ - 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
+ - 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
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
+ - 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
+ - `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
26
+ - Login page is ONE Server Component file with `<form action={loginAction}>` (wrapping `auth.loginAction`) — errors return via the `?error=` search param; a Client Component (`useActionState` + `loginFormAction`) ONLY when pending/inline-error UI is actually needed
27
+ - Reuse `auth.urls.*` (resolved, defaults applied) instead of repeating route literals, e.g. `redirect(auth.urls.afterLogin)`
28
+ - List page routes in `urls.public` — `proxyGuard()` stamps `x-pathname` so `redirectNonAuthenticated()` returns users to the deep page after login (pages are enforced by layouts, not by the proxy)
29
+ - Login page MUST live OUTSIDE the guarded layout (the guard would redirect to itself); `urls.afterLogin` pointing at the login page throws at creation
@@ -27,8 +27,9 @@ ALWAYS verify `turbo.json` or `nx.json` task definitions when modifying scripts
27
27
 
28
28
  # The `dependsOn: ["^wait"]` Pattern
29
29
 
30
- https://github.com/vercel/turborepo/issues/1497
31
- https://github.com/vercel/turborepo/discussions/1299
30
+ - https://github.com/vercel/turborepo/issues/1497
31
+ - https://github.com/vercel/turborepo/discussions/1299
32
+ - https://turborepo.dev/docs/guides/coordinating-runtime-dependencies
32
33
 
33
34
  Neither Turbo nor NX can run `persistent` or `continuous` dependent tasks in order. If package `A` depends on `B` and both have `start` command, in freshly checked out repo `A` will fail as `B` does not have anything built yet. Besides, two continuous tasks can't depend on each other as neither will ever exit. Options are:
34
35
 
@@ -54,3 +55,5 @@ The `start` task uses `"dependsOn": ["^wait"]` (upstream):
54
55
  3. `B` also runs `"start": "build --watch"` task (for example) which produces `dist/index.js`
55
56
  4. Once the file exists, `B`'s `wait-on` unblocks and exits, and `A`'s `start` can proceed
56
57
  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
58
+
59
+ For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in turbo.md.
package/rules/mui.md CHANGED
@@ -8,3 +8,15 @@ paths:
8
8
  - To use MUI default classes always use following notation because it's the only one that works with minification:
9
9
  - Import: `import Input, { inputClasses } from '@mui/material/Input';`
10
10
  - Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
11
+
12
+ # Admin Pages & Login
13
+
14
+ - ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see tailwind.md)
15
+ - ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
16
+ - 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)
17
+ - Use as less custom JSX as possible — prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled components
18
+
19
+ # Next.js
20
+
21
+ - 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`)
22
+ - Prefer `defineNextConfig` from `@kirill.konshin/next` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see nextjs.md)
package/rules/nextjs.md CHANGED
@@ -10,8 +10,18 @@ _EVERY_ Next.js page, layout, route handler or component must adhere to policy u
10
10
  - Prefer Route Handlers for redirects
11
11
  - Never use Pages Router
12
12
  - Always use App Router
13
- - Use `iron-session` for authentication
13
+ - Use `iron-session` for authentication via `@kirill.konshin/auth`, see auth.md
14
+ - Server-only modules (auth/session, DB access, anything touching secrets) 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
14
15
  - `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
16
+ - ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next`: 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)
17
+ - Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it)
18
+
19
+ # Admin Pages & Login
20
+
21
+ - 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
22
+ - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see mui.md
23
+ - Use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
24
+ - Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
15
25
 
16
26
  # Layouts
17
27
 
package/rules/tailwind.md CHANGED
@@ -3,6 +3,7 @@ type: always_apply
3
3
  description: Set of rules for projects which use Tailwind
4
4
  ---
5
5
 
6
+ - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see mui.md)
6
7
  - Always use latest version of Tailwind
7
8
  - Default UI library for use with Tailwind is Hero UI v3+
8
9
  - Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
package/rules/turbo.md CHANGED
@@ -10,31 +10,30 @@ paths:
10
10
 
11
11
  ```jsonc
12
12
  {
13
- "$schema": "https://turbo.build/schema.json",
14
- "globalDependencies": ["tsconfig.json"],
15
- "tasks": {
16
-
17
- // define task defaults
13
+ "$schema": "https://turbo.build/schema.json",
14
+ "globalDependencies": ["tsconfig.json"],
15
+ "tasks": {
16
+ // define task defaults
18
17
 
19
- "build": {},
20
- "wait": {
21
- "cache": false
22
- },
23
- "test": {
24
- "outputs": ["coverage/**/*"]
25
- },
26
- "start": {
27
- "persistent": true,
28
- "cache": false
29
- "dependsOn": ["^wait"]
30
- },
18
+ "build": {},
19
+ "wait": {
20
+ "cache": false,
21
+ },
22
+ "test": {
23
+ "outputs": ["coverage/**/*"],
24
+ },
25
+ "start": {
26
+ "persistent": true,
27
+ "cache": false,
28
+ "dependsOn": ["^wait"],
29
+ },
31
30
 
32
- // root tasks
31
+ // root tasks
33
32
 
34
- "//#lint": {
35
- "cache": false
33
+ "//#lint": {
34
+ "cache": false,
35
+ },
36
36
  },
37
- }
38
37
  }
39
38
  ```
40
39
 
@@ -56,3 +55,30 @@ paths:
56
55
  },
57
56
  }
58
57
  ```
58
+
59
+ # Runtime Services: `with` + `wait` (e.g. `web` <> `api`)
60
+
61
+ https://turborepo.dev/docs/guides/coordinating-runtime-dependencies
62
+
63
+ When an app needs a sibling service running in dev (`web` needs `api`), combine:
64
+
65
+ - `"with": ["api#start"]` — launches the service alongside, so `turbo run start --filter=web` brings up both (convenience instead of whole-repo `start`)
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)
68
+ - NEVER put persistent tasks in `dependsOn` — they never exit, so dependents never unblock; depend on the finite `wait` probe
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
+ - Task overrides replace, they don't merge — keep `^wait` when overriding `start`
71
+ - Run with at least `--concurrency=3` (a slot per persistent task + the probe)
72
+
73
+ ```jsonc
74
+ // ./apps/web/turbo.json
75
+ {
76
+ "extends": ["//"],
77
+ "tasks": {
78
+ "start": {
79
+ "with": ["api#start"],
80
+ "dependsOn": ["^wait", "api#wait"],
81
+ },
82
+ },
83
+ }
84
+ ```
@@ -11,6 +11,7 @@ paths:
11
11
 
12
12
  - ALL projects must use TypeScript by default
13
13
  - JavaScript is acceptable for service scripts, but discouraged, use `ts-node`
14
+ - Do NOT upgrade to TypeScript 7 until `typescript-eslint` supports it
14
15
  - ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
15
16
  - Prefer short-circuit evaluation and early exit
16
17
  - Use structured logging with context, consider adding function arguments to log:
package/rules/webstorm.md CHANGED
@@ -131,3 +131,49 @@ Applies if project is using Tailwind.
131
131
  </component>
132
132
  </project>
133
133
  ```
134
+
135
+ # Configure `.idea/jsonSchemas.xml`
136
+
137
+ ```xml
138
+ <?xml version="1.0" encoding="UTF-8"?>
139
+ <project version="4">
140
+ <component name="JsonSchemaMappingsProjectConfiguration">
141
+ <state>
142
+ <map>
143
+ <entry key="Gemini CLI settings">
144
+ <value>
145
+ <SchemaInfo>
146
+ <option name="name" value="Gemini CLI settings" />
147
+ <option name="relativePathToSchema" value="https://raw.githubusercontent.com/google-gemini/gemini-cli/refs/heads/main/schemas/settings.schema.json" />
148
+ <option name="applicationDefined" value="true" />
149
+ <option name="patterns">
150
+ <list>
151
+ <Item>
152
+ <option name="path" value=".gemini/settings.json" />
153
+ </Item>
154
+ </list>
155
+ </option>
156
+ </SchemaInfo>
157
+ </value>
158
+ </entry>
159
+ <entry key="Yarn Config (.yarnrc.yml)">
160
+ <value>
161
+ <SchemaInfo>
162
+ <option name="name" value="Yarn Config (.yarnrc.yml)" />
163
+ <option name="relativePathToSchema" value="https://yarnpkg.com/configuration/yarnrc.json" />
164
+ <option name="applicationDefined" value="true" />
165
+ <option name="patterns">
166
+ <list>
167
+ <Item>
168
+ <option name="path" value=".yarnrc.yml" />
169
+ </Item>
170
+ </list>
171
+ </option>
172
+ </SchemaInfo>
173
+ </value>
174
+ </entry>
175
+ </map>
176
+ </state>
177
+ </component>
178
+ </project>
179
+ ```