fastify-auto-sqlapi 0.1.14 → 0.2.0

package/AGENTS_BACKEND.md

@@ -462,7 +462,7 @@ export const TableCustomer = defineTable({
 
 ## Computed Fields (extension system)
 
-`computedFields` lets you declare **virtual fields** as SQL expressions on a per-table basis. Each computed becomes usable like a regular schema field across the search API: `filters` (equality), `conditions` (operators), `orderBy` (1-parte), `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main response. Same machinery serves JSON column extraction, derived strings, dialect-aware date/calendar bucketing — without growing the library case-by-case.
+`computedFields` lets you declare **virtual fields** as SQL expressions on a per-table basis. Each computed becomes usable like a regular schema field across the search API: `filters` (equality), `conditions` (operators), `orderBy` (1-part), `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main response. Same machinery serves JSON column extraction, derived strings, dialect-aware date/calendar bucketing — without growing the library case-by-case.
 
 ```typescript
 import { defineTable, exportTableInfo, Type } from 'fastify-auto-sqlapi';
@@ -546,7 +546,7 @@ For `joinLeft` specifically, the computed expr is automatically alias-prefixed b
 
 - **Bound `values` in computed expressions** work anywhere the expression lands in the `WHERE` clause or in `ORDER BY`: `filters` and `conditions` (main, `joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) and `orderBy`. The ConditionBuilder assigns the placeholder positions there, so no coordination is needed from the caller.
 - They are still rejected with 400 on `selectComputed`, `computeMin/Max/Sum/Avg`, `joinGroup.aggregations.by` and `defaultOrder`. Those expressions are emitted in the `SELECT` / `GROUP BY` list, which precedes the `WHERE` values in the parameter order — there is no correct position for them there. Most use cases (JSON extraction, concat, dateTrunc, simple ops) need no bound values at all.
-- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400 — it is emitted in the `SELECT`/`GROUP BY` list). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-parti aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
+- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400 — it is emitted in the `SELECT`/`GROUP BY` list). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-part aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
 - **Computed cannot be used as aggregation function** (`sum`/`min`/`max`/...). The values inside `aggregations.sum: ['<name>']` must be schema field names. To aggregate on a derived expression, declare the derivation as a computed and pass the computed name as the field, BUT only via `computeMin/Max/Sum/Avg` (top-level main aggregates), not the joinGroup ones.
 - **No chained computed** (a computed referencing another computed). Flat-only.
 - **Read-only**. Computed fields are not usable in insert/update bodies — the consumer's `expr` is for SELECT/WHERE/ORDER BY, never for writes.
@@ -635,8 +635,8 @@ const sqlApi = createSqlApi(db, dbTables, { dialect: 'mysql' });
 ```typescript
 // Search — full filter, join, pagination, aggregation support
 // orderBy supports two dotted notations:
-//   - 3-parti `<alias>.<fn>.<field>` for joinGroup aggregations (must be declared in the request body)
-//   - 2-parti `<alias>.<field>` for joinLeft parent fields
+//   - 3-part `<alias>.<fn>.<field>` for joinGroup aggregations (must be declared in the request body)
+//   - 2-part `<alias>.<field>` for joinLeft parent fields
 // See AGENTS_FRONTEND.md and BREAKING_CHANGES.md for the full reference.
 sqlApi.search(tableName, {
   filters?, conditions?,

package/BREAKING_CHANGES.md

@@ -144,7 +144,7 @@ Real `LEFT JOIN` for N:1 (parent) relationships. The parent rows are returned in
 
 The engine attaches a real `LEFT JOIN <parentTable> AS <alias>` to the main query **only when needed**:
 - when the request includes `filters` or `conditions` on the parent (effectively turns into INNER JOIN behavior on those aliases — main rows whose parent doesn't match are excluded);
-- when `orderBy` uses 2-parti dotted notation referring to a parent field (`alias.field`).
+- when `orderBy` uses 2-part dotted notation referring to a parent field (`alias.field`).
 
 Otherwise only a side query `WHERE pk IN (distinct fk values)` is issued — no LEFT JOIN, no row duplication. Either way, the response shape is the same.
 
@@ -158,7 +158,7 @@ Otherwise only a side query `WHERE pk IN (distinct fk values)` is issued — no
 | `<alias>.<field>` | `joinLeft` (`unique: true` aliases) | orders main query by a parent field via LEFT JOIN |
 | `<alias>.<fn>.<field>` | `joinGroup` (declared in the same body) | orders main query by an aggregation via correlated scalar subquery |
 
-Ambiguity: 2-parti and 3-parti are disambiguated by counting dots. The 2-parti is rejected unless the alias is in `joinLeft` allowlist; 3-parti is rejected unless the alias is in the request `joinGroup` declaration.
+Ambiguity: 2-part and 3-part are disambiguated by counting dots. The 2-part is rejected unless the alias is in `joinLeft` allowlist; 3-part is rejected unless the alias is in the request `joinGroup` declaration.
 
 ## Response shape
 
@@ -248,7 +248,7 @@ If you used the join table's name as the secondaries key, change it to the new a
 
 `<table>.<fn>.<field>` still works for joinGroup, but `<table>` must now be the alias declared in `buildRelation`. If the alias differs from the old `tableName`, update the string.
 
-If you need to order by a parent field, **add a `joinLeft`-eligible relation** (with `unique: true`) and use 2-parti notation `alias.field` (NEW capability — not available before).
+If you need to order by a parent field, **add a `joinLeft`-eligible relation** (with `unique: true`) and use 2-part notation `alias.field` (NEW capability — not available before).
 
 ## Validation summary (400 responses)
 
@@ -257,8 +257,8 @@ The engine rejects, with `statusCode: 400`, any of:
 - `joinLeft` referencing an alias declared with `unique: false`
 - `joinMultiple`/`joinMustExist`/`joinGroup` referencing an alias declared with `unique: true`
 - request keys referencing an alias not declared in `allowedReadJoins`
-- `orderBy` 2-parti `<alias>.<field>` whose alias is not in `joinLeft`-eligible (i.e. `unique:true`) declarations
-- `orderBy` 3-parti `<alias>.<fn>.<field>` whose alias or `(fn, field)` pair is not declared in `joinGroup` for the same request
+- `orderBy` 2-part `<alias>.<field>` whose alias is not in `joinLeft`-eligible (i.e. `unique:true`) declarations
+- `orderBy` 3-part `<alias>.<fn>.<field>` whose alias or `(fn, field)` pair is not declared in `joinGroup` for the same request
 - `defineTable` with two `allowedReadJoins`/`allowedWriteJoins` entries resolving to the same alias (thrown at startup, not at request time)
 
 ---

package/README.md

@@ -590,7 +590,7 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 - **`joinMustExist`** — EXISTS-based filter: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Aliases must come from `allowedReadJoins` declarations with `unique: false`.
 - **`joinMultiple`** — fetches related child rows in a side query. Accepts `{ filters, conditions, selection }`. Same `unique: false` aliases.
 - **`joinGroup`** — aggregations on the related table. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY (a schema field name or a computed-field name declared on the join table — e.g. for date bucketing declare a computed using `db.dateTrunc('month', qiCol('orderDate'))`). Accepts `{ filters, conditions }`. Same `unique: false` aliases.
-- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`. Its `filters` accept schema and computed fields only: the parent's `extraFilters` need an alias-aware `extendedCondition`, so they are rejected with a `400` here instead of being silently ignored — use `joinMustExist` on the same relation when you need one.
+- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-part `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`. Its `filters` accept schema and computed fields only: the parent's `extraFilters` need an alias-aware `extendedCondition`, so they are rejected with a `400` here instead of being silently ignored — use `joinMustExist` on the same relation when you need one.
 
 **Dot-notation in `orderBy` and `conditions`**:
 

package/dist/bin/generate-schema.js

@@ -6,6 +6,83 @@ import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspec
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
 import { applyExcludeTables, buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
 import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, parseArgs, runCli } from './utils.js';
+const STATUS_COLOR = {
+    created: CONSOLE_COLORS.green,
+    updated: CONSOLE_COLORS.cyan,
+    untouched: CONSOLE_COLORS.gray,
+};
+function introspect(dialect, schema) {
+    if (dialect === 'mysql' || dialect === 'mariadb') {
+        const connConfig = buildMysqlConnectionConfig();
+        return introspectMysqlTables(connConfig, connConfig.database);
+    }
+    return introspectTables(buildConnectionString(), schema);
+}
+/** Narrow the map to the `--tables` selection. Returns false when nothing matched. */
+function keepOnlyRequestedTables(tableMap, tableNames) {
+    if (!tableNames.length)
+        return true;
+    for (const schemaName of Object.keys(tableMap)) {
+        if (!tableNames.includes(tableMap[schemaName].name)) {
+            delete tableMap[schemaName];
+        }
+    }
+    return Object.keys(tableMap).length > 0;
+}
+function fileStatus(filename, content) {
+    if (!fs.existsSync(filename))
+        return 'created';
+    return fs.readFileSync(filename, 'utf-8') === content ? 'untouched' : 'updated';
+}
+function writeSchemaFiles(tableMap, schemasDir) {
+    const report = { created: false, touched: false, untouched: 0, files: new Set() };
+    for (const schemaName of Object.keys(tableMap)) {
+        const { name: tableName, fields, colMap, primary } = tableMap[schemaName];
+        const filename = path.join(schemasDir, `${schemaName}.ts`);
+        report.files.add(`${schemaName}.ts`);
+        const content = generateSchemaFile(schemaName, tableName, fields, colMap, primary);
+        const status = fileStatus(filename, content);
+        if (status === 'created')
+            report.created = true;
+        if (status === 'untouched') {
+            report.untouched++;
+            continue;
+        }
+        fs.writeFileSync(filename, content);
+        displayAsTableRow(filename, status, 90, STATUS_COLOR[status]);
+        report.touched = true;
+    }
+    return report;
+}
+/**
+ * Delete `Schema*.ts` files no longer backed by a table — including the ones whose table
+ * was just excluded by config. Only safe when generating every table: with `--tables` the
+ * unlisted schemas are legitimately absent from `generated`.
+ */
+function removeOrphanSchemas(schemasDir, generated) {
+    let removed = false;
+    for (const file of fs.readdirSync(schemasDir)) {
+        if (file.startsWith('Schema') && file.endsWith('.ts') && !generated.has(file)) {
+            const filePath = path.join(schemasDir, file);
+            fs.unlinkSync(filePath);
+            displayAsTableRow(filePath, 'removed', 90, CONSOLE_COLORS.red);
+            removed = true;
+        }
+    }
+    return removed;
+}
+function reportOutcome(report) {
+    console.log('');
+    if (report.untouched > 0) {
+        display(`${report.untouched} schema(s) untouched`, CONSOLE_COLORS.gray);
+    }
+    if (report.created) {
+        display("Don't forget to git add your new Schema files.", CONSOLE_COLORS.magenta);
+    }
+    if (!report.touched) {
+        display('All schemas are already up to date.', CONSOLE_COLORS.magenta);
+    }
+}
 await runCli('fastify-auto-sqlapi: generating schemas', async () => {
     const cliArgs = parseArgs({
         output: { type: 'value' },
@@ -15,99 +92,34 @@ await runCli('fastify-auto-sqlapi: generating schemas', async () => {
     const config = await loadConfig();
     loadEnvFile(config.envFile);
     const dialect = (cliArgs.dialect || config.dialect || 'postgres');
-    const schema = config.schema || (dialect === 'postgres' ? 'public' : config.schema || 'public');
+    const schema = config.schema || 'public';
     const outputDir = path.resolve(process.cwd(), cliArgs.output || config.outputDir);
     const schemasDir = path.join(outputDir, 'schemas');
     if (!fs.existsSync(schemasDir)) {
         fs.mkdirSync(schemasDir, { recursive: true });
         display(`Created directory: ${schemasDir}`, CONSOLE_COLORS.green);
     }
-    let rows;
-    if (dialect === 'mysql' || dialect === 'mariadb') {
-        const connConfig = buildMysqlConnectionConfig();
-        rows = await introspectMysqlTables(connConfig, connConfig.database);
-    }
-    else {
-        const connectionString = buildConnectionString();
-        rows = await introspectTables(connectionString, schema);
-    }
+    const rows = await introspect(dialect, schema);
     if (rows.length === 0) {
         display(`No tables found in schema "${schema}".`, CONSOLE_COLORS.magenta);
         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.
+    // Config blacklist: excluded tables are invisible to the generator, so their schema files
+    // (if any) fall through to the orphan cleanup below. Deliberately no early return when
+    // everything is excluded — that cleanup still has to run.
     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) {
-        for (const schemaName of Object.keys(tableMap)) {
-            if (!tableNames.includes(tableMap[schemaName].name)) {
-                delete tableMap[schemaName];
-            }
-        }
-        if (Object.keys(tableMap).length === 0) {
-            display(`No matching tables found for: ${tableNames.join(', ')}`, CONSOLE_COLORS.magenta);
-            return;
-        }
-    }
-    let somethingCreated = false;
-    let somethingTouched = false;
-    let untouched = 0;
-    const generatedFiles = new Set();
-    for (const schemaName of Object.keys(tableMap)) {
-        const { name: tableName, fields, colMap, primary } = tableMap[schemaName];
-        const filename = path.join(schemasDir, `${schemaName}.ts`);
-        generatedFiles.add(`${schemaName}.ts`);
-        const content = generateSchemaFile(schemaName, tableName, fields, colMap, primary);
-        let status = 'created';
-        let color = CONSOLE_COLORS.green;
-        if (fs.existsSync(filename)) {
-            status = 'untouched';
-            color = CONSOLE_COLORS.gray;
-            if (fs.readFileSync(filename, 'utf-8') !== content) {
-                status = 'updated';
-                color = CONSOLE_COLORS.cyan;
-            }
-        }
-        else {
-            somethingCreated = true;
-        }
-        if (status !== 'untouched') {
-            fs.writeFileSync(filename, content);
-            displayAsTableRow(filename, status, 90, color);
-            somethingTouched = true;
-        }
-        else {
-            untouched++;
-        }
-    }
-    // Remove orphan Schema*.ts files (only when generating all tables)
-    if (!tableNames.length) {
-        const existingFiles = fs.readdirSync(schemasDir);
-        for (const file of existingFiles) {
-            if (file.startsWith('Schema') && file.endsWith('.ts') && !generatedFiles.has(file)) {
-                const filePath = path.join(schemasDir, file);
-                fs.unlinkSync(filePath);
-                displayAsTableRow(filePath, 'removed', 90, CONSOLE_COLORS.red);
-                somethingTouched = true;
-            }
-        }
-    }
-    console.log('');
-    if (untouched > 0) {
-        display(`${untouched} schema(s) untouched`, CONSOLE_COLORS.gray);
-    }
-    if (somethingCreated) {
-        display("Don't forget to git add your new Schema files.", CONSOLE_COLORS.magenta);
+    if (!keepOnlyRequestedTables(tableMap, tableNames)) {
+        display(`No matching tables found for: ${tableNames.join(', ')}`, CONSOLE_COLORS.magenta);
+        return;
     }
-    if (!somethingTouched) {
-        display('All schemas are already up to date.', CONSOLE_COLORS.magenta);
+    const report = writeSchemaFiles(tableMap, schemasDir);
+    if (!tableNames.length && removeOrphanSchemas(schemasDir, report.files)) {
+        report.touched = true;
     }
+    reportOutcome(report);
 });

package/dist/bin/generate-tables.js

@@ -22,6 +22,74 @@ function printHelp() {
     display('Table*.ts files are only created if they do not already exist.', CONSOLE_COLORS.magenta);
     display('dbTables.ts is created if missing, indexing the Table*.ts files present on disk.', CONSOLE_COLORS.magenta);
 }
+const tableVarOf = (schema) => 'Table' + schema.schemaName.replace(/^Schema/, '');
+/** Parse every Schema*.ts on disk — relation detection needs them all, even for a subset run. */
+function parseAllSchemas(schemasDir, schemaFiles) {
+    const parsed = [];
+    for (const file of schemaFiles) {
+        const content = fs.readFileSync(path.join(schemasDir, file), 'utf-8');
+        const schema = parseSchemaFile(content);
+        if (schema)
+            parsed.push(schema);
+    }
+    return parsed;
+}
+/** The schemas to emit Table files for. Exits when a requested name has no schema. */
+function selectTargetSchemas(allSchemas, all, requested) {
+    if (all)
+        return allSchemas;
+    const requestedSet = new Set(requested);
+    const targets = allSchemas.filter((s) => requestedSet.has(s.tableName));
+    const foundNames = new Set(targets.map((s) => s.tableName));
+    for (const name of requestedSet) {
+        if (!foundNames.has(name)) {
+            error(`Table "${name}" not found. Available: ${allSchemas.map((s) => s.tableName).join(', ')}`);
+            process.exit(1);
+        }
+    }
+    return targets;
+}
+/** Write the missing Table*.ts files. Existing ones are never overwritten. */
+function writeTableFiles(targetSchemas, allSchemas, tablesDir) {
+    const created = [];
+    for (const schema of targetSchemas) {
+        const tableVarName = tableVarOf(schema);
+        const tableFile = path.join(tablesDir, `${tableVarName}.ts`);
+        if (fs.existsSync(tableFile)) {
+            displayAsTableRow(`${tableVarName}.ts`, 'skipped (already exists)', 60, CONSOLE_COLORS.gray);
+            continue;
+        }
+        fs.writeFileSync(tableFile, generateSingleTableFile(schema, allSchemas));
+        created.push(tableVarName);
+        displayAsTableRow(`${tableVarName}.ts`, 'created', 60, CONSOLE_COLORS.green);
+    }
+    return created;
+}
+/**
+ * Write `dbTables.ts` only when missing. The index must reference only the Table*.ts files
+ * actually on disk: a subset run would otherwise emit imports for files never generated,
+ * and the consumer's project would not compile. When it already exists, the newly created
+ * tables are reported instead of being silently left out.
+ */
+function writeDbTablesIndex(tablesDir, allSchemas, createdTableVars) {
+    const dbTablesFile = path.join(tablesDir, 'dbTables.ts');
+    if (!fs.existsSync(dbTablesFile)) {
+        const existingTableVars = new Set(fs
+            .readdirSync(tablesDir)
+            .filter((f) => f.startsWith('Table') && f.endsWith('.ts'))
+            .map((f) => f.slice(0, -'.ts'.length)));
+        const indexSchemas = allSchemas.filter((s) => existingTableVars.has(tableVarOf(s)));
+        fs.writeFileSync(dbTablesFile, generateDbTablesIndex(indexSchemas));
+        displayAsTableRow('dbTables.ts', 'created', 60, CONSOLE_COLORS.green);
+        return;
+    }
+    displayAsTableRow('dbTables.ts', 'skipped (already exists)', 60, CONSOLE_COLORS.gray);
+    const indexContent = fs.readFileSync(dbTablesFile, 'utf-8');
+    const missing = createdTableVars.filter((v) => !indexContent.includes(v));
+    if (missing.length > 0) {
+        display(`Remember to add the new tables to dbTables.ts: ${missing.join(', ')}`, CONSOLE_COLORS.yellow);
+    }
+}
 await runCli('fastify-auto-sqlapi: generating tables template', async () => {
     const cliArgs = parseArgs({
         output: { type: 'value' },
@@ -55,72 +123,14 @@ await runCli('fastify-auto-sqlapi: generating tables template', async () => {
         display('Run sqlapi-generate-schema first.', CONSOLE_COLORS.magenta);
         process.exit(1);
     }
-    // Parse all schemas (needed for relation detection even when generating a subset)
-    const allSchemas = [];
-    for (const file of schemaFiles) {
-        const content = fs.readFileSync(path.join(schemasDir, file), 'utf-8');
-        const parsed = parseSchemaFile(content);
-        if (parsed) {
-            allSchemas.push(parsed);
-        }
-    }
+    const allSchemas = parseAllSchemas(schemasDir, schemaFiles);
     if (allSchemas.length === 0) {
         error('No valid schemas parsed.');
         process.exit(1);
     }
-    // Determine which schemas to generate Table files for
-    let targetSchemas;
-    if (cliArgs.all) {
-        targetSchemas = allSchemas;
-    }
-    else {
-        const requestedSet = new Set(cliArgs.tables);
-        targetSchemas = allSchemas.filter((s) => requestedSet.has(s.tableName));
-        const foundNames = new Set(targetSchemas.map((s) => s.tableName));
-        for (const name of requestedSet) {
-            if (!foundNames.has(name)) {
-                error(`Table "${name}" not found. Available: ${allSchemas.map((s) => s.tableName).join(', ')}`);
-                process.exit(1);
-            }
-        }
-    }
-    const tableVarOf = (schema) => 'Table' + schema.schemaName.replace(/^Schema/, '');
-    // Generate individual Table*.ts files (skip if already exists)
-    const createdTableVars = [];
-    for (const schema of targetSchemas) {
-        const tableVarName = tableVarOf(schema);
-        const tableFile = path.join(tablesDir, `${tableVarName}.ts`);
-        if (fs.existsSync(tableFile)) {
-            displayAsTableRow(`${tableVarName}.ts`, 'skipped (already exists)', 60, CONSOLE_COLORS.gray);
-        }
-        else {
-            const content = generateSingleTableFile(schema, allSchemas);
-            fs.writeFileSync(tableFile, content);
-            createdTableVars.push(tableVarName);
-            displayAsTableRow(`${tableVarName}.ts`, 'created', 60, CONSOLE_COLORS.green);
-        }
-    }
-    // Generate dbTables.ts only if it does not exist. The index must reference only
-    // Table*.ts files actually present on disk, otherwise a subset run would emit
-    // imports for files that were never generated and the project would not compile.
-    const dbTablesFile = path.join(tablesDir, 'dbTables.ts');
-    if (fs.existsSync(dbTablesFile)) {
-        displayAsTableRow('dbTables.ts', 'skipped (already exists)', 60, CONSOLE_COLORS.gray);
-        const indexContent = fs.readFileSync(dbTablesFile, 'utf-8');
-        const missing = createdTableVars.filter((v) => !indexContent.includes(v));
-        if (missing.length > 0) {
-            display(`Remember to add the new tables to dbTables.ts: ${missing.join(', ')}`, CONSOLE_COLORS.yellow);
-        }
-    }
-    else {
-        const existingTableVars = new Set(fs
-            .readdirSync(tablesDir)
-            .filter((f) => f.startsWith('Table') && f.endsWith('.ts'))
-            .map((f) => f.slice(0, -'.ts'.length)));
-        const indexSchemas = allSchemas.filter((s) => existingTableVars.has(tableVarOf(s)));
-        fs.writeFileSync(dbTablesFile, generateDbTablesIndex(indexSchemas));
-        displayAsTableRow('dbTables.ts', 'created', 60, CONSOLE_COLORS.green);
-    }
+    const targetSchemas = selectTargetSchemas(allSchemas, cliArgs.all, cliArgs.tables);
+    const createdTableVars = writeTableFiles(targetSchemas, allSchemas, tablesDir);
+    writeDbTablesIndex(tablesDir, allSchemas, createdTableVars);
     console.log('');
     display('Edit the generated Table*.ts files to customize your table configuration.', CONSOLE_COLORS.magenta);
 });

package/dist/bin/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/bin/utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAqBlD;AAED,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAU,GAChB,IAAI,CAQN;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,IAAI,CAE7D;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExC;AAED,KAAK,OAAO,GACR;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,KAAK,QAAQ,CAAC,CAAC,SAAS,OAAO,IAC7B,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,OAAO,GAClC,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,GACnC,MAAM,GAAG,SAAS,CAAC;AAErB;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EACP,IAAI,WAAwB,GAC3B;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAyC/D;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/bin/utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAqBlD;AAED,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAU,GAChB,IAAI,CAQN;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,IAAI,CAE7D;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExC;AAED,KAAK,OAAO,GACR;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,KAAK,QAAQ,CAAC,CAAC,SAAS,OAAO,IAC7B,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,OAAO,GAClC,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,GACnC,MAAM,GAAG,SAAS,CAAC;AAErB;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EACP,IAAI,WAAwB,GAC3B;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAmB/D;AAqDD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}

package/dist/bin/utils.js

@@ -62,51 +62,65 @@ export function error(text) {
  * (split on ',') into the list as well, supporting both "a b" and "a,b" CLI shapes.
  */
 export function parseArgs(spec, argv = process.argv.slice(2)) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const out = { positional: [] };
     for (const [name, def] of Object.entries(spec)) {
         out[name] = def.type === 'flag' ? false : def.type === 'list' ? [] : undefined;
     }
-    for (let i = 0; i < argv.length; i++) {
+    let i = 0;
+    while (i < argv.length) {
         const token = argv[i];
         if (token.startsWith('--')) {
-            const name = token.slice(2);
-            const def = spec[name];
-            if (!def)
-                continue;
-            if (def.type === 'flag') {
-                out[name] = true;
-            }
-            else if (def.type === 'value' && i + 1 < argv.length) {
-                out[name] = argv[++i];
-            }
-            else if (def.type === 'list' && i + 1 < argv.length) {
-                const next = argv[++i];
-                for (const part of next.split(',')) {
-                    const t = part.trim();
-                    if (t)
-                        out[name].push(t);
-                }
-            }
+            // An option may consume the following entry as its value.
+            i += 1 + readOption(out, spec, argv, i);
         }
         else {
-            out.positional.push(token);
-            // Auto-distribute positional values into the (single) list spec, if any
-            for (const [n, def] of Object.entries(spec)) {
-                if (def.type === 'list') {
-                    for (const part of token.split(',')) {
-                        const t = part.trim();
-                        if (t)
-                            out[n].push(t);
-                    }
-                    break;
-                }
-            }
+            readPositional(out, spec, token);
+            i += 1;
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return out;
 }
+/** Split on ',' and append the non-empty tokens. */
+function pushCsv(target, raw) {
+    for (const part of raw.split(',')) {
+        const t = part.trim();
+        if (t)
+            target.push(t);
+    }
+}
+/**
+ * Read one `--name [value]` option at `i`. Returns how many *extra* argv entries it
+ * consumed (1 when it took the next entry as its value, 0 otherwise).
+ */
+function readOption(out, spec, argv, i) {
+    const name = argv[i].slice(2);
+    const def = spec[name];
+    if (!def)
+        return 0;
+    const hasNext = i + 1 < argv.length;
+    if (def.type === 'flag') {
+        out[name] = true;
+    }
+    else if (def.type === 'value' && hasNext) {
+        out[name] = argv[i + 1];
+        return 1;
+    }
+    else if (def.type === 'list' && hasNext) {
+        pushCsv(out[name], argv[i + 1]);
+        return 1;
+    }
+    return 0;
+}
+/** A positional token also feeds the (single) list spec, so `a b` and `a,b` both work. */
+function readPositional(out, spec, token) {
+    out.positional.push(token);
+    for (const [name, def] of Object.entries(spec)) {
+        if (def.type === 'list') {
+            pushCsv(out[name], token);
+            break;
+        }
+    }
+}
 /**
  * CLI entry-point wrapper: prints a header, awaits `fn`, and turns thrown errors into a red message
  * with a non-zero exit code (without aborting the process synchronously, so unfinished stdout flushes).

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

@@ -1,5 +1,5 @@
 import type { DbTables, ITable, TableOperation } from '../../types.js';
-export interface ManifestField {
+interface ManifestField {
     type: string;
     /** Present (true) when the field must be sent on insert. */
     required?: boolean;
@@ -8,7 +8,7 @@ export interface ManifestField {
     /** Present (true) when the field is writable but never returned by reads (readExclude). */
     writeOnly?: boolean;
 }
-export interface ManifestJoin {
+interface ManifestJoin {
     alias: string;
     table: string;
     /** '1:N' → usable in joinMustExist/joinMultiple/joinGroup; 'N:1' → usable in joinLeft. */
@@ -50,4 +50,5 @@ export declare function buildAgentManifest(dbTables: DbTables): AgentManifest;
  * Notation: `!` required on insert, `?` nullable, `(writeOnly)` never returned by reads.
  */
 export declare function renderAgentManifestMd(manifest: AgentManifest): string;
+export {};
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -1 +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,CA6CrE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAkB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvF,UAAU,aAAa;IACrB,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,UAAU,YAAY;IACpB,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;AA0DD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAMpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAkBrE"}