tina4-nodejs 3.13.92 → 3.13.95

package/packages/orm/src/index.ts

@@ -21,7 +21,9 @@ export {
   adapterTableExists, adapterTables, adapterColumns, adapterCreateTable,
   extractLastInsertId,
 } from "./database.js";
-export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
+export type { DatabaseConfig } from "./database.js";
+export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
+export type { DatabaseEngine } from "./databaseUrl.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";
 export {
@@ -54,6 +56,14 @@ export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export {
+  DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  CONNECT_TIMEOUT_TOLERANCE_MS,
+  connectTimeoutMillis,
+  driverConnectTimeoutMillis,
+  connectTarget,
+  withConnectTimeout,
+} from "./connectTimeout.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";
@@ -62,8 +72,8 @@ export type { SeedSummary, SeedOptions } from "./seeder.js";
 
 // DocStore — pymongo-style document store with a zero-config SQLite (JSON1) fallback
 export {
-  ObjectId, InvalidId, SqliteDatabase, SqliteCollection, Cursor,
-  getCollection, isServerless, resetDefaultStore,
+  ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor,
+  getCollection, isServerless, resetDefaultStore, closeDocStore,
   encodeValue, decodeValue, compileFilter,
 } from "./docstore.js";
 export type {

package/packages/orm/src/migration.ts

@@ -217,7 +217,14 @@ export async function syncModels(models: DiscoveredModel[]): Promise<void> {
       console.log(`    Created table: ${tableName}`);
     } else {
       // Check for new columns. SQLite exposes the legacy getTableColumns/
-      // addColumn helpers; other engines use columns()/ALTER TABLE.
+      // addColumn helpers; other engines use getColumns()/ALTER TABLE.
+      //
+      // Collapsing this into getColumns() looks obviously right and is NOT:
+      // it broke the legacy NOT NULL migration_id path, which is the bug that
+      // wedged every migration for ~20 releases (python#93). getTableColumns
+      // reads PRAGMA directly; getColumns goes through schema splitting and
+      // does not return the same thing here. Removing it needs its own change
+      // with that path tested, not a drive-by in an interface tidy-up.
       const existingCols = (adapter as any).getTableColumns
         ? (adapter as SQLiteAdapter).getTableColumns(tableName)
         : await adapterColumns(adapter, tableName);
@@ -508,8 +515,16 @@ async function recordApplied(
  */
 async function trackingColumns(db: DatabaseAdapter): Promise<Set<string>> {
   try {
-    // The DatabaseAdapter contract exposes columns(), not getColumns().
-    const cols = await (db as any).columns?.(MIGRATION_TABLE);
+    // The DatabaseAdapter contract exposes getColumns() (feature 3: renamed from
+    // columns() to match the other three frameworks and the get- prefix used
+    // everywhere else).
+    //
+    // This reads through `as any`, so the compiler could not catch the rename
+    // here - it went silently to undefined, `cols` came back empty, migration_id
+    // was left out of the insert and every migration failed on the legacy
+    // NOT NULL column. Exactly the failure python#93 caused, from the opposite
+    // direction. Kept optional-chained for adapters that predate the contract.
+    const cols = await (db as any).getColumns?.(MIGRATION_TABLE);
     if (!Array.isArray(cols)) return new Set();
     return new Set(
       cols.map((c: any) => String(c?.name ?? c ?? "").toLowerCase()).filter(Boolean),

package/packages/orm/src/queryBuilder.ts

@@ -19,6 +19,7 @@
 
 import type { DatabaseAdapter } from "./types.js";
 import { getAdapter, adapterFetch, adapterFetchOne } from "./database.js";
+import { DatabaseResult } from "./databaseResult.js";
 
 export class QueryBuilder {
   private table: string;
@@ -198,22 +199,55 @@ export class QueryBuilder {
   }
 
   /**
-   * Execute the query and return all matching rows.
+   * Execute the query and return a DatabaseResult.
    *
-   * @returns Array of row objects.
+   * BREAKING (3.13.95, parity): this returned a bare array of rows. The other
+   * three frameworks all return the DatabaseResult that `db.fetch()` produces:
+   *   Python  get() -> DatabaseResult   (orm/query_builder/__init__.py)
+   *   PHP     get(): mixed -> $this->db->fetch(...)
+   *   Ruby    get -> @db.fetch(...)
+   * Node was the odd one out, so the same builder chain returned a different
+   * TYPE per language and portable code could not read `.records`, `.count`,
+   * `.limit` or `.offset` off it.
+   *
+   * MIGRATION: read `.records` for the rows.
+   *   before: const rows = await qb.get();          rows.length
+   *   after:  const result = await qb.get();        result.records.length
+   * DatabaseResult is iterable, so `for (const row of result)` and
+   * `[...result]` work unchanged, and `response()`/`res.json()` already
+   * auto-serialize it to a JSON array.
+   *
+   * No default LIMIT is applied when `.limit()` was never called (v3.13.39) --
+   * a silent cap here was a data-loss-on-read footgun. That is unchanged.
+   *
+   * @returns DatabaseResult carrying `.records`, `.count`, `.limit`, `.offset`.
    */
-  async get<T = Record<string, unknown>>(): Promise<T[]> {
+  async get(): Promise<DatabaseResult> {
     this.ensureDb();
     const sql = this.toSql();
     const allParams = [...this.params, ...this.havingParams];
 
-    return adapterFetch<T>(
+    const rows = await adapterFetch(
       this.db!,
       sql,
       allParams.length > 0 ? allParams : undefined,
       this.limitVal,
       this.offsetVal,
     );
+
+    // Constructed exactly as Database._fetchWithLimit does, so a QueryBuilder
+    // result and a db.fetch() result are the same object in the same state --
+    // including leaving `count` to default to the row count and handing the
+    // adapter + sql through.
+    return new DatabaseResult(
+      rows as Record<string, unknown>[],
+      undefined,
+      undefined,
+      this.limitVal,
+      this.offsetVal,
+      this.db!,
+      sql,
+    );
   }
 
   /**

package/packages/orm/src/sqlTranslator.ts

@@ -19,6 +19,7 @@
 
 // ── SQL Translator ───────────────────────────────────────────
 
+import { DatabaseUrl } from "./databaseUrl.js";
 export class SQLTranslator {
   /**
    * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
@@ -172,6 +173,271 @@ export class SQLTranslator {
     if (idx === -1) return [null, name];
     return [name.slice(0, idx), name.slice(idx + 1)];
   }
+
+  /**
+   * Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
+   * Sourced from test/fixtures/batch_write_contract.json, byte-identical in all
+   * four frameworks.
+   */
+  static readonly MAX_BIND_PARAMS: Record<string, number> = {
+    sqlite: 999,
+    postgres: 65535,
+    mysql: 65535,
+    mssql: 2100,
+    firebird: 0,
+    odbc: 0,
+    mongodb: 0,
+  };
+
+  /**
+   * The four frameworks do not agree on what an engine calls itself — Python
+   * and PHP report "postgresql", Ruby and Node report "postgres". Without
+   * normalising, the cap lookup misses and the collapse silently does nothing
+   * on the engine with the largest win.
+   */
+  static readonly ENGINE_ALIASES: Record<string, string> = {
+    postgresql: "postgres",
+    pgsql: "postgres",
+    sqlite3: "sqlite",
+    sqlserver: "mssql",
+    sqlsrv: "mssql",
+    mariadb: "mysql",
+  };
+
+  // The `d` flag records group indices, so the head can be sliced at the exact
+  // start of the VALUES group rather than by hunting for a parenthesis (the
+  // column list has parentheses too).
+  private static readonly INSERT_VALUES =
+    /^\s*INSERT\s+INTO\s+.+?\s+VALUES\s*\(([^()]*)\)\s*$/dis;
+
+  /**
+   * Engines whose lastInsertId reports the FIRST generated id of a multi-row
+   * INSERT rather than the last. Verified live, not assumed: a 3-row insert
+   * into a fresh MySQL table reports 1 while MAX(id) is 3. SQLite, PostgreSQL
+   * and MSSQL already report the last, so collapsing does not change them.
+   */
+  static readonly FIRST_ID_ENGINES: readonly string[] = ["mysql"];
+
+  /**
+   * Normalise a collapsed batch's last id to the LAST row's id.
+   *
+   * A row-at-a-time batch reports the last row's id simply because the last
+   * statement inserted the last row. Collapsing rows into one statement changes
+   * that on any engine that reports the FIRST generated id, so this restores
+   * the contract instead of quietly redefining it. The ids in one statement are
+   * consecutive, so the last is `first + rows - 1`.
+   */
+  static batchLastId(reportedId: unknown, rowsInChunk: number, engine: string): unknown {
+    const lower = (engine ?? "").toLowerCase();
+    const name = SQLTranslator.ENGINE_ALIASES[lower] ?? lower;
+    if (!SQLTranslator.FIRST_ID_ENGINES.includes(name)) return reportedId;
+
+    const n = typeof reportedId === "bigint" ? Number(reportedId) : Number(reportedId);
+    if (reportedId === null || reportedId === undefined || Number.isNaN(n)) {
+      return reportedId;                    // UUID/ULID key — no successor
+    }
+    return n + Math.max(rowsInChunk, 1) - 1;
+  }
+
+  /**
+   * Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
+   *
+   * A batch that loops one INSERT per row pays a full network round-trip per
+   * row, and the round-trip — not SQL building — is the entire cost of a batch
+   * write. Measured over 500 rows: PostgreSQL 9848ms row-at-a-time against
+   * 15.8ms as a single multi-row statement (625x), MySQL 216x, MSSQL 121x.
+   *
+   * PURE: no I/O and no engine contact, so the chunking rules are checkable
+   * without a database. The live-engine runners prove the rows land.
+   *
+   * @returns Statements to run INSTEAD of the loop, or an EMPTY array meaning
+   *          "not collapsible — keep looping", which is always correct.
+   */
+  static buildBatchInserts(
+    sql: string,
+    paramSets: unknown[][],
+    engine: string,
+  ): Array<[string, unknown[]]> {
+    const rows = paramSets ?? [];
+    if (rows.length < 2) return [];
+
+    const lower = (engine ?? "").toLowerCase();
+    const name = SQLTranslator.ENGINE_ALIASES[lower] ?? lower;
+    const cap = SQLTranslator.MAX_BIND_PARAMS[name] ?? 0;
+    // Firebird has no multi-row VALUES syntax (verified against a live 5.0.4:
+    // -104 Token unknown); ODBC's real ceiling depends on the driver behind it.
+    // Emitting SQL the engine cannot parse to save a round-trip is not a trade
+    // worth making.
+    if (cap <= 0) return [];
+
+    const upper = sql.toUpperCase();
+    // A collapsed statement returns N rows where the caller expects one, and
+    // conflict arbitration changes once rows share a statement.
+    if (
+      upper.includes("RETURNING") ||
+      upper.includes("ON CONFLICT") ||
+      upper.includes("ON DUPLICATE KEY")
+    ) {
+      return [];
+    }
+
+    const match = SQLTranslator.INSERT_VALUES.exec(sql);
+    if (match === null) return [];
+
+    // Every slot must be a bare placeholder. `now()` repeated per row inside one
+    // statement is not the same write as `now()` evaluated per statement.
+    const slots = match[1].split(",").map((s) => s.trim());
+    if (slots.length === 0 || slots.some((s) => s !== "?")) return [];
+
+    const columns = slots.length;
+    if (rows.some((params) => params.length !== columns)) return [];
+
+    const chunkRows = Math.max(1, Math.floor(cap / columns));
+    if (chunkRows < 2) return [];
+
+    const valuesStart = match.indices?.[1]?.[0];
+    if (valuesStart === undefined) return [];
+    const head = sql.slice(0, valuesStart - 1).trimEnd();
+    const oneRow = `(${new Array(columns).fill("?").join(", ")})`;
+
+    const statements: Array<[string, unknown[]]> = [];
+    for (let start = 0; start < rows.length; start += chunkRows) {
+      const chunk = rows.slice(start, start + chunkRows);
+      const flat: unknown[] = [];
+      for (const params of chunk) flat.push(...params);
+      statements.push([`${head} ${new Array(chunk.length).fill(oneRow).join(", ")}`, flat]);
+    }
+    return statements;
+  }
+
+  /**
+   * Blank out string literals, quoted identifiers and comments, so a keyword
+   * search sees only real SQL. Blanks are spaces of the SAME LENGTH (newlines
+   * preserved), so offsets and line structure still line up with the original.
+   *
+   * This exists because "does the caller's SQL already have a LIMIT?" used to be
+   * `sql.toUpperCase().split("--")[0].includes("LIMIT")`, and MEASURED on a real
+   * 150-row table with the 100-row cap in force, every one of these returned
+   * ALL 150 ROWS instead of 100:
+   *
+   *     SELECT * FROM t WHERE label != 'LIMIT' ORDER BY id     -- literal
+   *     SELECT * FROM t ORDER BY id -- LIMIT 5                 -- line comment
+   *     SELECT * FROM t ORDER BY id /* LIMIT 5 *\/              -- block comment
+   *
+   * A column named `rate_limit` does it too. That is a silently UNCAPPED read of
+   * a whole table, which is the exact production incident the row cap exists to
+   * prevent, reachable through an ordinary column name.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   * @returns The same string with literals and comments replaced by spaces.
+   */
+  static scrubSqlText(sql: string): string {
+    let out = "";
+    let i = 0;
+    const blank = (ch: string): string => (ch === "\n" ? "\n" : " ");
+
+    while (i < sql.length) {
+      const c = sql[i];
+      const next = sql[i + 1];
+
+      // '...' string literal, with '' as the embedded-quote escape
+      if (c === "'" || c === '"') {
+        const quote = c;
+        out += " ";
+        i++;
+        while (i < sql.length) {
+          if (sql[i] === quote) {
+            if (sql[i + 1] === quote) {
+              out += "  ";
+              i += 2;
+              continue;
+            }
+            out += " ";
+            i++;
+            break;
+          }
+          out += blank(sql[i]);
+          i++;
+        }
+        continue;
+      }
+
+      // -- line comment, to end of line
+      if (c === "-" && next === "-") {
+        while (i < sql.length && sql[i] !== "\n") {
+          out += " ";
+          i++;
+        }
+        continue;
+      }
+
+      // /* block comment */
+      if (c === "/" && next === "*") {
+        out += "  ";
+        i += 2;
+        while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/")) {
+          out += blank(sql[i]);
+          i++;
+        }
+        if (i < sql.length) {
+          out += "  ";
+          i += 2;
+        }
+        continue;
+      }
+
+      out += c;
+      i++;
+    }
+
+    return out;
+  }
+
+  /**
+   * True when the statement ENDS with its own LIMIT clause, so appending another
+   * would be wrong (and on SQLite, a syntax error).
+   *
+   * Anchored to the END on purpose. A bare "contains LIMIT" test also matches a
+   * LIMIT inside a subquery, where the OUTER statement still needs its cap. This
+   * is tina4-php's `SqlNormalizerTrait::hasTrailingLimit` regex, ported verbatim
+   * so all four frameworks answer identically: it accepts a numeric value, `?`,
+   * `$1` and `:name` placeholders, MySQL's `LIMIT a, b`, and a trailing OFFSET.
+   *
+   * @param sql Raw SQL; literals and comments are scrubbed before matching.
+   */
+  static hasTrailingLimit(sql: string): boolean {
+    const val = String.raw`(?:\d+|\?|\$\d+|:\w+|%s)`;
+    const re = new RegExp(
+      String.raw`\bLIMIT\s+${val}(?:\s*,\s*${val})?(?:\s+OFFSET\s+${val})?\s*;?\s*$`,
+      "i",
+    );
+    return re.test(SQLTranslator.scrubSqlText(sql));
+  }
+
+  /**
+   * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
+   *
+   * The clause goes on a NEW LINE. Appending it inline is the second half of the
+   * same bug: `SELECT * FROM t -- note` + ` LIMIT 100` puts the clause INSIDE the
+   * trailing comment, where SQLite silently ignores it and the whole table comes
+   * back. A newline cannot be commented out by a `--` that started on the line
+   * above. Trailing semicolons are stripped first for the same reason
+   * (`SELECT * FROM t;` + `LIMIT 100` is a syntax error).
+   *
+   * @param sql    The caller's statement.
+   * @param limit  Row cap to apply; a non-positive value means "no cap".
+   * @param offset Rows to skip; omitted or 0 emits no OFFSET.
+   */
+  static appendLimit(sql: string, limit?: number, offset?: number): string {
+    if (limit === undefined || limit === null || limit <= 0) return sql;
+    if (SQLTranslator.hasTrailingLimit(sql)) return sql;
+
+    const trimmed = sql.replace(/[\s;]+$/, "");
+    const suffix = offset !== undefined && offset > 0
+      ? `LIMIT ${limit} OFFSET ${offset}`
+      : `LIMIT ${limit}`;
+    return `${trimmed}\n${suffix}`;
+  }
 }
 
 // ── Query Cache ──────────────────────────────────────────────
@@ -196,14 +462,54 @@ export class QueryCache {
   }
 
   /**
-   * Generate a cache key from a SQL query and params.
+   * Stable identity of the DATABASE a cache entry came from.
+   *
+   * `engine://host:port/database` - and deliberately NOTHING else.
+   *
+   * WHY IT EXISTS: the key used to be `query:${sql}:${params}` with nothing
+   * naming the connection, so on any SHARED backend two databases cross-served
+   * each other's rows. Two apps pointed at one Redis, or one app with a primary
+   * and an analytics connection, silently read each other's data. Identical SQL
+   * text across tenants is the COMMON case, not an edge case, so the collision
+   * was the normal outcome.
+   *
+   * WHY NO CREDENTIALS: a password in the key means every rotation silently
+   * cold-starts the cache, and a shared backend's key namespace is visible to
+   * every tenant of that backend - a secret must never be folded into it. The
+   * username is out for the same reason plus a second: two connections
+   * differing only by role read the SAME rows and should share the entry.
+   *
+   * WHY NOTHING PER-PROCESS: no pid, no object id, no salt. Those would isolate
+   * the databases by ACCIDENT and destroy the point of a shared cache, because
+   * no instance would ever hit another instance's entry.
    */
-  static queryKey(sql: string, params?: unknown[]): string {
+  static cacheIdentity(url: string): string {
+    try {
+      const parsed = new DatabaseUrl(url);
+      return `${parsed.engine}://${parsed.host ?? ""}:${parsed.port ?? ""}/${parsed.database}`;
+    } catch {
+      // An unparseable URL still needs a STABLE identity, and falling back to a
+      // constant would silently restore the cross-serving bug. The raw URL is
+      // stable and distinct; it is only reached for a URL the connection layer
+      // is about to reject anyway.
+      return url;
+    }
+  }
+
+  /**
+   * Generate a cache key from DATABASE IDENTITY + SQL + params.
+   *
+   * The NUL separators keep the three parts from running together, so a table
+   * named after the tail of a database name cannot forge another database's
+   * key. The key is not hashed here: the only backend with a key-length limit
+   * is memcached, and its backend already SHA-256-hashes whatever it is given.
+   */
+  static queryKey(sql: string, params?: unknown[], identity = ""): string {
     const paramStr = params ? JSON.stringify(params) : "";
-    // Simple hash via string combination
-    return `query:${sql}:${paramStr}`;
+    return `query:${identity}\u0000${sql}\u0000${paramStr}`;
   }
 
+
   /**
    * Get a cached value. Returns undefined if expired or missing.
    */

package/packages/orm/src/types.ts

@@ -77,8 +77,8 @@ export interface DatabaseAdapter {
   /** Insert one or more rows into a table, returns result with lastId. */
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
 
-  /** Update rows in a table matching filter, returns affected row count. */
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+  /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
 
   /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
   delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
@@ -93,10 +93,10 @@ export interface DatabaseAdapter {
   rollback(): void;
 
   /** List all tables in the database. */
-  tables(): string[];
+  getTables(): string[];
 
   /** List columns with types for a table. */
-  columns(table: string): ColumnInfo[];
+  getColumns(table: string): ColumnInfo[];
 
   /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
   lastInsertId(): number | bigint | string | null;
@@ -115,6 +115,17 @@ export interface DatabaseAdapter {
 
   /** Add a column to an existing table (legacy, used by migration). */
   addColumn?(table: string, colName: string, def: FieldDefinition): void;
+
+  /**
+   * Stable identity of the DATABASE this adapter is connected to, as
+   * `engine://host:port/database` with NO credentials - set by whoever built
+   * the adapter from a URL or config.
+   *
+   * The query cache folds this into every key. Without it two databases sharing
+   * one cache backend cross-serve each other's rows, because identical SQL text
+   * across tenants is the common case.
+   */
+  cacheIdentity?: string;
 }
 
 export interface PaginatedResult<T = Record<string, unknown>> {

package/types/cli/src/bin.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Kill any process listening on `port`. Returns true if anything was killed.
+ *
+ * Every PID is validated first. `parseInt` on a non-numeric lsof field yields
+ * 1, and SIGTERM to PID 1 is the container's own init -- which is exactly how a
+ * production container logged "Killed existing process on port 7148 (PID: 1
+ * ...)" and then exited 143, killing itself on startup.
+ */
+/**
+ * The PIDs from `lsof -ti` output that are safe to signal.
+ *
+ * Pure so the safety rule can be tested directly. An unvalidated parse is a
+ * footgun with real teeth: where lsof prints a different shape than -ti
+ * implies, a non-numeric field becomes 0, and signalling PID 0 hits EVERY
+ * process in the caller's own process group -- the server kills itself. That
+ * is what produced "Killed existing process on port 7148 (PID: 1 ...)" in a
+ * real image, where the container then exited 143.
+ *
+ * Accepts only all-digit tokens; never PID 0 (our group), PID 1 (init),
+ * ourselves, or our own process group.
+ */
+export declare function selectablePids(lsofOutput: string, me: number, myGroup?: number): number[];
+export interface CommandManifestEntry {
+    name: string;
+    summary: string;
+    args?: string[];
+    subcommands?: string[];
+    /** True when the tina4 client implements this command, not the framework. */
+    delegated?: boolean;
+}
+export interface CommandManifest {
+    framework: string;
+    version: string;
+    commands: CommandManifestEntry[];
+}
+/**
+ * Build the machine-readable manifest of the CLI's command surface.
+ *
+ * Pure data: reads the module-level COMMANDS and DELEGATED registries plus the
+ * framework version — no bootstrap, no database, no migrations, no app imports.
+ * This is exactly what `commands --json` serialises and what the tina4 Rust
+ * client consumes to discover which commands this framework supports.
+ *
+ * Commands handed to the `tina4` client carry `delegated: true`, so the manifest
+ * describes the WHOLE surface the CLI accepts while still saying who implements
+ * each one. The client needs no change: its help renderer already drops manifest
+ * names that clash with its own natives.
+ *
+ * Shape (identical keys to the Python master):
+ *   { framework: "nodejs", version: "<x.y.z>",
+ *     commands: [{ name, summary, args?, subcommands?, delegated? }, ...] }
+ */
+export declare function buildCommandManifest(): CommandManifest;
+/**
+ * Emit the CLI's own command surface — the self-describing manifest.
+ *
+ *   tina4nodejs commands           human-readable list
+ *   tina4nodejs commands --json    machine-readable manifest (for the tina4 CLI)
+ *
+ * CHEAP + side-effect-free by contract: it only prints the static COMMANDS
+ * registry plus the framework version. It MUST NOT bootstrap the framework,
+ * open a database, run migrations, or import app modules — the Rust client
+ * calls this on `tina4 --help`, in any directory, so it must be instant and
+ * safe to run anywhere.
+ */
+export declare function runCommands(args?: string[]): void;
+export interface CommandSpec {
+    handler: (cmdArgs: string[]) => void | Promise<void>;
+    summary: string;
+    usage?: string;
+    args?: string[];
+    subcommands?: string[];
+}
+export declare const COMMANDS: Record<string, CommandSpec>;
+export interface DelegatedSpec {
+    summary: string;
+    usage?: string;
+    args?: string[];
+}
+export declare const DELEGATED: Record<string, DelegatedSpec>;
+export declare const CLIENT_BINARY = "tina4";
+export declare const DELEGATION_GUARD_ENV = "TINA4_CLI_DELEGATED";
+export declare const EXIT_CLIENT_UNAVAILABLE = 127;
+export declare const EXIT_UNKNOWN_COMMAND = 1;
+/**
+ * Run `tina4 <command> <args...>`, returning the client's exit code.
+ *
+ * Returns EXIT_CLIENT_UNAVAILABLE (127) with an actionable message when the
+ * client is not on PATH, or when the re-entry guard shows the resolved `tina4`
+ * came back to a framework CLI (a delegation loop).
+ */
+export declare function delegateToClient(command: string, args: string[]): number;

package/types/cli/src/commands/build.d.ts

@@ -0,0 +1,2 @@
+/** Build the deployable Docker image. Fails loud (exit 1+) on missing prerequisites. */
+export declare function buildImage(args: string[]): void;

package/types/cli/src/commands/generate.d.ts

@@ -0,0 +1,47 @@
+export declare function toSnake(name: string): string;
+export declare function toTableName(name: string): string;
+/** slug-of-anything → PascalCase (order-emails → OrderEmails). */
+export declare function toPascal(name: string): string;
+export declare function parseFields(fieldsStr: string): Array<[string, string]>;
+export declare const DEFAULT_FIELDS: ReadonlyArray<[string, string]>;
+/** Parsed --fields, or the default single `name` column when none given. */
+export declare function fieldsOrDefault(fieldsStr: string): Array<[string, string]>;
+export declare function parseCliArgs(args: string[]): {
+    flags: Record<string, string | boolean>;
+    positional: string[];
+};
+/**
+ * Parse a `--every` duration ("5m", "30s", "2h", "1d", or bare seconds) → seconds.
+ * Falls back to 60s on an empty/unparseable value so a scaffold always has a
+ * valid ServiceRunner interval.
+ */
+export declare function parseEvery(every: string | boolean | undefined): number;
+/**
+ * The canonical AI-FILL placeholder for a LOGIC-shaped stub — a tight, grounded
+ * fill-spec (not a vague `// TODO`) so a coding agent (or dev) completes it
+ * correctly. `throw new Error(...)` makes an unfilled scaffold fail LOUD; the
+ * greppable `AI-FILL` banner lets a human/agent jump to every gap. `use` names
+ * only REAL tina4-nodejs symbols (verified in source).
+ */
+export declare function aiFill(fn: string, spec: {
+    intent: string;
+    given?: string;
+    use: string;
+    ret?: string;
+    ground: string;
+    raise: string;
+}, indent?: string): string;
+/**
+ * The lighter EXTEND marker for CRUD-shaped WORKING code — no throw (the
+ * boilerplate IS the feature); just a greppable hint at the natural extension
+ * point (custom validation / business rules / authorization).
+ */
+export declare function extend(note: string, hint?: string, indent?: string): string;
+export interface GeneratorSpec {
+    handler: (name: string, flags: Record<string, string | boolean>) => void;
+    /** Arg/flag hint shown in `tina4nodejs help` (human only). */
+    usage: string;
+    summary: string;
+}
+export declare const GENERATORS: Record<string, GeneratorSpec>;
+export declare function generate(what: string, name: string, extraArgs?: string[]): Promise<void>;

package/types/cli/src/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initProject(name: string): Promise<void>;

package/types/cli/src/commands/metrics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Run the metrics report. Returns the process exit code; does NOT call
+ * process.exit (the bin wrapper does). 0 = ok / below threshold, 1 = gated
+ * failure, 2 = bad arguments / analysis error.
+ */
+export declare function runMetrics(args?: string[]): number;

package/types/cli/src/commands/migrate.d.ts

@@ -0,0 +1 @@
+export declare function runMigrations(migrationDir?: string): Promise<void>;