fastify-auto-sqlapi 0.1.14 → 0.2.1

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

@@ -1 +1 @@
-{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,MAAM,EAAE,gBAAgB,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB"}
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,MAAM,EAAE,gBAAgB,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/docs/GLOSSARY.md

@@ -0,0 +1,30 @@
+# 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), `indirect` (via FK) or `anyOf`. |
+| `anyOf` scope | Tenant scope over several owner columns: the row is visible to any of them. |
+| Anchor | The owner column an `anyOf` write names to tie a new row to the caller. |
+| 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/0006-raw-db-errors.md

@@ -1,6 +1,7 @@
 # 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
 
-- **Status**: accepted
+- **Status**: accepted on the mapping; message exposure narrowed by
+  [0013](./0013-sanitized-db-errors.md)
 - **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
 
 ## Context

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

@@ -97,4 +97,7 @@ programmatic `sqlApi.search()` path.
   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.
+  resolver, not a route hook. It crosses joins **unconditionally** only since the tenant stopped
+  being resolved from the addressed table alone; before that, a host declaring no scope of its
+  own carried none into its join targets, which made the row above true only when the host
+  happened to be scoped too (see BREAKING_CHANGES.md).

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/0013-sanitized-db-errors.md

@@ -0,0 +1,114 @@
+# 0013. Database error messages are sanitized on the wire by default
+
+- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md)
+- **Date**: 2026-08-05
+
+## Context
+
+[ADR 0006](./0006-raw-db-errors.md) rejected two distinct proposals in one decision: mapping
+SQLSTATE codes to HTTP semantics, and sanitizing driver messages. The first rejection holds
+— the mapping is dialect-specific and encodes product decisions the plugin should not make.
+The second rested on "hiding details is an environment policy, and Fastify already gives
+consumers the hook for it", and three facts undermine it:
+
+- The plugin installs its own `setErrorHandler` in the routes' child scope
+  (`src/routes/auto/plugin.ts`), and it sends `error.message` verbatim for any status code.
+  A consumer handler registered on the parent scope never sees these errors, so the escape
+  route 0006 points at does not exist for the main-plugin path.
+- The posture is inconsistent with the rest of the codebase. `maxItemsPerPage`,
+  `maxBulkItems`, prototype-key filtering and the join field allowlist are all guards the
+  plugin applies by default where the cost is zero. A constraint name describing the schema
+  to whoever triggered a duplicate is the same class of free hardening.
+- [ADR 0002](./0002-open-by-default.md) amplifies the exposure: the scenario the plugin
+  optimizes for — internal scaffolding wired up in five minutes — is exactly the one where
+  nobody wrote an error handler.
+
+The failure mode is silent. A consumer who never thinks about it ships the leak and gets no
+signal.
+
+## Decision
+
+Errors escaping an auto-generated route handler are replaced with a bare
+`500 Internal Server Error` carrying no database detail. Errors the plugin raises itself are
+deliberate `4xx` with messages written for clients (`httpError`, `validationErrors`) and pass
+through untouched — the rule is `statusCode` in `[400, 500)`, nothing else.
+
+No status code is remapped: a `500` stays a `500`. ADR 0006 stands on that point.
+
+Nothing is lost. The original error is logged through `request.log.error` and attached as the
+`cause` of the error the consumer's `setErrorHandler` receives, so unique-violation → `409`
+remains implementable, and remains the consumer's decision. The sanitized body carries
+`requestId` — the same value Fastify binds as `reqId` on the request logger — so the client
+can name the log line holding the real error instead of describing a `500` that happened
+"around then".
+
+Developing against the API is a real need the log does not serve — a client building on it,
+an agent especially, may have no way to read the server's log, and a round trip per failure
+is expensive. `exposeDebugInfo: true` answers it by **adding** a `debugInfo` payload (driver
+message, `code`, `constraint`/`detail`, stack) beside the fields above, which keep the shape
+they have in production. Client-side error handling therefore does not fork between
+environments — the difference is extra data, not different data.
+
+`exposeDebugInfo` derives from nothing. Not `debug`, not `NODE_ENV`, not the log level. The
+deciding argument is that **`debug` belongs to the consumer**: whoever registers the plugin
+decides how it is wired — a constant in one deployment, an environment variable flipped
+during an incident in another — so the library cannot assume its lifecycle, and an option
+whose value the library does not control must not decide what leaves the server. Beyond that,
+`debug` writes to the log, an access-controlled internal channel; the response body is
+external, and under ADR 0002 often unauthenticated. And the posture wanted during a
+production incident — log everything, tell clients nothing — stops being expressible the
+moment one switch drives both.
+
+The guard sits in the handler built by `registerForAllTables`
+(`src/routes/auto/route-helpers.ts`) — the single choke point every auto route passes
+through, including route plugins registered standalone without the main plugin. The
+`debugInfo` payload is copied from the driver error by allowlist, never spread: an error
+object that starts carrying the connection config must not reach a client through it.
+
+## Alternatives considered
+
+- **`fastify.setErrorHandler` in the plugin** — rejected: the plugin is registered through
+  `fp()`, so a handler installed at that level would hijack error rendering for the
+  consumer's entire application, not just the auto routes.
+- **Sanitizing inside the existing child-scope handler in `plugin.ts`** — rejected: route
+  plugins registered standalone (`searchRoutes` alone, per AGENTS_BACKEND.md "Register only
+  specific routes") never reach that handler, and would keep leaking.
+- **Leaving it to the consumer, as 0006 decided** — rejected for the three reasons in
+  Context; the deciding one is that the plugin's own child-scope handler makes the
+  prescribed consumer remedy unreachable.
+- **Deriving the behaviour from `debug`** — rejected, for the reasons in Decision: the
+  consumer owns that option and may wire it to an environment variable, it currently governs
+  an internal channel only, and coupling makes "verbose log, silent response" unexpressible.
+  An override (`debug: true` + an explicit opt-out) would keep the combination reachable but
+  leaves the default pointing the dangerous way, which is the failure mode this ADR exists to
+  close.
+- **Keying it on `NODE_ENV`** — rejected. `NODE_ENV !== 'production'` is fail-open: the
+  variable is unset often enough in real deployments (a bare `node dist/server.js`, many
+  container images, systemd units) that the leak would come back precisely where nothing was
+  configured. `NODE_ENV === 'development'` would at least fail closed, but a security-relevant
+  response decided by the shell instead of by the registration call is action at a distance.
+- **Replacing `message` with the driver text instead of adding `debugInfo`** — rejected: it
+  makes one field mean different things in different environments, so client error handling
+  has to be written twice. The additive payload costs nothing and carries more, structured.
+- **Echoing only the SQLSTATE code** (`23505`, no names) — rejected: a third middle mode is
+  harder to reason about than a boolean, and reading meaning into SQLSTATE is the direction
+  0006 closed.
+- **Sending the detail only to localhost callers** — rejected: it makes the response depend
+  on network topology, which reverse proxies routinely flatten.
+
+## Consequences
+
+- Constraint violations reach clients as `{"statusCode":500,"error":"Internal Server
+  Error","message":"Internal Server Error","requestId":"…"}`. Diagnosing one requires the
+  server log — which is where the error was already going, under that same id.
+- Behavioural breaking change for consumers who parsed driver messages out of `500` bodies.
+  They read `debugInfo` instead, and only where the deployment opted in.
+- Development needs one more line (`exposeDebugInfo: true`) than it did. That is the price of
+  the option meaning exactly one thing: what a client sees is readable from the registration
+  call alone, without knowing how `debug` or the environment happen to be wired.
+- A deployment that leaves `exposeDebugInfo` on by mistake is back to disclosing schema
+  detail. The name is the mitigation: `expose` is the word that makes a reader stop, which
+  `debug` is not.
+- Errors thrown by consumer `onRequests` hooks are outside the handler and unaffected: that
+  is consumer code running before the plugin's SQL surface, and its messages are the
+  consumer's to write.

package/docs/adr/README.md

@@ -26,11 +26,14 @@ not by editing history.
 | [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 |
+| [0013](./0013-sanitized-db-errors.md) | Database error messages are sanitized on the wire by default (narrows 0006) |
 
 ## 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.14",
+  "version": "0.2.1",
   "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",