tina4-nodejs 3.13.146 → 3.13.147

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.146)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.147)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.146 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.147 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.146",
+  "version": "3.13.147",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -16940,6 +16940,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -27924,7 +27925,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -27996,6 +27998,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -28294,7 +28317,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -28313,7 +28341,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -29459,6 +29488,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -35497,7 +35530,9 @@ var init_docsParser = __esm({
 // ../core/src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -35724,6 +35759,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "../core/src/docs.ts"() {
@@ -36029,8 +36112,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

package/packages/core/dist/index.js

@@ -16939,6 +16939,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -27880,7 +27881,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -27952,6 +27954,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -28250,7 +28273,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -28269,7 +28297,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -29415,6 +29444,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -35453,7 +35486,9 @@ var init_docsParser = __esm({
 // src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -35680,6 +35715,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "src/docs.ts"() {
@@ -35985,8 +36068,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

package/packages/core/src/docs.ts

@@ -61,7 +61,7 @@ export interface MethodSpec {
   static: boolean;
   source: "framework" | "user" | "vendor";
   version: string;
-  params: Array<{ name: string; type: string; default?: string | null }>;
+  params: Array<{ name: string; type: string; required: boolean; default: string | null }>;
   return: string;
 }
 
@@ -448,6 +448,59 @@ function scoreFqn(entry: InternalEntry, tokens: string[]): number {
  */
 const sharedFrameworkIndex = new Map<string, { entries: Map<string, InternalEntry>; mtime: number }>();
 
+/** Split `text` on top-level commas, ignoring commas nested in <>, (), [] or {}. */
+function splitTopLevel(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) { parts.push(current); current = ""; } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+/** Index of the `)` closing the parameter list that opens at `open`, or -1. */
+function closingParen(signature: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Structured params `[{name, type, required, default}]` from `name(a: T, b?: U = 1) : R`. */
+export function paramsFromSignature(signature: string): MethodSpec["params"] {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText,
+    };
+  });
+}
+
+/** Return type text from `name(...) : R` (or `): R`), "" when absent. */
+export function returnFromSignature(signature: string): string {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
+
 export class Docs {
   private projectRoot: string;
   private frameworkRoots: string[];
@@ -622,8 +675,8 @@ export class Docs {
       static: entry.static ?? false,
       source: entry.source,
       version: entry.version,
-      params: [],
-      return: "",
+      params: paramsFromSignature(entry.signature),
+      return: returnFromSignature(entry.signature),
     };
   }
 

package/packages/core/src/mcp.ts

@@ -91,6 +91,7 @@ export interface JsonSchema {
   type: string;
   properties: Record<string, { type: string; default?: unknown }>;
   required?: string[];
+  additionalProperties?: boolean;
 }
 
 export interface McpToolParam {
@@ -203,6 +204,36 @@ export function schemaFromParams(params: McpToolParam[]): JsonSchema {
   return schema;
 }
 
+/**
+ * Check call arguments against a tool's input schema BEFORE the handler runs.
+ * Returns null when valid, else the actionable message
+ * `missing required argument '<p>' (<tool> takes <p1>, <p2>)` (or
+ * `unknown argument '<k>' (...)`). Byte-identical to tina4-python's
+ * `_validate_tool_arguments` (tina4-php#271) so a wrong key never surfaces as a
+ * raw TypeError / 500.
+ */
+export function validateToolArguments(toolName: string, schema: JsonSchema, args: unknown): string | null {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args as Record<string, unknown>;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
+
 // ── Localhost detection ──────────────────────────────────────
 
 /**
@@ -574,6 +605,10 @@ export class McpServer {
     }
 
     const args = (params.arguments as Record<string, unknown>) || {};
+    const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+    if (invalid) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+    }
     // Tool handlers may be async (the DB tools await the Database wrapper); a
     // sync handler's plain return value passes through `await` unchanged.
     const result = await tool.handler(args);
@@ -1139,7 +1174,14 @@ export function registerDevTools(server: McpServer): void {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table)) {
           return { error: "Invalid table name" };
         }
-        return (await db.getColumns?.(table)) ?? [];
+        // Schema metadata (PRAGMA / information_schema via the adapter), never the
+        // first row, so an EMPTY table still reports its columns (tina4-php#271).
+        const columns = (await db.getColumns?.(table)) ?? [];
+        if (columns.length === 0) {
+          const tables = ((await db.getTables?.()) ?? []) as string[];
+          if (!tables.includes(table)) return { error: `table not found: ${table}` };
+        }
+        return columns;
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1168,6 +1210,7 @@ export function registerDevTools(server: McpServer): void {
           method: r.method || "",
           path: r.pattern || r.path || "",
           auth_required: r.secure ?? false,
+          middleware: r.middleware ?? [],
         }));
       } catch (e) {
         return { error: (e as Error).message };

package/packages/core/src/router.ts

@@ -187,6 +187,8 @@ export interface RouteInfo {
   path: string;
   handler: string;
   middlewareCount: number;
+  /** Names of the middleware attached to the route (functions / classes / string specs). */
+  middleware: string[];
   cached: boolean;
   secure: boolean;
 }
@@ -486,6 +488,8 @@ export class Router {
           path: route.pattern,
           handler: route.filePath ?? (route.handler.name || "(anonymous)"),
           middlewareCount: route.middlewares?.length ?? 0,
+          middleware: (route.middlewares ?? []).map((attached: any) =>
+            typeof attached === "string" ? attached : (attached?.name || attached?.constructor?.name || "(anonymous)")),
           cached: route.cached ?? false,
           secure: route.secure ?? false,
         });

package/packages/orm/dist/index.js

@@ -4915,6 +4915,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -15856,7 +15857,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -15928,6 +15930,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -16226,7 +16249,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -16245,7 +16273,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -17391,6 +17420,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -23429,7 +23462,9 @@ var init_docsParser = __esm({
 // ../core/src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -23656,6 +23691,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "../core/src/docs.ts"() {
@@ -23961,8 +24044,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

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

@@ -30,7 +30,8 @@ export interface MethodSpec {
     params: Array<{
         name: string;
         type: string;
-        default?: string | null;
+        required: boolean;
+        default: string | null;
     }>;
     return: string;
 }
@@ -69,6 +70,10 @@ export interface DriftHit {
     line: number;
     block: string;
 }
+/** Structured params `[{name, type, required, default}]` from `name(a: T, b?: U = 1) : R`. */
+export declare function paramsFromSignature(signature: string): MethodSpec["params"];
+/** Return type text from `name(...) : R` (or `): R`), "" when absent. */
+export declare function returnFromSignature(signature: string): string;
 export declare class Docs {
     private projectRoot;
     private frameworkRoots;

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

@@ -30,6 +30,7 @@ export interface JsonSchema {
         default?: unknown;
     }>;
     required?: string[];
+    additionalProperties?: boolean;
 }
 export interface McpToolParam {
     name: string;
@@ -57,6 +58,15 @@ export declare function decodeRequest(data: string | Record<string, unknown>): {
  * Since TypeScript erases types at runtime, we use explicit metadata.
  */
 export declare function schemaFromParams(params: McpToolParam[]): JsonSchema;
+/**
+ * Check call arguments against a tool's input schema BEFORE the handler runs.
+ * Returns null when valid, else the actionable message
+ * `missing required argument '<p>' (<tool> takes <p1>, <p2>)` (or
+ * `unknown argument '<k>' (...)`). Byte-identical to tina4-python's
+ * `_validate_tool_arguments` (tina4-php#271) so a wrong key never surfaces as a
+ * raw TypeError / 500.
+ */
+export declare function validateToolArguments(toolName: string, schema: JsonSchema, args: unknown): string | null;
 /**
  * Informational only — whether the CONFIGURED host looks local.
  *

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

@@ -92,6 +92,8 @@ export interface RouteInfo {
     path: string;
     handler: string;
     middlewareCount: number;
+    /** Names of the middleware attached to the route (functions / classes / string specs). */
+    middleware: string[];
     cached: boolean;
     secure: boolean;
 }