@starci/eslint-canon-fe 8.2.13 → 8.2.15

package/lib/why.mjs

@@ -11,7 +11,7 @@
  * `fix` strings are the keys of `modules/i18n/messages/canon.yaml`, so `translator('vi')(entry.en)` and
  * `translator('vi')(entry.fix)` hand back the Vietnamese of the same sentence.
  *
- * Every rule that carries a catalogue id (R18, R22, R49-R59, R60-R62, R65) has an entry;
+ * Every rule that carries a catalogue id (R18, R22, R49-R59, R60-R62, R65, the fe-stack catalog) has an entry;
  * the twin test refuses a rule of those laws with no entry and an entry for a rule that does not exist.
  */
 
@@ -31,12 +31,12 @@ export const why = {
   },
   "fetch-only-in-api-client": {
     code: "FE_TRANSPORT_OWNER",
-    en: "`fetch` (or `Request`, `EventSource`, `sendBeacon`, another HTTP library) in `<file>` sits outside the one client (`modules/api/client.ts`, or `src/client.ts` of the shared api package). A repo has exactly one transport.",
-    fix: "Call the repo's client and receive `Outcome<T>`; do not call `fetch` yourself.",
+    en: "`<file>` reaches the back end outside the API layer: `fetch` (or `Request`, `EventSource`, `sendBeacon`, another HTTP library) outside `modules/api`, or Apollo, axios or socket.io-client outside its home (`modules/api`, `modules/api/rest`, `hooks/socketio`).",
+    fix: "Call an operation of `modules/api` (Apollo GraphQL, or axios in `modules/api/rest`) through its SWR hook in `hooks/swr`; listen to realtime through `hooks/socketio`.",
   },
   "client-fetch-has-signal": {
     code: "FE_TRANSPORT_OWNER",
-    en: "`fetch` in `<file>` has no `signal`. The client must carry a timeout and an `AbortSignal`.",
+    en: "`fetch` in `<file>` has no `signal`. Every request of the API layer must carry a timeout and an `AbortSignal`.",
     fix: "Pass `signal` (`AbortSignal.timeout(...)` combined with the caller's signal).",
   },
   "no-shared-transport-state": {
@@ -56,8 +56,8 @@ export const why = {
   },
   "no-hand-typed-wire": {
     code: "FE_WIRE_GENERATED",
-    en: "`<file>` hand-types a wire type or casts a response. Use the types generated from `be/contracts/`.",
-    fix: "Run codegen from the be contract snapshot (`be/contracts/`) and import the generated types; put GraphQL documents in `.graphql` files.",
+    en: "`<file>` hand-types a wire type, casts a response, or writes a GraphQL document outside the API layer. Use the types generated from `be/contracts/`.",
+    fix: "Run codegen from the be contract snapshot (`be/contracts/`) and import the generated types; write each GraphQL document in its operation file under `modules/api/graphql/queries` or `modules/api/graphql/mutations`.",
   },
   "use-client-only-at-boundary": {
     code: "FE_CLIENT_BOUNDARY",
@@ -66,8 +66,8 @@ export const why = {
   },
   "hooks-folder-holds-hooks-only": {
     code: "FE_HOOKS_ARE_HOOKS",
-    en: "`<file>` inside `hooks/` is not a React hook. A server reader goes to `modules/api`, a helper to `<domain>.shared.ts`.",
-    fix: "One hook per `use*.ts` file; a shared helper goes in `<domain>.shared.ts`; a server reader goes in `modules/api/<domain>/read-*.ts`.",
+    en: "`<file>` inside `hooks/` is not a React hook, or is not a file its hooks family names. A call to the back end goes to `modules/api`, a helper to `<domain>.shared.ts`.",
+    fix: "One hook per `use*.ts` file under the name its family gives it (`hooks/swr/api/graphql/queries/useQuery<X>Swr.ts`, `hooks/rhf/use<X>Form.ts`, ...); a shared helper goes in `<domain>.shared.ts`; a back-end call is an operation of `modules/api`.",
   },
   "no-middleware-file": {
     code: "FE_NEXT_CONVENTIONS",
@@ -172,7 +172,7 @@ export const why = {
   "no-data-fetch-in-effect": {
     code: "FE_EFFECT_FETCH",
     en: "`useEffect` in `<file>` starts a promise (`await`, `fetch`, `.then`, `void load()`, `mutate()`/`refresh()` called directly): no cache, no request merging, no loading/error state, no abort. Freshness of data comes from the SWR key, not from an effect.",
-    fix: "Read on the client with SWR calling the app's client (`hooks/`) keyed by what changes; call `mutate()` from the event that changes the data (handler, socket message); on the route use the server reader `modules/api/<domain>/read-*.ts`.",
+    fix: "Read with an SWR hook of `hooks/swr` over an operation of `modules/api`, keyed by what changes; call `mutate()` from the event that changes the data (handler, socket message).",
   },
   "no-empty-catch": {
     code: "FE_SWALLOWED_ERROR",
@@ -216,14 +216,19 @@ export const why = {
   },
   "client-no-server-import": {
     code: "FE_CLIENT_SERVER_IMPORT",
-    en: "A client component in `<file>` imports code that exists only on the server (`server-only`, `next/headers`, a Node module, a server reader).",
-    fix: "Read the data in a server component or a server reader and pass it down as props; or use SWR calling the app's client.",
+    en: "A client component in `<file>` imports code that exists only on the server (`server-only`, `next/headers`, a Node module, a server-only module).",
+    fix: "Read the data through an SWR hook of `hooks/swr` over an operation of `modules/api`; keep request-scoped server APIs in server components.",
   },
   "server-module-marks-server-only": {
     code: "FE_SERVER_ONLY_MARK",
     en: "Module `<file>` imports a server-only API (`next/headers`, `next/server`, `next-intl/server`, a Node module or an already server-only module) but does not open with `import \"server-only\"`.",
     fix: "Make `import \"server-only\"` the file's first statement; route files (`page`, `layout`, `route`, `proxy`) are server components already and need none.",
   },
+  "no-server-action": {
+    code: "FE_SERVER_ACTION_FORBIDDEN",
+    en: "`<file>` carries a `\"use server\"` directive: a Server Action, an endpoint the front end serves. The front end serves no API.",
+    fix: "Write it as a GraphQL mutation of the back end and call it through its operation in `modules/api` and its SWR hook in `hooks/swr`.",
+  },
   "web-storage-only-in-modules": {
     code: "FE_STORAGE_OUTSIDE_MODULES",
     en: "`<file>` uses `localStorage`/`sessionStorage` outside `modules/`; storage does not exist on the server and throws when over quota.",
@@ -261,8 +266,8 @@ export const why = {
   },
   "one-outcome-union": {
     code: "FE_HTTP_STATUS_COLLAPSE",
-    en: "`<file>` declares another result union (`ok` or `kind`) outside `outcome.ts`. A repo has only one `Outcome<T>`.",
-    fix: "Use `Outcome<T>` of `modules/api/outcome.ts` (or the shared api package); add business detail through the second parameter instead of declaring a new union.",
+    en: "`<file>` declares another result union (`success`, `ok` or `kind`) outside `modules/api/graphql/types.ts`. A repo has only one result vocabulary, `GraphQLResponse<T>`.",
+    fix: "Use `GraphQLResponse<T>` of `modules/api/graphql/types.ts` (or the shared api package); put the business detail in its `data` instead of declaring a new union.",
   },
   "i18n-stack-in-one-module": {
     code: "FE_I18N_PLACEMENT",
@@ -274,6 +279,11 @@ export const why = {
     en: "Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not hand-written HTML.",
     fix: "Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if grammar lacks it, add it to grammar or the ui package instead of drawing it in place.",
   },
+  "fe-stack-import": {
+    code: "FE_STACK_FORBIDDEN",
+    en: "`<file>` imports `<what>`, a library the front-end stack forbids (a second library for a concern that has one), or a Supabase package outside `modules/auth`.",
+    fix: "Use the concern's canonical library from `knowledge/hfs/fe-stack.yaml` (the message names it); Supabase on the front end is the auth client in `modules/auth` only, data goes through `modules/api`.",
+  },
   "file-size-growth": {
     code: "HFS_SIZE_GROWTH",
     en: "`<file>` exceeds the line budget: a new file already too long, or an existing file longer than at the parent commit. Every file must be small enough for one person to read through and one test to cover.",

package/next-conventions.mjs

@@ -12,11 +12,12 @@
  */
 
 import { attribute, attributeValue, calleeName, leadingTextOf, stringOf } from "./lib/ast.mjs"
+import { forbiddingConcern } from "./lib/fe-stack.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { baseName, classOf, fileOf, inSlot, roleOfFile, slotOfFile, stem } from "./lib/scope.mjs"
 
-/** Another i18n stack: a second place that decides which language a reader sees. */
-const OTHER_I18N = /^(?:react-i18next|i18next|next-i18next|react-intl|next-translate|@lingui\/.+|typesafe-i18n|rosetta)$/
+/** Another i18n stack: a second place that decides which language a reader sees (one the fe-stack catalog forbids by name is fe-stack-import's finding). */
+const OTHER_I18N = /^(?:react-i18next|i18next|next-i18next|react-intl|next-translate|@lingui\/.+|typesafe-i18n|rosetta)(?:\/.*)?$/
 
 // -- FE-NEXT-1 -------------------------------------------------------------------------------------
 
@@ -96,7 +97,7 @@ export const noSecondI18nStack = {
     return {
       ImportDeclaration(node) {
         const source = String(node.source.value)
-        if (OTHER_I18N.test(source)) context.report({ node, messageId: "stack", data: { name: source } })
+        if (OTHER_I18N.test(source) && !forbiddingConcern(source)) context.report({ node, messageId: "stack", data: { name: source } })
       },
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "8.2.13",
+  "version": "8.2.15",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -14,43 +14,38 @@ purpose: >-
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
-  '@starci/heroicons':
-    version: 0.3.3
-    group: starci
-    install: registry
-    side: fe
-    source: packages/heroicons/package.json
-    why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
+  # @starci/heroicons has no pin since 1.0.0-alpha.13: the application icon set is @phosphor-icons/react (fe-stack.yaml
+  # icons) and eslint-canon-fe one-icon-set refuses every other glyph catalogue, so no product repository installs it.
   '@starci/grammar':
-    version: 0.9.12
+    version: 0.9.14
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.2.13
+    version: 3.2.16
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.2.13
+    version: 8.2.15
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.7
+    version: 2.0.9
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
     why: 'the front-end stylelint canon: no-class-selector refuses a compound class selector (`div.card`); the brand layer accepts `--font-sans` and `--font-mono`; status-contrast measures the HeroUI soft pairs per theme; brand-layer-shape reads the shared :root,.light,.dark block and the info soft pair; appTokens come from loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
-    version: 2.0.3
+    version: 2.0.4
     group: starci
     install: registry
     side: both
@@ -62,7 +57,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.6
+    version: 2.2.7
     group: starci
     install: registry
     side: be
@@ -76,14 +71,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.2.12
+    version: 1.2.14
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.2.12
+    version: 4.2.14
     group: starci
     install: registry
     side: both
@@ -274,6 +269,11 @@ pins:
     side: be
     why: the e2e world of a back end calls the app over HTTP (/health/live in the skeleton); two product back ends resolve 7.3.0, one 7.2.2.
   # --- ui
+  '@xyflow/react':
+    version: 12.11.6
+    group: ui
+    side: fe
+    why: 'Grammar FlowGraph imports React Flow from @xyflow/react; every Grammar consumer declares this required peer at the version used by the Grammar package.'
   '@heroui/react':
     version: 3.2.6
     group: ui
@@ -294,6 +294,198 @@ pins:
     group: ui
     side: fe
     why: 'the PostCSS plugin tailwindcss 4 runs through; the reference app declares ^4 and resolves 4.3.3.'
+  # --- front-end stack (knowledge/hfs/fe-stack.yaml; owner ruling 2026-10-13: lite = full)
+  '@apollo/client':
+    version: 4.1.6
+    group: framework
+    side: fe
+    why: 'the GraphQL client of every front end (fe-stack graphql): auth and no-auth clients with the link chain in modules/api/graphql; version read from the starci-academy package-lock on 2026-10-13.'
+  '@graphql-codegen/cli':
+    version: 7.4.6
+    group: tooling
+    side: fe
+    why: 'generates the front-end wire types from be/contracts/<app>/schema.graphql into modules/api/graphql/__generated__ (fe-stack codegen); the latest registry version on 2026-10-13, academy has none.'
+  '@graphql-codegen/client-preset':
+    version: 6.2.3
+    group: tooling
+    side: fe
+    why: 'the codegen preset of the front-end wire types (fe-stack codegen); the latest registry version on 2026-10-13.'
+  'axios':
+    version: 1.15.2
+    group: framework
+    side: fe
+    why: 'the REST client of the front end for uploads, presigned URLs and auth endpoints (fe-stack rest); version read from the starci-academy package-lock on 2026-10-13.'
+  'swr':
+    version: 2.4.2
+    group: framework
+    side: fe
+    why: 'the data hooks and cache of every front end, hooks/swr (fe-stack data); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-hook-form':
+    version: 7.77.0
+    group: framework
+    side: fe
+    why: 'the form library, hooks/rhf (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  '@hookform/resolvers':
+    version: 5.4.0
+    group: framework
+    side: fe
+    why: 'the zod resolver of react-hook-form (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  'zod':
+    version: 4.4.3
+    group: framework
+    side: fe
+    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  '@reduxjs/toolkit':
+    version: 2.11.2
+    group: framework
+    side: fe
+    why: 'app-wide shared state, redux/ (fe-stack state-global); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-redux':
+    version: 9.2.0
+    group: framework
+    side: fe
+    why: 'the React binding of the app-wide store (fe-stack state-global); version read from the starci-academy package-lock on 2026-10-13.'
+  'zustand':
+    version: 5.0.12
+    group: framework
+    side: fe
+    why: 'feature-local client state, hooks/zustand (fe-stack state-local); version read from the starci-academy package-lock on 2026-10-13.'
+  'socket.io-client':
+    version: 4.8.3
+    group: framework
+    side: fe
+    why: 'the realtime client, hooks/socketio (fe-stack realtime); version read from the starci-academy package-lock on 2026-10-13.'
+  'eventemitter2':
+    version: 6.4.9
+    group: framework
+    side: fe
+    why: 'the fan-out emitter behind the socket side-effect component (fe-stack realtime); version read from the starci-academy package-lock on 2026-10-13.'
+  '@phosphor-icons/react':
+    version: 2.1.10
+    group: ui
+    side: fe
+    why: 'the one application icon set (fe-stack icons); version read from the starci-academy package-lock on 2026-10-13.'
+  'next-themes':
+    version: 0.4.6
+    group: ui
+    side: fe
+    why: 'light and dark theme switching in components/providers (fe-stack theme); version read from the starci-academy package-lock on 2026-10-13.'
+  'framer-motion':
+    version: 12.42.2
+    group: ui
+    side: fe
+    why: 'motion (fe-stack motion); version read from the starci-academy package-lock on 2026-10-13.'
+  'dayjs':
+    version: 1.11.21
+    group: framework
+    side: fe
+    why: 'date math and parsing, modules/dayjs (fe-stack dates); display goes through the next-intl formatter; version read from the starci-academy package-lock on 2026-10-13.'
+  'decimal.js':
+    version: 10.6.0
+    group: framework
+    side: fe
+    why: 'money and decimal arithmetic, modules/utils (fe-stack numbers); version read from the starci-academy package-lock on 2026-10-13.'
+  'superjson':
+    version: 2.2.6
+    group: framework
+    side: fe
+    why: 'serialization of stored values, modules/superjson and modules/storage (fe-stack storage); version read from the starci-academy package-lock on 2026-10-13.'
+  'lodash':
+    version: 4.17.23
+    group: framework
+    side: fe
+    why: 'per-method utilities, modules/utils (fe-stack utils); version read from the starci-academy package-lock on 2026-10-13.'
+  'usehooks-ts':
+    version: 3.1.1
+    group: framework
+    side: fe
+    why: 'reusable React hooks, hooks/reuseables (fe-stack utils); version read from the starci-academy package-lock on 2026-10-13.'
+  'recharts':
+    version: 3.8.1
+    group: ui
+    side: fe
+    why: 'charts (fe-stack charts); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-markdown':
+    version: 10.1.0
+    group: ui
+    side: fe
+    why: 'markdown rendering (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'remark-gfm':
+    version: 4.0.1
+    group: ui
+    side: fe
+    why: 'GitHub-flavoured markdown for react-markdown (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'remark-directive':
+    version: 4.0.0
+    group: ui
+    side: fe
+    why: 'markdown directives for react-markdown (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-shiki':
+    version: 0.9.2
+    group: ui
+    side: fe
+    why: 'code highlighting (fe-stack code); version read from the starci-academy package-lock on 2026-10-13.'
+  '@monaco-editor/react':
+    version: 4.7.0
+    group: ui
+    side: fe
+    why: 'the code editor (fe-stack code); version read from the starci-academy package-lock on 2026-10-13.'
+  'mermaid':
+    version: 11.16.0
+    group: ui
+    side: fe
+    why: 'diagrams (fe-stack diagrams); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-dropzone':
+    version: 15.0.0
+    group: ui
+    side: fe
+    why: 'file drop zones of uploads (fe-stack upload); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-pdf':
+    version: 10.4.1
+    group: ui
+    side: fe
+    why: 'PDF viewing (fe-stack pdf); version read from the starci-academy package-lock on 2026-10-13.'
+  '@fingerprintjs/fingerprintjs':
+    version: 5.2.0
+    group: framework
+    side: fe
+    why: 'the device id of the GraphQL fingerprint link (fe-stack device-id); version read from the starci-academy package-lock on 2026-10-13.'
+  '@sentry/nextjs':
+    version: 11.7.0
+    group: framework
+    side: fe
+    why: 'error reporting through sentry.*.config.ts and instrumentation.ts (fe-stack observability); the latest registry version on 2026-10-13, academy has none.'
+  # --- back-end transports the front end calls, and the realtime gateway
+  '@nestjs/graphql':
+    version: 13.4.5
+    group: framework
+    side: be
+    why: 'the GraphQL transport of every back end (be.transport.graphql) that the front end calls; the ecommerce-app resolution on 2026-10-13.'
+  '@nestjs/apollo':
+    version: 13.4.5
+    group: framework
+    side: be
+    why: 'the Apollo driver of @nestjs/graphql; the ecommerce-app resolution on 2026-10-13.'
+  '@apollo/server':
+    version: 5.5.1
+    group: framework
+    side: be
+    why: 'the Apollo server behind @nestjs/apollo; the ecommerce-app resolution on 2026-10-13.'
+  '@nestjs/websockets':
+    version: 11.2.5
+    group: framework
+    side: be
+    why: 'the socket.io gateway of a realtime back end (lite runs it in the api process, owner ruling 2026-10-13); the @nestjs/core pin line.'
+  '@nestjs/platform-socket.io':
+    version: 11.2.5
+    group: framework
+    side: be
+    why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  '@as-integrations/express5':
+    version: 1.1.2
+    group: framework
+    side: be
+    why: 'the Express 5 integration @nestjs/apollo loads at boot (R111 nestjs-apollo-express5, knowledge/hfs/peer-integrations.yaml); every api app that serves GraphQL installs it; the latest registry version on 2026-10-13.'
   # --- Supabase lite
   '@supabase/ssr':
     version: 0.12.7

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -0,0 +1,218 @@
+schema: starci/fe-stack@1
+purpose: >-
+  The front-end stack of every app, lite and full alike (owner ruling 2026-10-13, R212 case-2): for each common front-end concern the
+  ONE canonical library, its HFS home (slot ids of knowledge/hfs/slots.yaml), the pattern id that teaches it
+  (knowledge/patterns/fe/*.yaml) and the alternatives a front end never depends on or imports. Versions live in
+  knowledge/hfs/canon-pins.yaml only. `tier: core` packages are installed by every scaffold; `opt` packages are added when a feature
+  needs the concern. Source example: starci-lab/starci-academy (origin/main, 2026-10-13); it illustrates, this file decides.
+concerns:
+  - id: framework
+    tier: core
+    packages: [next, react, react-dom, typescript]
+    home: [fe.route, fe.source-root-pinned]
+    pattern: FE-ROUTE
+    forbids: []
+    why: App Router with thin routes; route handlers (except health/live and the auth callback slot) and Server Actions are refused by FE_ROUTE_HANDLER_FORBIDDEN and FE_SERVER_ACTION_FORBIDDEN.
+  - id: graphql
+    tier: core
+    packages: ['@apollo/client', graphql]
+    home: [fe.modules.api, fe.transport.client, fe.transport.outcome]
+    pattern: FE-API-GRAPHQL
+    forbids: [urql, graphql-request, '@urql/core', graphql-hooks, apollo-boost]
+    why: one file per operation under modules/api/graphql/{queries,mutations}, run by the auth or no-auth Apollo client with the link chain.
+  - id: codegen
+    tier: core
+    packages: ['@graphql-codegen/cli', '@graphql-codegen/client-preset']
+    home: [fe.modules.api]
+    pattern: FE-WIRE-GENERATED
+    forbids: []
+    why: the wire types are generated from be/contracts/<app>/schema.graphql into modules/api/graphql/__generated__, never typed by hand.
+  - id: rest
+    tier: core
+    packages: [axios]
+    home: [fe.modules.api]
+    pattern: FE-API-REST
+    forbids: [ky, superagent, node-fetch, cross-fetch, isomorphic-fetch]
+    why: modules/api/rest/<area>/*.ts for uploads, presigned URLs and auth endpoints only; GraphQL carries every other call.
+  - id: data
+    tier: core
+    packages: [swr]
+    home: [fe.hooks.swr]
+    pattern: FE-DATA-SWR
+    forbids: ['@tanstack/react-query', react-query]
+    why: hooks/swr/api/{graphql,rest}/{queries,mutations}/use*Swr.ts wrap one operation each; components call hooks only.
+  - id: toast
+    tier: core
+    packages: ['@heroui/react']
+    home: [fe.modules.toast]
+    pattern: FE-TOAST
+    forbids: [sonner, react-toastify, react-hot-toast, notistack]
+    why: mutation outcomes are reported by modules/toast (showGraphQLToast, use*WithToast) with next-intl labels.
+  - id: forms
+    tier: core
+    packages: [react-hook-form, '@hookform/resolvers', zod]
+    home: [fe.hooks.rhf]
+    pattern: FE-FORM
+    forbids: [formik, yup, final-form, react-final-form]
+    why: hooks/rhf/use<X>Form.ts builds a zod schema with next-intl messages and submits through an SWR mutation and the toast.
+  - id: state-global
+    tier: core
+    packages: ['@reduxjs/toolkit', react-redux]
+    home: [fe.redux]
+    pattern: FE-STATE-REDUX
+    forbids: [mobx, mobx-react, mobx-react-lite, recoil, jotai, valtio, redux-saga]
+    why: app-wide shared state (selected ids synced from the route, server-pushed entities) lives in redux/slices.
+  - id: state-local
+    tier: core
+    packages: [zustand]
+    home: [fe.hooks.zustand]
+    pattern: FE-STATE-ZUSTAND
+    forbids: []
+    why: feature-local UI, wizard and editor state lives in hooks/zustand/<store>.
+  - id: realtime
+    tier: opt
+    packages: [socket.io-client, eventemitter2]
+    home: [fe.hooks.socketio]
+    pattern: FE-REALTIME
+    forbids: [graphql-ws, subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
+    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process.
+  - id: auth
+    tier: core
+    packages: []
+    home: [fe.modules.auth]
+    pattern: FE-AUTH
+    forbids: []
+    why: modules/auth is the identity-provider client (lite - the @supabase/supabase-js auth client; full - the app's IdP client); it yields the session and the access token for the Apollo link and never reads data.
+  - id: i18n
+    tier: core
+    packages: [next-intl]
+    home: [fe.modules.i18n]
+    pattern: FE-I18N
+    forbids: [i18next, react-i18next, next-i18next, react-intl, '@lingui/react']
+    why: useTranslations for copy and the next-intl formatter for numbers, dates and currency.
+  - id: ui
+    tier: core
+    packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar']
+    home: [fe.components, fe.feature]
+    pattern: FE-UI
+    forbids: ['@mantine/core', '@mui/material', '@chakra-ui/react', antd, styled-components, '@emotion/react', '@emotion/styled']
+    why: the grammar renderers over HeroUI and Tailwind; no second UI kit and no CSS-in-JS.
+  - id: icons
+    tier: core
+    packages: ['@phosphor-icons/react']
+    home: [fe.components]
+    pattern: FE-ICON
+    forbids: [react-icons, lucide-react, '@iconify/react', '@gravity-ui/icons', '@tabler/icons-react', '@fortawesome/react-fontawesome']
+    why: one application icon set.
+  - id: theme
+    tier: core
+    packages: [next-themes]
+    home: [fe.components.providers]
+    pattern: FE-THEME
+    forbids: []
+    why: the theme provider lives in components/providers.
+  - id: motion
+    tier: opt
+    packages: [framer-motion]
+    home: [fe.components]
+    pattern: FE-MOTION
+    forbids: [react-spring, '@react-spring/web', gsap]
+    why: one motion library.
+  - id: dates
+    tier: core
+    packages: [dayjs]
+    home: [fe.modules]
+    pattern: FE-DATE
+    forbids: [moment, moment-timezone, date-fns, luxon]
+    why: dayjs (modules/dayjs) for date math and parsing; display through the next-intl formatter.
+  - id: numbers
+    tier: opt
+    packages: [decimal.js]
+    home: [fe.modules]
+    pattern: FE-NUMBER
+    forbids: [big.js, bignumber.js, numeral]
+    why: decimal.js for money arithmetic in modules/utils; display through the next-intl formatter.
+  - id: storage
+    tier: core
+    packages: [superjson]
+    home: [fe.modules]
+    pattern: FE-STORAGE
+    forbids: [localforage, store2]
+    why: modules/storage (local and session storage) serializes through modules/superjson; components never touch storage directly.
+  - id: utils
+    tier: opt
+    packages: [lodash, usehooks-ts]
+    home: [fe.modules, fe.hooks.reuseables]
+    pattern: FE-UTILS
+    forbids: [underscore, ramda, lodash-es]
+    why: per-method lodash imports in modules/utils and reusable hooks in hooks/reuseables.
+  - id: charts
+    tier: opt
+    packages: [recharts]
+    home: [fe.components]
+    pattern: FE-CHART
+    forbids: [chart.js, react-chartjs-2, '@nivo/core', d3, echarts, echarts-for-react]
+    why: one chart library, styled by the dataviz grammar.
+  - id: flow
+    tier: opt
+    packages: ['@xyflow/react']
+    home: [fe.components]
+    pattern: FE-FLOW
+    forbids: [reactflow, cytoscape]
+    why: graph canvases go through the grammar FlowGraph over React Flow.
+  - id: markdown
+    tier: opt
+    packages: [react-markdown, remark-gfm, remark-directive]
+    home: [fe.components]
+    pattern: FE-MARKDOWN
+    forbids: [marked, markdown-it, showdown]
+    why: markdown renders through react-markdown, never dangerouslySetInnerHTML.
+  - id: code
+    tier: opt
+    packages: [react-shiki, '@monaco-editor/react']
+    home: [fe.components]
+    pattern: FE-CODE
+    forbids: [prismjs, react-syntax-highlighter, highlight.js, '@uiw/react-codemirror', codemirror]
+    why: react-shiki highlights and Monaco edits.
+  - id: diagrams
+    tier: opt
+    packages: [mermaid]
+    home: [fe.components]
+    pattern: FE-DIAGRAM
+    forbids: []
+    why: diagrams render through mermaid in a block.
+  - id: upload
+    tier: opt
+    packages: [react-dropzone]
+    home: [fe.components, fe.modules.api]
+    pattern: FE-UPLOAD
+    forbids: [react-dropzone-uploader, filepond, react-filepond, uppy]
+    why: react-dropzone in a block and a presigned PUT through modules/api/rest.
+  - id: pdf
+    tier: opt
+    packages: [react-pdf]
+    home: [fe.components]
+    pattern: FE-PDF
+    forbids: ['@react-pdf-viewer/core', pdfjs-dist]
+    why: PDF viewing through react-pdf in a block.
+  - id: device-id
+    tier: opt
+    packages: ['@fingerprintjs/fingerprintjs']
+    home: [fe.transport.client]
+    pattern: FE-API-GRAPHQL
+    forbids: []
+    why: the fingerprint link of the Apollo client attaches the device id.
+  - id: observability
+    tier: opt
+    packages: ['@sentry/nextjs']
+    home: [fe.source-root-pinned]
+    pattern: FE-OBSERVE
+    forbids: [logrocket, bugsnag-js, '@bugsnag/js', '@datadog/browser-rum']
+    why: errors are reported through @sentry/nextjs (sentry.*.config.ts, instrumentation.ts), never console-only.
+  - id: lint
+    tier: core
+    packages: [eslint, prettier, '@starci/eslint-canon-fe', '@starci/prettier-config']
+    home: [fe.tool-config]
+    pattern: FE-LINT
+    forbids: []
+    why: the canon lint and format configuration.