tina4-nodejs 3.13.81 → 3.13.82

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.81)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.82)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.81 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.82 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -51,7 +51,7 @@ tina4-nodejs/
         baseModel.ts     # Base model class
         fakeData.ts      # ORM-aware fake data (extends core, field-type heuristics)
         seeder.ts        # Database seeding (seedTable, seedOrm, seedModels)
-        sqlTranslation.ts # Cross-engine SQL translator + query cache
+        sqlTranslator.ts # Cross-engine SQL translator + query cache
     swagger/    # OpenAPI spec generator, Swagger UI
     frond/      # Zero-dependency Twig-compatible template engine
   test/
@@ -155,7 +155,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `types.ts` — `FieldDefinition`, `ModelDefinition`, `DatabaseAdapter`, `QueryOptions`
 - `fakeData.ts` — ORM-aware fake data extending core (adds `forField()` with column-name heuristics)
 - `seeder.ts` — Database seeding (`seedTable` raw SQL, `seedOrm` model-based, `seedModels` FK-ordered batch). All return a `SeedSummary { seeded, failed, errors }`; per-row failures are logged + counted + skipped (`strict` re-raises). Options: `{ overrides, clear, seed, strict }`.
-- `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
+- `sqlTranslator.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|false` (fluent, false on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
 - **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
 - **Foreign key auto-wire:** Declare a field with `type: "foreignKey"` and `references: "ModelName"` to auto-wire both `belongsTo` on the declaring model and `hasMany` on the referenced model. Optional `relatedName` overrides the has-many key. Models must be registered via `BaseModel.registerModel(name, class)` for name-based resolution. Example: `user_id: { type: "foreignKey", references: "User" }` → `post.belongsTo(User, "user_id")` and `user.hasMany(Post, "user_id")` both resolve without extra wiring.
@@ -526,7 +526,7 @@ accepts `seed`/`clear`/`strict`, and returns `{ seeded, failed, errors, table }`
 
 Column-name heuristics in `forField()`: columns named `email`, `phone`, `name`, `address`, `city`, `country`, `company`, `url`, `uuid`, `ip`, `currency`, etc. get contextually appropriate fake data.
 
-## Module: SQL Translation (`packages/orm/src/sqlTranslation.ts`)
+## Module: SQL Translation (`packages/orm/src/sqlTranslator.ts`)
 
 Cross-engine SQL dialect translator and in-memory query cache. All translator methods are static on `SQLTranslator`. The `QueryCache` provides TTL-based caching with LRU eviction.
 
@@ -1237,7 +1237,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 
 ## v3 Features Summary
 
-- **45 built-in features**, zero third-party dependencies
+- **98 built-in features**, zero third-party dependencies
 - **5,379 tests** passing across 154 files (build + typecheck green; 9 PostgreSQL/Valkey service-gated failures)
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)

package/README.md

@@ -3,11 +3,11 @@
 </p>
 <h1 align="center">Tina4 Node.js</h1>
 <h3 align="center">The Intelligent Native Application 4ramework</h3>
-<p align="center">55 built-in features. Zero dependencies. One import, everything works.</p>
+<p align="center">98 built-in features. Zero dependencies. One import, everything works.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@tina4/core"><img src="https://img.shields.io/npm/v/@tina4/core?color=7b1fa2&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/tests-2%2C897%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/features-55-blue" alt="Features">
+  <img src="https://img.shields.io/badge/features-98-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
 </p>
@@ -93,7 +93,7 @@ Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 | Raw `node:http` | 91,110 | 0 | 1 |
 | **Tina4 Node.js** | **84,771** | 0 | 55 |
 
-Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in features, a zero-overhead architecture.
+Tina4 Node.js runs at **93% of raw Node.js speed** while providing 98 built-in features, a zero-overhead architecture.
 
 **Across all 4 Tina4 implementations:**
 
@@ -107,7 +107,7 @@ Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in f
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 97 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.81",
+  "version": "3.13.82",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/cli/src/bin.ts

@@ -11,9 +11,9 @@ import { runSeeds } from "./commands/seed.js";
 import { runMetrics } from "./commands/metrics.js";
 import { queueCommand, QUEUE_SUBCOMMAND_NAMES } from "./commands/queue.js";
 import { buildImage } from "./commands/build.js";
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // ── Version (cheap, side-effect-free) ───────────────────────────────
@@ -73,6 +73,8 @@ export interface CommandManifestEntry {
   summary: string;
   args?: string[];
   subcommands?: string[];
+  /** True when the tina4 client implements this command, not the framework. */
+  delegated?: boolean;
 }
 
 export interface CommandManifest {
@@ -84,14 +86,19 @@ export interface CommandManifest {
 /**
  * Build the machine-readable manifest of the CLI's command surface.
  *
- * Pure data: reads the module-level COMMANDS registry 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.
+ * 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? }, ...] }
+ *     commands: [{ name, summary, args?, subcommands?, delegated? }, ...] }
  */
 export function buildCommandManifest(): CommandManifest {
   const commands: CommandManifestEntry[] = Object.entries(COMMANDS).map(([name, spec]) => {
@@ -100,6 +107,11 @@ export function buildCommandManifest(): CommandManifest {
     if (spec.subcommands && spec.subcommands.length) entry.subcommands = [...spec.subcommands];
     return entry;
   });
+  for (const [name, spec] of Object.entries(DELEGATED)) {
+    const entry: CommandManifestEntry = { name, summary: spec.summary, delegated: true };
+    if (spec.args && spec.args.length) entry.args = [...spec.args];
+    commands.push(entry);
+  }
   return { framework: "nodejs", version: readCliVersion(), commands };
 }
 
@@ -126,7 +138,8 @@ export function runCommands(args: string[] = []): void {
   console.log(`\n  Tina4 ${manifest.framework} — ${manifest.version}\n`);
   const width = Math.max(...manifest.commands.map((c) => c.name.length));
   for (const c of manifest.commands) {
-    console.log(`  ${c.name.padEnd(width)}  ${c.summary}`);
+    const marker = c.delegated ? ` (${CLIENT_BINARY} client)` : "";
+    console.log(`  ${c.name.padEnd(width)}  ${c.summary}${marker}`);
     if (c.subcommands && c.subcommands.length) {
       console.log(`  ${" ".repeat(width)}    ${c.subcommands.join(", ")}`);
     }
@@ -137,21 +150,24 @@ export function runCommands(args: string[] = []): void {
 /**
  * Print the human-readable command reference.
  *
- * Generated from the COMMANDS and GENERATORS registries — the SAME single
- * source of truth that drives dispatch (`main`) and the `commands --json`
+ * Generated from the COMMANDS, DELEGATED and GENERATORS registries — the SAME
+ * single source of truth that drives dispatch (`main`) and the `commands --json`
  * manifest — so the help text can never drift from what the CLI actually does.
  */
 function printHelp(): void {
   const commandRows: [string, string][] = Object.entries(COMMANDS).map(
     ([name, spec]) => [`${name}${spec.usage ? " " + spec.usage : ""}`, spec.summary],
   );
+  const delegatedRows: [string, string][] = Object.entries(DELEGATED).map(
+    ([name, spec]) => [`${name}${spec.usage ? " " + spec.usage : ""}`, spec.summary],
+  );
   const generatorRows: [string, string][] = Object.entries(GENERATORS).map(
     ([name, spec]) => [`generate ${name}${spec.usage ? " " + spec.usage : ""}`, spec.summary],
   );
 
   // Align summaries in a column; a left cell longer than the cap overflows
   // cleanly (2-space gap) rather than pushing every other summary out.
-  const pad = Math.min(46, Math.max(...[...commandRows, ...generatorRows].map(([left]) => left.length)));
+  const pad = Math.min(46, Math.max(...[...commandRows, ...delegatedRows, ...generatorRows].map(([left]) => left.length)));
   const row = (left: string, summary: string): string => {
     const gap = left.length <= pad ? pad : left.length;
     return `  ${left.padEnd(gap)}  ${summary}`;
@@ -166,6 +182,10 @@ function printHelp(): void {
     "  Commands:",
     ...commandRows.map(([left, summary]) => row(left, summary)),
     "",
+    `  Delegated to the ${CLIENT_BINARY} client (same behaviour in every framework):`,
+    ...delegatedRows.map(([left, summary]) => row(left, summary)),
+    `    (these run the ${CLIENT_BINARY} client — install: curl -fsSL https://tina4.com/install.sh | sh)`,
+    "",
     "  Generators:",
     ...generatorRows.map(([left, summary]) => row(left, summary)),
     "",
@@ -356,6 +376,130 @@ export const COMMANDS: Record<string, CommandSpec> = {
   },
 };
 
+// ── Delegation to the `tina4` client ────────────────────────────────
+//
+// `doctor`, `setup` and `deploy` are owned by the Rust `tina4` client, not by
+// any framework. `doctor` probes ALL FOUR runtimes plus package managers, ports
+// and global AI-skills currency; `setup` installs language runtimes (Homebrew /
+// Chocolatey, with UAC elevation on Windows) and scaffolds a project from
+// nothing; `deploy` writes deployment boilerplate baked into the client binary.
+// Cloning any of them into four languages would duplicate hundreds of lines per
+// language for zero new capability — and four copies would immediately drift.
+//
+// So the framework CLI DELEGATES: it resolves `tina4` on PATH, runs it with the
+// same argv, and exits with the client's exit code. All four frameworks reach
+// the SAME implementation, which is a stronger parity guarantee than four ports.
+//
+// Delegation is ALLOW-LISTED, never blind. The client forwards ITS unknown
+// commands to the framework CLI, so a framework that forwarded its unknowns back
+// would ping-pong an unknown command between two processes forever — and that is
+// not hypothetical here: this package publishes a `tina4` bin alias, so `tina4`
+// on PATH can already resolve to THIS CLI. The closed DELEGATED set contains only
+// commands the client dispatches natively, so no loop is possible by
+// construction, and a real typo still gets "Unknown command".
+//
+// There are no handlers here: main() runs `tina4 <name> <args...>` and exits with
+// its code. Keep this set closed and identical in all four frameworks. Summaries
+// are the client's own wording, verbatim. Mirrors the Python master's DELEGATED.
+
+export interface DelegatedSpec {
+  summary: string;
+  usage?: string;
+  args?: string[];
+}
+
+export const DELEGATED: Record<string, DelegatedSpec> = {
+  doctor: { summary: "Check installed languages and tools" },
+  setup: { summary: "Guided, menu-driven setup: install everything + scaffold a ready-to-run project" },
+  deploy: {
+    usage: "<docker|systemd|nginx|cpanel> [--force]",
+    args: ["target"],
+    summary: "Generate deployment scaffolding (Dockerfile, systemd unit, nginx block, cPanel)",
+  },
+};
+
+export const CLIENT_BINARY = "tina4";
+
+// Internal process marker (same class as the client's own TINA4_SETUP_ELEVATED):
+// set on the child so a client that resolves back to a framework CLI is caught
+// instead of spawning forever. NOT user configuration — deliberately absent from
+// the CLI's known_vars().
+export const DELEGATION_GUARD_ENV = "TINA4_CLI_DELEGATED";
+
+// 127 is the conventional "command not found" and covers both ways the client
+// can be unreachable (absent from PATH, or the loop guard tripping).
+export const EXIT_CLIENT_UNAVAILABLE = 127;
+export const EXIT_UNKNOWN_COMMAND = 1;
+
+const CLIENT_INSTALL_HINT =
+  "  Install it:  curl -fsSL https://tina4.com/install.sh | sh\n" +
+  "  Windows:     irm https://tina4.com/install.ps1 | iex";
+
+/**
+ * Absolute path of the `tina4` client on PATH, or null if it isn't there.
+ *
+ * Scans PATH directly rather than shelling out to which/where — one less process
+ * and it behaves the same on every platform.
+ */
+function findClient(): string | null {
+  const windows = process.platform === "win32";
+  const names = windows
+    ? [`${CLIENT_BINARY}.exe`, `${CLIENT_BINARY}.cmd`, `${CLIENT_BINARY}.bat`]
+    : [CLIENT_BINARY];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = join(dir, name);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // not there — keep looking
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * 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 function delegateToClient(command: string, args: string[]): number {
+  if (process.env[DELEGATION_GUARD_ENV] === command) {
+    console.error(
+      `  Refusing to delegate '${command}' again — the 'tina4' on your PATH\n` +
+      `  resolved back to a framework CLI instead of the tina4 client.\n\n` +
+      `  Check which 'tina4' comes first on your PATH and put the client first.`,
+    );
+    return EXIT_CLIENT_UNAVAILABLE;
+  }
+
+  const client = findClient();
+  if (client === null) {
+    console.error(
+      `  '${command}' is provided by the tina4 client, which is not on your PATH.\n\n` +
+      `${CLIENT_INSTALL_HINT}\n\n` +
+      `  Then run:    ${CLIENT_BINARY} ${command}`,
+    );
+    return EXIT_CLIENT_UNAVAILABLE;
+  }
+
+  // stdio is inherited, so the client's interactive prompts (setup) and colour
+  // output work exactly as if it had been invoked directly.
+  const result = spawnSync(client, [command, ...args], {
+    stdio: "inherit",
+    env: { ...process.env, [DELEGATION_GUARD_ENV]: command },
+  });
+  if (result.error) {
+    console.error(`  Could not start the tina4 client at ${client}: ${result.error.message}`);
+    return EXIT_CLIENT_UNAVAILABLE;
+  }
+  return result.status ?? EXIT_CLIENT_UNAVAILABLE;
+}
+
 // ── Dispatch ────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -374,9 +518,15 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (command in DELEGATED) {
+    process.exit(delegateToClient(command, cmdArgs));
+  }
+
+  // A genuinely unknown command is an ERROR: exit non-zero so a typo in a script
+  // or CI step fails loudly instead of reporting success.
   console.error(`Unknown command: ${command}`);
   printHelp();
-  process.exit(1);
+  process.exit(EXIT_UNKNOWN_COMMAND);
 }
 
 // Run only when invoked as the entrypoint — importing this module (e.g. in a