fastify-auto-sqlapi 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -7,6 +7,43 @@ All notable changes to this project are documented here. This project follows
 
 Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)**.
 
+## [Unreleased]
+
+### Added
+
+- **`excludeTables` config option** — blacklist for `sqlapi-generate-schema`. Tables
+  listed in `excludeTables` in `sqlapi.config.ts` (exact names or `*` globs, e.g.
+  `knex_*`) are skipped during schema generation; their previously generated schema files
+  are removed as orphans on the next full run, like those of dropped tables (ADR 0009).
+  Does not apply to `sqlapi-generate-tables`, which is already explicit (ADR 0007).
+
+## [0.1.12]
+
+### Fixed
+
+- **Security: `aggregations.by` bypassed `readExclude`.** Every other reference to a
+  read-excluded field (filters, conditions, orderBy, aggregation fields, join selections)
+  is rejected with 400, but the `joinGroup` GROUP BY field was resolved without the check —
+  `aggregations: { by: '<excludedField>', count: [...] }` returned the hidden field's
+  distinct values verbatim in `rows[].by`. The field now goes through the same
+  `validateSchemaField` guard as aggregation fields (400).
+- **Security: HAVING-style conditions and 3-part aggregation `orderBy` could probe
+  read-excluded fields.** `buildAggOrderExpr` validated the aggregation field without the
+  join table's config, skipping the `readExclude` check. The downstream validation in the
+  joinGroup execution masked it — except when the main result set was empty, where that
+  validation is skipped entirely: a condition like `player.sum.<hiddenField> > X` answered
+  400 when at least one row matched and 200 when none did, a binary oracle allowing
+  bisection of the hidden field's aggregates. The check now fires at condition-build time.
+  Found by a full audit of every field-referencing input against `readExclude` (all other
+  paths verified guarded: filters, conditions, orderBy 1/2-part, selections, aggregation
+  fields, compute*, GET).
+
+### Added
+
+- ADR 0008: agent client interface — static grammar (`AGENTS_FRONTEND.md`, same filename by
+  design) + runtime manifest split, density as a feature, loose validation with the
+  structured 400 as the default tool strategy.
+
 ## [0.1.11]
 
 ### Breaking

package/README.md

@@ -1,14 +1,63 @@
 # fastify-auto-sqlapi
 
-Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL, with TypeBox validation and Swagger docs out of the box.
+**Your database already knows its tables, columns and relations. This plugin turns that knowledge into a complete REST API inside your [Fastify](https://fastify.dev/) app.**
 
-Point it at your database, and get a full REST API with search, advanced conditions, pagination, joins, aggregations, bulk operations, multi-tenant isolation, validation, and hooks.
+Two CLI commands introspect PostgreSQL / MySQL / MariaDB and generate typed schemas; one `register()` call turns each table *you choose to expose* into seven endpoints: search with filters, advanced conditions, relation joins and aggregations; validated writes with nested child records; bulk upsert/delete; multi-tenant isolation; Swagger docs. Related tables don't need endpoints of their own — reads reach them through joins, writes through nested children — so a whole subgraph can live behind a single exposed table. What's left to write is what makes your product yours — auth, business rules, custom logic — as plain TypeScript hooks next to your other routes.
+
+One request, to show the point — *"active customers with over 500 total in completed orders, with their order stats, biggest spenders first"*:
+
+```jsonc
+// POST /api/search/customer?orderBy=orders.sum.total DESC&page=1&itemsPerPage=20
+{
+  "filters": { "status": "active" },
+  "joinGroup": {
+    "orders": {
+      "filters": { "status": "completed" },
+      "aggregations": { "sum": ["total"], "count": ["id"] }
+    }
+  },
+  "conditions": [{ "field": "orders.sum.total", "method": "isGreater", "params": [500] }]
+}
+```
+
+Under the hood this is a fixed, request-shaped number of set-based queries — the main select plus one per requested join alias (EXISTS clauses and correlated subqueries ride inside them), **never one per returned row**. There are no lazy relations to accidentally loop over: the N+1 problem is structurally absent, not something you remember to avoid.
+
+Writes read the same way — *"sync these clients and their tags: update the ones that exist, insert the missing ones, don't duplicate a tag"*:
+
+```jsonc
+// PUT /api/bulk/customer — all mains in one SQL; child FKs auto-filled from each parent
+[
+  { "main": { "email": "mario@acme.it", "name": "Mario" },
+    "secondaries": { "tags": [{ "tag": "vip" }, { "tag": "newsletter" }] } },
+  { "main": { "email": "luigi@acme.it", "name": "Luigi" } }
+]
+// → 200 [{ "main": { "id": 1 }, "secondaries": { "tags": [{ "id": 10 }, { "id": 11 }] } },
+//        { "main": { "id": 2 } }]
+```
+
+Conflict keys are declared server-side (`upsertMap`: here customer on `email`, tag on `(customerId, tag)`), so re-sending the same payload updates rows instead of duplicating them — client-side sync without hand-written diffing.
+
+And multi-tenancy is one plugin option (`getTenantId: (req) => req.user.organizationId`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
+
+```jsonc
+// PUT /api/rest/order — order 7 is mine, customer 41 belongs to another tenant
+{ "main": { "id": 7, "customerId": 41 } }
+// → 403 Forbidden — cross-tenant references are rejected server-side
+```
+
+No endpoint written by hand, no resolvers, no query language on the server — and these requests are schema-validated, Swagger-documented, size-capped and tenant-isolated like every other one.
+
+## Not an ORM, not GraphQL — a third thing
+
+- **Not an ORM.** An ORM is a library *your* code uses to talk to the database — you still hand-write every endpoint on top of it. This plugin generates the endpoints themselves. And there is no ORM underneath either: no models, no migrations, no second schema to keep in sync. The database is the single source of truth (the CLI reads it from `information_schema`), and every request runs as plain parameterized SQL you can read with `debug: true`.
+- **Not GraphQL.** GraphQL buys client-driven flexibility with a heavy toolchain: a schema layer, hand-written resolvers (and their N+1 traps), mutations written one by one, client libraries, and query-cost analysis to stop hostile requests. This plugin covers what most projects actually reach for GraphQL for — filter, paginate, join related data, aggregate, in one round trip — with a fixed JSON grammar over plain REST: curl-able, Swagger-documented, bounded by design (join depth is fixed, page and bulk sizes are capped). The write side — nested children, upserts, bulk — is generated too, which GraphQL never gives you for free. What you give up: arbitrarily deep nesting, per-field selection on the main table, subscriptions. If you need those, you need GraphQL; most CRUD backends don't.
+- **Not a hosted black box.** PostgREST / Hasura / Supabase give you an instant API as a separate service, configured from the outside. This is a plugin inside your own app: hooks, validation and auth are TypeScript functions in your codebase, and you can always drop down to `app.sqlApi.*` or raw SQL in a custom route — same engine, no lock-in.
 
 ## Features
 
+- **Zero boilerplate** — 7 endpoints per exposed table; related tables can stay behind joins and nested writes instead of getting endpoints of their own
+- **No ORM** — raw SQL via `pg` + parameterized queries; set-based joins, so no N+1 by construction
 - **Agent-ready** — `AGENTS.md` and the ADRs ship *inside* the npm package, so a coding agent can configure the library without reading the source or guessing intent
-- **Zero boilerplate** — define your tables, get 7 endpoints each
-- **No ORM** — raw SQL via `pg` + parameterized queries
 - **TypeBox validation** — request/response schemas auto-generated from your DB
 - **Joins** — four explicit families (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) with alias support
 - **Computed fields** — declare virtual fields as SQL expressions in `defineTable`; usable like schema fields in filters/orderBy/conditions, and opt-in projected in the response via `selectComputed`. Covers JSON extraction, derived columns, dialect-aware date bucketing
@@ -25,37 +74,6 @@ Point it at your database, and get a full REST API with search, advanced conditi
 > with bound values, read the 0.1.6 entry — earlier versions could return wrong rows.
 
 
-## Working with coding agents
-
-The library is documented for two readers. Humans get this README; agents get task-oriented
-files that ship in the published package, so they are already on disk after `npm install`:
-
-| File                                   | Contents                                                          |
-| -------------------------------------- | ----------------------------------------------------------------- |
-| `AGENTS.md`                            | Entry point: what the library does, which file to read for what   |
-| `AGENTS_BACKEND.md`                    | `defineTable` reference, hooks, tenancy, computed fields, CLI      |
-| `AGENTS_FRONTEND.md`                   | Request/response shapes for every endpoint                        |
-| `docs/adr/`                            | Why the non-obvious behaviours are what they are                  |
-
-Point your agent at them once:
-
-> Read `node_modules/fastify-auto-sqlapi/AGENTS.md` before touching anything under `src/db/`.
-
-Three design choices make the generated code predictable enough for an agent to write it
-unsupervised:
-
-- **Configuration is declarative and local.** A table is one `defineTable()` call — nothing to
-  wire across files, so a diff is reviewable at a glance.
-- **One naming convention.** camelCase in requests, responses, hooks and validators; the
-  mapping to DB columns is automatic. There is no second convention to remember, and no
-  layer where the agent has to guess which one applies.
-- **Errors are machine-readable.** A 400 carries `fields: [{ path, code, message }]`, so a
-  failing request tells the agent exactly what to fix instead of requiring a guess.
-
-The ADRs matter more than they look: they answer the "why is it like this?" questions
-(open-by-default, non-transactional bulk, always-updatable fields) that an agent would
-otherwise resolve by inventing a workaround — or by proposing to change intentional behaviour.
-
 ## Quick Start
 
 ### 1. Install
@@ -76,6 +94,7 @@ export default {
   schema: 'public',            // PostgreSQL schema to introspect (default: 'public')
   // dialect: 'mysql',         // 'postgres' (default) | 'mysql' | 'mariadb'
   // envFile: '.env.local',    // env file to load (default: '.env')
+  // excludeTables: ['knex_*'], // tables to skip in schema generation ('*' = wildcard)
 };
 ```
 
@@ -113,6 +132,12 @@ This introspects your tables and generates one TypeBox schema file per table in
 `<outputDir>/schemas/` (e.g. `SchemaCustomer.ts`, `SchemaOrder.ts`). These files are
 auto-generated — don't edit them; re-run the command after a DB change.
 
+To keep some tables out of schema generation (migration bookkeeping, PostGIS internals, …)
+list them in `excludeTables` in the config — exact table names or `*` globs (e.g.
+`knex_*`). Excluded tables are invisible to the generator: their schemas are not created,
+and any previously generated schema file is removed as an orphan on the next full run,
+like that of a dropped table.
+
 ### 4. Generate the tables template
 
 ```bash
@@ -161,6 +186,37 @@ That's it. For a table called `customer`, you now have:
 
 > **Note:** Search uses `POST` because filters are passed as JSON in the request body.
 
+## Working with coding agents
+
+The library is documented for two readers. Humans get this README; agents get task-oriented
+files that ship in the published package, so they are already on disk after `npm install`:
+
+| File                                   | Contents                                                          |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `AGENTS.md`                            | Entry point: what the library does, which file to read for what   |
+| `AGENTS_BACKEND.md`                    | `defineTable` reference, hooks, tenancy, computed fields, CLI      |
+| `AGENTS_FRONTEND.md`                   | Request/response shapes for every endpoint                        |
+| `docs/adr/`                            | Why the non-obvious behaviours are what they are                  |
+
+Point your agent at them once:
+
+> Read `node_modules/fastify-auto-sqlapi/AGENTS.md` before touching anything under `src/db/`.
+
+Three design choices make the generated code predictable enough for an agent to write it
+unsupervised:
+
+- **Configuration is declarative and local.** A table is one `defineTable()` call — nothing to
+  wire across files, so a diff is reviewable at a glance.
+- **One naming convention.** camelCase in requests, responses, hooks and validators; the
+  mapping to DB columns is automatic. There is no second convention to remember, and no
+  layer where the agent has to guess which one applies.
+- **Errors are machine-readable.** A 400 carries `fields: [{ path, code, message }]`, so a
+  failing request tells the agent exactly what to fix instead of requiring a guess.
+
+The ADRs matter more than they look: they answer the "why is it like this?" questions
+(open-by-default, non-transactional bulk, always-updatable fields) that an agent would
+otherwise resolve by inventing a workaround — or by proposing to change intentional behaviour.
+
 ## Table Configuration
 
 Tables are configured with `defineTable()`. The only required fields are `primary` and the output of `exportTableInfo()`:

package/dist/bin/generate-schema.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import { loadConfig } from '../lib/cli/config.js';
 import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspect.js';
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
-import { buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
+import { applyExcludeTables, buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
 import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, parseArgs, runCli } from './utils.js';
 await runCli('fastify-auto-sqlapi: generating schemas', async () => {
     const cliArgs = parseArgs({
@@ -36,6 +36,14 @@ await runCli('fastify-auto-sqlapi: generating schemas', async () => {
         return;
     }
     const tableMap = buildTableMap(rows);
+    // Config blacklist: excluded tables are invisible to the generator, so their
+    // schema files (if any) fall through to the orphan cleanup below.
+    const excluded = applyExcludeTables(tableMap, config.excludeTables);
+    if (excluded.length) {
+        display(`Excluded by config (excludeTables): ${excluded.join(', ')}`, CONSOLE_COLORS.gray);
+    }
+    // Note: no early return when everything is excluded — the orphan cleanup below
+    // must still run to remove the schema files of freshly excluded tables.
     // Filter tables if --tables flag is provided
     const tableNames = cliArgs.tables;
     if (tableNames.length) {

package/dist/lib/cli/schema-codegen.d.ts

@@ -5,5 +5,12 @@ export declare function convertColType(udtName: string, columnInfo: {
     is_auto_increment?: boolean;
 }): string;
 export declare function buildTableMap(rows: ColumnInfo[]): TableMap;
+/**
+ * Remove from `tableMap` the tables matching any of the `excludeTables` config patterns.
+ * Patterns are matched against the DB table name (not the generated schema name);
+ * `*` is the only wildcard — everything else is literal.
+ * Returns the names of the excluded tables, in map order.
+ */
+export declare function applyExcludeTables(tableMap: TableMap, excludeTables?: string[]): string[];
 export declare function generateSchemaFile(schemaName: string, tableName: string, fields: Record<string, string>, colMap: Record<string, string>, primary?: string[]): string;
 //# sourceMappingURL=schema-codegen.d.ts.map

package/dist/lib/cli/schema-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,MAAM,CA0DR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAqC1D;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CA8CR"}
+{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,MAAM,CA0DR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAqC1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAoBzF;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CA8CR"}

package/dist/lib/cli/schema-codegen.js

@@ -85,6 +85,31 @@ export function buildTableMap(rows) {
         return acc;
     }, {});
 }
+/**
+ * Remove from `tableMap` the tables matching any of the `excludeTables` config patterns.
+ * Patterns are matched against the DB table name (not the generated schema name);
+ * `*` is the only wildcard — everything else is literal.
+ * Returns the names of the excluded tables, in map order.
+ */
+export function applyExcludeTables(tableMap, excludeTables) {
+    if (excludeTables === undefined)
+        return [];
+    if (!Array.isArray(excludeTables) || excludeTables.some((p) => typeof p !== 'string')) {
+        throw new Error('Invalid config: "excludeTables" must be an array of strings.');
+    }
+    if (excludeTables.length === 0)
+        return [];
+    const regexes = excludeTables.map((pattern) => new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replaceAll('\\*', '.*')}$`));
+    const excluded = [];
+    for (const schemaName of Object.keys(tableMap)) {
+        const tableName = tableMap[schemaName].name;
+        if (regexes.some((re) => re.test(tableName))) {
+            excluded.push(tableName);
+            delete tableMap[schemaName];
+        }
+    }
+    return excluded;
+}
 export function generateSchemaFile(schemaName, tableName, fields, colMap, primary) {
     const fieldsStr = JSON.stringify(fields, null, 2).replace(/"(.*?)"\s*:\s*"Type(.*?)"/g, '$1: Type$2');
     const colMapStr = JSON.stringify(colMap, null, 2);

package/dist/lib/engine/search/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AAwlC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA4HvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AA8lC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA4HvB"}

package/dist/lib/engine/search/search.js

@@ -219,7 +219,10 @@ function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup)
     if (groupReq.aggregations.by && groupReq.aggregations.by !== joinField) {
         err400(`Cannot order by aggregation on joinGroup with 'by' clause on non-FK column: ${alias} (grouped by '${groupReq.aggregations.by}', correlation FK is '${joinField}')`);
     }
-    const fieldCol = validateSchemaField(field, joinSchema);
+    // Pass the join table's conf: without it validateSchemaField skips the readExclude
+    // check, and a HAVING-style condition on a hidden field becomes a 400-vs-200 oracle
+    // (executeJoinGroup's own validation is skipped when the main result set is empty).
+    const fieldCol = validateSchemaField(field, joinSchema, dbTables[joinSchema.tableName]);
     const refs = extractJoinRefs(db, tableConf, joinDef);
     // The subquery FROM is aliased so the correlation to the outer table survives a
     // self-referencing relation; everything inside references the alias.
@@ -555,7 +558,10 @@ function buildByExpression(by, joinSchema, joinTableConf, db) {
         err400(`Invalid 'by' specification: expected a field or computed name`);
     }
     if (by in joinSchema.fields) {
-        return `${db.qi(joinSchema.tableName)}.${db.qi(joinSchema.col(by))}`;
+        // validateSchemaField also enforces readExclude: GROUP BY on a hidden field
+        // would return its distinct values verbatim in `rows[].by`.
+        const col = validateSchemaField(by, joinSchema, joinTableConf);
+        return `${db.qi(joinSchema.tableName)}.${db.qi(col)}`;
     }
     const fn = joinTableConf?.computedFields?.[by];
     if (fn) {

package/dist/types/cli.d.ts

@@ -4,6 +4,12 @@ export interface SqlApiConfig {
     schema?: string;
     dialect?: DialectName;
     envFile?: string;
+    /**
+     * Tables to skip during schema generation (`sqlapi-generate-schema`).
+     * Matched against the DB table name; `*` is a wildcard (e.g. "knex_*").
+     * Excluded schemas already on disk are removed as orphans on the next full run.
+     */
+    excludeTables?: string[];
 }
 export interface ColumnInfo {
     table_name: string;

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;CACH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;CACH"}

package/docs/adr/0008-agent-client-interface.md

@@ -0,0 +1,66 @@
+# 0008. Agent client interface: static grammar + runtime manifest
+
+- **Status**: accepted
+- **Date**: 2026-07-26
+
+## Context
+
+The plugin doubles as the enforcement layer for LLM clients that drive the API at runtime
+(a chat agent operating on backoffice data: whatever requests the model invents, tenant
+scoping, `readExclude`, `operations` and caps still apply). Such a client needs to be
+told how to call the API — but an LLM prompt has different constraints than human
+documentation: every line costs tokens on every call, and anything deployment-specific
+goes stale the moment the schema changes.
+
+## Decision
+
+The client-facing documentation is split into two halves with different lifecycles:
+
+- **Grammar** — `AGENTS_FRONTEND.md`: HOW to call the API (endpoints, search with the four
+  join families, condition methods with params arity, ordering notations, pagination,
+  writes, error shapes). Static, identical for every deployment, ~110 dense lines designed
+  for a system prompt. It deliberately contains **no tables, fields or aliases**.
+- **Vocabulary** — the manifest (`agentManifest: true` → `GET {prefix}/agent/manifest(.md)`,
+  or `buildAgentManifest()` programmatically): WHAT this deployment exposes — tables,
+  fields with type/required/nullable, enabled operations, join aliases with direction,
+  computed fields. Generated from `DbTables` at startup, so it can never drift from the
+  running configuration.
+
+Three deliberate properties:
+
+1. **The grammar file replaced the old tutorial-style `AGENTS_FRONTEND.md` under the same
+   filename.** The path `node_modules/fastify-auto-sqlapi/AGENTS_FRONTEND.md` is known to
+   consumers' coding agents; a new filename would have broken every existing reference for
+   zero benefit. Do not rename it.
+2. **Density is a feature, not a documentation gap.** The file lives in LLM system
+   prompts: jsonc examples with terse end-of-line comments, no rationale, no repetition —
+   each concept appears exactly once. Normative rules (what returns 400) belong in it;
+   explanations do not. Expanding it with prose and tutorials would revert this decision.
+3. **Loose validation with the structured 400 as retry signal is the default strategy**
+   for LLM tools; strict per-table JSON-Schema tools are opt-in via `agentToolSchemas()`.
+   The plugin's 400 (`fields: [{path, code, message}]`) was designed machine-readable, so
+   a loose generic tool self-corrects in one round trip. This is also why the plugin does
+   not ship an opinionated MCP/tool layer: it provides the pieces (grammar, manifest,
+   schemas), the consumer composes them.
+
+## Alternatives considered
+
+- **One complete document (grammar + tables of a given deployment)** — rejected: the
+  deployment-specific half goes stale on every schema change; the manifest endpoint is
+  the only source that cannot drift.
+- **A new `AGENT_CLIENT.md` alongside the old `AGENTS_FRONTEND.md`** — rejected: near-total
+  content overlap, proven drift risk (a fix had to be applied to both files during the
+  same session that created the second one), and known-path breakage on removal.
+- **Strict JSON-Schema tools as the default** — rejected: the full search schema per
+  table is enormous (conditions, four join families, per-alias shapes); across N tables
+  it explodes prompt size and degrades model performance. Kept as opt-in for hot tables.
+
+## Consequences
+
+- `AGENTS_FRONTEND.md` serves both coding agents (writing client code) and runtime LLM
+  clients; the verbose tutorial content it replaced is covered by the grammar plus
+  Swagger.
+- Contributions that add tables/fields/examples-with-prose to the grammar file, or rename
+  it, should be declined with a pointer to this ADR.
+- New request-shape features must update the grammar (a rule line, not a tutorial) and,
+  when they touch per-table capabilities, the manifest builder.

package/docs/adr/0009-schema-exclusion-config-blacklist.md

@@ -0,0 +1,47 @@
+# 0009. Schema exclusion is a config blacklist — excluded schemas are removed as orphans
+
+- **Status**: accepted
+- **Date**: 2026-07-27
+
+## Context
+
+`sqlapi-generate-schema` regenerates every table by default (ADR 0007: schemas are
+disposable mirrors). There was no way to keep unwanted tables — migration bookkeeping
+(`knex_migrations*`), PostGIS internals (`spatial_ref_sys`), vendor tables — out of the
+generated schemas short of deleting the files after every run.
+
+## Decision
+
+A blacklist lives in the existing config file: `excludeTables: string[]` in
+`sqlapi.config.ts`, matched against the DB table name, with `*` as the only wildcard.
+
+Excluded tables are **invisible to the generator**: their schemas are not generated, and a
+previously generated `Schema*.ts` for an excluded table is removed by the orphan cleanup
+on the next full run — exactly as if the table had been dropped. This keeps the ADR 0007
+invariant intact: everything under `schemas/` is a disposable mirror; excluding a table
+must not turn its schema file into a hand-maintained exception.
+
+This does not contradict ADR 0007's rejection of a skip-list for *tables*: there, explicit
+invocation solves exclusion for free. For schemas the default is "all", so a blacklist is
+the only way to exclude — and the same ADR is why `excludeTables` does **not** apply to
+`sqlapi-generate-tables`.
+
+## Alternatives considered
+
+- **`.schemaignore` file next to the schemas** — rejected: a second config format and a
+  second source of truth to parse and document, when a typed config file already exists.
+- **CLI-only `--exclude` flag** — rejected as the primary mechanism: the exclusion is a
+  durable property of the project, not of one invocation; forgetting the flag once would
+  resurrect the unwanted schemas.
+- **Keeping excluded schema files on disk (generator "never touches" them)** — rejected:
+  it would silently support hand-maintained files under `schemas/`, breaking the "always
+  safe to regenerate everything" property of ADR 0007.
+
+## Consequences
+
+- Adding a table to `excludeTables` deletes its generated schema file on the next full
+  run. This is intended: excluded means gone, not frozen.
+- Hand-written schemas do not belong in `schemas/`; exclusion is not a mechanism to
+  protect local edits.
+- An invalid `excludeTables` value (not an array of strings) fails the run with an
+  explicit error rather than being silently ignored.

package/docs/adr/README.md

@@ -22,6 +22,8 @@ not by editing history.
 | [0005](./0005-insert-pipeline-sanitize-before-hooks.md) | Insert pipeline: client payload sanitized before `beforeInsert` |
 | [0006](./0006-raw-db-errors.md) | Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping |
 | [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 |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",