tina4-nodejs 3.13.148 → 3.13.150

package/packages/core/src/devAdmin.ts

@@ -30,6 +30,7 @@ import { fullAnalysis, fileDetail, MetricsEngineError, metricsScanRoot } from ".
 import { registerFeedbackRoutes } from "./feedback.js";
 import { getDefaultDevServer, mcpEnabled, isRequestAllowed, isLoopback } from "./mcp.js";
 import { timingSafeEqual } from "node:crypto";
+import net from "node:net";
 // VERSION-DEC-01 (feature 130): the dashboard reads the SAME resolved version
 // as server.ts's banner/health and mcp.ts's default dev server -- one shared
 // walk-up resolver in ./version.ts, not this file's own two-fixed-path reader
@@ -55,6 +56,11 @@ export const DEV_SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
  */
 const DEV_MCP_PREFIXES = ["/__dev/api/mcp", "/__dev/mcp"];
 
+// Static dev-toolbar assets that carry no secrets and expose no actions, so the
+// peer gate does not cover them: wherever the toolbar is injected its stylesheet
+// and script must load (issue #279). Host + same-origin still apply.
+const DEV_PUBLIC_ASSETS = new Set(["/__dev/toolbar.css", "/__dev/toolbar.js"]);
+
 /** Private-key / credential basenames the file endpoints must never serve. */
 const DEV_SECRET_BASENAMES = new Set([
   ".env", ".envrc", "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519",
@@ -139,6 +145,65 @@ export function devHostAllowed(hostHeader: string | undefined | null): boolean {
   return allowed.has(name);
 }
 
+/**
+ * True when raw peer `ip` falls inside `entry` (a bare IP or a CIDR). IPv4 and
+ * IPv6 via node:net's BlockList; an IPv4-mapped IPv6 peer (::ffff:a.b.c.d) is
+ * matched as IPv4. `ip` is the real socket peer, `entry` is operator config -
+ * never a forwarded header.
+ */
+export function ipInCidr(ip: string, entry: string): boolean {
+  try {
+    ip = (ip ?? "").trim();
+    if (ip.toLowerCase().startsWith("::ffff:")) ip = ip.slice(7); // mapped -> IPv4
+    const ipFam = net.isIP(ip);
+    if (!ipFam) return false;
+    entry = (entry ?? "").trim();
+    const bl = new net.BlockList();
+    if (entry.includes("/")) {
+      const [addr, bitsStr] = entry.split("/");
+      const bits = Number(bitsStr);
+      const fam = net.isIP(addr);
+      if (!fam || !Number.isInteger(bits)) return false;
+      bl.addSubnet(addr, bits, fam === 4 ? "ipv4" : "ipv6");
+    } else {
+      const fam = net.isIP(entry);
+      if (!fam) return false;
+      bl.addAddress(entry, fam === 4 ? "ipv4" : "ipv6");
+    }
+    return bl.check(ip, ipFam === 4 ? "ipv4" : "ipv6");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the RAW socket peer may reach /__dev: loopback always, plus any
+ * IP/CIDR in TINA4_DEV_ALLOWED_PEERS (comma-separated, opt-in, default none).
+ * Reads the real socket peer ONLY, never a forwarded header, so it cannot be
+ * spoofed by X-Forwarded-For. The documented way to reach the dev dashboard from
+ * a Docker dev box, where requests arrive from the container-network gateway
+ * rather than loopback (issue #279).
+ */
+export function devPeerAllowed(remoteIp: string | undefined | null): boolean {
+  const ip = (remoteIp ?? "").trim();
+  if (isLoopback(ip)) return true;
+  const configured = (process.env.TINA4_DEV_ALLOWED_PEERS ?? "").trim();
+  if (!configured) return false;
+  return configured.split(",").some((entry) => entry.trim() !== "" && ipInCidr(ip, entry));
+}
+
+/**
+ * True when the toolbar may be injected for this viewer - the Host allow-list
+ * and the raw-peer gate both pass. A viewer the /__dev gate would refuse gets NO
+ * toolbar markup, so its stylesheet and script are never requested only to 403
+ * (issue #279).
+ */
+export function devToolbarAllowed(req: Tina4Request): boolean {
+  if (!devHostAllowed(req.header("host"))) return false;
+  const peer = (req as unknown as { socket?: { remoteAddress?: string } }).socket?.remoteAddress ?? "";
+  return devPeerAllowed(peer);
+}
+
 /**
  * Return `{status, error}` to REFUSE any /__dev request (read or write), or
  * `null` to allow (ADR-0082): Host allow-list, then same-origin, then the
@@ -155,9 +220,15 @@ export function devRequestDenial(req: Tina4Request): { status: number; error: st
   if (!devSameOriginOk(req)) {
     return { status: 403, error: "dev-admin: refused (cross-origin request)" };
   }
+  // The static toolbar assets are exempt from the peer gate (#279): they carry
+  // no secrets and the toolbar needs them wherever it is injected. Host +
+  // same-origin above still apply.
+  if (DEV_PUBLIC_ASSETS.has(path)) {
+    return null;
+  }
   if (!isMcp) {
     const peer = (req as unknown as { socket?: { remoteAddress?: string } }).socket?.remoteAddress ?? "";
-    if (!(isLoopback(peer) || mcpTokenOk(req, true))) {
+    if (!(devPeerAllowed(peer) || mcpTokenOk(req, true))) {
       return { status: 403, error: "dev-admin: refused (non-loopback peer)" };
     }
   }
@@ -759,6 +830,7 @@ export class DevAdmin {
       { method: "GET", pattern: "/__dev/api/docs/.well-known.json", handler: handleDocsWellKnown },
       // JS asset
       { method: "GET", pattern: "/__dev/js/tina4-dev-admin.min.js", handler: handleDevAdminJs },
+      { method: "GET", pattern: "/__dev/split", handler: handleDevAdminSplit },
       // Dev-toolbar assets — served as external CSS/JS so the injected toolbar is
       // CSP-clean (no inline style=, onclick=, or <script>) under a strict
       // `default-src 'self'`. Parity with PHP's /__dev/toolbar.css + toolbar.js.
@@ -3068,6 +3140,38 @@ const handleDevAdminJs: RouteHandler = async (_req, res) => {
   res.raw.end("tina4-dev-admin.min.js not found");
 };
 
+// ---------------------------------------------------------------------------
+// Dev Admin split view — the shared asset (same file python/php/ruby serve)
+// ---------------------------------------------------------------------------
+
+const handleDevAdminSplit: RouteHandler = async (_req, res) => {
+  const { readFileSync, existsSync } = await import("node:fs");
+  const { dirname, join, resolve } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  const dir = dirname(fileURLToPath(import.meta.url));
+
+  const candidates = [
+    join(dir, "..", "public", "js", "tina4-dev-admin-split.html"),
+    join(dir, "..", "..", "public", "js", "tina4-dev-admin-split.html"),
+    resolve(process.cwd(), "node_modules", "tina4-nodejs", "packages", "core", "public", "js", "tina4-dev-admin-split.html"),
+    resolve(process.cwd(), "public", "js", "tina4-dev-admin-split.html"),
+  ];
+
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      try {
+        const content = readFileSync(path, "utf-8");
+        res.raw.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+        res.raw.end(content);
+        return;
+      } catch { /* try next */ }
+    }
+  }
+
+  res.raw.writeHead(404, { "Content-Type": "text/plain" });
+  res.raw.end("tina4-dev-admin-split.html not found");
+};
+
 // ---------------------------------------------------------------------------
 // Overlay script — floating Tina4 button
 // ---------------------------------------------------------------------------

package/packages/core/src/index.ts

@@ -113,6 +113,9 @@ export { DevMailbox } from "./devMailbox.js";
 export { WSDLService, WSDLOperation } from "./wsdl.js";
 export type { WSDLOperationMeta } from "./wsdl.js";
 export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htmlElement.js";
+// Crud (ADR-0094) lives in @tina4/orm, not core: it is an opt-in feature, not on
+// every request path, so it must not enter core's eager import graph
+// (lazyFeatureLoading). Import it from "tina4-nodejs/orm".
 export { renderErrorOverlay, isDebugMode } from "./errorOverlay.js";
 export {
   cspNonce,

package/packages/core/src/messenger.ts

@@ -70,6 +70,52 @@ type SmtpTransport = "implicit_tls" | "starttls" | "plain";
 const SMTP_SEND_TIMEOUT_MS = 30_000;
 const SMTP_CHECK_TIMEOUT_MS = 10_000;
 
+/** Raw TINA4_MAIL_TIMEOUT values already warned about, so a bad one is said once. */
+const _timeoutWarned = new Set<string>();
+
+/**
+ * Resolve the SMTP send timeout in MILLISECONDS (issue #278). Priority:
+ * constructor (seconds) > TINA4_MAIL_TIMEOUT (seconds) > 30. Whole seconds, at
+ * least 1. An explicit constructor value is the caller's own instruction, so one
+ * that is not a whole second >= 1 is a programming error and THROWS. A bad env
+ * value is a misconfiguration: warn once and use the default. Zero and negative
+ * are garbage, not an opt-out. Mirrors the PHP master (Messenger::resolveTimeout,
+ * tina4-php#286); the SMTP_TIMEOUT fallback was dropped for parity.
+ */
+const DEFAULT_TIMEOUT_SECONDS = 30;
+
+function resolveSendTimeoutMs(optionTimeout?: number): number {
+  if (optionTimeout === undefined || optionTimeout === null) {
+    return resolveEnvTimeoutSeconds(process.env.TINA4_MAIL_TIMEOUT) * 1000;
+  }
+  if (!Number.isInteger(optionTimeout) || optionTimeout < 1) {
+    throw new Error(
+      `Messenger timeout must be a whole number of seconds and at least 1, got ${optionTimeout}.`,
+    );
+  }
+  return optionTimeout * 1000;
+}
+
+/** TINA4_MAIL_TIMEOUT in whole seconds; a blank value, or garbage/< 1 (warned once), is the default. */
+function resolveEnvTimeoutSeconds(raw?: string): number {
+  if (!raw || raw.trim() === "") return DEFAULT_TIMEOUT_SECONDS;
+  const trimmed = raw.trim();
+  const seconds = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+  if (Number.isInteger(seconds) && seconds >= 1) return seconds;
+  warnBadMailTimeout(raw);
+  return DEFAULT_TIMEOUT_SECONDS;
+}
+
+/** Warn once per distinct bad TINA4_MAIL_TIMEOUT value. */
+function warnBadMailTimeout(raw: string): void {
+  if (_timeoutWarned.has(raw)) return;
+  _timeoutWarned.add(raw);
+  Log.warning(
+    `TINA4_MAIL_TIMEOUT must be a whole number of seconds and at least 1, got ${JSON.stringify(raw)} ` +
+      `- using the default of ${DEFAULT_TIMEOUT_SECONDS} seconds`,
+  );
+}
+
 /**
  * Give a socket an idle timeout that fails it with a clear error. Without one a
  * client that waits for a greeting the server never sends (a plaintext client
@@ -194,6 +240,8 @@ interface MessengerOptions {
   imapPass?: string;
   /** IMAP transport security: "tls" (default), "starttls", or "none". */
   imapEncryption?: string;
+  /** SMTP send timeout in whole SECONDS, at least 1 (default 30; env TINA4_MAIL_TIMEOUT). */
+  timeout?: number;
 }
 
 export interface ImapMessage {
@@ -466,6 +514,8 @@ export class Messenger {
   private imapUser: string;
   private imapPass: string;
   private imapEncryption: string;
+  /** Resolved SMTP send timeout, in milliseconds (see the constructor). */
+  public readonly timeoutMs: number;
 
   constructor(options?: MessengerOptions) {
     // Priority: constructor > TINA4_MAIL_* > sensible default.
@@ -527,6 +577,12 @@ export class Messenger {
     this.imapEncryption = normaliseEncryption(options?.imapEncryption
       ?? process.env.TINA4_MAIL_IMAP_ENCRYPTION
       ?? "tls", "IMAP");
+
+    // SMTP send timeout (whole seconds, at least 1): constructor >
+    // TINA4_MAIL_TIMEOUT > 30. An explicit sub-second value throws; a bad env
+    // value warns once and uses the default. Stored as ms, the unit
+    // openSmtpSession/failOnIdle want. Parity with the PHP/Python/Ruby master.
+    this.timeoutMs = resolveSendTimeoutMs(options?.timeout);
   }
 
   /**
@@ -671,7 +727,7 @@ export class Messenger {
   private async sendSmtp(options: SendOptions, recipients: MailRecipients, messageId: string): Promise<SendResult> {
     let socket: SmtpSocket | null = null;
     try {
-      socket = await this.openSmtpSession();
+      socket = await this.openSmtpSession(this.timeoutMs);
       await this.authenticateSmtp(socket);
       await this.sendSmtpEnvelope(socket, recipients.allRecipients);
       await this.sendSmtpMessage(socket, options, recipients, messageId);

package/packages/core/src/metrics.ts

@@ -69,7 +69,11 @@ export function enginePath(): string | null {
 function runEngine(target: string): Record<string, any> {
   const binary = enginePath();
   if (!binary) throw new MetricsEngineError(`tina4 not found on PATH - ${INSTALL_HINT}`);
-  const processResult = spawnSync(binary, ["metrics", "--path", target, "--json"], {
+  // --no-history: a dashboard READ must never write .tina4-metrics.json.
+  // Without it every scan records history, the file watcher sees the write and
+  // reloads the page, which re-scans - a self-inflicted ~2-second reload loop
+  // that makes the dashboard unusable.
+  const processResult = spawnSync(binary, ["metrics", "--path", target, "--json", "--no-history"], {
     encoding: "utf8",
     timeout: 60_000,
     maxBuffer: 64 * 1024 * 1024,

package/packages/core/src/plan.ts

@@ -533,7 +533,7 @@ export const Plan = {
     const title = currentPlan.title || target;
     const goal = currentPlan.goal || "";
 
-    const aiUrl = process.env.TINA4_AI_URL || "http://localhost:11437/api/chat";
+    const aiUrl = process.env.TINA4_AI_URL || "http://localhost:11435/api/chat";
     const aiModel = process.env.TINA4_AI_MODEL || "qwen2.5-coder:14b";
     const prompts = fleshPrompt(title, goal, existing, prompt);
     const fetched = await fetchFleshReply(aiUrl, aiModel, prompts);

package/packages/core/src/router.ts

@@ -956,8 +956,18 @@ export async function runRouteMiddlewares(
  * Default global router instance.
  * Top-level get(), post(), etc. register routes here.
  * The server merges these routes on startup.
+ *
+ * Anchored on globalThis so it is a true single instance across bundles. The
+ * published package ships each workspace as its own esbuild bundle, so
+ * @tina4/orm carries an inlined copy of this module; without this, orm code
+ * (e.g. Crud.registerBackend, ADR-0094) would add AutoCrud routes to a second,
+ * private Router that the core server never serves. One globalThis slot makes
+ * every copy resolve to the same instance.
  */
-export const defaultRouter = new Router();
+const TINA4_DEFAULT_ROUTER = Symbol.for("tina4.defaultRouter");
+const globalRouterHost = globalThis as unknown as { [TINA4_DEFAULT_ROUTER]?: Router };
+export const defaultRouter: Router =
+  globalRouterHost[TINA4_DEFAULT_ROUTER] ?? (globalRouterHost[TINA4_DEFAULT_ROUTER] = new Router());
 
 /**
  * Top-level route registration functions — mirrors Python's decorator pattern.

package/packages/core/src/server.ts

@@ -46,7 +46,7 @@ import { generateNonce, runWithCspNonce, currentCspNonce } from "./csp.js";
 import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
-import { DevAdmin, RequestInspector, WsTracker, devRequestDenial, devHostAllowed } from "./devAdmin.js";
+import { DevAdmin, RequestInspector, WsTracker, devRequestDenial, devHostAllowed, devToolbarAllowed } from "./devAdmin.js";
 import { CLOSE_GOING_AWAY, devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
@@ -1311,7 +1311,10 @@ function isInjectableHtml(res: Tina4Response): boolean {
  * so calling it unconditionally is cheap when it no-ops.
  */
 function injectIntoHtml(ctx: ResponseWrapContext, devToolbar: boolean, html: string): string {
-  if (!devToolbar) return injectFeedbackWidget(ctx.req, html);
+  // Do not inject the toolbar for a viewer the /__dev gate would refuse (#279):
+  // otherwise the page carries toolbar markup whose stylesheet and script 403.
+  // The feedback widget still runs (it re-checks its own gate).
+  if (!devToolbar || !devToolbarAllowed(ctx.req)) return injectFeedbackWidget(ctx.req, html);
 
   const toolbarCtx: DevToolbarContext = {
     version: TINA4_VERSION,

package/packages/core/templates/crud/form.twig

@@ -0,0 +1,26 @@
+{#
+  crud/form.twig — the create/edit field inputs (and the public generateForm).
+
+  Override: drop your own src/templates/crud/form.twig to change how inputs render.
+
+  fields - one per input: { id, name, label, value, placeholder, required_attr,
+           and exactly ONE control flag: input (with type) | textarea | checkbox
+           (checked_attr) | select (options_html) }.
+  wrap        - render the <form> wrapper; form_id_attr/action/form_method set it
+  edit        - add the hidden primary-key input (edit modal)
+  modal_footer- render the Cancel/Save modal buttons; submit_button - a plain Submit
+
+  No inline styles or on*= handlers: the modal buttons carry data-crud-action and
+  are wired by the page script's delegated listener (ADR-0088).
+#}
+{% if wrap %}<form{{ form_id_attr|raw }} action="{{ action }}" method="{{ form_method }}" class="needs-validation" data-crud-form="1">{% endif %}
+{% if method_override %}<input type="hidden" name="_method" value="{{ method_override }}">{% endif %}
+{% if edit %}<input type="hidden" id="{{ mode }}-pk-value" name="{{ pk }}">{% endif %}
+{% if modal_footer %}<div class="crud-errors" data-crud-errors hidden></div>{% endif %}
+{% for field in fields %}<div class="mb-3">
+<label for="{{ field.id }}" class="form-label">{{ field.label }}</label>
+{% if field.textarea %}<textarea class="form-control" id="{{ field.id }}" name="{{ field.name }}"{{ field.required_attr|raw }}>{{ field.value }}</textarea>{% endif %}{% if field.checkbox %}<div class="form-check"><input class="form-check-input" type="checkbox" id="{{ field.id }}" name="{{ field.name }}"{{ field.checked_attr|raw }}></div>{% endif %}{% if field.select %}<select class="form-select" id="{{ field.id }}" name="{{ field.name }}"{{ field.required_attr|raw }}>{{ field.options_html|raw }}</select>{% endif %}{% if field.input %}<input type="{{ field.type }}" class="form-control" id="{{ field.id }}" name="{{ field.name }}" value="{{ field.value }}" placeholder="{{ field.placeholder }}"{{ field.required_attr|raw }}>{% endif %}
+</div>
+{% endfor %}
+{% if modal_footer %}<div class="modal-footer"><button type="button" class="btn btn-secondary" data-crud-action="close" data-crud-modal="{{ mode }}">Cancel</button><button type="button" class="btn btn-primary" data-crud-action="save" data-crud-mode="{{ mode }}">Save</button></div>{% endif %}{% if submit_button %}<button type="submit" class="btn btn-primary">Submit</button>{% endif %}
+{% if wrap %}</form>{% endif %}

package/packages/core/templates/crud/modals.twig

@@ -0,0 +1,31 @@
+{#
+  crud/modals.twig — the create, edit and delete-confirm dialogs.
+
+  Override: drop your own src/templates/crud/modals.twig to restyle the dialogs.
+  create_form / edit_form are the crud/form.twig renders injected here. Buttons
+  carry data-crud-action (close / confirm-delete) and are wired by the page
+  script — no inline on*= handlers (ADR-0088).
+#}
+<div class="modal-overlay" id="modal-create">
+  <div class="modal-box">
+    <h3>Create New Record</h3>
+    {{ create_form|raw }}
+  </div>
+</div>
+<div class="modal-overlay" id="modal-edit">
+  <div class="modal-box">
+    <h3>Edit Record</h3>
+    {{ edit_form|raw }}
+  </div>
+</div>
+<div class="modal-overlay" id="modal-delete">
+  <div class="modal-box">
+    <h3>Confirm Delete</h3>
+    <p>Are you sure you want to delete this record? This action cannot be undone.</p>
+    <input type="hidden" id="delete-pk-value">
+    <div class="modal-footer">
+      <button class="btn btn-secondary" data-crud-action="close" data-crud-modal="delete">Cancel</button>
+      <button class="btn btn-danger" data-crud-action="confirm-delete">Delete</button>
+    </div>
+  </div>
+</div>