tina4-nodejs 3.13.81 → 3.13.83

package/packages/core/src/mqttMessage.ts

@@ -0,0 +1,104 @@
+/**
+ * One MQTT 3.1.1 application message as delivered by the broker.
+ *
+ * Shaped like the Queue's job (its unit of work): it carries the payload plus
+ * the delivery metadata a consumer needs, and it knows how to acknowledge itself
+ * back to the client it came from. Mirrors tina4_python.mqtt.MqttMessage,
+ * Tina4::MqttMessage (Ruby), and Tina4\MqttMessage (PHP).
+ *
+ * The two flags matter for correctness, not decoration:
+ *
+ *   retained  — the broker replayed the topic's last known value to us because
+ *               we subscribed AFTER it was published. It is current state, not a
+ *               fresh event.
+ *   duplicate — the DUP flag. The broker is REDELIVERING a QoS 1 message it never
+ *               saw acknowledged. QoS 1 is at-least-once, so a duplicate is
+ *               guaranteed eventually; a consumer that treats a DUP delivery as a
+ *               new sample double-counts energy or mileage. Key the ingest on
+ *               (deviceId, deviceTimestamp) and it is harmless.
+ *
+ * The payload is a Buffer of the raw bytes; text() decodes it for JSON/string
+ * payloads.
+ */
+
+/** The slice of an Mqtt client an MqttMessage needs to acknowledge itself. */
+export interface MqttAcknowledger {
+  acknowledge(packetId: number): Promise<boolean>;
+}
+
+export class MqttMessage {
+  private acknowledgedFlag = false;
+
+  constructor(
+    public readonly topic: string,
+    public readonly payload: Buffer,
+    public readonly qos: number = 0,
+    public readonly retained: boolean = false,
+    public readonly duplicate: boolean = false,
+    public readonly packetId: number | null = null,
+    private readonly client: MqttAcknowledger | null = null,
+  ) {}
+
+  /** True when the broker replayed this as the topic's retained (last known) value. */
+  isRetained(): boolean {
+    return this.retained;
+  }
+
+  /**
+   * True when the broker set the DUP flag — a REDELIVERY of a QoS 1 message we
+   * never acknowledged, not a new sample.
+   */
+  isDuplicate(): boolean {
+    return this.duplicate;
+  }
+
+  /**
+   * PUBACK a QoS 1 delivery so the broker stops redelivering it.
+   *
+   * A QoS 0 message needs no acknowledgement, and a second call is a no-op, so
+   * this is always safe to call once processing succeeded. Returns true only
+   * when a PUBACK was actually sent.
+   */
+  async acknowledge(): Promise<boolean> {
+    if (this.acknowledgedFlag || this.qos === 0 || this.packetId === null || this.client === null) {
+      return false;
+    }
+    await this.client.acknowledge(this.packetId);
+    this.acknowledgedFlag = true;
+    return true;
+  }
+
+  /** True once this message has been acknowledged back to the broker. */
+  isAcknowledged(): boolean {
+    return this.acknowledgedFlag;
+  }
+
+  /** The payload decoded as text (for JSON / string payloads). */
+  text(encoding: BufferEncoding = "utf-8"): string {
+    return this.payload.toString(encoding);
+  }
+
+  /** The message as a plain object. */
+  toObject(): {
+    topic: string;
+    payload: Buffer;
+    qos: number;
+    retained: boolean;
+    duplicate: boolean;
+    packetId: number | null;
+  } {
+    return {
+      topic: this.topic,
+      payload: this.payload,
+      qos: this.qos,
+      retained: this.retained,
+      duplicate: this.duplicate,
+      packetId: this.packetId,
+    };
+  }
+
+  /** String form is the payload text (parity with Python __str__ / Ruby to_s). */
+  toString(): string {
+    return this.text();
+  }
+}

package/packages/core/src/scss.ts

@@ -168,9 +168,56 @@ function resolveImports(content: string, paths: string[], imported: Set<string>)
 
 // ── Variables ────────────────────────────────────────────────────
 
+/**
+ * Flags that may trail a variable declaration's value. `!default` means "assign
+ * only if this variable is not already set" — the flag that makes a variable
+ * themeable. `!global` is the scope flag. Both are compiler directives: they are
+ * consumed at the declaration and must never reach the CSS, because
+ * `padding: 1.5rem !default` is invalid CSS and browsers drop the whole
+ * declaration. Sass flag names are case-SENSITIVE (`!DEFAULT` is an error in
+ * Dart Sass), so the match is deliberately case-sensitive.
+ */
+const VARIABLE_FLAG = /\s*!(default|global)\s*$/;
+
+/**
+ * Split trailing `!default` / `!global` flags off a variable declaration value.
+ * Returns `[valueWithoutFlags, declaresDefault]`.
+ *
+ * Only ever called on the value of a `$name: value;` declaration, so a literal
+ * `!default` anywhere else — inside a quoted string (`content: "x !default y"`)
+ * or a function argument — is left untouched, exactly as Dart Sass leaves it. A
+ * blanket strip would corrupt real string content, and would silently turn
+ * `rgba(#000 !default, 0.1)` (a syntax error in Dart Sass) into valid-looking
+ * CSS that Sass would never emit.
+ */
+function stripVariableFlags(value: string): [string, boolean] {
+  let declaresDefault = false;
+  for (;;) {
+    const match = VARIABLE_FLAG.exec(value);
+    if (match === null) return [value.trim(), declaresDefault];
+    if (match[1] === "default") declaresDefault = true;
+    value = value.slice(0, match.index);
+  }
+}
+
+/**
+ * Extract `$variable: value;` declarations, honouring the `!default` flag.
+ *
+ * `$x: value !default;` assigns only when `$x` is not already set. That is what
+ * makes a variable themeable — a user who writes `$primary: red;` BEFORE
+ * importing a partial that declares `$primary: blue !default;` keeps red.
+ * Declarations are visited in source order, so "already set" means "set by an
+ * earlier declaration or by a preset variable". A value of `null` counts as
+ * unset, as in Sass.
+ */
 function extractVariables(scss: string, variables: Record<string, string>): string {
   return scss.replace(/\$([a-zA-Z_][\w-]*)\s*:\s*([^;]+);/g, (_m, name: string, value: string) => {
-    let resolved = value.trim();
+    const [stripped, declaresDefault] = stripVariableFlags(value.trim());
+    // !default must not overwrite a value that is already set.
+    if (declaresDefault && (variables[name] ?? "null") !== "null") {
+      return "";
+    }
+    let resolved = stripped;
     // Resolve variable references within the value
     for (const [vName, vVal] of Object.entries(variables)) {
       resolved = resolved.replaceAll(`$${vName}`, vVal);

package/packages/core/src/server.ts

@@ -34,6 +34,73 @@ const BUILTIN_ERROR_TEMPLATES_DIR = resolve(__dirname, "..", "templates");
 /** Built-in public directory for framework-bundled static assets. */
 const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
+/**
+ * Whether the framework's bundled Swagger UI assets (public/swagger/*) may be
+ * served.
+ *
+ * Static files are resolved BEFORE routes, so the shipped
+ * public/swagger/index.html answered `GET /swagger` even when
+ * `swaggerEnabled()` was false -- serving the Swagger UI in production and
+ * bypassing the documented TINA4_SWAGGER_ENABLED / TINA4_DEBUG gate entirely.
+ * The symptom was a 200 on /swagger with a 404 on /swagger/openapi.json (the
+ * gated route never registered, the static file still won).
+ *
+ * Set from `swaggerEnabled()` at boot. Stays false when swagger is disabled OR
+ * when the swagger module fails to load -- fail closed, never expose.
+ */
+let swaggerAssetsEnabled = false;
+
+/** Bundled Swagger UI asset paths that must honour the swagger gate. */
+function isSwaggerAssetPath(pathname: string): boolean {
+  return pathname === "/swagger" || pathname.startsWith("/swagger/");
+}
+
+/**
+ * Build the startup banner's optional surface lines (issue #99).
+ *
+ * Only advertise a surface that is actually REACHABLE. In production, or with
+ * TINA4_DEBUG off, /swagger and /__dev return 404 -- printing them anyway both
+ * misleads an operator into believing a dev surface is exposed and sends a
+ * developer to a dead link.
+ *
+ * Kept as a pure function of (port, two booleans) so the contract is unit
+ * testable without booting a server and grepping stdout. Parity: Python
+ * banner_surface_lines, PHP App::bannerSurfaceLines, Ruby
+ * Tina4.banner_surface_lines.
+ *
+ * @returns [swaggerLine, dashboardLine] -- each empty, or a newline plus the
+ *          banner row, ready to interpolate.
+ */
+export function bannerSurfaceLines(
+  port: number,
+  opts: { swaggerEnabled: boolean; devAdminEnabled: boolean },
+): [string, string] {
+  return [
+    opts.swaggerEnabled ? `\n  Swagger:   http://localhost:${port}/swagger` : "",
+    opts.devAdminEnabled ? `\n  Dashboard: http://localhost:${port}/__dev` : "",
+  ];
+}
+
+/**
+ * Whether the startup banner should ADVERTISE /swagger (issue #99).
+ *
+ * Mirrors `swaggerEnabled()` in packages/swagger/src/ui.ts: an explicit
+ * TINA4_SWAGGER_ENABLED wins, otherwise fall back to TINA4_DEBUG.
+ *
+ * Read from env here rather than importing the swagger package, because the
+ * CLUSTER PRIMARY prints its banner before any optional module is loaded (and a
+ * dynamic import for one banner line is not worth the boot cost). Keep this in
+ * sync with ui.ts -- it is the same two-line contract.
+ */
+function swaggerAdvertised(): boolean {
+  const TRUTHY = ["true", "1", "yes", "on"];
+  const raw = (process.env.TINA4_SWAGGER_ENABLED ?? "").trim().toLowerCase();
+  if (raw === "") {
+    return TRUTHY.includes((process.env.TINA4_DEBUG ?? "").trim().toLowerCase());
+  }
+  return TRUTHY.includes(raw);
+}
+
 /**
  * Apply pending DB migrations on startup — NON-BREAKING.
  *
@@ -787,6 +854,15 @@ export async function startServer(config?: Tina4Config): Promise<{
       const logLevel = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
 
       if (!isBannerSuppressed()) {
+        // Only advertise a surface that is actually reachable (issue #99).
+        // Cluster mode is the production path: debug is OFF, so /__dev always
+        // 404s here and is never advertised; /swagger only when explicitly on.
+        // Cluster mode is the production path: debug is OFF, so /__dev never
+        // advertises here.
+        const [swaggerLine] = bannerSurfaceLines(port, {
+          swaggerEnabled: swaggerAdvertised(),
+          devAdminEnabled: false,
+        });
         console.log(`${color}
   ______ _             __ __
  /_  __/(_)___  ____ _/ // /
@@ -796,9 +872,7 @@ export async function startServer(config?: Tina4Config): Promise<{
 ${reset}
   Tina4 Node.js v${TINA4_VERSION} — The Intelligent Native Application 4ramework
 
-  Server:    http://${displayHost}:${port} (cluster, ${numCPUs} workers)
-  Swagger:   http://localhost:${port}/swagger
-  Dashboard: http://localhost:${port}/__dev
+  Server:    http://${displayHost}:${port} (cluster, ${numCPUs} workers)${swaggerLine}
   Debug:     OFF (Log level: ${logLevel})
 `);
       }
@@ -1000,7 +1074,10 @@ ${reset}
   // when disabled.
   try {
     const swagger = await import("../../swagger/src/index.js");
-    if (!swagger.swaggerEnabled()) {
+    // Single source of truth for BOTH the gated routes and the bundled
+    // public/swagger assets (which static serving would otherwise expose).
+    swaggerAssetsEnabled = swagger.swaggerEnabled();
+    if (!swaggerAssetsEnabled) {
       // Skip the rest of the swagger block when disabled.
       throw new Error("__swagger_disabled__");
     }
@@ -1273,8 +1350,14 @@ ${reset}
       if (existsSync(srcPublicDir) && tryServeStatic(srcPublicDir, req, res)) {
         return;
       }
-      if (tryServeStatic(BUILTIN_PUBLIC_DIR, req, res)) {
-        return;
+      // Framework-bundled assets. The Swagger UI lives here (public/swagger/),
+      // and static files resolve BEFORE routes -- so this path MUST honour the
+      // swagger gate or /swagger is served in production regardless of
+      // TINA4_SWAGGER_ENABLED / TINA4_DEBUG.
+      if (swaggerAssetsEnabled || !isSwaggerAssetPath(pathname)) {
+        if (tryServeStatic(BUILTIN_PUBLIC_DIR, req, res)) {
+          return;
+        }
       }
 
       // Match route
@@ -1602,6 +1685,14 @@ ${reset}
         : "";
 
       if (!isBannerSuppressed()) {
+        // Only advertise a surface that is actually reachable (issue #99). With
+        // debug off / in production these endpoints 404, and printing a dead URL
+        // both misleads an operator into believing a dev surface is exposed and
+        // sends a developer to a 404.
+        const [swaggerLine, dashboardLine] = bannerSurfaceLines(port, {
+          swaggerEnabled: swaggerAdvertised(),
+          devAdminEnabled: isDebug,
+        });
         console.log(`${color}
   ______ _             __ __
  /_  __/(_)___  ____ _/ // /
@@ -1611,9 +1702,7 @@ ${reset}
 ${reset}
   Tina4 Node.js v${TINA4_VERSION} — The Intelligent Native Application 4ramework
 
-  Server:    http://${displayHost}:${port} (${serverMode})
-  Swagger:   http://localhost:${port}/swagger
-  Dashboard: http://localhost:${port}/__dev
+  Server:    http://${displayHost}:${port} (${serverMode})${swaggerLine}${dashboardLine}
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})${dualPortLines}
 `);
       }

package/packages/core/src/testClient.ts

@@ -18,7 +18,8 @@ import { IncomingMessage, ServerResponse } from "node:http";
 import { Socket } from "node:net";
 import { createRequest } from "./request.js";
 import { createResponse } from "./response.js";
-import { defaultRouter, type Router } from "./router.js";
+import { defaultRouter, Router, runRouteMiddlewares } from "./router.js";
+import { MiddlewareRunner } from "./middleware.js";
 import { enforceRouteAuth } from "./authGate.js";
 
 export class TestResponse {
@@ -160,14 +161,73 @@ export class TestClient {
     const cleanPath = path.includes("?") ? path.split("?")[0] : path;
 
     // Match route
-    const match = this.router.match(method.toUpperCase(), cleanPath);
+    const httpMethod = method.toUpperCase();
+    const match = this.router.match(httpMethod, cleanPath);
     if (!match) {
-      return new TestResponse(404, { "content-type": "application/json" }, '{"error":"Not found"}');
+      // D6: dispatch through the REAL front-controller behaviour on a miss —
+      // never fabricate a body. This mirrors the live server tail
+      // (server.ts dispatch): RFC 9110 conformance first (a path registered
+      // under another method answers OPTIONS with 204 + Allow and any other
+      // method with 405 + Allow), then the framework's real 404. The old
+      // TestClient short-circuited to a hand-invented {"error":"Not found"}
+      // that the live server never sends, so a green test proved nothing about
+      // production (the same silent-success class as Python's pre-fix client).
+      const allowed = this.router.methodsAllowedForPath(cleanPath);
+      if (allowed.length > 0) {
+        const allowHeader = allowed.join(", ");
+        if (httpMethod === "OPTIONS") {
+          return new TestResponse(204, { allow: allowHeader, "content-length": "0" }, "");
+        }
+        const body405 = JSON.stringify({
+          error: "Method Not Allowed",
+          path: cleanPath,
+          method: httpMethod,
+          allow: allowed,
+          statusCode: 405,
+        });
+        return new TestResponse(405, { allow: allowHeader, "content-type": "application/json" }, body405);
+      }
+      // The framework's real 404. The live server renders an HTML error page
+      // when a project templatesDir/frondEngine exists and otherwise emits this
+      // exact JSON; a server-less TestClient has no project dir, so it produces
+      // the JSON fallback the live front controller itself falls back to.
+      // tina4: HTML-error-page + filesystem static serving are the only live
+      // front-controller steps a server-less client can't reproduce.
+      const body404 = JSON.stringify({
+        error: "Not Found",
+        statusCode: 404,
+        message: `No route found for ${httpMethod} ${cleanPath}`,
+      });
+      return new TestResponse(404, { "content-type": "application/json" }, body404);
     }
 
     // Inject route params
     req.params = match.params;
 
+    // Global class-based middleware (Router.use / MiddlewareRunner.use), run in
+    // the SAME order the live dispatcher uses (server.ts): beforeX hooks before
+    // the handler, afterX hooks after — even on a before-short-circuit. Empty
+    // when a test registers none, so this is additive/non-breaking.
+    const globalMiddleware = [
+      ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
+    ];
+    if (globalMiddleware.length > 0) {
+      const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
+      if (!proceed || res.raw.writableEnded) {
+        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+        if (!res.raw.writableEnded) res.raw.end();
+        return this._collect(rawRes, chunks, socket);
+      }
+    }
+
+    // Per-route middleware, same as the live dispatcher.
+    if (match.middlewares && match.middlewares.length > 0) {
+      const proceed = await runRouteMiddlewares(match.middlewares, req, res);
+      if (!proceed || res.raw.writableEnded) {
+        return this._collect(rawRes, chunks, socket);
+      }
+    }
+
     // Route through the REAL auth gate (parity with the live server). A write to
     // an auth-required route (secure-by-default POST/PUT/PATCH/DELETE, or any
     // .secure() route) with no valid token / formToken / session token 401s here
@@ -183,9 +243,17 @@ export class TestClient {
     // Execute handler (only if auth passed)
     if (!rejected) {
       await match.handler(req, res);
+      // Global afterX hooks (logging / post-processing), mirroring the live tail.
+      if (globalMiddleware.length > 0) {
+        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+      }
     }
 
-    // Collect response
+    return this._collect(rawRes, chunks, socket);
+  }
+
+  /** Gather the captured status/headers/body into a TestResponse and free the socket. */
+  private _collect(rawRes: ServerResponse, chunks: Buffer[], socket: Socket): TestResponse {
     const responseBody = Buffer.concat(chunks).toString();
     const responseHeaders: Record<string, string> = {};
     for (const [name, value] of Object.entries(rawRes.getHeaders())) {
@@ -193,10 +261,7 @@ export class TestClient {
         responseHeaders[name] = Array.isArray(value) ? value.join(", ") : String(value);
       }
     }
-
-    // Clean up the socket
     socket.destroy();
-
     return new TestResponse(rawRes.statusCode, responseHeaders, responseBody);
   }
 }

package/packages/orm/src/adapters/firebird.ts

@@ -5,7 +5,7 @@
  * URL format: firebird://user:pass@host:port/path/to/database.fdb
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let firebird: any = null;

package/packages/orm/src/adapters/mssql.ts

@@ -5,7 +5,7 @@
  * URL format: mssql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let tedious: any = null;

package/packages/orm/src/adapters/mysql.ts

@@ -5,7 +5,7 @@
  * URL format: mysql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let mysql2: any = null;

package/packages/orm/src/adapters/postgres.ts

@@ -5,7 +5,7 @@
  * URL format: postgresql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 
 import { createRequire } from "node:module";
 

package/packages/orm/src/adapters/sqlite.ts

@@ -2,7 +2,7 @@ import { DatabaseSync } from "node:sqlite";
 import { mkdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 
 /** A safe-to-interpolate SQL identifier (no quoting/escaping needed). */
 function isIdentifier(str: string): boolean {

package/packages/orm/src/baseModel.ts

@@ -7,7 +7,7 @@ import {
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 import { Log } from "../../core/src/index.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 

package/packages/orm/src/cachedDatabase.ts

@@ -32,7 +32,7 @@
  *   db.cacheStats();                   // { enabled, mode, hits, misses, size, ttl }
  */
 
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
 import type { CacheBackend } from "../../core/src/index.js";
 

package/packages/orm/src/database.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, FieldDefinition } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
 import { CachedDatabaseAdapter, type CachedAdapterOptions } from "./cachedDatabase.js";
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 
 /**
  * v3.13.12 — strip trailing `;` and whitespace from user-supplied SQL

package/packages/orm/src/index.ts

@@ -53,7 +53,7 @@ export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
-export { SQLTranslator, QueryCache } from "./sqlTranslation.js";
+export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";