fastify-auto-sqlapi 0.1.13 → 0.2.0

package/dist/routes/auto/route-helpers.js

@@ -1,6 +1,6 @@
 import { ensureSqlApiDecorator } from '../../lib/sql-api-decorator.js';
 import { isCompositePrimary } from '../../types.js';
-export function mergeOnRequests(options, tableConf) {
+function mergeOnRequests(options, tableConf) {
     return [...(options.onRequests || []), ...(tableConf.onRequests || [])];
 }
 export function buildWriteDescription(action, tableName, tableConf) {
@@ -17,46 +17,62 @@ export function buildWriteDescription(action, tableName, tableConf) {
  * following `spec`. Centralizes onRequest hook merging, tags, schema response wrapping,
  * default reply when handler returns a value.
  */
+/**
+ * Whether this table is addressable by the spec's route shape.
+ *
+ * A single-PK route cannot address a composite-PK table. Skipping is the default, but when
+ * the consumer explicitly listed the operation it is a configuration error: failing at
+ * startup beats a route that silently never exists.
+ */
+function isTableRoutable(tableName, tableConf, spec) {
+    // operations acts as a whitelist; when omitted every operation is exposed.
+    if (tableConf.operations && !tableConf.operations.includes(spec.operation))
+        return false;
+    if (!spec.singlePkOnly || !isCompositePrimary(tableConf.primary))
+        return true;
+    if (tableConf.operations?.includes(spec.operation)) {
+        throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
+            `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
+            `Remove it from "operations", or handle the table via search/update or a custom route.`);
+    }
+    return false;
+}
+/**
+ * Fastify route schema for one table.
+ *
+ * Only keys that are actually defined are included: Fastify checks for key *presence*
+ * (not an undefined value) to decide whether to emit FSTWRN001.
+ */
+function buildRouteSchema(tableName, tableConf, spec, schemas) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const schema = {
+        tags: [`SqlAPI-${tableName}`],
+        summary: `${spec.summary} ${tableName}`,
+        description: spec.description(tableName, tableConf, schemas),
+    };
+    if (schemas.body !== undefined)
+        schema.body = schemas.body;
+    if (schemas.params !== undefined)
+        schema.params = schemas.params;
+    if (schemas.querystring !== undefined)
+        schema.querystring = schemas.querystring;
+    if (schemas.response !== undefined)
+        schema.response = { [spec.successStatus]: schemas.response };
+    return schema;
+}
 export async function registerForAllTables(fastify, options, spec) {
     // Granular composition support: when a route plugin is registered without the
     // main plugin, no ancestor has decorated `sqlApi` — create it in this scope.
     ensureSqlApiDecorator(fastify, options);
     const { DbTables } = options;
     for (const [tableName, tableConf] of Object.entries(DbTables)) {
-        // operations acts as a whitelist; when omitted every operation is exposed.
-        if (tableConf.operations && !tableConf.operations.includes(spec.operation))
-            continue;
-        // Single-PK routes cannot address composite-PK tables — skip them (default) or,
-        // when the consumer explicitly asked for the operation, fail loudly at startup.
-        if (spec.singlePkOnly && isCompositePrimary(tableConf.primary)) {
-            if (tableConf.operations?.includes(spec.operation)) {
-                throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
-                    `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
-                    `Remove it from "operations", or handle the table via search/update or a custom route.`);
-            }
+        if (!isTableRoutable(tableName, tableConf, spec))
             continue;
-        }
         const schemas = spec.schemas(DbTables, tableName, tableConf);
-        // Only include schema keys that are actually defined: Fastify checks for key
-        // *presence* (not undefined value) to decide whether to emit FSTWRN001.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const schema = {
-            tags: [`SqlAPI-${tableName}`],
-            summary: `${spec.summary} ${tableName}`,
-            description: spec.description(tableName, tableConf, schemas),
-        };
-        if (schemas.body !== undefined)
-            schema.body = schemas.body;
-        if (schemas.params !== undefined)
-            schema.params = schemas.params;
-        if (schemas.querystring !== undefined)
-            schema.querystring = schemas.querystring;
-        if (schemas.response !== undefined)
-            schema.response = { [spec.successStatus]: schemas.response };
         fastify.route({
             method: spec.method,
             url: spec.url(tableConf),
-            schema,
+            schema: buildRouteSchema(tableName, tableConf, spec, schemas),
             onRequest: mergeOnRequests(options, tableConf),
             handler: async (request, reply) => {
                 const result = await spec.handle(fastify, tableName, tableConf, request, reply);

package/dist/routes/auto/search.routes.js

@@ -15,7 +15,6 @@ export default async function searchRoutes(fastify, options) {
         }),
         summary: 'Search',
         description: (name, _tc, schemas) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const body = schemas.body;
             const multiAliases = Object.keys(body?.properties?.joinMultiple?.properties || {});
             const leftAliases = Object.keys(body?.properties?.joinLeft?.properties || {});

package/dist/types/join.d.ts

@@ -8,6 +8,15 @@ export interface JoinDefinition {
     alias: string;
     selection: string;
     unique: boolean;
+    /**
+     * Allowlist of the target table's fields reachable through this relation, when
+     * `buildRelation` was given one. `joinSchema` is already narrowed to it — this is kept
+     * so the engine can tell a restricted relation from a full one, which is what stops the
+     * default `'*'` selection from falling back to a real `SELECT *`.
+     *
+     * Read joins only: a write join declaring it is rejected by `defineTable`.
+     */
+    fields?: string[];
 }
 export interface AggregationRequest {
     /**

package/dist/types/join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types/table.d.ts

@@ -30,7 +30,7 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
     extraFilters: Record<string, TSchema>;
     /**
      * Virtual fields produced by a SQL expression. Usable like schema fields in
-     * `filters`, `conditions` (non-dotted), `orderBy` (1-parte),
+     * `filters`, `conditions` (non-dotted), `orderBy` (1-part),
      * `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main
      * response. Each entry MUST declare `type` for Swagger and validation.
      *

package/docs/GLOSSARY.md

@@ -0,0 +1,28 @@
+# Glossary
+
+One name per concept. Use these words in code, tests and docs — a second name for an
+existing concept makes search fail and the concept get built twice.
+
+| Term | Meaning |
+|---|---|
+| Table config | `defineTable()` result describing one table's routes, guards and joins. (not: model, entity) |
+| Schema | TypeBox definition of a table's columns, generated from the DB. (not: model) |
+| Relation | `buildRelation()` link between two schemas, identified by an alias. (not: association) |
+| Alias | Request/response key naming one relation; defaults to the joined table name. |
+| `joinMustExist` | Child→main 1:N filter via EXISTS; never returns child rows. |
+| `joinMultiple` | Child→main 1:N side query; child rows land in `result.joinMultiple.<alias>`. |
+| `joinGroup` | Child→main 1:N aggregations in `result.joinGroup.<alias>`. |
+| `joinLeft` | Parent→main N:1 real LEFT JOIN; needs `unique: true` on the relation. |
+| Secondaries | Child rows written in the same request as the main row. (not: nested, children) |
+| Deletions | Child rows removed in the same request as the main row update. |
+| Computed field | Server-side derived value resolved during search. (not: virtual, derived) |
+| Extra filter | Non-column search filter declared per table. (not: custom filter) |
+| Extended condition | Consumer-supplied SQL fragment merged into a search WHERE. |
+| Dotted notation | `orderBy`/condition key counted in parts: 1-part `field`, 2-part `alias.field`, 3-part `alias.fn.field`. (not: parti) |
+| Tenant scope | Row-level isolation: `direct` (own column) or `indirect` (via FK). |
+| Engine | Dialect-agnostic function performing one operation. (not: service, handler) |
+| Route | Fastify plugin exposing an engine over HTTP. (not: controller) |
+| Dialect | Per-DB SQL differences (`postgres` \| `mysql`). |
+| QueryClient | Connection wrapper the engines run SQL through. (not: db, connection) |
+| Paginator | Request object carrying page and items-per-page. (not: pagination, pager) |
+| Manifest | Runtime description of a deployment's tables, for agent clients. |

package/docs/adr/0010-joins-do-not-run-route-guards.md

@@ -0,0 +1,100 @@
+# 0010. A declared join is a read grant — joins do not run the target table's route guards
+
+- **Status**: accepted
+- **Date**: 2026-07-30
+
+## Context
+
+`onRequests` and `operations` are configured per table, which reads as "this table's
+protection". They are not. Both are properties of the *routes generated for* a table:
+`mergeOnRequests` composes the global and per-table hooks into `fastify.route({ onRequest })`,
+and `operations` decides which routes get registered at all.
+
+A join is resolved inside the query of the **host** table's route. `searchEngine` validates a
+join alias against the host's `allowedReadJoins` and nothing else — it never looks up the
+target's `operations`, and no Fastify hook fires mid-query. So:
+
+```typescript
+// agent: readable by every employee
+allowedReadJoins: [buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true })],
+
+// user: admins only... except through the join above
+const TableUser = defineTable({
+  ...exportTableInfo(SchemaUser),
+  onRequests: [requireAdmin],
+  operations: [],          // no HTTP routes at all
+});
+```
+
+`POST /search/agent` with `joinLeft: { user: { selection: 'id,email' } }` returns the emails.
+`requireAdmin` never ran, and `operations: []` did not matter: the caller was authorized as a
+reader of `agent`, and the join is part of what `agent` exposes.
+
+Reviewers reach this and read it as a hole to plug. It is a boundary, and the boundary needs
+to be stated rather than discovered.
+
+## Decision
+
+**Declaring a relation in `allowedReadJoins` grants read access to the target table, under
+the authorization of the host table.** The target's own route guards do not apply and are not
+made to apply.
+
+Route-level controls (`onRequests`, `operations`) do not follow joins. Configuration-level
+controls do, and are the ones to use on a join target:
+
+| Control | Follows a join | Granularity |
+|---|---|---|
+| `onRequests` | no | per route |
+| `operations` | no | per route |
+| `readExclude` | yes | per table, static |
+| the relation's `Schema` + `selection` | yes | per relation, static |
+| `tenantScope` + `getTenantId` | yes | per request |
+
+To expose a table broadly while keeping some of its columns narrow, declare the relation
+against a **trimmed copy of the Schema** and give it an explicit `selection`:
+
+```typescript
+const SchemaUserPublic = { ...SchemaUser, fields: { id: SchemaUser.fields.id, name: SchemaUser.fields.name } };
+
+buildRelation(SchemaAgent, 'userId', SchemaUserPublic, 'id', { unique: true, selection: 'id, name' })
+```
+
+Every read surface validates against the schema the relation was declared with — `selection`,
+`filters`, `conditions`, `orderBy`, aggregations — so a field outside it is `400 Unknown
+field`, not a hidden column. The explicit `selection` is not redundant: a relation left at the
+default `'*'` emits a literal `SELECT *` when the target declares no `readExclude`, and the
+extra columns are dropped only by the response serializer — they are still present on the
+programmatic `sqlApi.search()` path.
+
+## Alternatives considered
+
+- **Run the target's `onRequests` when it is joined** — rejected: a Fastify request hook may
+  reply and terminate; there is no coherent meaning for that halfway through building one
+  table's query. It would also fire N times per request with no request lifecycle to attach to.
+- **`canBeJoined?: (request) => Promise<boolean>` on `ITable`** — rejected: wrong granularity.
+  The real cases are "join yes, this column no", which a boolean cannot express, and the
+  refusal has no good answer (a `400` leaks the relation's existence; omitting the join
+  silently is indistinguishable from "no related rows"). It also adds a per-join await and
+  cannot be enforced for programmatic callers.
+- **Make the relation's `selection` a ceiling instead of a default** — rejected: breaking, and
+  it does not solve the case it looks like it solves. A ceiling is still static, and it caps
+  only the projection: the excluded field stays filterable through `conditions`, which is the
+  bisection leak `readExclude` exists to prevent. Trimming the schema closes every surface at
+  once.
+- **Refusing to register a table that is a join target of a less-protected table** — rejected:
+  the plugin has no way to compare two `onRequests` arrays for strictness, and ADR 0002 says
+  auth is the consumer's to model.
+
+## Consequences
+
+- `allowedReadJoins` must be read as a security decision, not just an ergonomics one. Adding a
+  relation widens the reachable data set for everyone authorized on the host table.
+- Column-level protection that depends on the caller's role has no mechanism today.
+  `readExclude` is per table and static; the trimmed schema is per relation and static. The
+  known gap is a request-resolved `readExclude`, which would work without new plumbing at the
+  join sites — every path already resolves it through `dbTables[joinSchema.tableName]` — but
+  requires the generated response and filter schemas to stay the widest set and the runtime to
+  narrow. Not decided here.
+- `tenantScope` remains the one request-derived protection that crosses joins, and is the
+  precedent for the shape any future one should take: table configuration plus a plugin-level
+  resolver, not a route hook.

package/docs/adr/0011-join-fields-allowlist.md

@@ -0,0 +1,95 @@
+# 0011. Per-relation field restriction is an allowlist, not a blocklist
+
+- **Status**: accepted
+- **Date**: 2026-07-31
+
+## Context
+
+[ADR 0010](./0010-joins-do-not-run-route-guards.md) establishes that a declared join is a read
+grant, and that the only thing narrowing what a relation exposes is the schema it was declared
+with. The pattern it documented was to hand-write a trimmed copy:
+
+```typescript
+const SchemaUserPublic = { ...SchemaUser, fields: { id: SchemaUser.fields.id, name: SchemaUser.fields.name } };
+```
+
+That works, but the copy is derived state with nothing keeping it in sync. Schemas are
+regenerated from the database as disposable mirrors (ADR 0007), so the copy silently drifts:
+adding a column to `user` leaves `SchemaUserPublic` correct, dropping or renaming one leaves it
+referencing a field that no longer exists, and neither shows up until a request fails.
+
+The restriction belongs in the relation, where someone reading the table configuration is
+already looking. The open question was its polarity.
+
+## Decision
+
+`buildRelation` takes `fields: string[]` — an **allowlist** of the target's fields reachable
+through that relation. The relation is declared against a schema narrowed to that list, so every
+existing check (`field in schema.fields`) enforces it without a parallel code path: `selection`,
+`filters`, `conditions`, `orderBy`, aggregations, `aggregations.by`, and the generated request
+and response schemas.
+
+```typescript
+buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] })
+```
+
+Allowlist, not a `excludeFields` blocklist, because the failure modes are not symmetric. A
+column added to the table later is not reachable through the relation until someone adds it —
+the new column is invisible by default, and the cost of forgetting is a `400`. Under a blocklist
+the same event silently widens every relation that did not anticipate it, and the cost of
+forgetting is disclosure. On a join — a grant handed out under *another* table's authorization —
+fail-closed is the only defensible default. It also reads the same way as `selection`, which is
+already an allowlist.
+
+Three rules follow from making it real rather than cosmetic:
+
+- **It must include the join field.** That column is what correlates the fetched rows with the
+  main ones; omitting it hands the caller rows it cannot match to anything. Rejected at
+  declaration, like `readExclude` refusing to hide a primary key.
+- **It is rejected on `allowedWriteJoins`.** Write paths resolve a secondary's upsert rule by
+  looking its schema up in `upsertMap` **by identity**; a narrowed relation carries a copy, so
+  the lookup would miss and the upsert would quietly degrade to a plain insert. The narrowed
+  schema would also drop columns the caller legitimately sent.
+- **Computed fields on the target resolve against the narrowed schema.** A computed field reads
+  whatever columns it likes; resolving it against the full table schema would leave a documented
+  way around the allowlist (`salaryBand` returning what `salary` says). One that stays inside the
+  list keeps working; one that reaches outside is a `400`.
+
+The default `selection: '*'` is spelled out into the allowed columns on a restricted relation.
+It used to emit a real `SELECT *`, with the extra columns removed only by the response
+serializer — which does not run for a caller of `sqlApi.search()`. An allowlist that leaks on its
+default is not an allowlist.
+
+## Alternatives considered
+
+- **`excludeFields: string[]` (blocklist)** — rejected on the fail-open argument above. It is
+  shorter to write when hiding one column out of twenty, and it would have read like
+  `readExclude`; neither outweighs a new column defaulting to exposed.
+- **`lockSelection: true`, making the declared `selection` a ceiling** — rejected: it caps the
+  projection only. The excluded column stays reachable from `filters`, `conditions` and
+  `orderBy`, which is the bisection leak `readExclude` exists to prevent — a guard that hides a
+  value from the output while leaving it interrogable is worse than none, because it reads as
+  protection.
+- **Making the relation's `selection` a ceiling instead of adding a field** — rejected in
+  ADR 0010: breaking, and still static.
+- **Threading the allowlist through every validation site instead of narrowing the schema** —
+  rejected: it would leave each new read surface to remember the check. Narrowing the schema is
+  closed by construction, which is the property that made the hand-written trimmed copy work in
+  the first place.
+- **Keeping the hand-written trimmed copy as the documented pattern** — rejected: it duplicates
+  regenerated state. It still works, and is the way out if a relation needs a shape `fields`
+  cannot express.
+
+## Consequences
+
+- `fields` restricts **reading** only. It is not a substitute for `readExclude`, which hides a
+  column from the owning table's own routes too, nor for `onRequests`, which is what decides who
+  may call them.
+- It is static, like everything else that crosses a join. Role-dependent column visibility —
+  admins seeing `email`, nobody else — still has no mechanism; the candidate remains a
+  request-resolved `readExclude`, unaffected by this ADR.
+- A relation and its write counterpart can no longer be the same `buildRelation` call when the
+  read side is restricted. Declaring two is the intended answer, not a workaround.
+- The generated agent manifest still describes join targets by table name only, so an LLM client
+  reading it may ask for a field the relation does not expose and get a `400`. Listing a
+  restricted relation's fields in the manifest is a follow-up.

package/docs/adr/0012-anti-duplication-tooling.md

@@ -0,0 +1,59 @@
+# 0012. Repository rules are enforced by executable gates, not by documentation
+
+- **Status**: accepted
+- **Date**: 2026-08-01
+
+## Context
+
+Every session starts with an empty context window. An agent that cannot find existing code
+rewrites it, invents a second name for an existing concept, and scatters logic across the
+tree. Documentation does not prevent this: it is only read when someone remembers to read
+it, and `CLAUDE.md` is weighted context, not configuration.
+
+The repository had no ESLint, no Prettier, no git hooks and no CI beyond publish-on-tag.
+Measured starting point: 2.50% duplicated lines (3.27% of tokens, 18 clones), naming drift
+effectively zero, layering already clean, and `fastify-plugin` imported but absent from
+`package.json` — a real packaging bug that no human review had caught.
+
+## Decision
+
+Anything that must not happen is a hook or a lint rule. Prose is reserved for what cannot
+be executed.
+
+Gates are **silent and zero-tolerance by default**; pre-existing debt is switched off and
+surfaced by `npm run debt` (`lint:strict`, `dup:strict`, `depcruise:strict`,
+`knip:strict`). npm scripts are the source of truth — git hooks only call them — so any
+gate can be run without touching git history.
+
+Rejected the ratchet-on-a-warning-count approach that was tried first: a run that always
+prints 241 warnings trains everyone to ignore its output, and the number drifts upward
+unnoticed. A rule is either enforced or explicitly deferred, never "warned about".
+
+## Alternatives considered
+
+- **Baseline thresholds with warnings** (`--max-warnings 241`) — rejected after
+  implementing it: noisy output is ignored output, and the boundary is invisible.
+- **Barrel enforcement via `no-restricted-imports`** — rejected: the repo has one barrel,
+  `src/index.ts`, which is the npm surface. Blocking deep imports would break every
+  internal import and require restructuring into per-module barrels. `dependency-cruiser`
+  encodes the same boundaries without moving a single file.
+- **Intent tags with a closed vocabulary, and `cspell`** — rejected: 64 files, coherent
+  naming, one maintainer. A half-maintained tag system is worse than none, and spellchecking
+  a 951-line README full of SQL identifiers is pure noise.
+- **Session worklog** — rejected: without a compaction ritual nobody will run, an
+  append-only log becomes context noise within weeks.
+
+## Consequences
+
+- New violations fail immediately; the deferred list in `eslint.config.js` is the debt
+  ledger and may only shrink.
+- `docs/INDEX.md` is generated and CI fails when it is stale, like a lockfile. It is
+  excluded from the npm package: publishing 204 internal declarations would invite
+  consumers to import what is not public API.
+- Type-only import cycles through `src/types.ts` are deferred, not fixed. Verified they
+  are erased on emit — the compiled `dist/` graph has zero cycles.
+- `knip` checks exports and types with no exclusions. The 16 symbols that were exported but
+  used only inside their own file lost the keyword; the 5 that only unit tests use are
+  tagged `@testonly`, which documents why they stay exported instead of hiding them.
+- Maintainer scripts require Node ≥22.18 (native TypeScript type stripping). The published
+  package still supports Node ≥18.

package/docs/adr/README.md

@@ -24,11 +24,15 @@ not by editing history.
 | [0007](./0007-explicit-table-generation.md) | Table generation is explicit — `--all` is a migration helper, not the default |
 | [0008](./0008-agent-client-interface.md) | Agent client interface: static grammar + runtime manifest |
 | [0009](./0009-schema-exclusion-config-blacklist.md) | Schema exclusion is a config blacklist — excluded schemas are removed as orphans |
+| [0010](./0010-joins-do-not-run-route-guards.md) | A declared join is a read grant — joins do not run the target table's route guards |
+| [0011](./0011-join-fields-allowlist.md) | Per-relation field restriction is an allowlist, not a blocklist |
+| [0012](./0012-anti-duplication-tooling.md) | Repository rules are enforced by executable gates, not by documentation |
 
 ## When to write one
 
 Only when a decision was genuinely debated, or is counter-intuitive enough that a reasonable
-outsider would mistake it for a bug. Plain conventions belong in [AGENTS.md](../../AGENTS.md).
+outsider would mistake it for a bug. Plain conventions belong in [AGENTS.md](../../AGENTS.md)
+for consumers, or in `CLAUDE.md` at the repository root for contributors.
 
 ## Format
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "docs",
+    "!docs/INDEX.md",
     "AGENTS.md",
     "AGENTS_BACKEND.md",
     "AGENTS_FRONTEND.md",
@@ -28,6 +29,21 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "rm -rf dist && tsc",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "lint:strict": "LINT_STRICT=1 eslint .",
+    "typecheck": "tsc --noEmit && tsc -p scripts/tsconfig.json",
+    "index": "node scripts/generate-index.ts",
+    "index:check": "node scripts/generate-index.ts --check",
+    "find-similar": "node scripts/find-similar.ts",
+    "dup": "jscpd src",
+    "dup:strict": "jscpd src --reporters console",
+    "knip": "knip --max-issues 0 --treat-config-hints-as-errors --treat-tag-hints-as-errors",
+    "depcruise": "depcruise src --config .dependency-cruiser.mjs --output-type err",
+    "depcruise:strict": "DEPCRUISE_STRICT=1 depcruise src --config .dependency-cruiser.mjs --output-type err",
+    "debt": "npm run lint:strict; npm run dup:strict; npm run depcruise:strict",
+    "check": "npm run lint && npm run typecheck",
+    "verify": "npm run check && npm run build && npm run index:check && npm run dup && npm run depcruise && npm run knip && npm run test:unit",
     "prepublishOnly": "npm run build && npm run test:unit",
     "test": "npm run test:unit && npm run test:integration:pg && npm run test:integration:mysql",
     "test:unit": "node --test test/unit/*.test.js",
@@ -67,18 +83,29 @@
   "homepage": "https://github.com/LucaRainone/fastify-auto-sqlapi#readme",
   "dependencies": {
     "@sinclair/typebox": "^0.34.14",
+    "fastify-plugin": "^5.1.0",
     "node-condition-builder": "^1.2.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@fastify/postgres": "^6.0.2",
     "@fastify/swagger": "^9.0.0",
     "@fastify/swagger-ui": "^5.0.0",
     "@types/node": "^22.13.4",
     "@types/pg": "^8.11.11",
+    "dependency-cruiser": "^18.1.0",
+    "eslint": "^10.8.0",
+    "eslint-plugin-sonarjs": "^4.2.0",
     "fastify": "5.8.5",
+    "fuse.js": "^7.5.0",
+    "jscpd": "^5.0.14",
+    "knip": "^6.31.0",
+    "lefthook": "^2.1.10",
     "mysql2": "^3.22.0",
     "pg": "^8.13.1",
-    "typescript": "^5.7.3"
+    "ts-morph": "^28.0.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.65.0"
   },
   "peerDependencies": {
     "@fastify/mysql": ">=4.0.0",