@nexusbloom/cli 0.3.4 → 0.8.0

package/src/sandbox.js

@@ -0,0 +1,167 @@
+/**
+ * sandbox.js — Execute tool source in a disposable child process.
+ *
+ * `Promise.race` cannot stop an infinite loop in the current process: the
+ * event loop never gets a turn, so the timeout never fires. A child process
+ * can simply be killed. This module is therefore the safety floor for any
+ * execution of downloaded code — single tools and pipelines alike.
+ *
+ * Guarantees:
+ *   - the deadline is enforced with SIGKILL, which a tool cannot trap
+ *   - the deadline starts at spawn, so a loop in the module top level (not
+ *     just in coreLogic) is still killed
+ *   - the child cannot write to the CLI's stdout/stderr
+ *   - a crash, OOM, or `process.exit()` inside the tool does not kill the CLI
+ */
+
+import { fork } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNNER_PATH = path.join(__dirname, "runner.js");
+
+/** Default V8 heap ceiling for tool code, in MB. */
+const DEFAULT_MEMORY_MB = 512;
+
+/** Node's own boot time is not counted against the tool's timeout budget. */
+const SPAWN_GRACE_MS = 750;
+
+let runnerMissing = false;
+
+/**
+ * Run a tool's source with the given input.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.source      v2 source text
+ * @param {object}   opts.input       input object passed to coreLogic
+ * @param {number}  [opts.timeoutMs]  wall-clock budget for the whole execution
+ * @param {number}  [opts.memoryMb]   V8 heap cap for the child
+ * @returns {Promise<{ok: boolean, result?: any, error?: string, timedOut?: boolean,
+ *                    durationMs: number, stderr?: string}>}
+ */
+export function execInSandbox({
+  source,
+  input = {},
+  timeoutMs = 5000,
+  memoryMb = DEFAULT_MEMORY_MB,
+} = {}) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+
+    if (runnerMissing) {
+      return resolve(fail("Sandbox runner is unavailable (runner.js not found).", startedAt));
+    }
+    if (typeof source !== "string" || !source.trim()) {
+      return resolve(fail("No tool source to execute.", startedAt));
+    }
+
+    const budgetMs = Math.max(1, timeoutMs) + SPAWN_GRACE_MS;
+    let child;
+    let settled = false;
+    let timer;
+
+    const done = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // Best-effort teardown; a tool may already be gone.
+      try {
+        if (child && !child.killed) child.kill("SIGKILL");
+      } catch {
+        /* already dead */
+      }
+      resolve({ durationMs: Date.now() - startedAt, ...payload });
+    };
+
+    try {
+      child = fork(RUNNER_PATH, [], {
+        cwd: process.cwd(),
+        env: { ...process.env, NXB_SANDBOX: "1" },
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        execArgv: [`--max-old-space-size=${memoryMb}`],
+        serialization: "advanced",
+      });
+    } catch (err) {
+      return done({ ok: false, error: `Could not start sandbox: ${err.message}` });
+    }
+
+    // Tool stdout/stderr is captured, never forwarded — a tool must not be
+    // able to corrupt the CLI's output or the user's terminal.
+    let stderr = "";
+    child.stderr?.on("data", (d) => {
+      if (stderr.length < 2000) stderr += String(d);
+    });
+    child.stdout?.resume();
+
+    child.on("message", (msg) => {
+      if (!msg || msg.type !== "result") return;
+      if (msg.ok) done({ ok: true, result: revive(msg.result) });
+      else done({ ok: false, error: msg.error || "Tool execution failed.", stderr });
+    });
+
+    // The deadline is armed immediately — before we know whether the source
+    // compiles — so a top-level infinite loop is still bounded.
+    timer = setTimeout(() => {
+      done({
+        ok: false,
+        timedOut: true,
+        error: `Timed out after ${timeoutMs}ms (tool process killed).`,
+        stderr,
+      });
+    }, budgetMs);
+
+    child.on("error", (err) => done({ ok: false, error: `Sandbox error: ${err.message}`, stderr }));
+
+    child.on("exit", (code, signal) => {
+      // Exiting without a result means the tool killed itself, or the child
+      // was OOM-killed. Distinguish the common case for a clearer message.
+      const reason =
+        stderr.includes("JavaScript heap out of memory") || stderr.includes("Allocation failed")
+          ? "Tool ran out of memory."
+          : signal
+            ? `Tool process terminated (${signal}).`
+            : `Tool process exited unexpectedly (code ${code}).`;
+      done({ ok: false, error: reason, stderr });
+    });
+
+    try {
+      child.send({ type: "run", source, input });
+    } catch (err) {
+      done({ ok: false, error: `Could not send input to sandbox: ${err.message}` });
+    }
+  });
+}
+
+/** Best-effort fallback for a CLI install with a broken/partial `src/`. */
+function fail(message, startedAt) {
+  return Promise.resolve({ ok: false, error: message, durationMs: Date.now() - startedAt });
+}
+
+/** Re-expand the sentinels runner.js uses for non-JSON values. */
+function revive(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(revive);
+  if (value.__undefined) return undefined;
+  if (value.__nan) return NaN;
+  if (value.__inf) return value.__inf > 0 ? Infinity : -Infinity;
+  if (value.__bigint) return BigInt(value.__bigint);
+  if (value.__function) return undefined;
+  if (value.__symbol) return Symbol(value.__symbol);
+  if (value.__date) return new Date(value.__date);
+  if (value.__error) return new Error(value.__error);
+  const out = {};
+  for (const [k, v] of Object.entries(value)) out[k] = revive(v);
+  return out;
+}
+
+/** Verify the runner exists once, so failures explain themselves. */
+export async function sandboxAvailable() {
+  if (runnerMissing) return false;
+  const fs = await import("node:fs");
+  if (!fs.existsSync(RUNNER_PATH)) {
+    runnerMissing = true;
+    return false;
+  }
+  return true;
+}

package/src/tools.js

@@ -12,10 +12,12 @@
  *   1. Local filesystem  → 2. cache (`tools/<slug>.json`) → 3. API/Supabase
  *
  * Exports:
- *   loadConfig / saveConfig / configGet / configSet
+ *   loadConfig / saveConfig / configGet / configSet / redactedConfig
  *   fetchTools()              — resolves list (cache-first on network failure)
  *   refreshTools()            — force a fresh fetch + persist to cache
  *   fetchToolSource(slug)     — { manifest, coreLogicSource }
+ *   filterTools / rankTools   — shared search used by list / search / abbr / run
+ *   isValidSlug / normalizeSlug
  *   scanLocalTools()
  *   findLocalTool(slug)
  *   generateAbbreviations(slugs)
@@ -26,33 +28,35 @@
 
 import fs from "fs";
 import path from "path";
-import os from "os";
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
+
+import { parseJsonish } from "./jsonish.js";
 
 import {
-  CONFIG_DIR,
   CONFIG_PATH,
   ensureConfigDir,
   ensureCacheDir,
   TOOLS_CACHE_DIR,
   TOOLS_LIST_CACHE_PATH,
 } from "./paths.js";
-import chalk from "chalk";
-
-const require = createRequire(import.meta.url);
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 export const API_BASE = process.env.NEXUSBLOOM_API_URL || "https://www.nexusbloom.dev";
 
-const SUPABASE_URL_DEFAULT = "https://dhxaqatmuprehrkszxzs.supabase.co";
-const SUPABASE_ANON_KEY_DEFAULT =
-  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRoeGFxYXRtdXByZWhya3N6eHpzIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMxNjIzNTQsImV4cCI6MjA4ODczODM1NH0.pq7DxW66ETQt6QlIAu2WiLO08tfA7JHQVPd2SvvA3sM";
+/**
+ * Supabase fallback is opt-in. No key is bundled with the CLI: a shipped
+ * anon key in a public npm package is readable by anyone, and rotating it
+ * would break every installed copy. Set NEXUSBLOOM_SUPABASE_ANON_KEY (or run
+ * `nxb config set supabaseKey ...`) to enable the offline fallback.
+ */
+export const SUPABASE_URL_DEFAULT = "https://dhxaqatmuprehrkszxzs.supabase.co";
 
 // Cache freshness threshold (30 min)
 const CACHE_TTL_MS = 30 * 60 * 1000;
 
+// Config keys whose values must never be printed or committed.
+const SECRET_CONFIG_KEYS = new Set(["key", "apikey", "apiKey", "supabaseKey", "token"]);
+
 // Common local-tool search roots (relative to CWD)
 const LOCAL_TOOL_DIRS = [
   "src/tools",
@@ -60,6 +64,24 @@ const LOCAL_TOOL_DIRS = [
   "apps/main-site/frontend/src/tools",
 ];
 
+// ─── Slug validation ─────────────────────────────────────────────────────────
+
+// Slugs are used as filenames (cache keys) and inside PostgREST query strings,
+// so they must be a strict, closed character set — no path separators, no
+// commas/parens that would let a caller rewrite the filter expression.
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+export function isValidSlug(slug) {
+  return typeof slug === "string" && SLUG_RE.test(slug);
+}
+
+/** Normalise CLI input into a safe slug, or return null if it is not one. */
+export function normalizeSlug(slug) {
+  if (typeof slug !== "string") return null;
+  const s = slug.trim();
+  return SLUG_RE.test(s) ? s : null;
+}
+
 // ─── Config helpers ─────────────────────────────────────────────────────────
 
 export function loadConfig() {
@@ -75,7 +97,14 @@ export function loadConfig() {
 
 export function saveConfig(store = {}) {
   ensureConfigDir();
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(store, null, 2), "utf-8");
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(store, null, 2), { encoding: "utf-8", mode: 0o600 });
+  // writeFileSync only applies `mode` when it creates the file — enforce it
+  // on every write so a pre-existing 0644 file gets tightened.
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    /* best effort (e.g. non-POSIX fs) */
+  }
 }
 
 export function configGet(key) {
@@ -89,21 +118,62 @@ export function configSet(key, value) {
   saveConfig(store);
 }
 
+/**
+ * Remove a config key. Without this there is no way to clear a stored API key
+ * from the CLI — `set` refuses an empty value, and hand-editing a 0600 file
+ * with a live secret in it is not a reasonable thing to ask of a user.
+ * @returns {boolean} true if the key was present
+ */
+export function configUnset(key) {
+  const store = loadConfig();
+  if (!(key in store)) return false;
+  delete store[key];
+  saveConfig(store);
+  return true;
+}
+
+/** True when a config key holds a secret that must be redacted on display. */
+export function isSecretKey(key) {
+  return SECRET_CONFIG_KEYS.has(key) || /key|token|secret|password/i.test(key);
+}
+
+/** Config with secret values masked — safe to print or log. */
+export function redactedConfig(store = loadConfig()) {
+  const out = {};
+  for (const [k, v] of Object.entries(store || {})) {
+    const s = v == null ? "" : String(v);
+    out[k] = isSecretKey(k)
+      ? s.length <= 8
+        ? "********"
+        : `${s.slice(0, 4)}…${s.slice(-4)}`
+      : v;
+  }
+  return out;
+}
+
 // ─── Supabase helpers ───────────────────────────────────────────────────────
 
 export function getSupabaseKey() {
-  return process.env.NEXUSBLOOM_SUPABASE_ANON_KEY || configGet("supabaseKey") || SUPABASE_ANON_KEY_DEFAULT;
+  return process.env.NEXUSBLOOM_SUPABASE_ANON_KEY || configGet("supabaseKey") || null;
 }
 
 export function getSupabaseUrl() {
-  return process.env.NEXUSBLOOM_SUPABASE_URL || SUPABASE_URL_DEFAULT;
+  return process.env.NEXUSBLOOM_SUPABASE_URL || configGet("supabaseUrl") || SUPABASE_URL_DEFAULT;
 }
 
 export function supabaseHeaders(extra = {}) {
   const key = getSupabaseKey();
+  if (!key) return {};
   return { apikey: key, Authorization: `Bearer ${key}`, ...extra };
 }
 
+/** Human-readable reason the Supabase fallback is unavailable (or null if it is). */
+export function supabaseUnavailableReason() {
+  if (!getSupabaseKey())
+    return "Set NEXUSBLOOM_SUPABASE_ANON_KEY or run `nxb config set supabaseKey <key>`.";
+  return null;
+}
+
 // ─── Tools list cache (tools-list.json) ──────────────────────────────────────
 
 /**
@@ -186,6 +256,7 @@ function normalizeTool(t) {
  * Normalises to the same shape the API returns.
  */
 async function fetchToolsFromSupabase() {
+  if (!getSupabaseKey()) return null; // no key configured — skip the round-trip
   const headers = supabaseHeaders();
   const supabaseUrl = getSupabaseUrl();
   try {
@@ -290,6 +361,71 @@ function mergeLocalTools(remoteTools) {
   return [...local, ...deduped];
 }
 
+// ─── Search ──────────────────────────────────────────────────────────────────
+
+/**
+ * Filter a tool list by a free-text query.
+ *
+ * Case-insensitive across slug, name, description, category, type and tags.
+ * A multi-word query ("json format") matches when *every* word matches at
+ * least one field, so extra words narrow the list rather than emptying it.
+ *
+ *   filterTools(tools, "ssl")     → tools whose slug/name/desc mentions ssl
+ *   filterTools(tools, "json pd") → tools matching both "json" and "pd"
+ */
+export function filterTools(tools, query) {
+  const list = Array.isArray(tools) ? tools : [];
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return list;
+
+  const words = q.split(/\s+/).filter(Boolean);
+  const haystack = (t) =>
+    [
+      t.slug,
+      t.name,
+      t.short_description,
+      t.description,
+      t.category,
+      t.type,
+      t.runtime,
+      ...(Array.isArray(t.tags) ? t.tags : []),
+    ]
+      .filter(Boolean)
+      .join(" ")
+      .toLowerCase();
+
+  return list.filter((t) => {
+    const hay = haystack(t);
+    return words.every((w) => hay.includes(w));
+  });
+}
+
+/**
+ * Score + sort tools for a query so the closest match is first.
+ * Exact slug > slug prefix > slug contains > name/description contains.
+ */
+export function rankTools(tools, query) {
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return Array.isArray(tools) ? tools : [];
+
+  const score = (t) => {
+    const slug = (t.slug || "").toLowerCase();
+    const name = (t.name || "").toLowerCase();
+    if (slug === q) return 0;
+    if (name === q) return 1;
+    if (slug.startsWith(q)) return 2;
+    if (slug.includes(q)) return 3;
+    if (name.startsWith(q)) return 4;
+    if (name.includes(q)) return 5;
+    return 6;
+  };
+
+  return filterTools(tools, q)
+    .map((t, i) => ({ t, i, s: score(t) }))
+    .sort((a, b) => a.s - b.s || a.i - b.i)
+    .map(({ t }) => t);
+}
+
 // ─── Single tool source (for --local execution) ──────────────────────────────
 
 /**
@@ -297,7 +433,10 @@ function mergeLocalTools(remoteTools) {
  *
  *   1. Local filesystem → 2. per-tool cache → 3. API → 4. Supabase
  */
-export async function fetchToolSource(slug) {
+export async function fetchToolSource(rawSlug) {
+  const slug = normalizeSlug(rawSlug);
+  if (!slug) return null;
+
   ensureCacheDir();
   const cacheFile = path.join(TOOLS_CACHE_DIR, `${slug}.json`);
 
@@ -305,7 +444,7 @@ export async function fetchToolSource(slug) {
   const localPath = findLocalTool(slug);
   if (localPath) {
     const source = fs.readFileSync(localPath, "utf-8");
-    const manifest = extractManifest(source);
+    const manifest = extractManifest(source, { trusted: true });
     if (manifest) {
       // Refresh cache from local source
       fs.writeFileSync(cacheFile, JSON.stringify({ manifest, coreLogicSource: source, cachedAt: new Date().toISOString() }), "utf-8");
@@ -361,6 +500,7 @@ export async function fetchToolSource(slug) {
  * Returns { manifest, coreLogicSource } or null.
  */
 export async function fetchToolFromSupabase(slug) {
+  if (!getSupabaseKey()) return null;
   const headers = supabaseHeaders();
   const supabaseUrl = getSupabaseUrl();
   try {
@@ -404,22 +544,33 @@ export async function fetchToolFromSupabase(slug) {
 // ─── Manifest extraction ────────────────────────────────────────────────────
 
 /**
- * Extract a MANIFEST object from v2 source text.
- * Handles JS object literals (unquoted keys, single quotes) gracefully.
+ * Extract the MANIFEST object literal from v2 source text.
+ *
+ * The literal is parsed, never evaluated: manifest text fetched from the API or
+ * Supabase is untrusted input, and `new Function` on it would execute it.
+ * `trusted: true` is passed only for files read off the developer's own disk.
+ *
+ * @param {string} source
+ * @param {{trusted?: boolean}} [opts]
+ * @returns {object|null}
  */
-export function extractManifest(source) {
+export function extractManifest(source, { trusted = false } = {}) {
   if (!source) return null;
   const match = source.match(/export\s+const\s+MANIFEST\s*=\s*({[\s\S]*?});/);
   if (!match) return null;
+
+  const parsed = parseJsonish(match[1]);
+  if (parsed && typeof parsed === "object") return parsed;
+  if (!trusted) return null;
+
+  // Developer-owned file that used syntax the literal parser does not accept.
+  // Only reached for local src/tools — never for network content.
   try {
     // eslint-disable-next-line no-new-func
-    return new Function("return " + match[1])();
+    const value = new Function(`return ${match[1]}`)();
+    return value && typeof value === "object" ? value : null;
   } catch {
-    try {
-      return JSON.parse(match[1].replace(/(\w+):/g, '"$1":').replace(/'/g, '"'));
-    } catch {
-      return null;
-    }
+    return null;
   }
 }
 
@@ -472,7 +623,7 @@ export function scanLocalTools() {
       if (!fs.existsSync(v2Path)) continue;
       try {
         const source = fs.readFileSync(v2Path, "utf-8");
-        const manifest = extractManifest(source);
+        const manifest = extractManifest(source, { trusted: true });
         if (!manifest) continue;
         tools.push({
           slug: manifest.slug || entry.name,

package/src/types.js

@@ -0,0 +1,178 @@
+/**
+ * types.js — Type inference and the compatibility rules for pipeline wiring.
+ *
+ * The rule the whole pipeline design rests on: conversions that cannot lose
+ * information happen silently, conversions that can lose information require an
+ * explicit transform. That is what "keep types in mind" means in practice —
+ * `$max → count` (integer → integer) just works, `$text → count` does not.
+ */
+
+/** Runtime type of a concrete value. */
+export function inferType(value) {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return "array";
+  const t = typeof value;
+  if (t === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (t === "string") return "string";
+  if (t === "boolean") return "boolean";
+  if (t === "object") return "object";
+  return t;
+}
+
+/** Normalise a JSON-schema `type` field into a list of type names. */
+export function schemaTypes(prop) {
+  if (!prop || typeof prop !== "object") return [];
+  const t = prop.type;
+  if (Array.isArray(t)) return t.filter((x) => typeof x === "string");
+  if (typeof t === "string") return [t];
+  if (t === undefined && prop.properties) return ["object"];
+  if (t === undefined && prop.items) return ["array"];
+  return [];
+}
+
+/** Human label for display, e.g. `integer`, `string`, `string|number`. */
+export function typeLabel(types) {
+  const list = Array.isArray(types) ? types : [types];
+  if (!list.length) return "any";
+  return list.join("|");
+}
+
+/** Ordered by widening: an integer satisfies a number target. */
+const WIDENS = { integer: ["number"] };
+
+/**
+ * Decide whether a value of `fromType` may feed a schema field accepting
+ * `toTypes`, ignoring transforms (the caller applies those first).
+ *
+ * @returns {{level: "ok"|"lossy"|"cast"|"invalid", note: string, suggestion?: string}}
+ */
+export function compatibility(fromType, toTypes) {
+  const targets = Array.isArray(toTypes) ? toTypes : [toTypes];
+  const from = Array.isArray(fromType) ? fromType[0] : fromType;
+
+  if (!targets.length) return { level: "ok", note: "untyped target" };
+  if (!from || from === "null" || from === "unknown") {
+    return { level: "cast", note: "source has no fixed type", suggestion: "default()" };
+  }
+  if (targets.includes(from)) return { level: "ok", note: "exact match" };
+
+  // Lossless widening: integer into number.
+  for (const w of WIDENS[from] || []) {
+    if (targets.includes(w)) return { level: "ok", note: `${from} widens to ${w}` };
+  }
+
+  // Lossy narrowing: number into integer.
+  if (from === "number" && targets.includes("integer")) {
+    return { level: "lossy", note: "may lose the fraction", suggestion: "int()" };
+  }
+
+  // Everything renders to a string, and nothing is lost in the text.
+  if (targets.includes("string") && ["number", "integer", "boolean"].includes(from)) {
+    return { level: "ok", note: `rendered as string` };
+  }
+
+  // String into a typed field needs a deliberate cast.
+  if (from === "string" && targets.some((t) => ["integer", "number"].includes(t))) {
+    return { level: "cast", note: "string is not a number", suggestion: targets.includes("integer") ? "int()" : "float()" };
+  }
+  if (from === "string" && targets.includes("boolean")) {
+    return { level: "cast", note: "string is not a boolean", suggestion: "bool()" };
+  }
+
+  // Collections must be reduced before they can be scalars.
+  if (from === "array" && targets.some((t) => t !== "array")) {
+    return { level: "cast", note: "array used as a single value", suggestion: "first()" };
+  }
+  if (from === "object" && targets.some((t) => t !== "object")) {
+    return { level: "cast", note: "object used as a single value", suggestion: "pick(field)" };
+  }
+
+  return {
+    level: "invalid",
+    note: `${from} is not accepted by ${typeLabel(targets)}`,
+  };
+}
+
+/**
+ * Runtime check of a value against a schema field. Enums are enforced here,
+ * because a declared enum is the one place a "compatible" type can still be
+ * wrong at runtime.
+ *
+ * @returns {{ok: boolean, error?: string, suggestion?: string}}
+ */
+export function validateValue(value, prop) {
+  const targets = schemaTypes(prop);
+  const enumValues = Array.isArray(prop?.enum) ? prop.enum : null;
+
+  // Absent is not the same as null: report it as a missing value so the fix
+  // points at supplying one rather than at a type mismatch.
+  if (value === undefined) {
+    return { ok: false, error: "no value was supplied", suggestion: "add |default(...)" };
+  }
+
+  const actual = inferType(value);
+
+  if (value === null) {
+    // JSON-Schema "null" only when explicitly allowed; otherwise treated as missing.
+    if (targets.includes("null")) return { ok: true };
+    return { ok: false, error: `expected ${typeLabel(targets)}, got null`, suggestion: "default()" };
+  }
+
+  if (enumValues && !enumValues.includes(value)) {
+    return {
+      ok: false,
+      error: `${JSON.stringify(value)} is not one of: ${enumValues.map((v) => JSON.stringify(v)).join(", ")}`,
+    };
+  }
+
+  if (!targets.length) return { ok: true };
+
+  const widened = actual === "integer" && targets.includes("number");
+  if (targets.includes(actual) || widened) return { ok: true };
+
+  const hint =
+    actual === "string" && (targets.includes("integer") || targets.includes("number"))
+      ? targets.includes("integer") ? "add |int()" : "add |float()"
+      : actual === "array" ? "add |first()"
+      : actual === "number" && targets.includes("integer") ? "add |int()"
+      : null;
+
+  return {
+    ok: false,
+    error: `expected ${typeLabel(targets)}, got ${actual}`,
+    suggestion: hint,
+  };
+}
+
+/**
+ * Validate a whole input object against a tool's `input_schema`.
+ * Missing required fields are reported too, so a pipeline can fail before it
+ * executes rather than on step 3.
+ *
+ * @returns {Array<{field: string, error: string, suggestion?: string}>}
+ */
+export function validateInput(input, inputSchema) {
+  const problems = [];
+  if (!inputSchema || typeof inputSchema !== "object") return problems;
+
+  const props = inputSchema.properties || {};
+  const required = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+
+  for (const field of required) {
+    const v = input?.[field];
+    // `false` and `0` are legitimate values, so only absent/null count as missing.
+    if (v === undefined || v === null) {
+      problems.push({ field, error: "required field is missing" });
+    }
+  }
+
+  for (const [field, value] of Object.entries(input || {})) {
+    if (!props[field]) continue; // extra fields are allowed by many tools
+    const check = validateValue(value, props[field]);
+    if (!check.ok) {
+      problems.push({ field, error: check.error, suggestion: check.suggestion });
+    }
+  }
+
+  return problems;
+}