tina4-nodejs 3.13.133 → 3.13.135

package/packages/orm/src/seederTable.ts

@@ -0,0 +1,101 @@
+import { FakeData } from "./fakeData.js";
+import { adapterExecute, adapterColumns, adapterInsert } from "./database.js";
+import { Log } from "../../core/src/index.js";
+import type { DatabaseAdapter, FieldDefinition, FieldType } from "./types.js";
+import type { SeedOptions, SeedSummary } from "./seederTypes.js";
+
+function normaliseOptions(overrides?: Record<string, unknown>, opts?: SeedOptions):
+  Required<Pick<SeedOptions, "clear" | "strict">> & { overrides?: Record<string, unknown> } {
+  const merged = { ...(opts ?? {}) };
+  return {
+    overrides: merged.overrides ?? overrides,
+    clear: merged.clear ?? false,
+    strict: merged.strict ?? false,
+  };
+}
+
+/** Delete every row, logging but not hiding a clear failure. */
+export async function clearTable(db: DatabaseAdapter, tableName: string): Promise<void> {
+  try {
+    await adapterExecute(db, `DELETE FROM "${tableName}"`);
+  } catch (e) {
+    Log.warning(`Seeder: could not clear '${tableName}': ${(e as Error).message}`);
+  }
+}
+
+function sqlTypeToFieldType(sqlType: string): FieldType {
+  const type = (sqlType || "").toUpperCase();
+  if (type.includes("INT")) return "integer";
+  if (type.includes("BOOL")) return "boolean";
+  if (["REAL", "FLOA", "DOUB", "NUM", "DEC"].some((part) => type.includes(part))) return "number";
+  if (type.includes("DATE") || type.includes("TIME")) return "datetime";
+  if (type.includes("TEXT") || type.includes("CLOB")) return "text";
+  return "string";
+}
+
+/** Build generators from live table metadata for the explicit seedTable path. */
+export async function autoFieldMap(
+  db: DatabaseAdapter,
+  table: string,
+  fake: FakeData = new FakeData(),
+): Promise<Record<string, () => unknown>> {
+  const columns = await adapterColumns(db, table);
+  const fieldMap: Record<string, () => unknown> = {};
+  for (const column of columns) {
+    const name = column.name;
+    const sqlType = String(column.type ?? "").toUpperCase();
+    const generatedPk = column.primaryKey === true &&
+      (sqlType.includes("AUTO") || sqlType.includes("SERIAL") || sqlType.includes("IDENTITY") || name.toLowerCase() === "id");
+    if (generatedPk) continue;
+    fieldMap[name] = () => fake.forField({ type: sqlTypeToFieldType(sqlType) }, name, table);
+  }
+  return fieldMap;
+}
+
+/** Seed a table through the adapter insert path, counting or re-raising row failures. */
+export async function seedTable(
+  db: DatabaseAdapter,
+  tableName: string,
+  count = 10,
+  fieldMap?: Record<string, (() => unknown) | unknown>,
+  overrides?: Record<string, unknown>,
+  opts?: SeedOptions,
+): Promise<SeedSummary> {
+  if (opts?.seed !== undefined) {
+    throw new Error(
+      "seedTable() no longer accepts opts.seed: it has no generators of its own to seed " +
+      "(fieldMap callables are opaque). Build a seeded FakeData yourself and close over it " +
+      "in fieldMap, e.g. const fake = new FakeData(42); seedTable(db, table, count, " +
+      "{ name: () => fake.name() }).",
+    );
+  }
+  const { overrides: effectiveOverrides, clear, strict } = normaliseOptions(overrides, opts);
+  if (!fieldMap || Object.keys(fieldMap).length === 0) return { seeded: 0, failed: 0, errors: [] };
+  if (clear) await clearTable(db, tableName);
+
+  let seeded = 0;
+  let failed = 0;
+  const errors: Array<{ row: number; message: string }> = [];
+  for (let i = 0; i < count; i++) {
+    try {
+      const row: Record<string, unknown> = {};
+      for (const [column, generator] of Object.entries(fieldMap)) {
+        row[column] = typeof generator === "function" ? (generator as () => unknown)() : generator;
+      }
+      for (const [column, value] of Object.entries(effectiveOverrides ?? {})) row[column] = value;
+      await adapterInsert(db, tableName, row);
+      seeded++;
+    } catch (e) {
+      const message = (e as Error).message ?? String(e);
+      if (strict) {
+        Log.error(`Seeder: row ${i} failed seeding '${tableName}' (strict): ${message}`);
+        throw e;
+      }
+      failed++;
+      errors.push({ row: i, message });
+      Log.warning(`Seeder: row ${i} failed seeding '${tableName}', skipped: ${message}`);
+    }
+  }
+  Log.info(`Seeder: '${tableName}' — seeded ${seeded}, ${failed} failed`);
+  return { seeded, failed, errors };
+}

package/packages/orm/src/seederTypes.ts

@@ -0,0 +1,14 @@
+/** Result of a seed run. */
+export interface SeedSummary {
+  seeded: number;
+  failed: number;
+  errors: Array<{ row: number; message: string }>;
+}
+
+/** Options shared by the table and ORM seed paths. */
+export interface SeedOptions {
+  overrides?: Record<string, unknown>;
+  clear?: boolean;
+  seed?: number;
+  strict?: boolean;
+}

package/packages/orm/src/validation.ts

@@ -5,6 +5,101 @@ export interface ValidationError {
   message: string;
 }
 
+function error(field: string, message: string): ValidationError {
+  return { field, message };
+}
+
+function validateString(
+  name: string,
+  value: string,
+  def: FieldDefinition,
+  pattern: RegExp | undefined,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  if (def.minLength !== undefined && value.length < def.minLength) {
+    errors.push(error(name, `must be at least ${def.minLength} characters`));
+  }
+  if (def.maxLength !== undefined && value.length > def.maxLength) {
+    errors.push(error(name, `must be at most ${def.maxLength} characters`));
+  }
+  if (pattern && !pattern.test(value)) {
+    errors.push(error(name, "does not match the required format"));
+  }
+  return errors;
+}
+
+function validateNumber(name: string, value: unknown, def: FieldDefinition): ValidationError[] {
+  const num = typeof value === "string" ? Number(value) : value;
+  if (typeof num !== "number" || isNaN(num)) return [error(name, "must be a number")];
+
+  const errors: ValidationError[] = [];
+  if (def.type === "integer" && !Number.isInteger(num)) {
+    errors.push(error(name, "must be an integer"));
+  }
+  if (def.min !== undefined && num < def.min) {
+    errors.push(error(name, `must be at least ${def.min}`));
+  }
+  if (def.max !== undefined && num > def.max) {
+    errors.push(error(name, `must be at most ${def.max}`));
+  }
+  return errors;
+}
+
+function validateBoolean(name: string, value: unknown): ValidationError[] {
+  return typeof value === "boolean" || value === 0 || value === 1 || value === "true" || value === "false"
+    ? []
+    : [error(name, "must be a boolean")];
+}
+
+function validateDatetime(name: string, value: unknown): ValidationError[] {
+  return typeof value === "string" && isNaN(Date.parse(value))
+    ? [error(name, "must be a valid date/time")]
+    : [];
+}
+
+function validateJson(name: string, value: unknown): ValidationError[] {
+  return value !== null && typeof value !== "object" && typeof value !== "string"
+    ? [error(name, "must be a JSON object or array")]
+    : [];
+}
+
+function validateForeignKey(name: string, value: unknown): ValidationError[] {
+  const fkNum = typeof value === "string" ? Number(value) : value;
+  return typeof fkNum !== "number" || isNaN(fkNum) || !Number.isInteger(fkNum)
+    ? [error(name, "must be a valid foreign key (integer)")]
+    : [];
+}
+
+function validateField(
+  name: string,
+  value: unknown,
+  def: FieldDefinition,
+  pattern: RegExp | undefined,
+): ValidationError[] {
+  if (def.type === "string" || def.type === "text") {
+    return typeof value === "string"
+      ? validateString(name, value, def, pattern)
+      : [error(name, "must be a string")];
+  }
+
+  if (def.type === "integer" || def.type === "number" || def.type === "numeric") {
+    return validateNumber(name, value, def);
+  }
+
+  switch (def.type) {
+    case "boolean":
+      return validateBoolean(name, value);
+    case "datetime":
+      return validateDatetime(name, value);
+    case "json":
+      return validateJson(name, value);
+    case "foreignKey":
+      return validateForeignKey(name, value);
+    default:
+      return [];
+  }
+}
+
 export function validate(
   data: Record<string, unknown>,
   fields: Record<string, FieldDefinition>,
@@ -28,92 +123,14 @@ export function validate(
 
     // Required check (skip on update if field not provided)
     if (def.required && !isUpdate && (value === undefined || value === null || value === "")) {
-      errors.push({ field: name, message: "is required" });
+      errors.push(error(name, "is required"));
       continue;
     }
 
     // Skip further validation if value not provided
     if (value === undefined || value === null) continue;
 
-    // Type checks
-    switch (def.type) {
-      case "string":
-      case "text":
-        if (typeof value !== "string") {
-          errors.push({ field: name, message: "must be a string" });
-        } else {
-          if (def.minLength !== undefined && value.length < def.minLength) {
-            errors.push({ field: name, message: `must be at least ${def.minLength} characters` });
-          }
-          if (def.maxLength !== undefined && value.length > def.maxLength) {
-            errors.push({ field: name, message: `must be at most ${def.maxLength} characters` });
-          }
-          const regex = compiledPatterns.get(name);
-          if (regex && !regex.test(value)) {
-            // Feature 19 (VALID-TWO-MESSAGES): one canonical wording per rule
-            // across BOTH validators. The request Validator says "does not match
-            // the required format"; the ORM validator must say the same so a
-            // client keying on the message matches either surface.
-            errors.push({ field: name, message: `does not match the required format` });
-          }
-        }
-        break;
-
-      case "integer":
-      case "number":
-      case "numeric": {
-        const num = typeof value === "string" ? Number(value) : value;
-        if (typeof num !== "number" || isNaN(num)) {
-          errors.push({ field: name, message: "must be a number" });
-        } else {
-          if (def.type === "integer" && !Number.isInteger(num)) {
-            errors.push({ field: name, message: "must be an integer" });
-          }
-          if (def.min !== undefined && num < def.min) {
-            errors.push({ field: name, message: `must be at least ${def.min}` });
-          }
-          if (def.max !== undefined && num > def.max) {
-            errors.push({ field: name, message: `must be at most ${def.max}` });
-          }
-        }
-        break;
-      }
-
-      case "boolean":
-        if (typeof value !== "boolean" && value !== 0 && value !== 1 && value !== "true" && value !== "false") {
-          errors.push({ field: name, message: "must be a boolean" });
-        }
-        break;
-
-      case "datetime":
-        if (typeof value === "string" && isNaN(Date.parse(value))) {
-          errors.push({ field: name, message: "must be a valid date/time" });
-        }
-        break;
-
-      case "json":
-        // A JSON column holds an object/array (or a pre-serialised JSON
-        // string); reject a bare scalar. A value that can't be JSON-encoded
-        // (a circular reference, a BigInt) fails loud at save time.
-        if (value !== null && typeof value !== "object" && typeof value !== "string") {
-          errors.push({ field: name, message: "must be a JSON object or array" });
-        }
-        break;
-
-      case "foreignKey": {
-        // Outlier D: previously there was no foreignKey case, so ANY value
-        // passed validation silently. A foreign key references another model's
-        // primary key — by default an auto-increment integer — so validate it
-        // as an integer (a numeric string like "12" is coerced and accepted).
-        // This catches the common bug of assigning a whole object / array /
-        // non-numeric string to an *_id column before it reaches the driver.
-        const fkNum = typeof value === "string" ? Number(value) : value;
-        if (typeof fkNum !== "number" || isNaN(fkNum) || !Number.isInteger(fkNum)) {
-          errors.push({ field: name, message: "must be a valid foreign key (integer)" });
-        }
-        break;
-      }
-    }
+    errors.push(...validateField(name, value, def, compiledPatterns.get(name)));
   }
 
   return errors;

package/types/core/src/aiClient.d.ts

@@ -146,6 +146,10 @@ export declare class Ai {
      */
     private static validateMessages;
     private static validateContent;
+    private static validateContentPart;
+    private static validateTextPart;
+    private static validateImagePart;
+    private static validateToolResultPart;
     /**
      * Validate the outbound tool declarations (ADR-0061). Each tool needs a
      * non-empty `name`, a string `description`, and a JSON-Schema-shaped
@@ -215,5 +219,6 @@ export declare class Ai {
      */
     private static streamRequest;
     private static responseChunks;
+    private static readStream;
     private static streamError;
 }

package/types/core/src/devAdmin.d.ts

@@ -9,7 +9,7 @@
  *   - System info (Node.js version, V8, memory, uptime, platform)
  */
 import type { Router } from "./router.js";
-import type { Tina4Request } from "./types.js";
+import type { RouteHandler, Tina4Request } from "./types.js";
 /** Safe HTTP methods that never carry a state change — they skip the write gate. */
 export declare const DEV_SAFE_METHODS: Set<string>;
 /**
@@ -203,6 +203,19 @@ export declare class DevAdmin {
  *   4. Fallback `http://127.0.0.1:9145` — matches standalone `tina4 agent`.
  */
 export declare function supervisorBaseUrl(): string;
+/**
+ * Version check — a check that did not happen says so.
+ *
+ * This used to fall back to `latest = current` on any failure, and the toolbar
+ * renders that as a green "You are up to date!" — so a developer several
+ * releases behind, on a machine with no route out, was told the opposite of the
+ * truth, and the toolbar's own "Could not check for updates" branch could never
+ * fire because the failure arrived as a success. `latest` is `null` when the
+ * check could not be made, and `error` says why. The registry URL is
+ * `TINA4_VERSION_CHECK_URL` when set (a mirror, or a test's own server), else
+ * npm. Mirrors Python `tina4_python.dev_admin._api_version_check`.
+ */
+export declare const handleVersionCheck: RouteHandler;
 /**
  * Resolve a CodeMirror-friendly language id from a file path's basename.
  *
@@ -212,4 +225,13 @@ export declare function supervisorBaseUrl(): string;
  * - anything unknown → "text"
  */
 export declare function devAdminLanguage(rel: string): string;
+/**
+ * JS for the injected dev toolbar — the version-check modal, the dashboard
+ * overlay, and the WebSocket-primary live reloader. Served as an external
+ * script so the toolbar carries no inline handlers or `<script>` and stays
+ * CSP-clean. Every interaction is wired via addEventListener. The reloader only
+ * starts when the toolbar's `data-reload` is "1" (reload not suppressed for this
+ * request/port). Mirrors PHP DevAdmin::toolbarJs().
+ */
+export declare function toolbarJs(): string;
 export {};

package/types/core/src/docsParser.d.ts

@@ -0,0 +1,28 @@
+export interface ParsedClass {
+    name: string;
+    line: number;
+    doc: string;
+    exported: boolean;
+    methods: ParsedMethod[];
+}
+export interface ParsedMethod {
+    name: string;
+    line: number;
+    doc: string;
+    signature: string;
+    visibility: "public" | "protected" | "private";
+    static: boolean;
+}
+export interface ParsedFile {
+    classes: ParsedClass[];
+    functions: ParsedMethod[];
+}
+/**
+ * Parse a TS source string. Lightweight — finds top-level classes and their
+ * public methods, plus top-level exported functions. Captures preceding JSDoc.
+ *
+ * Strategy: scan token-by-token. We don't need a full AST — we only care
+ * about identifying class declarations, brace depth (to find class members),
+ * method/function declarations, and JSDoc comments immediately above.
+ */
+export declare function parseTypeScript(source: string, _debugTag?: string): ParsedFile;

package/types/core/src/docsScanner.d.ts

@@ -0,0 +1 @@
+export declare function stripStrings(source: string): string;

package/types/core/src/docsSignatures.d.ts

@@ -0,0 +1,11 @@
+interface MethodMatch {
+    name: string;
+    signature: string;
+    endIndex: number;
+    nameStart: number;
+    visibility: "public" | "protected" | "private";
+    static: boolean;
+}
+export declare function matchMethodSignature(stripped: string, source: string, i: number): MethodMatch | null;
+export declare function matchTopLevelFunction(stripped: string, source: string, i: number): MethodMatch | null;
+export {};

package/types/core/src/index.d.ts

@@ -57,6 +57,8 @@ export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateC
 export type { AiTool } from "./ai.js";
 export { Sso, SSO, SsoError } from "./sso.js";
 export type { SsoOptions } from "./sso.js";
+export { Push, PushError, generateVapidKeys } from "./push.js";
+export type { PushOptions, PushSubscription, PushResult, PushPayload } from "./push.js";
 export { Ai, AiError, AiConfigError, AiHTTPError, AiTimeoutError, AiParseError } from "./aiClient.js";
 export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions, AiEvent, ContentPart, AiMessageContent, AiToolDeclaration, AiToolChoice } from "./aiClient.js";
 export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";

package/types/core/src/messenger.d.ts

@@ -139,6 +139,14 @@ export declare class Messenger {
     private shouldCapture;
     /** The local mailbox, created on first capture and reused after. */
     private getDevMailbox;
+    private prepareRecipients;
+    private connectSmtpSocket;
+    private requireSmtpResponse;
+    private openSmtpSession;
+    private authenticateSmtp;
+    private sendSmtpEnvelope;
+    private sendSmtpMessage;
+    private sendSmtp;
     send(to: string | string[], subject: string, body: string, html?: boolean, text?: string, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
     /**
      * Render a Frond template STRING and send it as an HTML email (G7, parity with

package/types/core/src/projectIndexExtractors.d.ts

@@ -0,0 +1,3 @@
+import type { FileEntry } from "./projectIndex.js";
+export declare function extractForPath(filePath: string, text: string): FileEntry;
+export declare function languageFor(filePath: string): string;

package/types/core/src/projectIndexStorage.d.ts

@@ -0,0 +1,13 @@
+import type { FileEntry } from "./projectIndex.js";
+export interface IndexData {
+    version: number;
+    files: Record<string, FileEntry>;
+    generated_at: number;
+}
+export declare function projectRoot(): string;
+export declare function indexPath(): string;
+export declare function summarise(entry: FileEntry): string;
+export declare function extract(fullPath: string): FileEntry;
+export declare function walk(dir: string, out: string[]): void;
+export declare function loadRaw(): IndexData;
+export declare function saveRaw(data: IndexData): void;

package/types/core/src/push.d.ts

@@ -0,0 +1,45 @@
+export interface PushSubscription {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+export interface PushOptions {
+    subject?: string;
+    publicKey?: string;
+    privateKey?: string;
+    ttl?: number;
+    urgency?: "very-low" | "low" | "normal" | "high";
+}
+export interface PushResult {
+    ok: boolean;
+    status: number;
+    dead: boolean;
+    retryable: boolean;
+    endpoint: string;
+    response: string;
+}
+export type PushPayload = string | Uint8Array | Record<string, unknown> | unknown[] | number | boolean | null;
+export declare class PushError extends Error {
+    constructor(message: string);
+}
+export declare function generateVapidKeys(): {
+    publicKey: string;
+    privateKey: string;
+};
+/** Provider-neutral Web Push sender. A subscription is accepted as returned by PushManager. */
+export declare class Push {
+    private readonly options;
+    constructor(options?: PushOptions);
+    static fromEnv(options?: PushOptions): Push;
+    static generateKeys(): {
+        publicKey: string;
+        privateKey: string;
+    };
+    private requireConfiguration;
+    private endpointFor;
+    private vapidKeys;
+    private deliver;
+    send(subscription: PushSubscription, payload: PushPayload): Promise<PushResult>;
+}

package/types/frond/src/engine.d.ts

@@ -97,6 +97,7 @@ export declare class Frond {
     private _allowedVars;
     private fragmentCache;
     private _autoEscape;
+    private readonly blockHandlers;
     /**
      * Token pre-compilation cache for file templates.
      *
@@ -188,6 +189,10 @@ export declare class Frond {
      */
     private substituteBlocks;
     private renderWithBlocks;
+    private dispatchBlock;
+    private renderTextToken;
+    private renderVarToken;
+    private renderBlockToken;
     private renderTokens;
     /**
      * May this filter RUN under the current sandbox?
@@ -206,6 +211,7 @@ export declare class Frond {
      * instead of the four names that happened to be checked individually.
      */
     private tagPermitted;
+    private applyFilterValue;
     /**
      * Consume a denied tag WITHOUT running it, returning the index past its body.
      *
@@ -228,8 +234,22 @@ export declare class Frond {
     private applyFilters;
     private evalVar;
     private evalVarRaw;
+    /**
+     * Apply the no-argument filters that are common enough to avoid generic
+     * dispatch. Keeping this table separate from evalVarInner makes the
+     * expression pipeline easier to audit without changing filter order.
+     */
+    private applyFastFilter;
+    private applyRenderedFilter;
+    private variablePermitted;
+    private resolveConcatenation;
+    private applyRenderedFilters;
     private evalVarInner;
+    private pushIfBranch;
+    private collectIfBranches;
     private handleIf;
+    private collectForTokens;
+    private forItems;
     private handleFor;
     private handleSet;
     private handleInclude;
@@ -257,6 +277,8 @@ export declare class Frond {
      */
     private handleImportAs;
     private handleFromImport;
+    private collectMacroDefinitions;
+    private createMacro;
     /**
      * Collect the body tokens of a {% <openTag> %}...{% end<openTag> %} block,
      * starting from the token after the opening tag (start + 1). Nested same-tag
@@ -279,6 +301,9 @@ export declare class Frond {
      * Python master's _handle_live and PHP/Ruby handleLive.
      */
     private handleLive;
+    private parseLiveOptions;
+    private collectLiveBody;
+    private liveAttributes;
     /**
      * Re-render a registered {% live %} fragment by name with fresh data.
      * Returns the rendered HTML, or null if no fragment is registered under that

package/types/orm/src/fakeData.d.ts

@@ -19,6 +19,9 @@ export declare class FakeData extends CoreFakeData {
      * Matches the Python API's datetime() method.
      */
     datetime(startYear?: number, endYear?: number): Date;
+    private heuristicValue;
+    private stringValue;
+    private typedValue;
     /**
      * Generate a fake value appropriate for an ORM field definition.
      * Respects min/max, minLength/maxLength, and type constraints.