tina4-nodejs 3.13.72 → 3.13.73

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.71)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.73)
 
 > 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.71 - 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.73 - 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.
 
@@ -839,7 +839,7 @@ syncModels(discoveredModels);               // auto-create tables / add columns
 
 - SQL files live in `migrations/`, named `NNNNNN_description.sql` (sequential) or `YYYYMMDDHHMMSS_description.sql` (timestamp), and are split on the `;` delimiter.
 - Files are applied in **numeric-prefix order** (`9_` before `10_` — a plain lexical sort misorders unpadded prefixes because `"10" < "9"`). A file with no numeric/timestamp prefix sorts **after** the numbered ones (lexically) and logs a `Log.warning` — its order is undefined.
-- State is tracked by **row existence** in `tina4_migration` (id, name, batch, applied_at), auto-created per engine: a migration runs once — if a row with its `name` exists it is skipped. A FAILED migration is **never** recorded (no row is written, nothing is deleted) — fix the bad file and re-run; the `migrate()` summary's `failed[]` carries the failure.
+- State is tracked in the `tina4_migration` table (auto-created per engine, canonical columns `id, migration_name VARCHAR(500) NOT NULL UNIQUE, description VARCHAR(500), batch INTEGER NOT NULL DEFAULT 1, executed_at VARCHAR(50) NOT NULL, passed INTEGER NOT NULL DEFAULT 1` - identical across all four frameworks). A migration is **applied** when a row exists for it with `passed = 1` (the applied-read is `WHERE passed = 1`). `migrate()` writes **only `passed = 1` rows**, and it does so **delete-before-insert**: on success it DELETEs any existing row for that `migration_name` and then INSERTs the fresh `passed = 1` row (the shared `recordApplied()` helper, mirroring the Python master's `_record_applied()`), so the table holds **at most one row per `migration_name`** - latest state wins. A FAILED migration file is rolled back and **no row is written** for it (it is NOT recorded as `passed = 0`; the record step is never reached), and the run STOPS (the `migrate()` summary's `failed[]` carries the failure). The public `recordMigration(name, batch, passed)` API can write a `passed = 0` row (and one may be carried over from an older table); any `passed = 0` row is treated as **not applied**. Because the success path deletes any existing row for the `migration_name` before the `passed = 1` INSERT, a leftover `passed = 0` row **re-applies cleanly** on the next `migrate()` - the stale row is superseded rather than colliding on the UNIQUE `migration_name` (that collision previously wedged a re-run). Fix the bad file and re-run.
 - **Each migration FILE is wrapped in its own transaction.** On a failure the file rolls back and `migrate()` **STOPS** — later files are never applied on top of a missing earlier one (parity with Python/PHP/Ruby). Already-applied files stay applied. The explicit `tina4 migrate` CLI surfaces a non-empty `failed[]` as a non-zero exit; startup auto-migration logs it and the service still boots (see `TINA4_AUTO_MIGRATE` above).
 - **Atomicity caveat:** per-file transactions are truly atomic only on engines with **transactional DDL (PostgreSQL)**. MySQL, Firebird, and SQLite auto-commit DDL, so a multi-statement migration that fails midway on those engines leaves earlier statements applied — keep one logical change per file. `CREATE TABLE` and `ALTER TABLE ... ADD` are made idempotent on Firebird/MSSQL (existence-checked via `RDB$RELATION_FIELDS` / `tableExists`) so a re-run with a raw `CREATE`/`ADD` does not error "object already exists"; SQLite/MySQL/PostgreSQL support `IF NOT EXISTS` and are left to the engine. Only a genuine already-exists is skipped — every other error still raises.
 - The stored-proc block delimiters (`$$ … $$` / `// … //`) are extracted before splitting, but a `//` preceded by a colon is **not** treated as a delimiter, so a URL (`https://…`) or any `://` literal inside a migration is never swallowed as an opaque block.

package/package.json

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

package/packages/core/gallery/auth/src/routes/api/gallery/auth/login/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: Auth — login endpoint, returns a JWT token. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   const body = (req.body as Record<string, unknown>) ?? {};
@@ -7,7 +7,7 @@ export default async function (req: Tina4Request, res: Tina4Response) {
   const password = (body.password as string) ?? "";
 
   if (username && password) {
-    // In a real app: import { Auth } from "@tina4/core";
+    // In a real app: import { Auth } from "tina4-nodejs";
     // const auth = new Auth();
     // const token = auth.createToken({ username, role: "user" });
     // For the gallery demo, generate a simple base64 token

package/packages/core/gallery/auth/src/routes/api/gallery/auth/verify/get.ts

@@ -1,11 +1,11 @@
 /** Gallery: Auth — verify a JWT token. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   const url = new URL(req.url ?? "/", "http://localhost");
   const token = url.searchParams.get("token") ?? "";
 
-  // In a real app: import { Auth } from "@tina4/core";
+  // In a real app: import { Auth } from "tina4-nodejs";
   // const auth = new Auth();
   // const isValid = auth.validateToken(token);
   // For the gallery demo, just check the token has 3 parts

package/packages/core/gallery/auth/src/routes/gallery/auth/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: Auth — JWT login with a visual demo page. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   const html = `<!DOCTYPE html>
@@ -44,7 +44,7 @@ export default async function (_req: Tina4Request, res: Tina4Response) {
     <div class="card bg-dark mt-4" style="border:1px solid #334155;">
         <div class="card-body">
             <h6 style="color:#e2e8f0;">How it works</h6>
-            <pre style="background:#0f172a;color:#4ade80;padding:1rem;border-radius:0.5rem;font-size:0.8rem;"><code>import { Auth } from "@tina4/core";
+            <pre style="background:#0f172a;color:#4ade80;padding:1rem;border-radius:0.5rem;font-size:0.8rem;"><code>import { Auth } from "tina4-nodejs";
 const auth = new Auth();
 const token = auth.createToken({ username: "admin" });
 const payload = auth.getPayload(token);

package/packages/core/gallery/database/src/routes/api/gallery/db/notes/get.ts

@@ -1,10 +1,10 @@
 /** Gallery: Database — list notes from the gallery database. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   try {
-    const orm = await import("@tina4/orm");
-    const db = orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
+    const orm = await import("tina4-nodejs/orm");
+    const db = await orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
     const result = await db.fetch("SELECT * FROM gallery_notes ORDER BY id DESC", undefined, 50);
     return res.json(result.records ?? []);
   } catch (e: unknown) {

package/packages/core/gallery/database/src/routes/api/gallery/db/notes/post.ts

@@ -1,11 +1,11 @@
 /** Gallery: Database — create a note in the gallery database. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   try {
     const body = (req.body as Record<string, unknown>) ?? {};
-    const orm = await import("@tina4/orm");
-    const db = orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
+    const orm = await import("tina4-nodejs/orm");
+    const db = await orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
     await db.insert("gallery_notes", {
       title: (body.title as string) ?? "Untitled",
       body: (body.body as string) ?? "",

package/packages/core/gallery/database/src/routes/api/gallery/db/tables/get.ts

@@ -1,10 +1,10 @@
 /** Gallery: Database — list tables in the gallery database. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   try {
-    const orm = await import("@tina4/orm");
-    const db = orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
+    const orm = await import("tina4-nodejs/orm");
+    const db = await orm.initDatabase({ type: "sqlite", path: "./data/gallery.db" });
 
     await db.execute(`
       CREATE TABLE IF NOT EXISTS gallery_notes (

package/packages/core/gallery/error-overlay/src/routes/api/gallery/crash/get.ts

@@ -7,7 +7,7 @@
  * - Request details (method, path, headers)
  * - Environment info (framework version, Node.js version)
  */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, _res: Tina4Response) {
   // Simulate a realistic error — accessing a missing property

package/packages/core/gallery/orm/src/routes/api/gallery/products/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: ORM — list products (demo data). */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   return res.json({

package/packages/core/gallery/orm/src/routes/api/gallery/products/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: ORM — create a product (demo). */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   const data = (req.body as Record<string, unknown>) ?? {};

package/packages/core/gallery/queue/src/lib/queueDb.ts

@@ -1,5 +1,5 @@
 /** Shared SQLite database helper for the queue gallery demo. */
-import type { DatabaseAdapter } from "@tina4/orm";
+import type { DatabaseAdapter } from "tina4-nodejs/orm";
 
 let _db: DatabaseAdapter | null = null;
 
@@ -7,7 +7,7 @@ export const MAX_RETRIES = 3;
 
 export async function getQueueDb(): Promise<DatabaseAdapter> {
   if (_db) return _db;
-  const orm = await import("@tina4/orm");
+  const orm = await import("tina4-nodejs/orm");
   _db = await orm.initDatabase({ type: "sqlite", path: "./data/gallery_queue.db" });
   try {
     _db.execute(`CREATE TABLE IF NOT EXISTS tina4_queue (

package/packages/core/gallery/queue/src/routes/api/gallery/queue/consume/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — consume (complete) the next pending message. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 import { getQueueDb, now } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {

package/packages/core/gallery/queue/src/routes/api/gallery/queue/fail/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — deliberately fail the next pending message. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 import { getQueueDb, now } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {

package/packages/core/gallery/queue/src/routes/api/gallery/queue/produce/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — produce a message into the queue. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 import { getQueueDb, now } from "../../../../lib/queueDb.js";
 
 export default async function (req: Tina4Request, res: Tina4Response) {

package/packages/core/gallery/queue/src/routes/api/gallery/queue/retry/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — retry failed messages (re-queue under max retries). */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 import { getQueueDb, now, MAX_RETRIES } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {

package/packages/core/gallery/queue/src/routes/api/gallery/queue/status/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — list all messages with statuses. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 import { getQueueDb, MAX_RETRIES } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {

package/packages/core/gallery/queue/src/routes/gallery/queue/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: Queue — interactive queue demo with visual web UI. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   const html = `<!DOCTYPE html>

package/packages/core/gallery/rest-api/src/routes/api/gallery/hello/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: REST API — simple JSON GET endpoint. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   return res.json({ message: "Hello from Tina4!", method: "GET" });

package/packages/core/gallery/rest-api/src/routes/api/gallery/hello/post.ts

@@ -1,5 +1,5 @@
 /** Gallery: REST API — simple JSON POST endpoint. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
   const data = (req.body as Record<string, unknown>) ?? {};

package/packages/core/gallery/templates/src/routes/gallery/page/get.ts

@@ -1,5 +1,5 @@
 /** Gallery: Templates — render an HTML page with dynamic data via template export. */
-import type { Tina4Request, Tina4Response } from "@tina4/core";
+import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 export const template = "gallery_page.twig";
 

package/packages/orm/src/migration.ts

@@ -437,32 +437,66 @@ export async function isMigrationApplied(name: string): Promise<boolean> {
 }
 
 /**
- * Record a migration as applied. Writes the canonical columns: migration_name,
- * a derived description, batch, an explicit ISO-8601 executed_at timestamp, and
- * passed (default 1). Preserves the Firebird generator-id branch.
+ * Write the canonical "applied" bookkeeping row for a migration.
+ *
+ * DELETEs any existing row for this migration_name FIRST, then INSERTs the
+ * fresh row. A leftover passed=0 row (a prior failure recorded via the public
+ * recordMigration() API, or one carried over from a <= 3.13.54 upgrade) is
+ * therefore superseded, so the migration re-applies cleanly instead of colliding
+ * on the UNIQUE migration_name constraint when the fresh passed=1 row is
+ * INSERTed (that collision used to wedge a previously-failed migration).
+ * DELETE+INSERT is portable across every engine (no UPSERT dialect variance) and
+ * holds the invariant that the table carries AT MOST ONE row per migration_name -
+ * latest state wins.
+ *
+ * Operates on the passed adapter so both migrate() (its own adapter) and
+ * recordMigration() (the global adapter) share ONE implementation - mirrors the
+ * Python master's single _record_applied(). Preserves the Firebird generator-id
+ * branch (no AUTOINCREMENT on Firebird). Writes the canonical columns:
+ * migration_name, a derived description, batch, an explicit ISO-8601 executed_at
+ * timestamp, and passed (default 1).
  */
-export async function recordMigration(name: string, batch: number, passed: number = 1): Promise<void> {
-  const adapter = getAdapter();
+async function recordApplied(
+  db: DatabaseAdapter,
+  name: string,
+  batch: number,
+  passed: number = 1,
+): Promise<void> {
   const now = new Date().toISOString();
   const description = deriveDescription(name);
-  if (isFirebirdAdapter(adapter)) {
-    // Firebird: generate ID from sequence
-    const rows = await adapterQuery<{ NEXT_ID: number }>(adapter,
+  // Delete-before-insert: supersede any leftover row for this migration_name so
+  // the INSERT below never collides on the UNIQUE migration_name.
+  await adapterExecute(db,
+    `DELETE FROM "${MIGRATION_TABLE}" WHERE migration_name = ?`,
+    [name],
+  );
+  if (isFirebirdAdapter(db)) {
+    // Firebird: generate the id from the sequence.
+    const rows = await adapterQuery<{ NEXT_ID: number }>(db,
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE",
     );
     const nextId = rows[0]?.NEXT_ID ?? 1;
-    await adapterExecute(adapter,
+    await adapterExecute(db,
       `INSERT INTO "${MIGRATION_TABLE}" (id, migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, ?, ?)`,
       [nextId, name, description, batch, now, passed],
     );
   } else {
-    await adapterExecute(adapter,
+    await adapterExecute(db,
       `INSERT INTO "${MIGRATION_TABLE}" (migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, ?)`,
       [name, description, batch, now, passed],
     );
   }
 }
 
+/**
+ * Record a migration as applied (public API). Routes through recordApplied() so
+ * a leftover passed=0 row for the same migration_name is deleted before the
+ * fresh row is written (at most one row per migration_name).
+ */
+export async function recordMigration(name: string, batch: number, passed: number = 1): Promise<void> {
+  await recordApplied(getAdapter(), name, batch, passed);
+}
+
 /**
  * Apply a migration (run its up function and record it).
  */
@@ -981,26 +1015,12 @@ export async function migrate(
         await adapterExecute(db, stmt);
       }
 
-      // Record as applied (passed = 1) with the canonical columns and an
-      // explicit ISO-8601 executed_at timestamp.
-      const now = new Date().toISOString();
-      const description = deriveDescription(migrationId);
-      if (isFirebirdAdapter(db)) {
-        // Firebird: generate ID from sequence
-        const idRows = await adapterQuery<{ NEXT_ID: number }>(db,
-          "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE",
-        );
-        const nextId = idRows[0]?.NEXT_ID ?? 1;
-        await adapterExecute(db,
-          `INSERT INTO "${MIGRATION_TABLE}" (id, migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, ?, 1)`,
-          [nextId, migrationId, description, currentBatch, now],
-        );
-      } else {
-        await adapterExecute(db,
-          `INSERT INTO "${MIGRATION_TABLE}" (migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, 1)`,
-          [migrationId, description, currentBatch, now],
-        );
-      }
+      // Record as applied (passed = 1) via recordApplied(), which DELETEs any
+      // leftover row for this migration_name before the fresh INSERT - so a
+      // previously-failed migration (a leftover passed=0 row) re-applies
+      // cleanly instead of colliding on the UNIQUE migration_name. Both the
+      // DELETE and INSERT run inside this file's open transaction.
+      await recordApplied(db, migrationId, currentBatch);
 
       await adapterCommit(db);
       result.applied.push(file);