tina4-nodejs 3.13.32 → 3.13.34

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.32)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.34)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -946,7 +946,7 @@ The `tina4` Rust CLI is the sole file watcher for the Tina4 stack — there is n
 
 No configuration needed — set `TINA4_DEBUG=true` to enable. If you're running without the Rust CLI (e.g. Docker), there is no automatic reload; the production path is unaffected.
 
-**AI dual-port mode:** when `TINA4_DEBUG=true` and `TINA4_NO_AI_PORT` is unset, the main port suppresses reload/toolbar injection (so AI tools never trigger a refresh) and a second server on `port+1000` provides the normal hot-reload experience for browser testing.
+**AI dual-port mode:** when `TINA4_DEBUG=true` and `TINA4_NO_AI_PORT` is unset, the **main port** provides the normal hot-reload experience (dev toolbar + `/__dev_reload` injected) for the human dev, and a second server on `port+1000` is the **stable AI port** — it suppresses reload/toolbar injection (and returns 404 for `/__dev_reload`) so an AI tool can drive it without its own edits triggering a refresh. The `tina4` client posts `/__dev/api/reload` to the **main port**. Matches Python (master), PHP, and Ruby.
 
 ## Conventions You Must Follow
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.32",
+  "version": "3.13.34",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/cli/src/commands/init.ts

@@ -63,11 +63,11 @@ export async function initProject(name: string): Promise<void> {
         private: true,
         type: "module",
         scripts: {
-          dev: "tina4 serve",
-          serve: "tina4 serve",
+          dev: "npx tina4nodejs serve",
+          serve: "npx tina4nodejs serve",
         },
         dependencies: {
-          "tina4-nodejs": "^0.0.1",
+          "tina4-nodejs": "^3.0.0",
         },
         devDependencies: {
           typescript: "^5.7.0",

package/packages/core/src/index.ts

@@ -96,7 +96,7 @@ export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateC
 export type { AiTool } from "./ai.js";
 export type { ImapMessage, ImapFullMessage } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
-export { RabbitMQBackend } from "./queueBackends/rabbitmqBackend.js";
+export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
 export { KafkaBackend } from "./queueBackends/kafkaBackend.js";
 export type { KafkaConfig } from "./queueBackends/kafkaBackend.js";

package/packages/core/src/job.ts

@@ -48,12 +48,17 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
   const job: QueueJob = {
     ...data,
     complete() {
+      // Terminal — the job was already removed from the queue on pop().
       job.status = "completed";
     },
     fail(reason = "") {
+      // Record a failed attempt. `attempts` is incremented exactly once, inside
+      // the backend's failJob() — NOT here — so a persistently-failing job runs
+      // exactly maxRetries times before it is dead-lettered. The backend decides
+      // whether to re-enqueue (attempts < maxRetries) or dead-letter
+      // (attempts >= maxRetries).
       job.status = "failed";
       job.error = reason;
-      job.attempts = (job.attempts || 0) + 1;
       queue._failJob(job.topic, job, reason, queue.getMaxRetries());
     },
     reject(reason = "") {

package/packages/core/src/queue.ts

@@ -45,6 +45,12 @@ export interface QueueConfig {
   path?: string;
   topic?: string;
   maxRetries?: number;
+  /**
+   * Seconds to delay a failed job's automatic re-enqueue. 0 (the default)
+   * means retry immediately — the next pop()/consume() iteration picks it up
+   * straight away. Parity with Python's retry_backoff.
+   */
+  retryBackoff?: number;
 }
 
 export interface ProcessOptions {
@@ -75,6 +81,7 @@ export class Queue {
   private basePath: string;
   private topic: string;
   private _maxRetries: number;
+  private _retryBackoff: number;
   private externalBackend: QueueBackendInterface | null = null;
   private liteBackend!: LiteBackend;
 
@@ -104,6 +111,7 @@ export class Queue {
       ?? "data/queue";
     this.topic = resolvedConfig.topic ?? "default";
     this._maxRetries = resolvedConfig.maxRetries ?? 3;
+    this._retryBackoff = resolvedConfig.retryBackoff ?? 0;
     this.liteBackend = new LiteBackend(this.basePath);
 
     // Initialize external backends
@@ -234,10 +242,12 @@ export class Queue {
   }
 
   /**
-   * Get all failed jobs for this queue's topic.
+   * 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().
    */
   failed(): QueueJob[] {
-    return this.liteBackend.failed(this.topic);
+    return this.liteBackend.failed(this.topic, this._maxRetries);
   }
 
   /**
@@ -396,11 +406,17 @@ export class Queue {
     return this._maxRetries;
   }
 
+  getRetryBackoff(): number {
+    return this._retryBackoff;
+  }
+
   /**
-   * Move a job to the failed directory.
+   * Record a failed attempt for a job. The backend increments `attempts`
+   * exactly once and decides whether to re-enqueue (attempts < maxRetries,
+   * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
    */
   _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
-    this.liteBackend.failJob(queue, job, error, maxRetries);
+    this.liteBackend.failJob(queue, job, error, maxRetries, this._retryBackoff);
   }
 
   /**

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -5,8 +5,12 @@
  * for message storage and delivery.
  *
  * Configure via environment variables:
- *   TINA4_KAFKA_BROKERS   (default: "localhost:9092")
+ *   TINA4_QUEUE_URL       — broker list (strips a leading kafka:// if present)
+ *   TINA4_KAFKA_BROKERS   (override; default: "localhost:9092")
  *   TINA4_KAFKA_GROUP_ID  (default: "tina4_consumer_group")
+ *
+ * Precedence for brokers: specific TINA4_KAFKA_BROKERS var (if set)
+ *   > value derived from TINA4_QUEUE_URL > existing default.
  */
 import net from "node:net";
 import { execFileSync } from "node:child_process";
@@ -54,10 +58,25 @@ export class KafkaBackend implements QueueBackend {
   private groupId: string;
 
   constructor(config?: KafkaConfig) {
-    this.brokers = config?.brokers ?? process.env.TINA4_KAFKA_BROKERS ?? "localhost:9092";
+    // Base layer: brokers derived from TINA4_QUEUE_URL (strip a leading
+    // kafka:// scheme if present; otherwise use the value as-is, e.g.
+    // "localhost:9092").
+    const url = process.env.TINA4_QUEUE_URL;
+    const fromUrl = url ? url.replace(/^kafka:\/\//, "") : undefined;
+
+    // Precedence: explicit config arg > specific TINA4_KAFKA_BROKERS var
+    // > value from TINA4_QUEUE_URL > existing default.
+    this.brokers = config?.brokers ?? process.env.TINA4_KAFKA_BROKERS ?? fromUrl ?? "localhost:9092";
     this.groupId = config?.groupId ?? process.env.TINA4_KAFKA_GROUP_ID ?? "tina4_consumer_group";
   }
 
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): Required<KafkaConfig> {
+    return { brokers: this.brokers, groupId: this.groupId };
+  }
+
   /**
    * Parse broker string into host:port.
    */

package/packages/core/src/queueBackends/liteBackend.ts

@@ -1,6 +1,19 @@
 /**
  * LiteBackend — file-based queue backend for Tina4 Queue.
  * Stores jobs as JSON files on disk. Zero dependencies.
+ *
+ * Dequeue policy (parity with Python master): the highest-priority AVAILABLE
+ * job is returned first; ties are broken oldest-first by createdAt. The file
+ * *name* is no longer the ordering key — the stored `priority` and `createdAt`
+ * fields are. Delayed jobs (delayUntil in the future) are skipped until due.
+ *
+ * Failure lifecycle (parity with Python master): job.fail() records one failed
+ * attempt — `attempts` is incremented exactly once, here in failJob(). If the
+ * job still has retries left (attempts < maxRetries) it is automatically
+ * re-enqueued to the pending queue (immediately, or after retryBackoff seconds
+ * if configured) so the next pop()/consume() picks it up again. Once it has
+ * been attempted maxRetries times (attempts >= maxRetries) it is moved to the
+ * dead-letter (failed/) directory, where deadLetters() returns it.
  */
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -28,11 +41,15 @@ export class LiteBackend {
     return dir;
   }
 
+  private nextPrefix(): string {
+    this.seq++;
+    return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+  }
+
   push(queue: string, payload: unknown, delay?: number, priority?: number): string {
     const dir = this.ensureDir(queue);
     const id = randomUUID();
     const now = new Date().toISOString();
-    this.seq++;
 
     const job = {
       id,
@@ -42,48 +59,74 @@ export class LiteBackend {
       attempts: 0,
       delayUntil: delay ? new Date(Date.now() + delay * 1000).toISOString() : null,
       priority: priority ?? 0,
+      topic: queue,
+      error: undefined as string | undefined,
     };
 
-    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+    const prefix = this.nextPrefix();
     writeFileSync(join(dir, `${prefix}_${id}.queue-data`), JSON.stringify(job, null, 2));
     return id;
   }
 
-  pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
+  /**
+   * Return [filename, jobData] for every pending, non-delayed job, ordered by
+   * the dequeue policy: highest priority first, ties broken oldest-first by
+   * createdAt. createdAt is an ISO-8601 string, so lexicographic comparison ==
+   * chronological order.
+   */
+  private availableCandidates(queue: string, now: string): Array<[string, any]> {
     const dir = this.ensureDir(queue);
 
-    let files: string[];
+    let filenames: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
+      filenames = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
     } catch {
-      return null;
+      return [];
     }
 
-    const now = new Date().toISOString();
-
-    for (const file of files) {
-      const filePath = join(dir, file);
-      let job: QueueJob;
+    const candidates: Array<[string, any]> = [];
+    for (const filename of filenames) {
+      const filePath = join(dir, filename);
+      let job: any;
       try {
         job = JSON.parse(readFileSync(filePath, "utf-8"));
       } catch {
         continue;
       }
-
       if (job.status !== "pending") continue;
-      if (job.delayUntil && job.delayUntil > now) continue;
+      if (job.delayUntil && job.delayUntil > now) continue; // still delayed
+      candidates.push([filename, job]);
+    }
 
-      job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
-      writeFileSync(filePath, JSON.stringify(job, null, 2));
+    // priority DESC, then createdAt ASC (oldest first).
+    candidates.sort((a, b) => {
+      const pa = Number(a[1].priority ?? 0) || 0;
+      const pb = Number(b[1].priority ?? 0) || 0;
+      if (pb !== pa) return pb - pa;
+      const ca = (a[1].createdAt ?? "") as string;
+      const cb = (b[1].createdAt ?? "") as string;
+      return ca < cb ? -1 : ca > cb ? 1 : 0;
+    });
+
+    return candidates;
+  }
+
+  pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
+    const dir = this.ensureDir(queue);
+    const now = new Date().toISOString();
 
+    for (const [filename, job] of this.availableCandidates(queue, now)) {
+      const filePath = join(dir, filename);
+      // Claim the job by deleting the file.
       try {
         unlinkSync(filePath);
       } catch {
-        // Already consumed by another worker
+        continue; // Already consumed by another worker
       }
 
+      job.status = "reserved";
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
       return createJob(job as any, bridge);
     }
 
@@ -92,71 +135,52 @@ export class LiteBackend {
 
   popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
     const dir = this.ensureDir(queue);
-
-    let files: string[];
-    try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
-    } catch {
-      return [];
-    }
-
     const now = new Date().toISOString();
     const results: QueueJob[] = [];
 
-    for (const file of files) {
+    for (const [filename, job] of this.availableCandidates(queue, now)) {
       if (results.length >= count) break;
-      const filePath = join(dir, file);
-      let job: QueueJob;
+      const filePath = join(dir, filename);
       try {
-        job = JSON.parse(readFileSync(filePath, "utf-8"));
+        unlinkSync(filePath);
       } catch {
-        continue;
+        continue; // Already consumed by another worker
       }
 
-      if (job.status !== "pending") continue;
-      if (job.delayUntil && job.delayUntil > now) continue;
-
       job.status = "reserved";
       job.topic = queue;
       job.priority = job.priority ?? 0;
-      writeFileSync(filePath, JSON.stringify(job, null, 2));
-
-      try {
-        unlinkSync(filePath);
-      } catch {
-        // Already consumed by another worker
-      }
-
       results.push(createJob(job as any, bridge));
     }
 
     return results;
   }
 
+  // Status aliases that live in the failed/ directory (dead-lettered jobs)
+  // rather than as pending files in the queue directory.
+  private static readonly DEAD_STATES = ["failed", "dead", "dead_letter"];
+
   size(queue: string, status: string = "pending"): number {
-    if (status === "failed") {
-      const failedDir = this.ensureFailedDir(queue);
-      let files: string[];
-      try {
-        files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
-      } catch {
-        return 0;
-      }
-      return files.length;
-    }
+    const isDead = LiteBackend.DEAD_STATES.includes(status);
+    const scanDir = isDead ? this.ensureFailedDir(queue) : this.ensureDir(queue);
 
-    const dir = this.ensureDir(queue);
     let files: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+      files = readdirSync(scanDir).filter(f => f.endsWith(".queue-data"));
     } catch {
       return 0;
     }
 
+    if (isDead) {
+      // Every file in failed/ is a dead-letter; count them all regardless of
+      // the exact stored status string.
+      return files.length;
+    }
+
     let count = 0;
     for (const file of files) {
       try {
-        const job = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+        const job = JSON.parse(readFileSync(join(scanDir, file), "utf-8"));
         if (job.status === status) count++;
       } catch {
         // skip corrupt files
@@ -178,7 +202,7 @@ export class LiteBackend {
       // directory might not exist
     }
 
-    // Also clear failed jobs
+    // Also clear dead-letter jobs.
     const failedDir = join(dir, "failed");
     try {
       if (existsSync(failedDir)) {
@@ -194,16 +218,27 @@ export class LiteBackend {
     return count;
   }
 
-  failed(queue: string): QueueJob[] {
-    const failedDir = this.ensureFailedDir(queue);
+  /**
+   * Jobs that have failed at least once but are still being retried.
+   *
+   * Under the auto-retry lifecycle a failed-but-retryable job lives in the
+   * pending queue (not the dead-letter dir), so this scans the queue dir for
+   * pending jobs with attempts > 0 that have not yet exhausted their retries.
+   * Dead-lettered jobs are returned by deadLetters().
+   */
+  failed(queue: string, maxRetries: number = 3): QueueJob[] {
+    const dir = this.ensureDir(queue);
     const results: QueueJob[] = [];
 
     try {
-      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
+      const files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
       for (const file of files) {
         try {
-          const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-          results.push(job);
+          const job: QueueJob = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+          const attempts = job.attempts || 0;
+          if (attempts > 0 && attempts < maxRetries) {
+            results.push(job);
+          }
         } catch {
           // skip corrupt files
         }
@@ -215,6 +250,13 @@ export class LiteBackend {
     return results;
   }
 
+  /**
+   * Revive a specific dead-letter job by id back to the pending queue.
+   *
+   * Manual override (Queue.retry(jobId) / job.retry()) — always revives a
+   * dead-letter regardless of attempt count. Returns false only if no
+   * dead-letter with that id exists.
+   */
   retry(queue: string, jobId: string, delaySeconds?: number): boolean {
     try {
       const queues = readdirSync(this.basePath);
@@ -227,10 +269,10 @@ export class LiteBackend {
           job.status = "pending";
           job.attempts = (job.attempts || 0) + 1;
           job.error = undefined;
+          job.createdAt = new Date().toISOString();
           job.delayUntil = delaySeconds ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null;
 
-          this.seq++;
-          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          const prefix = this.nextPrefix();
           const queueDir = join(this.basePath, q);
           writeFileSync(join(queueDir, `${prefix}_${jobId}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
@@ -270,38 +312,19 @@ export class LiteBackend {
 
   purge(queue: string, status: string, maxRetries: number = 3): number {
     let count = 0;
+    const isDead = LiteBackend.DEAD_STATES.includes(status);
 
-    if (status === "dead") {
-      const failedDir = this.ensureFailedDir(queue);
-      try {
-        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
-        for (const file of files) {
-          try {
-            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-            if ((job.attempts || 0) >= maxRetries) {
-              unlinkSync(join(failedDir, file));
-              count++;
-            }
-          } catch {
-            // skip corrupt files
-          }
-        }
-      } catch {
-        // directory might not exist
-      }
-    } else if (status === "failed") {
+    if (isDead) {
+      // Every file in failed/ is a dead-letter — purge them all.
       const failedDir = this.ensureFailedDir(queue);
       try {
         const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
         for (const file of files) {
           try {
-            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-            if ((job.attempts || 0) < maxRetries) {
-              unlinkSync(join(failedDir, file));
-              count++;
-            }
+            unlinkSync(join(failedDir, file));
+            count++;
           } catch {
-            // skip corrupt files
+            // already removed
           }
         }
       } catch {
@@ -330,6 +353,11 @@ export class LiteBackend {
     return count;
   }
 
+  /**
+   * Re-queue dead-letter jobs that are under the (possibly raised) limit back
+   * to pending. Mirrors Python retry_failed(): a job dead-lettered at the
+   * original maxRetries needs a raised limit to qualify again.
+   */
   retryFailed(queue: string, maxRetries: number = 3): number {
     const failedDir = this.ensureFailedDir(queue);
     const queueDir = this.ensureDir(queue);
@@ -348,9 +376,10 @@ export class LiteBackend {
 
           job.status = "pending";
           job.error = undefined;
+          job.createdAt = new Date().toISOString();
+          job.delayUntil = null;
 
-          this.seq++;
-          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          const prefix = this.nextPrefix();
           writeFileSync(join(queueDir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
           count++;
@@ -376,6 +405,7 @@ export class LiteBackend {
     }
 
     for (const file of files) {
+      if (!file.includes(id)) continue;
       const filePath = join(dir, file);
       let job: QueueJob;
       try {
@@ -394,24 +424,79 @@ export class LiteBackend {
     return null;
   }
 
-  failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+  /**
+   * Write the job back to the pending queue (queue dir).
+   *
+   * Re-enqueued jobs get a fresh createdAt so that within a priority tier they
+   * sort behind jobs that have not yet been attempted. `attempts` already
+   * reflects the latest failure count. The job carries its prior error.
+   */
+  private requeue(queue: string, job: QueueJob, delaySeconds: number = 0, error?: string): void {
+    const dir = this.ensureDir(queue);
+    const jobData = {
+      id: job.id,
+      payload: job.payload,
+      status: "pending" as const,
+      createdAt: new Date().toISOString(),
+      attempts: job.attempts ?? 0,
+      delayUntil: delaySeconds > 0 ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null,
+      priority: job.priority ?? 0,
+      topic: job.topic,
+      error,
+    };
+    const prefix = this.nextPrefix();
+    writeFileSync(join(dir, `${prefix}_${job.id}.queue-data`), JSON.stringify(jobData, null, 2));
+  }
+
+  /**
+   * Move the job to the dead-letter (failed/) directory. Terminal until a
+   * manual retryFailed()/retry() revives it.
+   */
+  private deadLetter(queue: string, job: QueueJob, error?: string): void {
     const failedDir = this.ensureFailedDir(queue);
-    job.status = "failed";
+    const jobData = {
+      id: job.id,
+      payload: job.payload,
+      status: "dead" as const,
+      createdAt: job.createdAt,
+      attempts: job.attempts ?? 0,
+      delayUntil: null,
+      priority: job.priority ?? 0,
+      topic: job.topic,
+      error,
+      failedAt: new Date().toISOString(),
+    };
+    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(jobData, null, 2));
+  }
+
+  /**
+   * Record a failed attempt.
+   *
+   * Increments `attempts` exactly once (the increment lives here, NOT in
+   * job.ts — see the double-increment fix). If the job still has retries left
+   * (attempts < maxRetries) it is automatically re-enqueued to pending, after
+   * an optional retryBackoff delay. Once it has been attempted maxRetries times
+   * (attempts >= maxRetries) it is moved to the dead-letter store.
+   */
+  failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff: number = 0): void {
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
-
-    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(job, null, 2));
+    if (job.attempts < maxRetries) {
+      this.requeue(queue, job, retryBackoff, error);
+    } else {
+      this.deadLetter(queue, job, error);
+    }
   }
 
+  /**
+   * 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.
+   */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
-    const dir = this.ensureDir(queue);
-    job.status = "pending";
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
-    job.delayUntil = delaySeconds ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null;
-
-    this.seq++;
-    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
-    writeFileSync(join(dir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
+    this.requeue(queue, job, delaySeconds ?? 0, undefined);
   }
 }

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -5,13 +5,18 @@
  * for message storage and delivery. Atomic pop via findOneAndUpdate.
  *
  * Configure via environment variables:
+ *   TINA4_QUEUE_URL        — connection URI (mongodb://...)
+ *   TINA4_MONGO_URI        (override; wins over TINA4_QUEUE_URL)
  *   TINA4_MONGO_HOST       (default: "localhost")
  *   TINA4_MONGO_PORT       (default: 27017)
- *   TINA4_MONGO_URI        (overrides host/port/username/password)
  *   TINA4_MONGO_USERNAME   (optional)
  *   TINA4_MONGO_PASSWORD   (optional)
  *   TINA4_MONGO_DB         (default: "tina4")
  *   TINA4_MONGO_COLLECTION (default: "tina4_queue")
+ *
+ * Precedence for the connection URI: explicit config.uri
+ *   > TINA4_MONGO_URI > TINA4_QUEUE_URL > a URI built from the
+ *   TINA4_MONGO_HOST/PORT/USERNAME/PASSWORD field vars (existing defaults).
  */
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
@@ -63,9 +68,11 @@ export class MongoBackend implements QueueBackend {
     this.database = config?.database ?? process.env.TINA4_MONGO_DB ?? "tina4";
     this.collection = config?.collection ?? process.env.TINA4_MONGO_COLLECTION ?? "tina4_queue";
 
-    // URI overrides individual host/port/auth settings
-    if (config?.uri ?? process.env.TINA4_MONGO_URI) {
-      this.uri = config?.uri ?? process.env.TINA4_MONGO_URI!;
+    // Connection URI precedence: explicit config.uri > TINA4_MONGO_URI
+    // > TINA4_QUEUE_URL > a URI built from the host/port/auth field vars.
+    const explicitUri = config?.uri ?? process.env.TINA4_MONGO_URI ?? process.env.TINA4_QUEUE_URL;
+    if (explicitUri) {
+      this.uri = explicitUri;
     } else {
       const auth = this.username
         ? `${encodeURIComponent(this.username)}:${encodeURIComponent(this.password)}@`
@@ -74,6 +81,13 @@ export class MongoBackend implements QueueBackend {
     }
   }
 
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): { uri: string; database: string; collection: string } {
+    return { uri: this.uri, database: this.database, collection: this.collection };
+  }
+
   /**
    * Execute a MongoDB operation synchronously via a child process.
    */

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -5,11 +5,15 @@
  * for message storage and delivery.
  *
  * Configure via environment variables:
- *   TINA4_RABBITMQ_HOST     (default: "localhost")
- *   TINA4_RABBITMQ_PORT     (default: 5672)
- *   TINA4_RABBITMQ_USERNAME (default: "guest")
- *   TINA4_RABBITMQ_PASSWORD (default: "guest")
- *   TINA4_RABBITMQ_VHOST    (default: "/")
+ *   TINA4_QUEUE_URL         — AMQP URL (amqp://[user:pass@]host:port[/vhost])
+ *   TINA4_RABBITMQ_HOST     (override; default: "localhost")
+ *   TINA4_RABBITMQ_PORT     (override; default: 5672)
+ *   TINA4_RABBITMQ_USERNAME (override; default: "guest")
+ *   TINA4_RABBITMQ_PASSWORD (override; default: "guest")
+ *   TINA4_RABBITMQ_VHOST    (override; default: "/")
+ *
+ * Precedence per field: specific TINA4_RABBITMQ_* var (if set)
+ *   > value derived from TINA4_QUEUE_URL > existing default.
  */
 import net from "node:net";
 import { execFileSync } from "node:child_process";
@@ -26,6 +30,51 @@ export interface RabbitMQConfig {
   vhost?: string;
 }
 
+/**
+ * Parse an AMQP URL (amqp://[user:pass@]host[:port][/vhost]) into a partial
+ * RabbitMQConfig. Mirrors the Python/PHP/Ruby `parse_amqp_url` semantics:
+ * strips a leading amqp:// or amqps:// scheme, splits optional credentials,
+ * and prepends a leading "/" to the vhost when missing. Only fields present
+ * in the URL are populated.
+ */
+export function parseAmqpUrl(url: string): RabbitMQConfig {
+  const config: RabbitMQConfig = {};
+  let rest = url.replace(/^amqps:\/\//, "").replace(/^amqp:\/\//, "");
+
+  const atIndex = rest.indexOf("@");
+  if (atIndex !== -1) {
+    const creds = rest.slice(0, atIndex);
+    rest = rest.slice(atIndex + 1);
+    const colonIndex = creds.indexOf(":");
+    if (colonIndex !== -1) {
+      config.username = creds.slice(0, colonIndex);
+      config.password = creds.slice(colonIndex + 1);
+    } else {
+      config.username = creds;
+    }
+  }
+
+  let hostport = rest;
+  const slashIndex = rest.indexOf("/");
+  if (slashIndex !== -1) {
+    hostport = rest.slice(0, slashIndex);
+    const vhost = rest.slice(slashIndex + 1);
+    if (vhost) {
+      config.vhost = vhost.startsWith("/") ? vhost : "/" + vhost;
+    }
+  }
+
+  const portColon = hostport.indexOf(":");
+  if (portColon !== -1) {
+    config.host = hostport.slice(0, portColon);
+    config.port = parseInt(hostport.slice(portColon + 1), 10);
+  } else if (hostport) {
+    config.host = hostport;
+  }
+
+  return config;
+}
+
 export interface QueueBackend {
   push(queue: string, payload: unknown, delay?: number): string;
   pop(queue: string): QueueJob | null;
@@ -133,12 +182,32 @@ export class RabbitMQBackend implements QueueBackend {
   private vhost: string;
 
   constructor(config?: RabbitMQConfig) {
-    this.host = config?.host ?? process.env.TINA4_RABBITMQ_HOST ?? "localhost";
+    // Base layer: values derived from TINA4_QUEUE_URL (parsed as an AMQP URL).
+    const url = process.env.TINA4_QUEUE_URL;
+    const fromUrl = url ? parseAmqpUrl(url) : {};
+
+    // Precedence per field: explicit config arg > specific TINA4_RABBITMQ_* var
+    // > value from TINA4_QUEUE_URL > existing default.
+    this.host = config?.host ?? process.env.TINA4_RABBITMQ_HOST ?? fromUrl.host ?? "localhost";
     this.port = config?.port
-      ?? (process.env.TINA4_RABBITMQ_PORT ? parseInt(process.env.TINA4_RABBITMQ_PORT, 10) : 5672);
-    this.username = config?.username ?? process.env.TINA4_RABBITMQ_USERNAME ?? "guest";
-    this.password = config?.password ?? process.env.TINA4_RABBITMQ_PASSWORD ?? "guest";
-    this.vhost = config?.vhost ?? process.env.TINA4_RABBITMQ_VHOST ?? "/";
+      ?? (process.env.TINA4_RABBITMQ_PORT ? parseInt(process.env.TINA4_RABBITMQ_PORT, 10) : undefined)
+      ?? fromUrl.port ?? 5672;
+    this.username = config?.username ?? process.env.TINA4_RABBITMQ_USERNAME ?? fromUrl.username ?? "guest";
+    this.password = config?.password ?? process.env.TINA4_RABBITMQ_PASSWORD ?? fromUrl.password ?? "guest";
+    this.vhost = config?.vhost ?? process.env.TINA4_RABBITMQ_VHOST ?? fromUrl.vhost ?? "/";
+  }
+
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): Required<RabbitMQConfig> {
+    return {
+      host: this.host,
+      port: this.port,
+      username: this.username,
+      password: this.password,
+      vhost: this.vhost,
+    };
   }
 
   /**

package/packages/core/src/server.ts

@@ -1379,17 +1379,11 @@ ${reset}
   // Assign to module-level so handle() can dispatch without a server reference
   _dispatchFn = dispatch;
 
-  // When dual-port is active (debug mode + no TINA4_NO_AI_PORT), tag main port requests
-  // as AI port to suppress reload/toolbar injection. Test port (port+1000) gets full reload.
-  const _dualPortActive = isTruthy(process.env.TINA4_DEBUG ?? "") &&
-    !isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
-  const mainPortDispatch = _dualPortActive
-    ? async (req: IncomingMessage, res: ServerResponse) => {
-        (req as any)._tina4AiPort = true;
-        await dispatch(req, res);
-      }
-    : dispatch;
-  const server = createServer(mainPortDispatch);
+  // Dual-port (debug + no TINA4_NO_AI_PORT): the MAIN port hot-reloads for the human
+  // dev; the stable AI port (port+1000, created below) suppresses reload/toolbar so an
+  // AI tool can drive it without its own edits triggering refreshes. The tina4 client
+  // posts /__dev/api/reload to the MAIN port. Matches Python (master).
+  const server = createServer(dispatch);
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {
@@ -1405,16 +1399,17 @@ ${reset}
       // Determine server mode label
       const serverMode = isDebug ? "single" : (cluster.isWorker ? "cluster-worker" : "single");
 
-      // AI dual-port: main port = AI dev port (no reload), port+1000 = user testing port (hot-reload)
-      // When TINA4_DEBUG=true and TINA4_NO_AI_PORT is not set, main server suppresses reload/toolbar
-      // and a second server on port+1000 provides the normal hot-reload experience.
+      // AI dual-port: main port = hot-reload (human dev); port+1000 = stable AI port
+      // (reload/toolbar suppressed) so an AI tool can drive it without its edits
+      // triggering refreshes. The tina4 client fires reloads at the MAIN port. Matches Python.
       const noAiPort = isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
       let aiServer: ReturnType<typeof createServer> | null = null;
       let testPort = port + 1000;
 
       if (isDebug && !noAiPort) {
-        // Test port (port+1000): normal dispatch with full hot-reload
+        // Stable AI port (port+1000): tag requests so /__dev_reload + toolbar are suppressed.
         aiServer = createServer(async (req, res) => {
+          (req as any)._tina4AiPort = true;
           await dispatch(req, res);
         });
 
@@ -1451,11 +1446,8 @@ ${reset}
       }
       const noBrowser = isTruthy(process.env.TINA4_NO_BROWSER);
       if (!noBrowser) {
-        // Open browser on test port (hot-reload) if available, otherwise main port
-        const browserTarget = (isDebug && !noAiPort && aiServer)
-          ? `http://${displayHost}:${testPort}`
-          : `http://${displayHost}:${port}`;
-        openBrowser(browserTarget);
+        // Open the browser on the MAIN port — that's the hot-reload port.
+        openBrowser(`http://${displayHost}:${port}`);
       }
       resolvePromise({
         close: () => {