fastify-auto-sqlapi 0.1.10 → 0.1.12

package/docs/adr/0007-explicit-table-generation.md

@@ -0,0 +1,39 @@
+# 0007. Table generation is explicit — `--all` is a migration helper, not the default
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+`sqlapi-generate-schema` with no arguments introspects every table, while
+`sqlapi-generate-tables` with no arguments prints usage and exits, requiring `--all` or
+explicit table names. A review flagged the opposite defaults as an inconsistency to
+harmonize.
+
+## Decision
+
+The asymmetry is deliberate and stays. The two generators have different roles:
+
+- **Schemas** are disposable mirrors of the database — regenerating all of them is always
+  correct, so "all" is the natural default.
+- **Table files are the consumer's working set**: which tables become API endpoints is a
+  deliberate choice, and it is legitimate to keep tables out of `DbTables`. The intended
+  flow is *"I added a table, I generate its Table file explicitly"*
+  (`sqlapi-generate-tables customer`). If the default were "all", every run would
+  resurrect Table files the consumer had deliberately deleted, forcing them to delete the
+  same files again and again. `--all` exists only as a bootstrap helper when introducing
+  the plugin into an existing codebase.
+
+## Alternatives considered
+
+- **Default to `--all` (mirror generate-schema)** — rejected: re-creates deleted Table
+  files on every run, fighting the consumer's curation of the exposed surface.
+- **Tracking deleted tables** (a skip-list) — rejected: state to maintain for a problem
+  explicit invocation solves for free.
+
+## Consequences
+
+- `sqlapi-generate-tables` keeps requiring `--all` or table names; running it bare prints
+  usage and exits non-zero.
+- The generator never overwrites existing Table files, so both the explicit and the
+  `--all` flow are safe to re-run.

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/README.md

@@ -21,6 +21,8 @@ not by editing history.
 | [0004](./0004-updates-always-open.md) | Updates are always open — no `excludeFromUpdate` |
 | [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 |
 
 ## When to write one
 

package/package.json

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