fastify-auto-sqlapi 0.1.10 → 0.1.11

package/BREAKING_CHANGES.md

@@ -317,3 +317,66 @@ including `joinLeft.filters` / `joinLeft.conditions` and `orderBy`, which previo
 them with 400. They remain rejected in `selectComputed`, `computeMin/Max/Sum/Avg`,
 `joinGroup.aggregations.by` and `defaultOrder`, where the expression precedes the `WHERE`
 values in the parameter order.
+
+# Breaking Change — by-single-id operations disabled for composite primary keys
+
+Since **0.1.11**, tables whose `primary` is an array of more than one field no longer expose
+the operations that address a record by a single PK value:
+
+- `GET /rest/:table/:id` and `DELETE /rest/:table/:id` are **not registered** (404);
+- `POST /bulk/:table/delete` is **not registered** (404);
+- explicitly listing `get`, `delete` or `bulkDelete` in `ITable.operations` for such a table
+  now **throws at startup** with a descriptive error;
+- the programmatic `sqlApi.get/delete/bulkDelete` reject with `400`.
+
+Search, insert, update and bulk upsert are unaffected — they already matched every PK column.
+
+## Why this changed
+
+These operations matched on the **first** PK column alone. On `primary: ['agentId', 'teamId']`:
+
+- `DELETE /rest/t/1` deleted **every** row with `agent_id = 1` — not one record;
+- `GET /rest/t/1` returned an arbitrary row among those sharing `agent_id = 1`;
+- bulk delete removed every row matching each listed first-column value.
+
+A single `:id` cannot address a composite key; silently matching a prefix of the key is data
+loss waiting to happen, so the operations are refused loudly instead.
+
+## Who is affected
+
+Only consumers with composite-PK tables **and** clients calling get/delete/bulk-delete on
+them. If your composite table's first PK column happens to be unique on its own, these
+endpoints previously behaved correctly for you — they are now gone and you must migrate.
+
+## Migration
+
+- **Read one record** → `search` with every PK field in the filters:
+
+  ```typescript
+  await fetch('/auto/search/agent_team', {
+    method: 'POST',
+    body: JSON.stringify({ filters: { agentId: 1, teamId: 2 } }),
+  });
+  ```
+
+- **Delete one record** → a custom route using the low-level `QueryClient`, matching the
+  full key:
+
+  ```typescript
+  import { createQueryClient, pgQueryable } from 'fastify-auto-sqlapi';
+
+  const db = createQueryClient(pgQueryable(app.pg), 'postgres');
+
+  app.delete('/agent-team/:agentId/:teamId', async (req) => {
+    const { agentId, teamId } = req.params;
+    await db.delete('agent_team', { agent_id: agentId, team_id: teamId });
+    return { main: { agentId, teamId } };
+  });
+  ```
+
+- **Row removal as part of an edit flow** → `update` on the parent with `deletions` (write
+  joins), or bulk upsert — both match every PK column.
+
+- **First PK column is truly unique on its own?** Then the composite declaration was
+  redundant: declare `primary: 'id'` (single) and keep the second column as a plain field —
+  every by-id operation comes back.

package/CHANGELOG.md

@@ -7,6 +7,75 @@ 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)**.
 
+## [0.1.11]
+
+### Breaking
+
+- **⚠️ By-single-id operations are disabled for composite-PK tables.** `GET /rest/:id`,
+  `DELETE /rest/:id` and `POST /bulk/:table/delete` matched on the **first** PK column alone:
+  on a table with `primary: ['agentId', 'teamId']`, `DELETE /rest/t/1` deleted **every** row
+  with `agentId = 1`, not one record. These routes are no longer registered for composite-PK
+  tables (404); explicitly listing one of them in `operations` now throws at startup, and the
+  programmatic `sqlApi.get/delete/bulkDelete` reject with 400. Search, insert, update and
+  bulk upsert are unaffected — they already handled every PK column. If your composite table's
+  first PK column happens to be unique, these endpoints previously worked for you and are now
+  gone — see
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--by-single-id-operations-disabled-for-composite-primary-keys)
+  for the migration paths.
+
+### Fixed
+
+- **⚠️ NULL values were serialized as `0` / `""` in read responses.** The generator mapped
+  nullable columns to `Type.Optional(T)`, which means "key may be absent" — not "value may
+  be null" — so fast-json-stringify coerced every NULL to the type's zero value (a NULL FK
+  was served as `0`). Nullable columns are now generated as `Type.Optional(Nullable(T))`,
+  where the new exported `Nullable()` helper emits the JSON-Schema type-array form
+  (`type: ['integer', 'null']`). **Regenerate your schemas** (`sqlapi-generate-schema`) to
+  pick up the fix. Note: the type-array form is deliberate — a `Type.Union([T, Type.Null()])`
+  would NOT fix it, because Fastify's default Ajv `coerceTypes` corrupts values through
+  union branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first);
+  with a type array no coercion happens. As a side effect, writes now accept an explicit
+  `null` to set a column to NULL.
+- **`maxItemsPerPage` below 500 broke every request without an explicit `itemsPerPage`.**
+  The search querystring schema declared a fixed `default: 500`; Ajv injects defaults before
+  the cap check runs, so any lower cap rejected the injected default with 400. The schema is
+  now parameterized: `default = min(500, maxItemsPerPage)` and the cap doubles as the schema
+  `maximum` (structured 400 instead of a plain error). The `SearchTableQuery(cap)` builder is
+  exported; `SearchTableQueryString` remains as the default-cap variant.
+
+### Changed
+
+- **`filters` with an explicit `null` now filter by `IS NULL`.** Previously a null filter
+  was silently dropped — a request asking "field is null" returned unfiltered results. An
+  explicit `null` on a schema field now builds `WHERE col IS NULL` (undefined/absent keys
+  are still ignored). `conditions` + `isNull` keeps working as before.
+
+### Added
+
+- **LLM / agent client support.** The plugin doubles as the enforcement layer for a chat
+  agent operating on your data (tenant scoping, `readExclude`, `operations`, caps apply to
+  whatever the model invents). New pieces:
+  - `AGENTS_FRONTEND.md` rewritten as a compact LLM-oriented request grammar (search with
+    all join families, ordering, pagination, writes, error shapes) — usable both by coding
+    agents and as the system prompt of a runtime agent client. Same filename and package
+    path as before, so existing references keep working; the verbose tutorial-style
+    content it replaces is fully covered by the grammar plus Swagger.
+  - `agentManifest: true` plugin option → `GET {prefix}/agent/manifest` (JSON) and
+    `/agent/manifest.md` (markdown for the system prompt): per-table fields with
+    type/required/nullable, enabled operations, join aliases with direction, computed
+    fields, extra filters — always in sync with the running config, behind the same
+    global `onRequests`. Also exported programmatically (`buildAgentManifest`,
+    `renderAgentManifestMd`) and as a granular route plugin (`agentManifestRoutes`).
+  - `agentToolSchemas(dbTables, table)` — the exact JSON Schemas the routes validate
+    with, per enabled operation, for strict provider-side tool definitions.
+  - README "LLM / agent clients" section and AGENTS_BACKEND.md pattern: read-only agent
+    surface via granular composition, loose-tool + structured-400 retry loop vs strict
+    tools.
+- `Nullable(schema)` export: marks a TypeBox schema nullable via the JSON-Schema type-array
+  form — the only representation safe under Fastify's default Ajv/fast-json-stringify on
+  both input validation and response serialization.
+- ADR 0007: table generation is explicit — `--all` is a migration helper, not the default.
+
 ## [0.1.10]
 
 ### Added

package/README.md

@@ -4,18 +4,9 @@ Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fa
 
 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.
 
-## What LLMs Are Saying
-
-> API: 5 new read-only tables — and this is where your plugin really shined.
-
-> Yes, it genuinely saved me a lot of work, and the numbers make that obvious: I deleted about 350 lines of hand-written API repository and route code, replacing them with roughly 150 lines of declarative configuration. And it wasn't a one-for-one trade. In return, I gained features I simply didn't have before: complete Swagger documentation, the conditions DSL (previously I only had sorting and fixed filters), pagination with total counts, structured 400 errors, and consistent camelCase conversion. 
-
-> The moment I thought, "Okay, this is well designed," was when I used computedFields: the case of "attributes stored inside a jsonb column that still need to be sortable and filterable" is exactly the kind of problem that usually forces you to step outside the framework, yet it fit in cleanly. It worked end-to-end with the role-based CASE expression, remained sortable, could be projected with selectComputed, and required zero SQL in the routes.
-
-> The AGENTS files deserve a mention: I configured everything without ever opening the source code—CLI schema, defineTable, buildRelation, computed, extraFilters, and the frontend request/response shapes. As "documentation for agents," they genuinely work, and that's more than I can say for most libraries.
-
 ## Features
 
+- **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
@@ -33,6 +24,38 @@ Point it at your database, and get a full REST API with search, advanced conditi
 > **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for migration guides. If you use `computedFields`
 > 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
@@ -513,6 +536,13 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 
 Returns `{ main: { ... } }` or 404.
 
+> **Composite primary keys:** `GET /rest/:id`, `DELETE /rest/:id` and `POST /bulk/:table/delete`
+> address a record by a single PK value, so they are **not registered** for tables whose
+> primary key spans multiple columns (a match on the first column alone could hit many rows —
+> for the deletes, destructively). Explicitly listing one of these operations in `operations`
+> for such a table throws at startup. Use `search` with all PK fields in the filters, `update`
+> (which matches every PK column), or a custom route.
+
 ### POST /rest/{table}
 
 **Body:**
@@ -540,7 +570,7 @@ Returns `{ main: { ... } }` or 404.
 > ),
 > // → PUT /rest/product { "main": {...}, "secondaries": { "translations": [{ "lang": "en", "name": "Bike" }] } }
 > ```
-> Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — composite PKs are fully supported there too.
+> Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — search, insert, update and bulk upsert fully support composite PKs; the by-single-id routes (get, delete, bulkDelete) are skipped for them (see the note under GET).
 
 **Response (201):** `{ main: { ... }, secondaries: { ... } }`
 
@@ -691,6 +721,60 @@ await app.register(async (instance) => {
 }, { prefix: '/admin' });
 ```
 
+## LLM / agent clients
+
+The plugin is a natural enforcement layer for an agent that operates on your data through
+chat: whatever requests the LLM invents, they pass through the same tenant scoping,
+`readExclude`, `operations` whitelist, validation and request caps as any HTTP client —
+direct-DB firepower, backoffice constraints. Three pieces make this practical:
+
+**1. The grammar** — [`AGENTS_FRONTEND.md`](./AGENTS_FRONTEND.md) (ships in the npm package)
+is a compact, LLM-oriented reference of how to call the API: search with all four join
+families, ordering, pagination, writes, error shapes. Put it in the system prompt.
+
+**2. The vocabulary** — enable the manifest endpoint to describe *this deployment's* tables:
+
+```typescript
+await app.register(fastifyAutoSqlApi, {
+  DbTables: dbTables,
+  agentManifest: true,   // GET {prefix}/agent/manifest (JSON) + /agent/manifest.md
+});
+```
+
+`GET /agent/manifest.md` returns a compact markdown block per table — fields with
+type/required/nullable, enabled operations, join aliases (with direction), computed fields,
+extra filters — always in sync with the running config, behind the same `onRequests` auth.
+Fetch it at session start: grammar + vocabulary is everything the model needs. The same data
+is available programmatically via `buildAgentManifest(dbTables)` /
+`renderAgentManifestMd(manifest)`.
+
+**3. The guardrails** — writes are often too dangerous to hand to a model. Register a
+read-only surface with granular composition and give the agent only that:
+
+```typescript
+import { searchRoutes, getRoutes, agentManifestRoutes } from 'fastify-auto-sqlapi';
+
+await app.register(async (instance) => {
+  const opts = { DbTables: dbTables, onRequests: [agentAuth] };
+  await instance.register(searchRoutes, opts);
+  await instance.register(getRoutes, opts);
+  await instance.register(agentManifestRoutes, opts);
+}, { prefix: '/agent' });   // reads only: no insert/update/delete routes exist here
+```
+
+**Validation strategy** — two options, per table or per deployment:
+
+- *Loose tool + retry loop* (recommended default): expose a generic tool
+  (`table` as enum from the manifest, `body` as free object) and let the plugin validate.
+  A failed request returns a structured 400 with `fields: [{path, code, message}]` — feed
+  it back to the model and it self-corrects in one round trip. Cheap prompts, no schema
+  duplication.
+- *Strict tools*: `agentToolSchemas(dbTables, 'customer')` returns the exact JSON Schemas
+  the routes validate with (body + querystring for search, bodies for writes, only for the
+  operations enabled on that table) — plug them into provider-side tool definitions when
+  you want invalid calls rejected before they leave the model. Costs prompt size; best for
+  a few hot tables.
+
 ## Design Decisions
 
 Deliberate, non-obvious choices — open-by-default, non-transactional bulk operations,
@@ -707,6 +791,8 @@ proposes changing one of these behaviors.
 - **`joinMustExist` / `joinMultiple` / `joinGroup`** are 1:N (child→main) and use side queries / EXISTS / correlated subqueries — no row duplication
 - **`joinLeft`** is N:1 (parent→main) and adds a real `LEFT JOIN` on demand (only when filtering/ordering by parent)
 - **All response fields are Optional** — response schemas use `Type.Partial` since `RETURNING *` may return any subset
+- **Nullable columns use `Nullable(T)`** — the generator emits the JSON-Schema type-array form (`type: ['integer', 'null']`) via the exported `Nullable()` helper. This is deliberate: a bare `Type.Optional(T)` serializes NULL as `0`/`""`, and a `Type.Union([T, Type.Null()])` gets corrupted by Ajv's default type coercion (`null` ↔ `0`/`""` through the branches). In `filters`, an explicit `null` filters by `IS NULL`
+- **The `pg` driver returns `numeric`/`int8` as strings** and parses timestamps into local-timezone `Date`s — driver defaults the plugin deliberately does not override (global state). See "PostgreSQL driver type parsers" in AGENTS_BACKEND.md for the recommended one-time setup
 
 ## Re-exports
 
@@ -725,6 +811,7 @@ import {
   buildRelation,
   buildUpsertRule,
   buildUpsertRules,
+  Nullable,               // type-array nullable schema (see Conventions)
 
   // DB layer
   QueryClient,            // raw SQL query helper

package/dist/index.d.ts

@@ -4,13 +4,17 @@ export { getDialect, type SqlDialect, type DialectName } from './lib/dialect.js'
 export { pgQueryable } from './lib/adapters/pg-adapter.js';
 export { mysqlQueryable } from './lib/adapters/mysql-adapter.js';
 export { exportTableInfo, defineTable, buildRelation, buildUpsertRule, buildUpsertRules } from './lib/table-helpers.js';
+export { Nullable } from './lib/nullable.js';
+export { buildAgentManifest, renderAgentManifestMd, type AgentManifest, type ManifestTable, } from './lib/agent/manifest.js';
+export { agentToolSchemas, type AgentToolSchemas } from './lib/agent/tool-schemas.js';
+export { default as agentManifestRoutes } from './routes/auto/agent-manifest.routes.js';
 export { resolveTenant } from './lib/tenant.js';
 export { SqlApi, createSqlApi } from './lib/sql-api.js';
 export type { SqlApiOptions, SqlApiSearchParams, SqlApiInsertParams, SqlApiUpdateParams } from './lib/sql-api.js';
 export { default as fastifyAutoSqlApi } from './routes/auto/plugin.js';
 export { setupSwagger } from './lib/setup-swagger.js';
 export { searchEngine } from './lib/engine/search/search.js';
-export { SearchTableBodyPost, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
+export { SearchTableBodyPost, SearchTableQuery, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
 export { default as searchRoutes } from './routes/auto/search.routes.js';
 export { insertEngine } from './lib/engine/rest/insert.js';
 export { InsertTableBody, InsertTableResponse } from './lib/schema/insert.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -9,6 +9,11 @@ export { pgQueryable } from './lib/adapters/pg-adapter.js';
 export { mysqlQueryable } from './lib/adapters/mysql-adapter.js';
 // Table helpers
 export { exportTableInfo, defineTable, buildRelation, buildUpsertRule, buildUpsertRules } from './lib/table-helpers.js';
+export { Nullable } from './lib/nullable.js';
+// Agent / LLM client helpers
+export { buildAgentManifest, renderAgentManifestMd, } from './lib/agent/manifest.js';
+export { agentToolSchemas } from './lib/agent/tool-schemas.js';
+export { default as agentManifestRoutes } from './routes/auto/agent-manifest.routes.js';
 // Tenant
 export { resolveTenant } from './lib/tenant.js';
 // SqlApi — programmatic high-level API
@@ -19,7 +24,7 @@ export { default as fastifyAutoSqlApi } from './routes/auto/plugin.js';
 export { setupSwagger } from './lib/setup-swagger.js';
 // Search
 export { searchEngine } from './lib/engine/search/search.js';
-export { SearchTableBodyPost, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
+export { SearchTableBodyPost, SearchTableQuery, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
 export { default as searchRoutes } from './routes/auto/search.routes.js';
 // Insert
 export { insertEngine } from './lib/engine/rest/insert.js';

package/dist/lib/agent/manifest.d.ts

@@ -0,0 +1,53 @@
+import type { DbTables, ITable, TableOperation } from '../../types.js';
+export interface ManifestField {
+    type: string;
+    /** Present (true) when the field must be sent on insert. */
+    required?: boolean;
+    /** Present (true) when the column accepts null. */
+    nullable?: boolean;
+    /** Present (true) when the field is writable but never returned by reads (readExclude). */
+    writeOnly?: boolean;
+}
+export interface ManifestJoin {
+    alias: string;
+    table: string;
+    /** '1:N' → usable in joinMustExist/joinMultiple/joinGroup; 'N:1' → usable in joinLeft. */
+    kind: '1:N' | 'N:1';
+}
+export interface ManifestTable {
+    /** URL segment for this table's routes. */
+    table: string;
+    primary: string | string[];
+    operations: TableOperation[];
+    fields: Record<string, ManifestField>;
+    /** Fields stripped from client input on insert (server-generated: PKs, timestamps). */
+    serverGenerated?: string[];
+    /** Computed (virtual) fields: usable in filters/conditions/orderBy/selectComputed. */
+    computed?: Record<string, string>;
+    /** Extra filter names accepted in `filters` beyond schema fields. */
+    extraFilters?: Record<string, string>;
+    readJoins?: ManifestJoin[];
+    /** Aliases accepted as `secondaries`/`deletions` keys in writes. */
+    writeJoins?: ManifestJoin[];
+    /** Present (true) when rows are automatically scoped to the caller's tenant. */
+    tenantScoped?: boolean;
+    defaultOrder?: string;
+}
+export interface AgentManifest {
+    tables: Record<string, ManifestTable>;
+}
+export declare function tableOperations(tableConf: ITable): TableOperation[];
+/**
+ * Build the machine-readable description of every table exposed by this deployment:
+ * fields (type/required/nullable), enabled operations, join aliases, computed fields,
+ * extra filters, tenant scoping. Derived entirely from `DbTables`, so it is always in
+ * sync with the running configuration. Pairs with AGENTS_FRONTEND.md (the request grammar)
+ * to give an LLM client everything it needs to drive the API.
+ */
+export declare function buildAgentManifest(dbTables: DbTables): AgentManifest;
+/**
+ * Compact markdown rendering of the manifest, designed for an LLM system prompt.
+ * Notation: `!` required on insert, `?` nullable, `(writeOnly)` never returned by reads.
+ */
+export declare function renderAgentManifestMd(manifest: AgentManifest): string;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/lib/agent/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAgCD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA2CrE"}

package/dist/lib/agent/manifest.js

@@ -0,0 +1,153 @@
+import { isCompositePrimary } from '../../types.js';
+const ALL_OPERATIONS = [
+    'search', 'get', 'insert', 'update', 'delete', 'bulkUpsert', 'bulkDelete',
+];
+const SINGLE_PK_OPERATIONS = new Set(['get', 'delete', 'bulkDelete']);
+function shortType(schema) {
+    if (!schema)
+        return 'any';
+    const t = schema.type;
+    if (!t)
+        return 'any';
+    const types = (Array.isArray(t) ? t : [t]).filter((x) => x !== 'null');
+    return types[0] ?? 'any';
+}
+function isNullable(schema) {
+    const t = schema?.type;
+    return Array.isArray(t) && t.includes('null');
+}
+function computedTypes(tableConf) {
+    if (!tableConf.computedFields)
+        return undefined;
+    const out = {};
+    for (const [name, fn] of Object.entries(tableConf.computedFields)) {
+        try {
+            const stub = fn({
+                db: { qi: (s) => s, dialectName: 'postgres' },
+                qiCol: () => '""',
+            });
+            out[name] = shortType(stub.type);
+        }
+        catch {
+            out[name] = 'any';
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+export function tableOperations(tableConf) {
+    const requested = tableConf.operations ?? ALL_OPERATIONS;
+    if (!isCompositePrimary(tableConf.primary))
+        return [...requested];
+    return requested.filter((op) => !SINGLE_PK_OPERATIONS.has(op));
+}
+/**
+ * Build the machine-readable description of every table exposed by this deployment:
+ * fields (type/required/nullable), enabled operations, join aliases, computed fields,
+ * extra filters, tenant scoping. Derived entirely from `DbTables`, so it is always in
+ * sync with the running configuration. Pairs with AGENTS_FRONTEND.md (the request grammar)
+ * to give an LLM client everything it needs to drive the API.
+ */
+export function buildAgentManifest(dbTables) {
+    const tables = {};
+    for (const [key, tableConf] of Object.entries(dbTables)) {
+        const schema = tableConf.Schema;
+        const required = new Set((schema.validation.required) ?? []);
+        const readExcluded = new Set(tableConf.readExclude ?? []);
+        const fields = {};
+        for (const [name, fieldSchema] of Object.entries(schema.fields)) {
+            const f = { type: shortType(fieldSchema) };
+            if (required.has(name))
+                f.required = true;
+            if (isNullable(fieldSchema))
+                f.nullable = true;
+            if (readExcluded.has(name))
+                f.writeOnly = true;
+            fields[name] = f;
+        }
+        const readJoins = (tableConf.allowedReadJoins ?? []).map((j) => ({
+            alias: j.alias,
+            table: j.joinSchema.tableName,
+            kind: j.unique ? 'N:1' : '1:N',
+        }));
+        const writeJoins = (tableConf.allowedWriteJoins ?? []).map((j) => ({
+            alias: j.alias,
+            table: j.joinSchema.tableName,
+            kind: j.unique ? 'N:1' : '1:N',
+        }));
+        const extraFilters = Object.keys(tableConf.extraFilters ?? {}).length
+            ? Object.fromEntries(Object.entries(tableConf.extraFilters).map(([n, s]) => [n, shortType(s)]))
+            : undefined;
+        const entry = {
+            table: schema.tableName,
+            primary: tableConf.primary,
+            operations: tableOperations(tableConf),
+            fields,
+        };
+        if (tableConf.excludeFromCreation?.length)
+            entry.serverGenerated = [...tableConf.excludeFromCreation];
+        const computed = computedTypes(tableConf);
+        if (computed)
+            entry.computed = computed;
+        if (extraFilters)
+            entry.extraFilters = extraFilters;
+        if (readJoins.length)
+            entry.readJoins = readJoins;
+        if (writeJoins.length)
+            entry.writeJoins = writeJoins;
+        if (tableConf.tenantScope)
+            entry.tenantScoped = true;
+        if (tableConf.defaultOrder)
+            entry.defaultOrder = tableConf.defaultOrder;
+        tables[key] = entry;
+    }
+    return { tables };
+}
+/**
+ * Compact markdown rendering of the manifest, designed for an LLM system prompt.
+ * Notation: `!` required on insert, `?` nullable, `(writeOnly)` never returned by reads.
+ */
+export function renderAgentManifestMd(manifest) {
+    const lines = [
+        '# Tables',
+        '',
+        'Notation: `!`=required on insert, `?`=nullable, `(writeOnly)`=writable, never in reads.',
+        'serverGenerated fields: omit on insert (values from client are ignored).',
+        'readJoins aliases: `1:N` → joinMustExist/joinMultiple/joinGroup; `N:1` → joinLeft.',
+        'writeJoins aliases: keys for `secondaries`/`deletions` in writes.',
+        '',
+    ];
+    for (const t of Object.values(manifest.tables)) {
+        const pk = Array.isArray(t.primary) ? t.primary.join('+') : t.primary;
+        const flags = t.tenantScoped ? '  [tenant-scoped]' : '';
+        lines.push(`## ${t.table}  PK:${pk}  ops:${t.operations.join(',')}${flags}`);
+        const fieldParts = Object.entries(t.fields).map(([name, f]) => {
+            let s = `${name}:${f.type}`;
+            if (f.required)
+                s += '!';
+            if (f.nullable)
+                s += '?';
+            if (f.writeOnly)
+                s += '(writeOnly)';
+            return s;
+        });
+        lines.push(`fields: ${fieldParts.join(', ')}`);
+        if (t.serverGenerated)
+            lines.push(`serverGenerated: ${t.serverGenerated.join(', ')}`);
+        if (t.computed) {
+            lines.push(`computed: ${Object.entries(t.computed).map(([n, ty]) => `${n}:${ty}`).join(', ')}`);
+        }
+        if (t.extraFilters) {
+            lines.push(`extraFilters: ${Object.entries(t.extraFilters).map(([n, ty]) => `${n}:${ty}`).join(', ')}`);
+        }
+        if (t.readJoins) {
+            lines.push(`readJoins: ${t.readJoins.map((j) => `${j.alias}→${j.table}(${j.kind})`).join(', ')}`);
+        }
+        if (t.writeJoins) {
+            lines.push(`writeJoins: ${t.writeJoins.map((j) => `${j.alias}→${j.table}`).join(', ')}`);
+        }
+        if (t.defaultOrder)
+            lines.push(`defaultOrder: ${t.defaultOrder}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/lib/agent/tool-schemas.d.ts

@@ -0,0 +1,36 @@
+import type { DbTables } from '../../types.js';
+export interface AgentToolSchemas {
+    /** POST /search/{table}: `body` + `querystring` (orderBy/page/itemsPerPage/compute*). */
+    search?: {
+        body: object;
+        querystring: object;
+    };
+    insert?: {
+        body: object;
+    };
+    update?: {
+        body: object;
+    };
+    bulkUpsert?: {
+        body: object;
+    };
+    bulkDelete?: {
+        body: object;
+    };
+}
+/**
+ * Ready-to-use JSON Schemas for exposing a table's operations as strict LLM tools —
+ * the same TypeBox schemas the HTTP routes validate with (TypeBox objects ARE plain
+ * JSON Schema). Only the operations actually enabled for the table are included
+ * (`operations` whitelist, composite-PK rules). `get` and `delete` take a single PK
+ * path param and need no schema.
+ *
+ * Strict tools trade prompt size for provider-side validation; the lighter
+ * alternative is a loose tool plus the plugin's structured 400 as the retry signal
+ * (see "LLM / agent clients" in the README).
+ */
+export declare function agentToolSchemas(dbTables: DbTables, tableName: string, opts?: {
+    maxItemsPerPage?: number;
+    maxBulkItems?: number;
+}): AgentToolSchemas;
+//# sourceMappingURL=tool-schemas.d.ts.map

package/dist/lib/agent/tool-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/tool-schemas.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD,gBAAgB,CA6BlB"}