tina4-nodejs 3.13.104 → 3.13.108

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.104)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.108)
 
 > 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.104 - 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.108 - 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.
 
@@ -309,6 +309,20 @@ queue.consume(topic?, id?, pollInterval=1000): AsyncGenerator<QueueJob>
 // Usage: for await (const job of queue.consume("emails")) { ... }
 ```
 
+**size / failed / deadLetters — three surfaces, one distinction (3.13.105 parity).**
+- `queue.size(status)` — `"pending"` counts jobs waiting to be popped AND retryable-
+  but-attempted ones (they live in the pending queue under the auto-retry lifecycle).
+  `"reserved"` counts in-flight jobs against the visibility timeout. `"completed"`
+  counts finished jobs. `"failed"` / `"dead"` / `"dead_letter"` are ALIASES — all
+  three count the dead-letter store (== `queue.deadLetters().length`).
+- `queue.failed()` — retryable-but-attempted jobs (0 < attempts < maxRetries) that
+  live in the pending queue and are still being auto-retried. They are counted under
+  `size("pending")`, NOT `size("failed")`. Use this to LIST them; use
+  `size("pending")` to include them in a total.
+- `queue.deadLetters()` — terminal failures (attempts >= maxRetries). Same set that
+  `size("failed")` / `size("dead")` / `size("dead_letter")` count. Returns wrapped
+  `Job` objects so callers can iterate uniformly and call `.retry()` on each.
+
 ### @tina4/swagger (`packages/swagger/`)
 Auto-generates OpenAPI 3.0.3 docs.
 

package/README.md

@@ -3,11 +3,10 @@
 </p>
 <h1 align="center">Tina4 Node.js</h1>
 <h3 align="center">The Intelligent Native Application 4ramework</h3>
-<p align="center">98 built-in features. Zero dependencies. One import, everything works.</p>
+<p align="center">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-98-blue" alt="Features">
+  <a href="https://github.com/tina4stack/tina4-nodejs/releases"><img src="https://img.shields.io/github/v/tag/tina4stack/tina4-nodejs?color=7b1fa2&label=version&sort=semver" alt="version"></a>
+  <a href="https://github.com/tina4stack/tina4-nodejs/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/tina4stack/tina4-nodejs/test.yml?label=tests" alt="Tests"></a>
   <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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.104",
+  "version": "3.13.108",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -12352,7 +12352,9 @@ function buildAddColumnSql(adapter, table2, colName, def) {
   return sql;
 }
 function mt(db) {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+  if (engine === "firebird") return MIGRATION_TABLE;
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 function deriveDescription(name) {
   return name.replace(/^\d+_/, "").replace(/_/g, " ");
@@ -12375,9 +12377,9 @@ async function ensureMigrationTableOn(db) {
         id INTEGER NOT NULL PRIMARY KEY,
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
-        batch INTEGER NOT NULL DEFAULT 1,
+        batch INTEGER DEFAULT 1 NOT NULL,
         executed_at VARCHAR(50) NOT NULL,
-        passed INTEGER NOT NULL DEFAULT 1
+        passed INTEGER DEFAULT 1 NOT NULL
       )`);
     } else {
       const idCol = migrationIdColumn(db);
@@ -12474,7 +12476,7 @@ async function recordApplied(db, name, batch, passed = 1) {
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE"
     );
     insertCols.unshift("id");
-    values.unshift(rows[0]?.NEXT_ID ?? 1);
+    values.unshift(rows[0]?.next_id ?? 1);
   }
   const placeholders = insertCols.map(() => "?").join(", ");
   await adapterExecute(
@@ -14888,15 +14890,25 @@ var init_baseModel = __esm({
       /**
        * Invalidate every cached query that touches this model's table.
        *
-       * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-       * this table is busted too (it carries this table's tag), while a query that
-       * never touches this table is left intact. Called after every ORM write
-       * (save/delete/forceDelete/restore) so a read-after-write never serves a
-       * stale/deleted row (CACHE-DEC-01).
+       * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+       * this table is busted too because it carries this table's tag; a query
+       * that never touches this table is left intact), then cascaded to the
+       * DB layer on this model's bound connection so an out-of-band write /
+       * deliberate refresh / race-with-another-process cannot leave stale rows
+       * in db.fetch()'s persistent cache. Called after every ORM write
+       * (save/delete/forceDelete/restore) so a read-after-write never serves
+       * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+       * DB-layer cascade -- previously the two cache layers disagreed under
+       * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
        */
       static clearCache() {
         const ModelClass = this;
         modelQueryCache.clearTag((ModelClass.tableName ?? "").toLowerCase());
+        try {
+          const db = ModelClass.getDb();
+          if (typeof db?.cacheClear === "function") db.cacheClear();
+        } catch {
+        }
       }
       /**
        * Execute a raw SQL SELECT and return results as model instances.
@@ -19183,6 +19195,31 @@ var init_router = __esm({
         this.route.noAuth = true;
         return this;
       }
+      /**
+       * RBAC: require ONE of the named roles (OR). Reads the verified JWT `roles`
+       * claim. Chain .role()/.can() for AND. Implies auth. Feature 138 / ADR-0058.
+       */
+      role(...names) {
+        const clean = names.filter((n) => n !== "");
+        if (clean.length > 0) {
+          (this.route.requiredRoles ??= []).push(clean);
+          this.route.secure = true;
+        }
+        return this;
+      }
+      /**
+       * RBAC: require ONE of the named permissions (OR). Reads the verified JWT
+       * `permissions` claim; granted-side wildcards (`posts.*`, `*`) satisfy a
+       * concrete requirement. Chain for AND. Implies auth. Feature 138.
+       */
+      can(...permissions) {
+        const clean = permissions.filter((p) => p !== "");
+        if (clean.length > 0) {
+          (this.route.requiredPerms ??= []).push(clean);
+          this.route.secure = true;
+        }
+        return this;
+      }
       /** Mark this route's response as cacheable. */
       cache() {
         this.route.cached = true;
@@ -19250,7 +19287,9 @@ var init_router = __esm({
           secure: secureDefault,
           cached: definition.cached,
           noAuth: definition.noAuth,
-          template: definition.template
+          template: definition.template,
+          requiredRoles: definition.requiredRoles,
+          requiredPerms: definition.requiredPerms
         };
         routes.push(compiled);
         return new RouteRef(compiled);
@@ -19397,7 +19436,9 @@ var init_router = __esm({
               template: route.template,
               secure: route.secure,
               cached: route.cached,
-              noAuth: route.noAuth
+              noAuth: route.noAuth,
+              requiredRoles: route.requiredRoles,
+              requiredPerms: route.requiredPerms
             };
           }
         }
@@ -19420,7 +19461,9 @@ var init_router = __esm({
               template: route.template,
               secure: route.secure,
               cached: route.cached,
-              noAuth: route.noAuth
+              noAuth: route.noAuth,
+              requiredRoles: route.requiredRoles,
+              requiredPerms: route.requiredPerms
             });
           }
         }
@@ -19782,7 +19825,7 @@ function enforceRouteAuth(req2, res, match, isDevAdmin) {
     const identity = sso?.identity;
     if (identity?.issuer && identity?.subject) {
       req2.user = identity;
-      return false;
+      return rbacForbidden(match, identity, res);
     }
     const sessionToken = req2.session?.get?.("token");
     if (sessionToken && validToken(sessionToken)) {
@@ -19802,8 +19845,45 @@ function enforceRouteAuth(req2, res, match, isDevAdmin) {
       res.header("FreshToken", fresh);
     }
   }
+  return rbacForbidden(match, req2.user, res);
+}
+function rbacClaimList(subject, key, legacy) {
+  const coerce = (v) => {
+    if (typeof v === "string") return v === "" ? [] : [v];
+    if (Array.isArray(v)) return v.map((x) => String(x)).filter((x) => x !== "");
+    return [];
+  };
+  let out = coerce(subject[key]);
+  if (out.length === 0 && legacy) out = coerce(subject[legacy]);
+  return out;
+}
+function rbacPermGranted(granted, required) {
+  return granted.some(
+    (g) => g === "*" || g === required || g.endsWith(".*") && required.startsWith(g.slice(0, -1))
+  );
+}
+function rbacForbidden(match, payload, res) {
+  const requiredRoles = match.requiredRoles ?? [];
+  const requiredPerms = match.requiredPerms ?? [];
+  if (requiredRoles.length === 0 && requiredPerms.length === 0) {
+    return false;
+  }
+  const subject = payload && typeof payload === "object" ? payload : {};
+  const roles = rbacClaimList(subject, "roles", "role");
+  for (const group of requiredRoles) {
+    if (!group.some((r) => roles.includes(r))) return writeForbidden(res);
+  }
+  const perms = rbacClaimList(subject, "permissions");
+  for (const group of requiredPerms) {
+    if (!group.some((p) => rbacPermGranted(perms, p))) return writeForbidden(res);
+  }
   return false;
 }
+function writeForbidden(res) {
+  res.raw.writeHead(403, { "Content-Type": "application/json" });
+  res.raw.end(JSON.stringify({ error: "Forbidden" }));
+  return true;
+}
 var init_authGate = __esm({
   "../core/src/authGate.ts"() {
     "use strict";
@@ -28115,17 +28195,67 @@ var init_mongoBackend = __esm({
             process.stdout.write("__OK__");
           }
           else if (operation === "retry") {
-            // Explicit manual re-queue (always re-enqueues). data = JSON
-            // { id, delaySeconds }.
+            // Explicit manual re-queue. Serves BOTH Queue.retry(id) (revive
+            // a dead-letter job) AND job.retry() (manual re-queue of a live
+            // reserved/pending job) so the Mongo backend matches
+            // LiteBackend's dual behaviour.
+            //
+            // 1) DL revival (Queue.retry(id) after fail exhausted retries).
+            //    Pre-3.13.105 this branch was BROKEN: the search filter was
+            //    { queue: queueName, id, status: "failed" } -- three separate
+            //    reasons it could never match. dead_letter() inserts under
+            //    queueName + ".dead_letter" (not queueName), carries
+            //    status "dead" (not "failed"), and the original under
+            //    queueName was already acked to "completed" by the time the
+            //    DL was written. Now we look up in the DL namespace by id,
+            //    delete the DL doc first (so an interrupted retry never
+            //    leaves both a DL and a fresh pending doc), and upsert the
+            //    original back to pending -- re-hydrating if the original
+            //    was purged (housekeeping) so a retry always works.
+            // 2) Live-doc manual re-queue (job.retry() on a job the caller
+            //    just popped and wants back in pending). The live-doc path
+            //    is preserved from before 3.13.105.
+            //
+            // Returns __OK__ when either path acted; __NOT_FOUND__ when
+            // neither the DL nor the live doc existed, so Queue.retry(id)
+            // can now report the pre-3.13.105 blanket-true as false for
+            // unknown ids. data = JSON { id, delaySeconds }.
             const info = JSON.parse(data);
+            const dlTopic = queueName + ".dead_letter";
+            const now = new Date().toISOString();
             const avail = info.delaySeconds > 0
               ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
-              : new Date().toISOString();
-            await col.updateOne(
-              { queue: queueName, id: info.id },
-              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
-            );
-            process.stdout.write("__OK__");
+              : now;
+            const dlDoc = await col.findOne({ queue: dlTopic, id: info.id });
+            if (dlDoc !== null) {
+              await col.deleteOne({ _id: dlDoc._id });
+              const payload = dlDoc.payload ?? {};
+              const priority = dlDoc.priority ?? 0;
+              await col.updateOne(
+                { queue: queueName, id: info.id },
+                {
+                  $set: {
+                    status: "pending",
+                    availableAt: avail,
+                    reservedAt: null,
+                    error: null,
+                    payload,
+                    priority,
+                    id: info.id,
+                    createdAt: dlDoc.createdAt ?? now,
+                  },
+                  $inc: { attempts: 1 },
+                },
+                { upsert: true },
+              );
+              process.stdout.write("__OK__");
+            } else {
+              const result = await col.updateOne(
+                { queue: queueName, id: info.id },
+                { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+              );
+              process.stdout.write(result.matchedCount > 0 ? "__OK__" : "__NOT_FOUND__");
+            }
           }
           else if (operation === "deadLetters") {
             const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
@@ -28170,10 +28300,20 @@ var init_mongoBackend = __esm({
             process.stdout.write(String(revived));
           }
           else if (operation === "purge") {
-            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            // Delete docs by status (default: every doc for the topic).
+            // Pre-3.13.105 this filtered by { queue: queueName, status } for
+            // EVERY status -- correct for pending/reserved/completed, wrong
+            // for the dead-letter states (dead/failed/dead_letter) which
+            // live under queueName + ".dead_letter" and carry status "dead".
+            // A purge("dead") therefore deleted nothing and returned 0.
+            // data = JSON { status }.
             const info = data ? JSON.parse(data) : {};
-            const filter = { queue: queueName };
-            if (info.status) filter.status = info.status;
+            const isDead = info.status && ["dead", "failed", "dead_letter"].includes(info.status);
+            const filter = isDead
+              ? { queue: queueName + ".dead_letter" }
+              : (info.status
+                ? { queue: queueName, status: info.status }
+                : { queue: queueName });
             const res = await col.deleteMany(filter);
             process.stdout.write(String(res.deletedCount || 0));
           }
@@ -28270,9 +28410,15 @@ var init_mongoBackend = __esm({
       fail(queue, id, error, maxRetries, retryBackoff = 0) {
         this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
       }
-      /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+      /**
+       * Revive a specific dead-letter job by id. Returns true if the DL was found
+       * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+       * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+       * and Queue.retry(id) reported success for every call, even for unknown ids.
+       */
       retry(queue, id, delaySeconds = 0) {
-        this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        const out = this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        return out.includes("__OK__");
       }
       /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
       deadLetters(queue, maxRetries) {
@@ -28941,10 +29087,20 @@ var init_liteBackend = __esm({
        * Explicit re-queue requested by the caller (job.retry()).
        *
        * Always re-enqueues regardless of the retry limit — manual override,
-       * distinct from the automatic failJob() path.
+       * distinct from the automatic failJob() path. Cleans up BOTH the
+       * reservation record AND any dead-letter file for this id, so a caller
+       * that iterates deadLetters() and calls .retry() on each doesn't leave
+       * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+       * Aligns with retry(queue, jobId) which had always unlinked the
+       * dead-letter file -- two spellings of the same intent that previously
+       * diverged.
        */
       retryJob(queue, job, delaySeconds) {
         this.clearReservation(queue, job.id);
+        try {
+          unlinkSync7(join23(this.ensureFailedDir(queue), `${job.id}.queue-data`));
+        } catch {
+        }
         job.attempts = (job.attempts || 0) + 1;
         job.error = void 0;
         this.requeue(queue, job, delaySeconds ?? 0, void 0);
@@ -29143,7 +29299,19 @@ var init_queue = __esm({
         }
       }
       /**
-       * Count jobs filtered by status. Defaults to "pending".
+       * Count jobs by status. Defaults to "pending".
+       *
+       * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+       * but-attempted ones, because they live in the pending queue under the
+       * auto-retry lifecycle (see failed()).
+       * ``"reserved"`` counts jobs a consumer has popped but not yet
+       * completed/failed (in-flight against the visibility timeout).
+       * ``"completed"`` counts jobs the consumer has finished successfully.
+       * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+       * the dead-letter store -- jobs whose attempts >= maxRetries and that
+       * have given up. Use deadLetters() to list them. Retryable-but-attempted
+       * jobs are NOT counted by size("failed"); use failed() to list them or
+       * size("pending") to include them in a total.
        */
       size(status2 = "pending") {
         const q = this.topic;
@@ -29193,13 +29361,17 @@ var init_queue = __esm({
       /**
        * Get jobs that failed at least once but are still being retried
        * (0 < attempts < maxRetries). These live in the pending queue under the
-       * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+       * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+       * count and a retryBackoff delay) so pop() picks them up again. They are
+       * NOT counted by size("failed") -- that alias counts the dead-letter store,
+       * matching deadLetters(). To include retryable-failed jobs in a total, use
+       * size("pending"). Terminal failures are returned by deadLetters().
        */
       failed() {
-        if (this.externalBackend?.failed) {
-          return this.externalBackend.failed(this.topic, this._maxRetries);
-        }
-        return this.liteBackend.failed(this.topic, this._maxRetries);
+        const raw = this.externalBackend?.failed ? this.externalBackend.failed(this.topic, this._maxRetries) : this.liteBackend.failed(this.topic, this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Retry all dead letter jobs for this queue's topic.
@@ -29211,8 +29383,8 @@ var init_queue = __esm({
       retry(jobId, delaySeconds) {
         if (jobId) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, jobId, delaySeconds);
-            return true;
+            const result = this.externalBackend.retry(this.topic, jobId, delaySeconds);
+            return result === void 0 ? true : Boolean(result);
           }
           return this.liteBackend.retry(this.topic, jobId, delaySeconds);
         }
@@ -29221,8 +29393,8 @@ var init_queue = __esm({
         let retried = false;
         for (const job of deadJobs) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, job.id, delaySeconds);
-            retried = true;
+            const result = this.externalBackend.retry(this.topic, job.id, delaySeconds);
+            if (result === void 0 || Boolean(result)) retried = true;
           } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
             retried = true;
           }
@@ -29230,13 +29402,28 @@ var init_queue = __esm({
         return retried;
       }
       /**
-       * Get dead letter jobs — failed jobs that exceeded max retries.
+       * Get jobs that exceeded max_retries -- terminal failures.
+       *
+       * Same set counted by size("failed") / size("dead") / size("dead_letter")
+       * (three aliases for the dead-letter store). To LIST retryable-but-
+       * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+       * being auto-retried, use failed() -- those live in the pending queue and
+       * are NOT dead letters.
+       *
+       * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+       * so callers can iterate uniformly with the rest of the queue API and, in
+       * particular, call ``.retry()`` on each to manually revive it:
+       *
+       *     for (const job of queue.deadLetters()) {
+       *       Log.warn(`revived ${job.id}: ${job.error}`);
+       *       job.retry();
+       *     }
        */
       deadLetters(maxRetries) {
-        if (this.externalBackend?.deadLetters) {
-          return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
-        }
-        return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        const raw = this.externalBackend?.deadLetters ? this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries) : this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Delete messages by status (e.g. "completed", "failed", "dead").
@@ -35793,6 +35980,9 @@ function asHtmlString(chunk) {
   if (Buffer.isBuffer(chunk)) return chunk.toString("utf-8");
   return null;
 }
+function isInjectableHtml(res) {
+  return isHtmlResponse(res) && !res.raw.getHeader("content-encoding");
+}
 function injectIntoHtml(ctx, devToolbar, html) {
   if (!devToolbar) return injectFeedbackWidget(ctx.req, html);
   const toolbarCtx = {
@@ -35820,7 +36010,7 @@ function wrapResponseEnd(ctx) {
         Date.now() - ctx.reqStartTime
       );
     }
-    if (isHtmlResponse(res)) {
+    if (isInjectableHtml(res)) {
       const html = asHtmlString(chunk);
       if (html !== null) chunk = injectIntoHtml(ctx, devToolbar, html);
       if (!res.raw.headersSent) res.raw.removeHeader("content-length");