tina4-nodejs 3.13.148 → 3.13.150

package/packages/orm/src/migration.ts

@@ -6,8 +6,10 @@ License, v. 2.0. If a copy of the MPL was not distributed with this
 file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
 
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 import { Log } from "../../core/src/index.js";
 import type { FieldDefinition, DatabaseAdapter } from "./types.js";
 import type { SQLiteAdapter } from "./adapters/sqlite.js";
@@ -1016,6 +1018,144 @@ function warnUnprefixedMigrations(files: string[]): void {
  * @param adapter - A DatabaseAdapter instance (or omit to use the global adapter).
  * @param options - Optional configuration.
  */
+// ── Cross-process migration lock (issue #277) ──────────────────────────────
+const MIGRATION_LOCK_NAME = "tina4_migration_lock";
+// A stable signed-64-bit key for PostgreSQL's pg_advisory_lock, derived from the
+// name so it cannot collide with an application's own advisory-lock keys. It is a
+// constant (not user input), so inlining it in the SQL is injection-safe.
+const PG_ADVISORY_KEY = BigInt.asIntN(
+  64,
+  BigInt("0x" + createHash("sha256").update(MIGRATION_LOCK_NAME).digest("hex").slice(0, 16)),
+).toString();
+
+type MigrationLock = { kind: "postgres" | "mysql" | "mssql" | "file" | "none"; resource?: string };
+
+const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * Take the run-wide migration lock, blocking until it is held. PostgreSQL/MySQL/
+ * MSSQL use a native session-scoped advisory lock; SQLite, Firebird and anything
+ * else fall back to an atomic exclusive-create file lock on a sidecar in the
+ * system temp dir (crash-safe via a stale-PID check). A backend that cannot
+ * lock degrades to the file lock, and finally to running unlocked.
+ */
+async function acquireMigrationLock(db: DatabaseAdapter, dir: string): Promise<MigrationLock> {
+  let engine = "";
+  try {
+    engine = (db.getDatabaseType() || "").toLowerCase();
+  } catch {
+    engine = "";
+  }
+
+  try {
+    if (engine.startsWith("postgres")) {
+      await adapterQuery(db, `SELECT pg_advisory_lock(${PG_ADVISORY_KEY}) AS locked`);
+      return { kind: "postgres" };
+    }
+    if (engine.startsWith("mysql")) {
+      // -1 = wait indefinitely; GET_LOCK is connection-scoped.
+      await adapterQuery(db, `SELECT GET_LOCK('${MIGRATION_LOCK_NAME}', -1) AS locked`);
+      return { kind: "mysql" };
+    }
+    if (engine === "mssql" || engine === "sqlserver") {
+      await adapterExecute(
+        db,
+        `DECLARE @res INT; EXEC @res = sp_getapplock @Resource = '${MIGRATION_LOCK_NAME}', ` +
+          `@LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = -1`,
+      );
+      return { kind: "mssql" };
+    }
+  } catch (err) {
+    Log.debug(`DB migration lock unavailable (${engine}): ${err instanceof Error ? err.message : err}; using a file lock`);
+  }
+
+  return acquireFileLock(dir);
+}
+
+/**
+ * Atomic exclusive-file cross-process lock (Node core has no flock). An
+ * O_CREAT|O_EXCL ("wx") write IS the lock: exactly one process creates the file.
+ * It records the holder's PID so a waiter can clear a lock left by a CRASHED
+ * holder — but ONLY when it reads a valid PID that is confirmed dead. An unread-
+ * able, empty or missing PID is treated as NOT stale (the holder created the file
+ * microseconds before writing its PID; stealing on that window double-applied the
+ * migration — the exact 2-rows/1-tracker-row signature of issue #277). Returns
+ * {kind:"none"} rather than blocking boot forever if it cannot be taken.
+ */
+async function acquireFileLock(dir: string): Promise<MigrationLock> {
+  // The lock file lives in the system temp dir, NOT the migrations folder — a
+  // runtime lock is not a migration, and a dotfile left in the tracked
+  // migrations/ dir gets committed by accident and blocks a plain rmdir. The
+  // name is hashed from the ABSOLUTE migrations path so every worker of the same
+  // app lands on the same file (issue #277, parity with PHP fileLockPath()).
+  const lockFile = join(tmpdir(), `tina4-migration-${createHash("sha256").update(resolve(dir)).digest("hex")}.lock`);
+  const deadline = Date.now() + 60_000;
+  for (;;) {
+    try {
+      writeFileSync(lockFile, String(process.pid), { flag: "wx" }); // atomic create-exclusive
+      return { kind: "file", resource: lockFile };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+        Log.debug(`file migration lock unavailable: ${err instanceof Error ? err.message : err}; running unlocked`);
+        return { kind: "none" };
+      }
+      if (isStaleLock(lockFile)) {
+        try {
+          rmSync(lockFile, { force: true });
+        } catch {
+          /* another process may have cleared it first */
+        }
+        continue;
+      }
+      if (Date.now() > deadline) {
+        Log.debug("file migration lock wait timed out; running unlocked");
+        return { kind: "none" };
+      }
+      await delay(50);
+    }
+  }
+}
+
+/**
+ * Stale ONLY when the lock file records a VALID pid that is confirmed dead. An
+ * empty/unparseable pid (holder mid-write) or a vanished file (holder released)
+ * is NOT stale — treating either as stale lets a waiter steal a live lock.
+ */
+function isStaleLock(lockFile: string): boolean {
+  let raw: string;
+  try {
+    raw = readFileSync(lockFile, "utf-8").trim();
+  } catch {
+    return false; // ENOENT: the lock was released — retry acquisition, don't steal
+  }
+  const pid = parseInt(raw, 10);
+  if (!raw || !Number.isFinite(pid) || pid <= 0) {
+    return false; // holder has not written its pid yet — give it the benefit of the doubt
+  }
+  try {
+    process.kill(pid, 0); // throws ESRCH if the process is gone
+    return false;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "ESRCH";
+  }
+}
+
+async function releaseMigrationLock(db: DatabaseAdapter, lock: MigrationLock): Promise<void> {
+  try {
+    if (lock.kind === "postgres") {
+      await adapterQuery(db, `SELECT pg_advisory_unlock(${PG_ADVISORY_KEY}) AS released`);
+    } else if (lock.kind === "mysql") {
+      await adapterQuery(db, `SELECT RELEASE_LOCK('${MIGRATION_LOCK_NAME}') AS released`);
+    } else if (lock.kind === "mssql") {
+      await adapterExecute(db, `EXEC sp_releaseapplock @Resource = '${MIGRATION_LOCK_NAME}', @LockOwner = 'Session'`);
+    } else if (lock.kind === "file" && lock.resource) {
+      rmSync(lock.resource, { recursive: true, force: true });
+    }
+  } catch (err) {
+    Log.debug(`migration lock release failed (${lock.kind}): ${err instanceof Error ? err.message : err}`);
+  }
+}
+
 export async function migrate(
   adapter?: DatabaseAdapter,
   options?: { migrationsDir?: string; delimiter?: string },
@@ -1024,11 +1164,34 @@ export async function migrate(
   const dir = resolve(options?.migrationsDir ?? "migrations");
   const delimiter = options?.delimiter ?? ";";
 
-  const result: MigrationResult = { applied: [], skipped: [], failed: [] };
-
   if (!existsSync(dir)) {
-    return result;
+    return { applied: [], skipped: [], failed: [] };
+  }
+
+  // Serialize concurrent startup migrations across processes (#277): the hook
+  // runs once per process on a long-lived server and on every request under
+  // php -S-style servers, so several workers/instances could reach a fresh
+  // database at once and apply the same migration more than once (a data
+  // migration then inserted its rows twice). The winner migrates while the rest
+  // block, then re-read the applied set and find nothing pending. Every backend
+  // auto-releases the lock when the holder's session/process dies.
+  const lock = await acquireMigrationLock(db, dir);
+  try {
+    return await runPendingMigrations(db, dir, delimiter);
+  } finally {
+    await releaseMigrationLock(db, lock);
   }
+}
+
+/**
+ * Apply every pending migration, in order. Caller holds the run-wide lock.
+ */
+async function runPendingMigrations(
+  db: DatabaseAdapter,
+  dir: string,
+  delimiter: string,
+): Promise<MigrationResult> {
+  const result: MigrationResult = { applied: [], skipped: [], failed: [] };
 
   // Ensure the canonical tracking table exists (creates it, or upgrades an
   // older <= 3.13.54 `name`/`applied_at` table in place). Shared with

package/packages/orm/src/query.ts

@@ -93,6 +93,62 @@ const filterValueError = (field: string): InvalidQueryParameterError =>
  * not resolve throws UnknownFieldError before any SQL exists. With no
  * resolver, no filter or sort key resolves (ADR-0069).
  */
+/**
+ * ADR-0094: ?search=term filters the list - a LIKE %term% OR'd across the
+ * model's declared string/text columns (already resolved + passed in by the
+ * caller), added to the WHERE before limit/offset so the COUNT reflects the
+ * filtered set. The columns come from the model, never the request, so the
+ * identifiers are safe; the term itself is bound. A model with no string/text
+ * column simply matches nothing (the handler passes an empty list).
+ */
+function applySearch(
+  options: QueryOptions,
+  conditions: string[],
+  params: unknown[],
+  quote: (name: string) => string,
+): void {
+  const searchTerm = (options.search ?? "").trim();
+  if (searchTerm === "" || !options.searchColumns || options.searchColumns.length === 0) return;
+  const likeParts = options.searchColumns.map((col) => `${quote(col)} LIKE ?`);
+  conditions.push(`(${likeParts.join(" OR ")})`);
+  for (const _ of options.searchColumns) params.push(`%${searchTerm}%`);
+}
+
+/**
+ * Build the ORDER BY clause from ?sort. Comma-separated parts, empty parts
+ * skipped, a leading "-" = DESC. ORDER BY is built only from resolved columns
+ * and the words ASC / DESC. ADR-0094: a single bare ?sort=column honours
+ * ?sort_dir=asc|desc (the CRUD grid's spelling); a comma list or a leading "-"
+ * keeps its own inline direction and ignores sort_dir.
+ */
+/** One resolved "col ASC|DESC" ORDER BY term, or null for an empty part. */
+function orderPart(
+  rawPart: string,
+  bareDir: string | null,
+  column: (kind: "filter" | "sort", key: string) => string,
+): string | null {
+  const trimmed = rawPart.trim();
+  if (trimmed === "") return null;
+  const descending = trimmed.startsWith("-");
+  const col = column("sort", descending ? trimmed.slice(1) : trimmed);
+  return `${col} ${bareDir ?? (descending ? "DESC" : "ASC")}`;
+}
+
+function buildOrderClause(
+  options: QueryOptions,
+  column: (kind: "filter" | "sort", key: string) => string,
+): string {
+  if (!options.sort) return "";
+  const rawParts = options.sort.split(",");
+  const first = rawParts[0].trim();
+  const singleBare = rawParts.length === 1 && first !== "" && !first.startsWith("-");
+  const bareDir = singleBare && String(options.sortDir).toLowerCase() === "desc" ? "DESC" : null;
+  const parts = rawParts
+    .map((part) => orderPart(part, bareDir, column))
+    .filter((term): term is string => term !== null);
+  return parts.length > 0 ? `ORDER BY ${parts.join(", ")}` : "";
+}
+
 export function buildQuery(
   tableName: string,
   options: QueryOptions,
@@ -142,22 +198,10 @@ export function buildQuery(
     }
   }
 
-  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  applySearch(options, conditions, params, quote);
 
-  // Sort: comma-separated parts, empty parts skipped, leading "-" = DESC.
-  // ORDER BY is built only from resolved columns and the words ASC / DESC.
-  let orderClause = "";
-  if (options.sort) {
-    const parts: string[] = [];
-    for (const part of options.sort.split(",")) {
-      const trimmed = part.trim();
-      if (trimmed === "") continue;
-      const descending = trimmed.startsWith("-");
-      const col = column("sort", descending ? trimmed.slice(1) : trimmed);
-      parts.push(`${col} ${descending ? "DESC" : "ASC"}`);
-    }
-    if (parts.length > 0) orderClause = `ORDER BY ${parts.join(", ")}`;
-  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const orderClause = buildOrderClause(options, column);
 
   // Pagination — PAGE-DEC-01: clamp page >= 1 BEFORE deriving offset, so
   // offset=(page-1)*limit can never go negative (a page=0/negative request used
@@ -188,43 +232,58 @@ export function buildQuery(
   };
 }
 
-export function parseQueryString(query: Record<string, string>): QueryOptions {
-  const options: QueryOptions = {};
-
-  // Parse filter params: filter[name]=John or filter[age][gt]=25. ANY key
-  // inside the brackets is captured - buildQuery rejects one that is not a
-  // declared field rather than it being silently ignored here (ADR-0069).
-  // A second bracket must be a known operator; a list (filter[name][]), a map
-  // (filter[name][x]) or a nested key is a wrong-shaped value and throws
-  // InvalidQueryParameterError. `sort[...]` is a list/map where a single
-  // comma-separated string belongs, and throws the same way.
-  // A null-prototype map, so a "__proto__" key is stored (and then rejected)
-  // instead of silently re-pointing the object's prototype.
+/**
+ * Parse filter params: filter[name]=John or filter[age][gt]=25. ANY key
+ * inside the brackets is captured - buildQuery rejects one that is not a
+ * declared field rather than it being silently ignored here (ADR-0069).
+ * A second bracket must be a known operator; a list (filter[name][]), a map
+ * (filter[name][x]) or a nested key is a wrong-shaped value and throws
+ * InvalidQueryParameterError. `sort[...]` is a list/map where a single
+ * comma-separated string belongs, and throws the same way.
+ * A null-prototype map, so a "__proto__" key is stored (and then rejected)
+ * instead of silently re-pointing the object's prototype.
+ */
+function parseFilterParams(query: Record<string, string>): Record<string, unknown> {
   const filter: Record<string, unknown> = Object.create(null);
   for (const [key, value] of Object.entries(query)) {
     if (key.startsWith("sort[")) {
       throw new InvalidQueryParameterError("Query parameter 'sort' must be a single comma-separated string");
     }
     if (!key.startsWith("filter[")) continue;
-    const filterMatch = key.match(/^filter\[([^\]]*)\](.*)$/s);
-    if (!filterMatch) throw new UnknownFieldError("filter", key.slice("filter[".length));
-    const [, field, rest] = filterMatch;
-    if (rest === "") {
-      filter[field] = value;
-      continue;
-    }
-    const operator = rest.match(/^\[([^[\]]*)\]$/)?.[1];
-    if (operator === undefined || !Object.hasOwn(operatorMap, operator)) throw filterValueError(field);
-    if (!filter[field] || typeof filter[field] !== "object") {
-      filter[field] = {};
-    }
-    (filter[field] as Record<string, string>)[operator] = value;
+    addFilterKey(filter, key, value);
+  }
+  return filter;
+}
+
+/** Store one filter[field] / filter[field][op] param into the filter map. */
+function addFilterKey(filter: Record<string, unknown>, key: string, value: string): void {
+  const filterMatch = key.match(/^filter\[([^\]]*)\](.*)$/s);
+  if (!filterMatch) throw new UnknownFieldError("filter", key.slice("filter[".length));
+  const [, field, rest] = filterMatch;
+  if (rest === "") {
+    filter[field] = value;
+    return;
   }
+  const operator = rest.match(/^\[([^[\]]*)\]$/)?.[1];
+  if (operator === undefined || !Object.hasOwn(operatorMap, operator)) throw filterValueError(field);
+  if (!filter[field] || typeof filter[field] !== "object") {
+    filter[field] = {};
+  }
+  (filter[field] as Record<string, string>)[operator] = value;
+}
+
+export function parseQueryString(query: Record<string, string>): QueryOptions {
+  const options: QueryOptions = {};
+
+  const filter = parseFilterParams(query);
   if (Object.keys(filter).length > 0) {
     options.filter = filter;
   }
 
   if (query.sort) options.sort = query.sort;
+  // ADR-0094: the CRUD grid's search + single-column sort direction.
+  if (query.search !== undefined) options.search = query.search;
+  if (query.sort_dir !== undefined) options.sortDir = query.sort_dir;
   if (query.page) options.page = parseInt(query.page, 10);
   if (query.limit) options.limit = parseInt(query.limit, 10);
   // Allow ?offset= as an alternative to ?page= (offset-based pagination)

package/packages/orm/src/sqlTranslator.ts

@@ -802,7 +802,14 @@ export class SQLTranslator {
     if (limit === undefined || limit === null || limit <= 0) return sql;
     if (SQLTranslator.hasTrailingLimit(sql)) return sql;
 
-    const trimmed = sql.replace(/[\s;]+$/, "");
+    // Strip trailing whitespace/semicolons with a linear end-scan rather than a
+    // `/[\s;]+$/` replace, which backtracks superlinearly on a long run of
+    // whitespace/semicolons followed by a non-matching tail (ReDoS-safe). Plain
+    // character comparison — no regex.
+    const trailing = " \t\n\r\f\v;";
+    let end = sql.length;
+    while (end > 0 && trailing.includes(sql[end - 1])) end--;
+    const trimmed = sql.slice(0, end);
     const suffix = offset !== undefined && offset > 0
       ? `LIMIT ${limit} OFFSET ${offset}`
       : `LIMIT ${limit}`;

package/packages/orm/src/types.ts

@@ -235,4 +235,23 @@ export interface QueryOptions {
   sort?: string;
   page?: number;
   limit?: number;
+  /**
+   * ADR-0094: full-text search term. LIKE %term% is OR'd across `searchColumns`
+   * and added to the WHERE before limit/offset, so the total reflects the
+   * filtered set. The CRUD admin grid (and any client) drives this via ?search=.
+   */
+  search?: string;
+  /**
+   * DB columns the `search` term matches against (the model's declared
+   * string/text columns, already resolved to their mapped column names). The
+   * caller resolves these from the model; buildQuery only quotes and binds them,
+   * so nothing but a declared column can reach SQL (ADR-0069).
+   */
+  searchColumns?: string[];
+  /**
+   * ADR-0094: direction for a single bare ?sort=column (the CRUD grid's
+   * spelling). "desc" sorts descending; anything else ascending. Ignored for a
+   * Mongo-style "-field,field" sort, which carries its own inline direction.
+   */
+  sortDir?: string;
 }

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

@@ -35,6 +35,29 @@ export declare function devMutationDenial(req: Tina4Request): {
  * governs it instead.
  */
 export declare function devHostAllowed(hostHeader: string | undefined | null): boolean;
+/**
+ * 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 declare function ipInCidr(ip: string, entry: string): boolean;
+/**
+ * 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 declare function devPeerAllowed(remoteIp: string | undefined | null): boolean;
+/**
+ * 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 declare function devToolbarAllowed(req: Tina4Request): boolean;
 /**
  * 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

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

@@ -58,6 +58,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 {
     uid: string;
@@ -114,6 +116,8 @@ export declare class Messenger {
     private imapUser;
     private imapPass;
     private imapEncryption;
+    /** Resolved SMTP send timeout, in milliseconds (see the constructor). */
+    readonly timeoutMs: number;
     constructor(options?: MessengerOptions);
     /**
      * How the SMTP connection is secured (ADR-0071 section 1). Port 465 is the

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

@@ -352,11 +352,6 @@ export declare function resolveStringMiddleware(spec: string): Promise<Middlewar
  * was inert. Python and PHP both ran per-route class hooks already.
  */
 export declare function runRouteMiddlewares(middlewares: MiddlewareSpec[], req: Tina4Request, res: Tina4Response): Promise<boolean>;
-/**
- * Default global router instance.
- * Top-level get(), post(), etc. register routes here.
- * The server merges these routes on startup.
- */
 export declare const defaultRouter: Router;
 /**
  * Top-level route registration functions — mirrors Python's decorator pattern.

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

@@ -49,6 +49,12 @@ export declare const TEMPLATE_CACHE_MAX = 256;
 export declare const MEMO_CACHE_MAX = 1024;
 /** Cached expression dispatcher branch; exported only for cache-bound verification. */
 export declare const expressionFormCache: Map<string, number>;
+/**
+ * The framework's ONE canonical HTML escaper (the five-character table `& < > " '`,
+ * byte-identical across all four Tina4 frameworks). Exported so a component such as
+ * Crud.toCrud never carries its own copy of the escape table (ADR-0094).
+ */
+export declare function escapeHtml(value: unknown): string;
 /**
  * Set the session ID used by formToken() / form_token() for CSRF session binding.
  */

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

@@ -1,2 +1,2 @@
-export { Frond } from "./engine.js";
+export { Frond, escapeHtml, setCspNonceProvider } from "./engine.js";
 export type { FilterFn, TestFn, LiveProvider, LiveRequest, LiveResponse, LiveBroadcaster } from "./engine.js";

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

@@ -0,0 +1,82 @@
+/**
+ * Crud (ADR-0094) — a FRONTEND over AutoCrud.
+ *
+ * `Crud.toCrud(request, options)` renders a complete server-rendered admin UI
+ * (searchable, sortable, paginated table + create/edit/delete modals) for an ORM
+ * model. It owns NO backend routes: the entire REST backend (GET list, GET /{id},
+ * POST, PUT, DELETE, secure-by-default) is delegated to AutoCrud, and the UI's
+ * JavaScript talks to those routes over fetch(). The HTML comes from four
+ * app-overridable Frond templates under `crud/` (page, table, form, modals),
+ * resolved app-first-then-framework (the same convention the error pages use), so
+ * an app restyles the admin by dropping its own `src/templates/crud/<name>.twig`.
+ *
+ * Lives in @tina4/orm (next to AutoCrud, the ORM it drives) rather than in the
+ * eager @tina4/core barrel: Crud is an opt-in feature, not on every request
+ * path, so it must not be pulled into core's import graph (lazyFeatureLoading).
+ *
+ * Node returns `Promise<string>` (the DB adapters are async); the Python/PHP/Ruby
+ * entry points return a string. generateTable / generateForm stay synchronous.
+ *
+ * Usage:
+ *   get("/admin/users", async (request, response) =>
+ *     response.html(await Crud.toCrud(request, { model: User, title: "Users" }))
+ *   ).secure();
+ *
+ * A custom `sql` only shapes the LISTING grid (a filter/join/projection); the
+ * model still drives columns, the primary key, and every write path, so a custom
+ * listing can never create an unauthenticated or divergent write route.
+ */
+import type { Tina4Request } from "../../core/src/types.js";
+import { type CrudModel, stripOrderAndLimit } from "./crudHelpers.js";
+import { generateTable, generateForm } from "./crudRender.js";
+export type { CrudModel } from "./crudHelpers.js";
+export type { FormFieldDef } from "./crudRender.js";
+export { generateTable, generateForm } from "./crudRender.js";
+export { stripOrderAndLimit } from "./crudHelpers.js";
+export interface ToCrudOptions {
+    /** REQUIRED — the ORM model class (a BaseModel subclass). */
+    model: CrudModel;
+    /** Optional listing query (inferred from the model when omitted); shapes only the displayed grid. */
+    sql?: string;
+    /** Page title (default "CRUD"). */
+    title?: string;
+    /** AutoCrud route prefix (default "/api"). */
+    prefix?: string;
+    /** Records per page (default 10). */
+    limit?: number;
+    /** When true, the AutoCrud write routes are OPEN (no auth). Default false (secure). */
+    public?: boolean;
+}
+/** Reset the registration cache (tests). */
+export declare function _resetCrudRegistrations(): void;
+/**
+ * Delegate the ENTIRE backend to AutoCrud. Idempotent per (prefix, table):
+ * the first registration wins (so a scaffolded route that opted writes public
+ * is not later reset to secure), and addRoute replaces a route in place anyway.
+ */
+export declare function registerBackend(model: CrudModel, options?: {
+    prefix?: string;
+    public?: boolean;
+}): Promise<void>;
+/**
+ * Render the CRUD admin page for `model` and register its AutoCrud routes.
+ * Returns the rendered crud/page template.
+ */
+export declare function toCrud(request: Tina4Request, options: ToCrudOptions): Promise<string>;
+/** The public Crud surface (ADR-0094). `CRUD` is an uppercase alias. */
+export declare const Crud: {
+    toCrud: typeof toCrud;
+    registerBackend: typeof registerBackend;
+    generateTable: typeof generateTable;
+    generateForm: typeof generateForm;
+    stripOrderAndLimit: typeof stripOrderAndLimit;
+    _resetCrudRegistrations: typeof _resetCrudRegistrations;
+};
+export declare const CRUD: {
+    toCrud: typeof toCrud;
+    registerBackend: typeof registerBackend;
+    generateTable: typeof generateTable;
+    generateForm: typeof generateForm;
+    stripOrderAndLimit: typeof stripOrderAndLimit;
+    _resetCrudRegistrations: typeof _resetCrudRegistrations;
+};

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

@@ -0,0 +1,63 @@
+/**
+ * Crud (ADR-0094) — the pure helpers behind the HTML admin page.
+ *
+ * No I/O, no templates, no DB: column/label/alignment derivation, safe-sort
+ * resolution, the pre-joined table-data hash, the pagination controls, the
+ * injected JS config, and the two linear SQL-listing parsers. Kept in their own
+ * module so `crud.ts` stays a thin orchestrator and no single file carries the
+ * whole feature (the second-pass split by concern).
+ */
+import { escapeHtml } from "../../frond/src/engine.js";
+/** A BaseModel-like class: the statics Crud reads + the query statics it calls. */
+export interface CrudModel {
+    tableName: string;
+    fields: Record<string, {
+        type?: string;
+        primaryKey?: boolean;
+        [k: string]: unknown;
+    }>;
+    fieldMapping?: Record<string, string>;
+    softDelete?: boolean;
+    tableFilter?: string;
+    name?: string;
+    all(limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<any>;
+    where(conditions: string, params?: unknown[], limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<any>;
+    count(conditions?: string, params?: unknown[]): Promise<number>;
+}
+/** Escape alias used throughout the CRUD HTML assembly. */
+export declare const h: typeof escapeHtml;
+/** The DB column a property name maps to (fieldMapping or the property itself). */
+export declare function columnOf(model: CrudModel, prop: string): string;
+/** The primary-key property name (the field flagged primaryKey, else "id"). */
+export declare function primaryKeyProp(model: CrudModel): string;
+/** The model's declared string/text property names. */
+export declare function searchableProps(model: CrudModel): string[];
+/** Column alignment from the field type: numeric right, everything else left. */
+export declare function columnAlignment(model: CrudModel | null, col: string): string;
+/** Pretty label from a column name: "user_name" => "User Name". */
+export declare function prettyLabel(col: string): string;
+/**
+ * ADR-0069 safe sort: resolve the requested sort to a declared field PROPERTY
+ * (the grid's headers + client state are keyed by property), else the primary
+ * key. A request may name the field by its property or its mapped column; the
+ * DB column for the ORDER BY is derived with columnOf(). A rendered page ignores
+ * a bad sort rather than erroring.
+ */
+export declare function crudSortProp(model: CrudModel, requested: string | undefined, pkProp: string): string;
+/** Read one column value from a record hash (keyed by property name). */
+export declare function cellValue(record: Record<string, unknown>, col: string): unknown;
+/** Build the pre-joined <td> run for one row (every value escaped + aligned). */
+export declare function buildCells(columns: string[], record: Record<string, unknown>, editable: boolean, aligns: string[]): string;
+/**
+ * Drop a trailing ORDER BY / LIMIT clause from each line of a custom listing SQL.
+ * Pure string scanning — no backtracking regex.
+ */
+export declare function stripOrderAndLimit(sql: string): string;
+/**
+ * The column names a custom listing SQL selects (for the search CAST LIKE).
+ * Linear string scan: locate the first SELECT / FROM keywords (whitespace
+ * bounded, case-insensitive) and split the projection on commas — no
+ * backtracking regex over caller-supplied SQL (ReDoS-safe), mirroring the
+ * Ruby master's plain-string SQL parsing.
+ */
+export declare function extractColumns(sql: string): string[];