tina4-nodejs 3.13.91 → 3.13.94

package/packages/orm/src/adapters/sqlite.ts

@@ -279,7 +279,10 @@ export class SQLiteAdapter implements DatabaseAdapter {
       name: string; type: string; notnull: number; dflt_value: unknown; pk: number;
     }>;
     return rows.map((r) => ({
-      name: r.name, type: r.type, nullable: r.notnull === 0, default: r.dflt_value, primaryKey: r.pk === 1,
+      // PRAGMA table_info reports `pk` as the 1-BASED POSITION within the primary
+      // key, not a boolean: a composite key gives pk=1, pk=2, ... Testing `=== 1`
+      // reported only the first column of a composite key.
+      name: r.name, type: r.type, nullable: r.notnull === 0, default: r.dflt_value, primaryKey: Number(r.pk) > 0,
     }));
   }
 

package/packages/orm/src/database.ts

@@ -484,6 +484,9 @@ export class Database {
   /** Factory for creating new adapters (used by pool) */
   private adapterFactory: (() => Promise<DatabaseAdapter>) | null = null;
 
+  /** table -> primary-key column name (or null), introspected once */
+  private _pkCache: Map<string, string[]> = new Map();
+
   /**
    * Whether a standalone write auto-commits. ON by default — a write made
    * outside an explicit transaction commits on its own connection before
@@ -787,28 +790,125 @@ export class Database {
     return result;
   }
 
-  /** Update rows in a table matching filter. */
+  /**
+   * The table's primary-key column, introspected once and cached.
+   *
+   * Uses the cross-engine getColumns() contract (v3.13.14, #48), which reports
+   * primaryKey per column on every adapter. Resolves to null when the table has
+   * no primary key or cannot be introspected.
+   */
+  async primaryKey(table: string): Promise<string[]> {
+    if (!this._pkCache.has(table)) {
+      let pk: string[] = [];
+      try {
+        const columns = await this.getColumns(table);
+        pk = columns.filter((c) => c.primaryKey).map((c) => c.name);
+      } catch {
+        pk = [];
+      }
+      this._pkCache.set(table, pk);
+    }
+    return this._pkCache.get(table) ?? [];
+  }
+
+  /**
+   * A failed write must be loud.
+   *
+   * The adapters catch a SQL error and return { success: false, affectedRows: 0 },
+   * so a filterless update produced invalid SQL ("... WHERE ") and reported
+   * nothing rather than raising. A caller who does not inspect the result
+   * believes the write landed (audit feature 4, P1).
+   */
+  private static assertWrote(result: DatabaseWriteResult, verb: string, table: string): DatabaseWriteResult {
+    if (result && (result as any).success === false) {
+      throw new Error(
+        `${verb} failed on ${table}: ${(result as any).error ?? "unknown error"}`,
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Update rows. A write with no filter is an error, not a full-table write.
+   *
+   * With no explicit filter the primary key is taken out of `data` and used as
+   * the WHERE clause. With neither a filter nor a primary key in `data` this
+   * throws rather than silently changing nothing (audit feature 4, P1).
+   */
   async update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult> {
+    let effectiveFilter = filter ?? {};
+    let effectiveData = data;
+
+    if (Object.keys(effectiveFilter).length === 0) {
+      const pkColumns = await this.primaryKey(table);
+      const missing = pkColumns.filter((c) => !(c in data));
+      if (pkColumns.length === 0 || missing.length > 0) {
+        throw new Error(
+          `update requires a filter or the complete primary key in the data; pass ` +
+            `filter explicitly to update multiple rows (table=${table}, ` +
+            `primary key=[${pkColumns.join(", ")}], missing from data=[${missing.join(", ")}]). ` +
+            `To empty a table use truncate(${table}).`,
+        );
+      }
+      // EVERY key column goes into the WHERE. A composite key built from only its
+      // first column would match every row sharing that value - the data-loss bug
+      // this method exists to prevent, reintroduced.
+      effectiveData = { ...data };
+      const keyed: Record<string, unknown> = {};
+      for (const col of pkColumns) {
+        keyed[col] = effectiveData[col];
+        delete effectiveData[col];
+      }
+      if (Object.keys(effectiveData).length === 0) {
+        throw new Error(
+          `update was given only the primary key [${pkColumns.join(", ")}] and no ` +
+            `columns to set (table=${table})`,
+        );
+      }
+      effectiveFilter = keyed;
+    }
+
     const adapter = this.getNextAdapter();
     const result = (adapter as any).updateAsync
-      ? await (adapter as any).updateAsync(table, data, filter ?? {}, params)
-      : adapter.update(table, data, filter ?? {}, params);
+      ? await (adapter as any).updateAsync(table, effectiveData, effectiveFilter, params)
+      : adapter.update(table, effectiveData, effectiveFilter, params);
     if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
-    return result;
+    return Database.assertWrote(result, "update", table);
   }
 
-  /** Delete rows from a table matching filter. */
+  /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
   async delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult> {
+    const effectiveFilter = filter ?? {};
+    if (!Array.isArray(effectiveFilter) && typeof effectiveFilter !== "string"
+        && Object.keys(effectiveFilter).length === 0) {
+      throw new Error(
+        `delete requires a filter (table=${table}). To remove every row use truncate(${table}).`,
+      );
+    }
+
     const adapter = this.getNextAdapter();
     const result = (adapter as any).deleteAsync
-      ? await (adapter as any).deleteAsync(table, filter ?? {}, params)
-      : adapter.delete(table, filter ?? {}, params);
+      ? await (adapter as any).deleteAsync(table, effectiveFilter, params)
+      : adapter.delete(table, effectiveFilter, params);
     if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
-    return result;
+    return Database.assertWrote(result, "delete", table);
+  }
+
+  /** Remove every row. The explicit spelling of a whole-table delete. */
+  async truncate(table: string): Promise<DatabaseWriteResult> {
+    const adapter = this.getNextAdapter();
+    // The adapters' delete() already accepts a raw string WHERE clause.
+    const result = (adapter as any).deleteAsync
+      ? await (adapter as any).deleteAsync(table, "1 = 1", [])
+      : adapter.delete(table, "1 = 1" as any, []);
+    if (this.autoCommit && !this.inExplicitTransaction()) {
+      try { await adapterCommit(adapter); } catch { /* no active transaction */ }
+    }
+    return Database.assertWrote(result, "truncate", table);
   }
 
   /** Close all database connections (pool or single). */

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>;

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

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

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

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

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

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

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

@@ -0,0 +1,20 @@
+/** A per-job handler declared by a consumer module (receives the job payload). */
+export type QueueHandler = (payload: unknown) => unknown | Promise<unknown>;
+/**
+ * Return the per-job handler that a consumer module declares for `topic`.
+ *
+ * A consumer module (e.g. the one `generate queue <topic>` scaffolds) exposes a
+ * default-export config; when its `topic` matches, `queue work` drives the
+ * consumer through that config's per-job `handle` callable — so the worker owns
+ * the poll loop (honouring --poll and the bounded --once drain) instead of the
+ * consumer's own endless loop. Returns the callable, or null when no consumer in
+ * `servicesDir` targets this topic. Mirrors Python's _resolve_queue_handler.
+ */
+export declare function resolveQueueHandler(servicesDir: string, topic: string): Promise<QueueHandler | null>;
+/** Subcommand names, in order — surfaced in `commands --json` for the tina4 client. */
+export declare const QUEUE_SUBCOMMAND_NAMES: string[];
+/**
+ * Top-level queue command: run workers and manage jobs. Dispatches to the
+ * subcommand handlers above; unknown / missing subcommands fail loud (exit 1).
+ */
+export declare function queueCommand(args?: string[]): Promise<void>;

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

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

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

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

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

@@ -0,0 +1,6 @@
+export interface ServeOptions {
+    port?: number;
+    noBrowser?: boolean;
+    noReload?: boolean;
+}
+export declare function serveProject(options: ServeOptions): Promise<void>;

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

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

package/types/core/src/ai.d.ts

@@ -0,0 +1,64 @@
+export interface AiTool {
+    name: string;
+    description: string;
+    contextFile: string;
+    configDir: string | null;
+}
+export declare const AI_TOOLS: AiTool[];
+export declare const DEV_SKILL = "tina4-developer-nodejs";
+/**
+ * Install the Tina4 SKILL.md skills into the project AND the global
+ * ~/.claude/skills, fetched from the release ref matching this framework
+ * version. Returns the skills that were fully installed. Network-dependent —
+ * on a fetch failure the skill is skipped, never fatal.
+ */
+export declare function installSkills(root?: string, targets?: string[]): string[];
+/**
+ * Check if a tool's context file already exists.
+ */
+export declare function isInstalled(root: string, tool: AiTool): boolean;
+/**
+ * Print the numbered menu and read user input via readline.
+ * Returns a promise that resolves to the user's selection string.
+ */
+export declare function showMenu(root?: string): Promise<string>;
+/**
+ * Install context files for the selected tools.
+ *
+ * selection: comma-separated numbers like "1,2,3" or "all"
+ * Returns list of created/updated file paths.
+ */
+export declare function installSelected(root: string, selection: string): string[];
+/**
+ * Install context for all AI tools (non-interactive).
+ */
+export declare function installAll(root?: string): string[];
+/** Return [start, end] markers for a context file. */
+export declare function markersFor(contextFile: string): [string, string];
+/** Return the marker-bracketed Tina4 skill registration block. */
+export declare function skillBlock(contextFile: string): string;
+/** True iff both start and end markers appear in order. */
+export declare function hasMarkers(existing: string, start: string, end: string): boolean;
+/** Replace the bracketed block in `existing` with `block`. */
+export declare function replaceMarkerBlock(existing: string, block: string, start: string, end: string): string;
+/**
+ * True if the file starts with a header the pre-v3.13.9 installer
+ * wrote. Used to migrate one-time off the old clobber-style install.
+ */
+export declare function looksLikeOldFrameworkInstall(existing: string): boolean;
+/**
+ * Write the context file non-destructively. Returns a human-readable
+ * action verb for the caller's log line.
+ *
+ * Four branches:
+ *   1. Doesn't exist  \u2192 write framework guide + skill block
+ *   2. Has markers    \u2192 refresh just the skill block (idempotent)
+ *   3. Old header     \u2192 migrate: replace old dump with new guide + block
+ *   4. User content   \u2192 append the skill block, preserve everything else
+ */
+export declare function writeOrMerge(contextPath: string, contextFile: string, frameworkGuide: string): string;
+/**
+ * Generate the Tina4 context document for a specific AI tool.
+ */
+export declare function generateContext(toolName?: string): string;
+export { AiTool as AiToolType };