tina4-nodejs 3.13.94 → 3.13.96

package/packages/orm/src/types.ts

@@ -31,6 +31,13 @@ export interface RelationshipDefinition {
 
 export interface ModelDefinition {
   tableName: string;
+  /**
+   * The model CLASS name (e.g. `Item` for tableName `items`), carried from
+   * `ModelClass.name` at discovery. Swagger keys `components.schemas` by this —
+   * the type name a generated client wants — falling back to a singular
+   * PascalCase derivation of tableName when a raw definition carries none.
+   */
+  className?: string;
   fields: Record<string, FieldDefinition>;
   fieldMapping?: Record<string, string>;
   softDelete?: boolean;
@@ -77,8 +84,8 @@ export interface DatabaseAdapter {
   /** Insert one or more rows into a table, returns result with lastId. */
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
 
-  /** Update rows in a table matching filter, returns affected row count. */
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+  /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
 
   /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
   delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
@@ -93,10 +100,10 @@ export interface DatabaseAdapter {
   rollback(): void;
 
   /** List all tables in the database. */
-  tables(): string[];
+  getTables(): string[];
 
   /** List columns with types for a table. */
-  columns(table: string): ColumnInfo[];
+  getColumns(table: string): ColumnInfo[];
 
   /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
   lastInsertId(): number | bigint | string | null;
@@ -115,80 +122,17 @@ export interface DatabaseAdapter {
 
   /** Add a column to an existing table (legacy, used by migration). */
   addColumn?(table: string, colName: string, def: FieldDefinition): void;
-}
 
-export interface PaginatedResult<T = Record<string, unknown>> {
-  data: T[];
-  page: number;
-  perPage: number;
-  total: number;
-  totalPages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-}
-
-/**
- * Wraps an array of fetched rows with convenience methods.
- *
- * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
- */
-export class FetchResult<T = Record<string, unknown>> {
-  readonly records: T[];
-  readonly count: number;
-  readonly sql: string;
-
-  constructor(records: T[], sql = "") {
-    this.records = records;
-    this.count = records.length;
-    this.sql = sql;
-  }
-
-  /** Paginate the in-memory result set. */
-  toPaginate(page = 1, perPage = 20): PaginatedResult<T> {
-    const total = this.count;
-    const totalPages = Math.max(1, Math.ceil(total / perPage));
-    const offset = (page - 1) * perPage;
-    const data = this.records.slice(offset, offset + perPage);
-    return {
-      data,
-      page,
-      perPage,
-      total,
-      totalPages,
-      hasNext: page < totalPages,
-      hasPrev: page > 1,
-    };
-  }
-
-  /** Return the first record or null. */
-  first(): T | null {
-    return this.records[0] ?? null;
-  }
-
-  /** Return the last record or null. */
-  last(): T | null {
-    return this.records[this.records.length - 1] ?? null;
-  }
-
-  /** Check if result is empty. */
-  isEmpty(): boolean {
-    return this.records.length === 0;
-  }
-
-  /** Convert to plain array. */
-  toArray(): T[] {
-    return [...this.records];
-  }
-
-  /** Convert to JSON string. */
-  toJSON(): string {
-    return JSON.stringify(this.records);
-  }
-
-  /** Iterate over records. */
-  [Symbol.iterator](): Iterator<T> {
-    return this.records[Symbol.iterator]();
-  }
+  /**
+   * Stable identity of the DATABASE this adapter is connected to, as
+   * `engine://host:port/database` with NO credentials - set by whoever built
+   * the adapter from a URL or config.
+   *
+   * The query cache folds this into every key. Without it two databases sharing
+   * one cache backend cross-serve each other's rows, because identical SQL text
+   * across tenants is the common case.
+   */
+  cacheIdentity?: string;
 }
 
 export interface QueryOptions {

package/packages/swagger/dist/index.js

@@ -73,8 +73,12 @@ function sanitizeSecurity(reqs, schemes) {
 function generate(routes, models = []) {
   const info = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation"
+    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
+    // 0.0.1). description defaults to the empty string, not a canned sentence.
+    // Both are the settled cross-framework defaults (parity with the Python
+    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
+    version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? ""
   };
   const contactEmail = (process.env.TINA4_SWAGGER_CONTACT_EMAIL ?? "").trim();
   const contactName = (process.env.TINA4_SWAGGER_CONTACT_TEAM ?? "").trim();
@@ -107,9 +111,11 @@ function generate(routes, models = []) {
   const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
   const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
   const refSchemas = /* @__PURE__ */ new Set();
+  const tableToSchema = /* @__PURE__ */ new Map();
   for (const model of models) {
-    const schema = modelToSchema(model);
-    spec.components.schemas[model.tableName] = schema;
+    const schemaKey = schemaNameForModel(model);
+    tableToSchema.set(model.tableName, schemaKey);
+    spec.components.schemas[schemaKey] = modelToSchema(model);
   }
   const usedTags = [];
   const seenIds = /* @__PURE__ */ new Set();
@@ -136,11 +142,11 @@ function generate(routes, models = []) {
     if (route.meta?.deprecated) operation.deprecated = true;
     const pathParams = extractPathParams(route.pattern);
     if (pathParams.length > 0) {
-      operation.parameters = pathParams.map((name) => ({
+      operation.parameters = pathParams.map(({ name, schema }) => ({
         name,
         in: "path",
         required: true,
-        schema: { type: "string" }
+        schema
       }));
     }
     if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
@@ -166,19 +172,20 @@ function generate(routes, models = []) {
       };
     } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        const media = {
-          schema: { $ref: `#/components/schemas/${modelName}` }
-        };
+      const schemaKey = modelName ? tableToSchema.get(modelName) : void 0;
+      if (schemaKey) {
+        const sref = `#/components/schemas/${schemaKey}`;
+        const media = { schema: { $ref: sref } };
         if (route.meta?.example !== void 0) media.example = route.meta.example;
         operation.requestBody = {
           required: true,
           content: { "application/json": media }
         };
-        operation.responses = {
-          ...method === "post" ? { "201": { description: "Created", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } } : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } },
-          "422": { description: "Validation failed" }
-        };
+        if (route.meta?.responses === void 0) {
+          operation.responses = {
+            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
+          };
+        }
       } else if (route.meta?.example !== void 0) {
         operation.requestBody = {
           content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
@@ -265,6 +272,21 @@ function resolveServers() {
   const dev = (process.env.SWAGGER_DEV_URL ?? "").trim();
   return dev.length > 0 ? [{ url: dev }] : [{ url: "/" }];
 }
+function schemaNameForModel(model) {
+  const explicit = model.className?.trim();
+  if (explicit) return explicit;
+  return deriveClassName(model.tableName);
+}
+function deriveClassName(tableName) {
+  return singularize(tableName).split(/[_\s-]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("") || tableName;
+}
+function singularize(word) {
+  if (/ies$/i.test(word) && word.length > 3) return word.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/i.test(word)) return word.slice(0, -2);
+  if (/ss$/i.test(word)) return word;
+  if (/s$/i.test(word) && word.length > 1) return word.slice(0, -1);
+  return word;
+}
 function modelToSchema(model) {
   const properties = {};
   const required = [];
@@ -338,15 +360,47 @@ function inferSchema(value) {
   if (typeof value === "number") return { type: Number.isInteger(value) ? "integer" : "number" };
   return { type: "string" };
 }
+var PARAM_TYPE_SCHEMA = {
+  int: { type: "integer" },
+  integer: { type: "integer" },
+  float: { type: "number" },
+  number: { type: "number" },
+  uuid: { type: "string", format: "uuid" },
+  slug: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+  alpha: { type: "string", pattern: "^[A-Za-z]+$" },
+  alnum: { type: "string", pattern: "^[A-Za-z0-9]+$" },
+  path: { type: "string" },
+  string: { type: "string" }
+};
+function segmentParam(segment) {
+  if (segment.startsWith("{") && segment.endsWith("}")) {
+    const inner = segment.slice(1, -1);
+    if (inner.startsWith("...")) return { name: inner.slice(3), type: "string" };
+    const colon = inner.indexOf(":");
+    if (colon >= 0) return { name: inner.slice(0, colon), type: inner.slice(colon + 1) };
+    return { name: inner, type: "string" };
+  }
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    const inner = segment.slice(1, -1);
+    return { name: inner.startsWith("...") ? inner.slice(3) : inner, type: "string" };
+  }
+  if (segment.startsWith(":") && segment.length > 1) {
+    return { name: segment.slice(1), type: "string" };
+  }
+  return null;
+}
 function patternToOpenAPI(pattern) {
-  return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
+  return pattern.split("/").map((segment) => {
+    const p = segmentParam(segment);
+    return p ? `{${p.name}}` : segment;
+  }).join("/");
 }
 function extractPathParams(pattern) {
   const params = [];
-  const regex = /\[(?:\.\.\.)?(\w+)\]/g;
-  let match;
-  while ((match = regex.exec(pattern)) !== null) {
-    params.push(match[1]);
+  for (const segment of pattern.split("/")) {
+    const p = segmentParam(segment);
+    if (!p) continue;
+    params.push({ name: p.name, schema: { ...PARAM_TYPE_SCHEMA[p.type] ?? { type: "string" } } });
   }
   return params;
 }
@@ -368,8 +422,12 @@ function inferModelFromPath(pattern) {
   if (rest.length === 1 && /^[[{]\.{0,3}\w+[\]}]$/.test(rest[0])) return candidate;
   return null;
 }
+function operationIdBase(method, openApiPath) {
+  const clean = openApiPath.replace(/^\/+|\/+$/g, "").replace(/\//g, "_").replace(/\.\.\./g, "").replace(/[{}]/g, "").replace(/\*/g, "wildcard");
+  return clean ? `${method}_${clean}` : method;
+}
 function uniqueOperationId(method, openApiPath, seen) {
-  const base = (method + openApiPath.replace(/[/{}]/g, "_")).replace(/_+/g, "_").replace(/_$/, "");
+  const base = operationIdBase(method, openApiPath);
   let oid = base;
   let n = 2;
   while (seen.has(oid)) {

package/packages/swagger/src/generator.ts

@@ -140,8 +140,12 @@ export function generate(
 ): OpenAPISpec {
   const info: OpenAPISpecInfo = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
+    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
+    // 0.0.1). description defaults to the empty string, not a canned sentence.
+    // Both are the settled cross-framework defaults (parity with the Python
+    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
+    version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "",
   };
 
   // Optional contact — email, plus name/url (the interface declares them; they
@@ -188,10 +192,15 @@ export function generate(
   // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
   const refSchemas = new Set<string>();
 
-  // Generate schemas from models
+  // Generate schemas from models, keyed by the model CLASS name ('Item'), which
+  // is the type name a generated client wants — never the tableName ('items').
+  // `tableToSchema` maps a path-inferred tableName back to that schema key so a
+  // POST/PUT request body $ref resolves to the same 'Item' entry.
+  const tableToSchema = new Map<string, string>();
   for (const model of models) {
-    const schema = modelToSchema(model);
-    spec.components!.schemas![model.tableName] = schema;
+    const schemaKey = schemaNameForModel(model);
+    tableToSchema.set(model.tableName, schemaKey);
+    spec.components!.schemas![schemaKey] = modelToSchema(model);
   }
 
   const usedTags: string[] = [];
@@ -224,14 +233,18 @@ export function generate(
     if (route.meta?.description) operation.description = route.meta.description;
     if (route.meta?.deprecated) operation.deprecated = true;
 
-    // Add path parameters
+    // Add path parameters. Each typed token maps to its JSON Schema fragment
+    // (int -> integer, uuid -> string+format, slug -> string+pattern, ...) via
+    // PARAM_TYPE_SCHEMA below, mirroring the Python master's _PARAM_TYPE_SCHEMA
+    // and the router's accepted token set. An unknown token degrades to string
+    // rather than dropping the parameter, and the token never reaches the key.
     const pathParams = extractPathParams(route.pattern);
     if (pathParams.length > 0) {
-      operation.parameters = pathParams.map((name) => ({
+      operation.parameters = pathParams.map(({ name, schema }) => ({
         name,
         in: "path",
         required: true,
-        schema: { type: "string" },
+        schema,
       }));
     }
 
@@ -263,23 +276,27 @@ export function generate(
       };
     } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        const media: Record<string, unknown> = {
-          schema: { $ref: `#/components/schemas/${modelName}` },
-        };
+      const schemaKey = modelName ? tableToSchema.get(modelName) : undefined;
+      if (schemaKey) {
+        const sref = `#/components/schemas/${schemaKey}`;
+        const media: Record<string, unknown> = { schema: { $ref: sref } };
         if (route.meta?.example !== undefined) media.example = route.meta.example;
         operation.requestBody = {
           required: true,
           content: { "application/json": media },
         };
 
-        // Add response schema
-        operation.responses = {
-          ...(method === "post"
-            ? { "201": { description: "Created", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }
-            : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }),
-          "422": { description: "Validation failed" },
-        };
+        // Response documents 200 with the resource schema — parity with the
+        // Python master, which emits ONLY 200 for a model write. The old code
+        // stamped an unconditional 422 and a 201 the generator has no way to know
+        // a given route returns; both were fiction on a path-inferred write. A
+        // route that genuinely answers another code declares it via
+        // meta.responses, which is honoured above and never clobbered here.
+        if (route.meta?.responses === undefined) {
+          operation.responses = {
+            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } },
+          };
+        }
       } else if (route.meta?.example !== undefined) {
         // Non-model body with an explicit example.
         operation.requestBody = {
@@ -394,6 +411,36 @@ function resolveServers(): { url: string }[] {
   return dev.length > 0 ? [{ url: dev }] : [{ url: "/" }];
 }
 
+/**
+ * The `components.schemas` key for a model: its CLASS name when carried from
+ * discovery (`ModelClass.name`, e.g. `Item`), else a singular PascalCase
+ * derivation of the tableName so a raw `{tableName, fields}` still yields a
+ * client-friendly type name ('items' -> 'Item').
+ */
+function schemaNameForModel(model: ModelDefinition): string {
+  const explicit = model.className?.trim();
+  if (explicit) return explicit;
+  return deriveClassName(model.tableName);
+}
+
+/** 'items' -> 'Item', 'blog_posts' -> 'BlogPost', 'categories' -> 'Category'. */
+function deriveClassName(tableName: string): string {
+  return singularize(tableName)
+    .split(/[_\s-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("") || tableName;
+}
+
+/** Best-effort English singularisation for the common plural-table convention. */
+function singularize(word: string): string {
+  if (/ies$/i.test(word) && word.length > 3) return word.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/i.test(word)) return word.slice(0, -2);
+  if (/ss$/i.test(word)) return word;      // "class"/"address" stay as-is
+  if (/s$/i.test(word) && word.length > 1) return word.slice(0, -1);
+  return word;
+}
+
 function modelToSchema(model: ModelDefinition): Record<string, unknown> {
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
@@ -479,16 +526,93 @@ function inferSchema(value: unknown): Record<string, unknown> {
   return { type: "string" };
 }
 
+/**
+ * Path-param type token -> JSON Schema fragment. Mirrors the Python master's
+ * `_PARAM_TYPE_SCHEMA` (tina4_python/swagger/__init__.py) and the router's
+ * `PARAM_TYPE_PATTERNS`, so the documented contract matches EXACTLY what the
+ * router accepts. `int`/`integer` -> integer, `float`/`number` -> number,
+ * `uuid` -> string+format, `slug`/`alpha`/`alnum` -> string+pattern, bare/`path`
+ * -> string. A token NOT in this table degrades to `{type:"string"}` (see
+ * `extractPathParams`) rather than dropping the parameter.
+ */
+const PARAM_TYPE_SCHEMA: Record<string, Record<string, unknown>> = {
+  int: { type: "integer" },
+  integer: { type: "integer" },
+  float: { type: "number" },
+  number: { type: "number" },
+  uuid: { type: "string", format: "uuid" },
+  slug: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+  alpha: { type: "string", pattern: "^[A-Za-z]+$" },
+  alnum: { type: "string", pattern: "^[A-Za-z0-9]+$" },
+  path: { type: "string" },
+  string: { type: "string" },
+};
+
+/**
+ * The (name, type) of a single dynamic path segment, or null for a static one.
+ *
+ * Accepts EVERY shape a route pattern can carry: the brace form `{id}` /
+ * `{id:int}` / `{...slug}` (the runtime/programmatic spelling), the file-system
+ * form `[id]` / `[...slug]` (route discovery converts these to `{...}` before a
+ * route is registered, but `generate()` is public and a caller may hand either),
+ * and the Express form `:id`. A catch-all (`...`) carries no type token, so it
+ * is always a string.
+ */
+function segmentParam(segment: string): { name: string; type: string } | null {
+  if (segment.startsWith("{") && segment.endsWith("}")) {
+    const inner = segment.slice(1, -1);
+    if (inner.startsWith("...")) return { name: inner.slice(3), type: "string" };
+    const colon = inner.indexOf(":");
+    if (colon >= 0) return { name: inner.slice(0, colon), type: inner.slice(colon + 1) };
+    return { name: inner, type: "string" };
+  }
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    const inner = segment.slice(1, -1);
+    return { name: inner.startsWith("...") ? inner.slice(3) : inner, type: "string" };
+  }
+  if (segment.startsWith(":") && segment.length > 1) {
+    return { name: segment.slice(1), type: "string" };
+  }
+  return null;
+}
+
+/**
+ * The OpenAPI path key for a route pattern: every dynamic segment collapses to a
+ * bare `{name}`, so the type token NEVER leaks into the key (PHP shipped
+ * `/api/typed/{id:int}` as the key — invalid, and a mismatch with the declared
+ * parameter). File-system `[id]`/`[...slug]`, runtime `{id:int}`/`{...slug}` and
+ * Express `:id` all normalise to `{name}`.
+ */
 function patternToOpenAPI(pattern: string): string {
-  return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
+  return pattern
+    .split("/")
+    .map((segment) => {
+      const p = segmentParam(segment);
+      return p ? `{${p.name}}` : segment;
+    })
+    .join("/");
 }
 
-function extractPathParams(pattern: string): string[] {
-  const params: string[] = [];
-  const regex = /\[(?:\.\.\.)?(\w+)\]/g;
-  let match;
-  while ((match = regex.exec(pattern)) !== null) {
-    params.push(match[1]);
+/**
+ * Every dynamic path parameter of a route pattern as a `{name, schema}` pair.
+ *
+ * This once matched only `[id]` - the FILE-SYSTEM spelling - while route
+ * discovery had already converted `[id]` to `{id}`, so at runtime the regex ran
+ * against `{id}` looking for `[id]` and returned nothing: every operation
+ * shipped with no `in: path` parameter, an invalid document (measured against
+ * openapi-spec-validator), unconditionally, because the framework registers
+ * `/__frond/live/{name}` itself. Beyond that first fix, a TYPED token like
+ * `{id:int}` was still dropped (the name-only regex did not match past the
+ * colon) and its type leaked into the path key. This segment-based walk resolves
+ * both spellings AND the type token, mapping it through PARAM_TYPE_SCHEMA so the
+ * documented type matches the route the router compiled.
+ */
+function extractPathParams(pattern: string): Array<{ name: string; schema: Record<string, unknown> }> {
+  const params: Array<{ name: string; schema: Record<string, unknown> }> = [];
+  for (const segment of pattern.split("/")) {
+    const p = segmentParam(segment);
+    if (!p) continue;
+    params.push({ name: p.name, schema: { ...(PARAM_TYPE_SCHEMA[p.type] ?? { type: "string" }) } });
   }
   return params;
 }
@@ -517,10 +641,29 @@ function inferModelFromPath(pattern: string): string | null {
   return null;
 }
 
+/**
+ * operationId base from method + path, mirroring the Python master's
+ * `_operation_id`: strip leading/trailing slashes, turn internal `/` into `_`,
+ * drop braces, catch-all `...` and a bare splat `*` -> `wildcard`.
+ *
+ * Underscores are deliberately NOT collapsed. Collapsing made `/__health` and
+ * `/health` both reduce to `get_health`, so one got a `_2` suffix and WHICH one
+ * depended on registration order — a generated client's method name flipping
+ * between builds. Preserving them yields `get___health` vs `get_health`, two
+ * distinct ids straight from the two distinct paths.
+ */
+function operationIdBase(method: string, openApiPath: string): string {
+  const clean = openApiPath
+    .replace(/^\/+|\/+$/g, "")   // strip leading/trailing slashes (Python .strip("/"))
+    .replace(/\//g, "_")          // internal slash -> underscore
+    .replace(/\.\.\./g, "")       // catch-all '...' inside braces -> nothing ({...slug} -> slug)
+    .replace(/[{}]/g, "")         // drop braces
+    .replace(/\*/g, "wildcard");  // bare splat -> wildcard
+  return clean ? `${method}_${clean}` : method;
+}
+
 function uniqueOperationId(method: string, openApiPath: string, seen: Set<string>): string {
-  const base = (method + openApiPath.replace(/[/{}]/g, "_"))
-    .replace(/_+/g, "_")
-    .replace(/_$/, "");
+  const base = operationIdBase(method, openApiPath);
   let oid = base;
   let n = 2;
   while (seen.has(oid)) {

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

@@ -61,4 +61,4 @@ export declare function writeOrMerge(contextPath: string, contextFile: string, f
  * Generate the Tina4 context document for a specific AI tool.
  */
 export declare function generateContext(toolName?: string): string;
-export { AiTool as AiToolType };
+export type { AiTool as AiToolType };

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

@@ -16,6 +16,18 @@ import type { Middleware } from "./types.js";
  * @returns The newly-generated secret, or null when nothing was generated.
  */
 export declare function ensureDevSecret(cwd?: string): string | null;
+/**
+ * Can this runtime actually sign and verify `algorithm` right now?
+ *
+ * The cross-framework capability check — same question, same answer shape, in
+ * all four frameworks. HMAC answers `true` everywhere. RS256 answers `true`
+ * only where the runtime ships asymmetric crypto natively (node:crypto here,
+ * core ext-openssl in PHP, the stdlib openssl gem in Ruby) and `false` in
+ * tina4-python. An algorithm Tina4 does not know at all answers `false`.
+ */
+export declare function algorithmAvailable(algorithm: string): boolean;
+/** Every algorithm this runtime can sign and verify right now, in advertised order. */
+export declare function availableAlgorithms(): string[];
 /**
  * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
  *
@@ -27,8 +39,12 @@ export declare const JWT_LEEWAY_SECONDS = 60;
 /**
  * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
  *
- * Throws (naming the supported set and the env var) when asked for an algorithm
- * we cannot sign — a silent downgrade to HS256 is the whole bug in python#106.
+ * Throws when asked for an algorithm Tina4 does not know (naming the known set,
+ * what is available here, and the env var), and throws again — with the runtime's
+ * own reason and a remedy — when it knows the algorithm but this build cannot
+ * provide it. A silent downgrade to HS256 is the whole bug in python#106, and a
+ * silent downgrade from RS256 would be worse: it would quietly turn asymmetric
+ * verification into a shared secret.
  *
  * @param algorithm - Explicit algorithm; wins over the environment when given.
  */
@@ -37,8 +53,11 @@ export declare function resolveAlgorithm(algorithm?: string): string;
  * Create a signed JWT token.
  *
  * Secret is always read from `process.env.TINA4_SECRET`.
- * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256");
- * HS256 / HS384 / HS512 / RS256 are supported and anything else throws.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ * HS256 / HS384 / HS512 is the cross-framework standard; RS256 is an opt-in
+ * extra that Node provides from builtin node:crypto (pass the PEM private key
+ * as the secret). An unknown algorithm, or one this runtime cannot provide,
+ * throws — see `resolveAlgorithm`.
  *
  * The header's `alg` is always the algorithm that actually signed the token.
  *
@@ -117,7 +136,8 @@ export declare function refreshToken(token: string, expiresIn?: number): string
  *
  * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
  * @param secret    - HMAC secret or PEM public key
- * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @param algorithm - Omit it to honour TINA4_JWT_ALGORITHM (then HS256). HS256 /
+ *   HS384 / HS512 everywhere; RS256 where the runtime provides it (it does here).
  * @returns Decoded payload, or null if missing/invalid
  */
 export declare function authenticateRequest(headers: Record<string, string | string[] | undefined>, secret?: string, algorithm?: string): Record<string, unknown> | null;
@@ -144,6 +164,9 @@ export declare function validateApiKey(provided: string, expected?: string): boo
 export declare class Auth {
     static getToken: typeof getToken;
     static validToken: typeof validToken;
+    static resolveAlgorithm: typeof resolveAlgorithm;
+    static algorithmAvailable: typeof algorithmAvailable;
+    static availableAlgorithms: typeof availableAlgorithms;
     static getPayload: typeof getPayload;
     static hashPassword: typeof hashPassword;
     static checkPassword: typeof checkPassword;

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

@@ -25,9 +25,9 @@ export declare function background(callback: () => unknown | Promise<unknown>, i
     stop: () => void;
 };
 /**
- * Clear every registered background task. Called automatically on SIGTERM/SIGINT;
- * also called from the server's `close()` so a manual server shutdown stops
- * the timer wheel along with HTTP listeners.
+ * Clear every registered background task. Called by the server's graceful
+ * shutdown (its first step on SIGTERM/SIGINT) and by its `close()`, so both a
+ * signal and a manual shutdown stop the timer wheel along with the listeners.
  */
 export declare function stopAllBackgroundTasks(): void;
 /** Number of currently-registered background tasks (test helper). */