@kirill.konshin/lint 0.3.3 → 0.3.5
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/package.json +1 -1
- package/rules/auth.md +29 -0
- package/rules/github.md +14 -1
- package/rules/gitlab.md +3 -1
- package/rules/mui.md +6 -0
- package/rules/nextjs.md +5 -1
- package/rules/npm-yarn.md +15 -4
package/package.json
CHANGED
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
|
package/rules/github.md
CHANGED
|
@@ -28,6 +28,7 @@ jobs:
|
|
|
28
28
|
runs-on: ubuntu-latest
|
|
29
29
|
env:
|
|
30
30
|
TURBO_CACHE_DIR: .turbo # if project uses Turbo
|
|
31
|
+
YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
|
|
31
32
|
|
|
32
33
|
# If project publishes to NPM
|
|
33
34
|
# https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
|
|
@@ -52,6 +53,10 @@ jobs:
|
|
|
52
53
|
- name: Enable Corepack
|
|
53
54
|
run: corepack enable
|
|
54
55
|
|
|
56
|
+
- name: Get yarn cache directory path
|
|
57
|
+
id: yarn-cache-dir-path
|
|
58
|
+
run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
|
|
59
|
+
|
|
55
60
|
- name: Install dependencies
|
|
56
61
|
run: yarn install --immutable
|
|
57
62
|
|
|
@@ -59,10 +64,18 @@ jobs:
|
|
|
59
64
|
- name: Prepare
|
|
60
65
|
run: yarn prepare
|
|
61
66
|
|
|
67
|
+
- uses: actions/cache@v6
|
|
68
|
+
id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
|
|
69
|
+
with:
|
|
70
|
+
path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
|
|
71
|
+
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
|
|
72
|
+
restore-keys: |
|
|
73
|
+
${{ runner.os }}-yarn-
|
|
74
|
+
|
|
62
75
|
#TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
|
|
63
76
|
#TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
|
|
64
77
|
- name: Cache turbo build setup
|
|
65
|
-
uses: actions/cache@
|
|
78
|
+
uses: actions/cache@v6
|
|
66
79
|
with:
|
|
67
80
|
path: .turbo
|
|
68
81
|
key: ${{ runner.os }}-turbo-${{ github.sha }}
|
package/rules/gitlab.md
CHANGED
|
@@ -13,6 +13,8 @@ paths:
|
|
|
13
13
|
```yml
|
|
14
14
|
build:
|
|
15
15
|
image: node:24
|
|
16
|
+
env:
|
|
17
|
+
YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
|
|
16
18
|
cache:
|
|
17
19
|
key:
|
|
18
20
|
files:
|
|
@@ -24,7 +26,7 @@ build:
|
|
|
24
26
|
- '**/node_modules'
|
|
25
27
|
- '**/.turbo'
|
|
26
28
|
- '**/.tscache'
|
|
27
|
-
-
|
|
29
|
+
- '**/.next/cache'
|
|
28
30
|
script:
|
|
29
31
|
- yarn --immutable
|
|
30
32
|
- yarn prepare # Add this if Yarn 2+ is used and package is NOT private
|
package/rules/mui.md
CHANGED
|
@@ -13,4 +13,10 @@ paths:
|
|
|
13
13
|
|
|
14
14
|
- ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see tailwind.md)
|
|
15
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)
|
|
16
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,12 +10,16 @@ _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)
|
|
15
18
|
|
|
16
19
|
# Admin Pages & Login
|
|
17
20
|
|
|
18
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
|
|
19
23
|
- Use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
|
|
20
24
|
- Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
|
|
21
25
|
|
package/rules/npm-yarn.md
CHANGED
|
@@ -60,10 +60,21 @@ All other `package.json`:
|
|
|
60
60
|
|
|
61
61
|
# `.yarnrc.yml`
|
|
62
62
|
|
|
63
|
+
Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
|
|
64
|
+
|
|
63
65
|
```yml
|
|
64
|
-
|
|
66
|
+
approvedGitRepositories:
|
|
67
|
+
- '**'
|
|
68
|
+
|
|
69
|
+
compressionLevel: mixed
|
|
70
|
+
|
|
71
|
+
enableScripts: true
|
|
72
|
+
|
|
65
73
|
nodeLinker: node-modules
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
74
|
+
|
|
75
|
+
npmMinimalAgeGate: 0
|
|
76
|
+
|
|
77
|
+
# own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
|
|
78
|
+
npmPreapprovedPackages:
|
|
79
|
+
- '@kirill.konshin/*'
|
|
69
80
|
```
|