chainlesschain 0.162.78 → 0.162.79

package/src/lib/json-schema-output.js

@@ -34,21 +34,32 @@ export function validateAgainstSchema(value, schema, path = "$") {
   if (schema.type) {
     const want = Array.isArray(schema.type) ? schema.type : [schema.type];
     const got = typeOf(value);
-    const ok = want.some((t) => t === got || (t === "number" && got === "integer"));
+    const ok = want.some(
+      (t) => t === got || (t === "number" && got === "integer"),
+    );
     if (!ok) {
       errors.push(`${path}: expected type ${want.join("|")}, got ${got}`);
       return errors; // type mismatch — deeper checks are noise
     }
   }
-  if (schema.enum && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
-    errors.push(`${path}: value not in enum [${schema.enum.map((e) => JSON.stringify(e)).join(", ")}]`);
+  if (
+    schema.enum &&
+    !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))
+  ) {
+    errors.push(
+      `${path}: value not in enum [${schema.enum.map((e) => JSON.stringify(e)).join(", ")}]`,
+    );
   }
-  if (schema.const !== undefined && JSON.stringify(schema.const) !== JSON.stringify(value)) {
+  if (
+    schema.const !== undefined &&
+    JSON.stringify(schema.const) !== JSON.stringify(value)
+  ) {
     errors.push(`${path}: must equal const ${JSON.stringify(schema.const)}`);
   }
   if (typeOf(value) === "object" && !Array.isArray(value)) {
     for (const req of schema.required || []) {
-      if (!(req in value)) errors.push(`${path}: missing required property "${req}"`);
+      if (!(req in value))
+        errors.push(`${path}: missing required property "${req}"`);
     }
     const props = schema.properties || {};
     for (const [k, v] of Object.entries(value)) {
@@ -61,7 +72,9 @@ export function validateAgainstSchema(value, schema, path = "$") {
   }
   if (Array.isArray(value) && schema.items) {
     value.forEach((item, i) => {
-      errors.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+      errors.push(
+        ...validateAgainstSchema(item, schema.items, `${path}[${i}]`),
+      );
     });
   }
   return errors;
@@ -76,10 +89,12 @@ export function extractJsonPayload(text) {
   if (fence) tries.push(fence[1].trim());
   const firstObj = raw.indexOf("{");
   const lastObj = raw.lastIndexOf("}");
-  if (firstObj !== -1 && lastObj > firstObj) tries.push(raw.slice(firstObj, lastObj + 1));
+  if (firstObj !== -1 && lastObj > firstObj)
+    tries.push(raw.slice(firstObj, lastObj + 1));
   const firstArr = raw.indexOf("[");
   const lastArr = raw.lastIndexOf("]");
-  if (firstArr !== -1 && lastArr > firstArr) tries.push(raw.slice(firstArr, lastArr + 1));
+  if (firstArr !== -1 && lastArr > firstArr)
+    tries.push(raw.slice(firstArr, lastArr + 1));
   for (const candidate of tries) {
     if (!candidate) continue;
     try {
@@ -111,6 +126,35 @@ export function buildRetryPrompt(originalPrompt, raw, errors) {
   ].join("\n");
 }
 
+/**
+ * Load + parse a --json-schema file, raising errors that name the file and
+ * the underlying cause instead of a bare `ENOENT …` or `Unexpected token …`
+ * stack (which is all the user would otherwise see).
+ *
+ * @param {{ readFileSync: Function }} fs
+ * @param {string} schemaFile
+ */
+export function loadSchemaFile(fs, schemaFile) {
+  if (!schemaFile) {
+    throw new Error(
+      "No schema provided: pass --json-schema <file> or a schema object",
+    );
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(schemaFile, "utf-8");
+  } catch (e) {
+    throw new Error(`Cannot read schema file "${schemaFile}": ${e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `Invalid JSON in schema file "${schemaFile}": ${e.message}`,
+    );
+  }
+}
+
 /**
  * Run a headless turn constrained to a schema, retrying on validation
  * failure. Prints the validated JSON to writeOut; returns the exit code.
@@ -124,8 +168,7 @@ export async function runJsonSchemaConstrained(cfg = {}) {
   const writeErr = cfg.writeErr || ((s) => process.stderr.write(s));
   const maxAttempts = cfg.maxAttempts || MAX_ATTEMPTS;
 
-  const schema =
-    cfg.schema || JSON.parse(fs.readFileSync(cfg.schemaFile, "utf-8"));
+  const schema = cfg.schema || loadSchemaFile(fs, cfg.schemaFile);
   const instruction = buildSchemaInstruction(schema);
   const base = cfg.baseOptions || {};
 
@@ -151,7 +194,8 @@ export async function runJsonSchemaConstrained(cfg = {}) {
         writeErr,
       },
     );
-    const raw = String(outcome?.result ?? captured ?? "").trim() || captured.trim();
+    const raw =
+      String(outcome?.result ?? captured ?? "").trim() || captured.trim();
     lastRaw = raw;
     const parsed = extractJsonPayload(raw);
     if (parsed.ok) {

package/src/lib/mcp-oauth.js

@@ -39,7 +39,11 @@ export const _deps = {
 };
 
 const base64url = (buf) =>
-  Buffer.from(buf).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  Buffer.from(buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
 
 /** RFC 7636 PKCE pair (S256). */
 export function generatePkce() {
@@ -53,6 +57,52 @@ export function randomState(bytes = 16) {
   return base64url(_deps.randomBytes(bytes));
 }
 
+/** Minimal HTML-escape for values reflected into the callback page. */
+function escapeHtml(s) {
+  return String(s).replace(
+    /[&<>"']/g,
+    (c) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+      })[c],
+  );
+}
+
+/**
+ * The HTML shown in the user's browser after the OAuth redirect hits our
+ * localhost callback. On success it AUTO-CLOSES the tab (Claude-Code 2.1.181
+ * parity) — best-effort, since window.close() only acts on script-opened
+ * windows, so the page still tells the user they may close it manually. The
+ * provider-supplied `error` is HTML-escaped (it is reflected into the page).
+ * Pure → unit-testable.
+ *
+ * @param {string|null|undefined} error  the `error` query param, if any
+ */
+export function renderCallbackPage(error) {
+  const ok = !error;
+  const title = ok ? "Authorized" : "Authorization failed";
+  const body = ok
+    ? "You can close this tab and return to the terminal."
+    : `The provider returned an error: ${escapeHtml(error)}`;
+  const autoClose = ok
+    ? "<script>setTimeout(function(){try{window.close();}catch(e){}},800);</script>"
+    : "";
+  return (
+    '<!doctype html><html><head><meta charset="utf-8"><title>' +
+    title +
+    "</title></head>" +
+    '<body style="font-family:system-ui,-apple-system,sans-serif;text-align:center;margin-top:18vh;color:#222">' +
+    `<h2 style="color:${ok ? "#16794a" : "#b00020"}">${title}</h2>` +
+    `<p style="color:#555">${body}</p>` +
+    autoClose +
+    "</body></html>"
+  );
+}
+
 async function fetchJson(url, opts) {
   const res = await _deps.fetch(url, opts);
   if (!res || !res.ok) {
@@ -63,7 +113,9 @@ async function fetchJson(url, opts) {
     } catch {
       /* ignore */
     }
-    const err = new Error(`HTTP ${status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+    const err = new Error(
+      `HTTP ${status}${body ? `: ${body.slice(0, 200)}` : ""}`,
+    );
     err.status = res ? res.status : null;
     throw err;
   }
@@ -76,7 +128,10 @@ async function fetchJson(url, opts) {
  * the authorization-server doc directly at the origin.
  * @returns {Promise<{issuer?,authorization_endpoint,token_endpoint,registration_endpoint?,scopes_supported?}>}
  */
-export async function discoverAuthMetadata(serverUrl, { resourceMetadataUrl } = {}) {
+export async function discoverAuthMetadata(
+  serverUrl,
+  { resourceMetadataUrl } = {},
+) {
   const origin = new URL(serverUrl).origin;
   // 1. protected-resource metadata (RFC 9728) → authorization_servers[]
   let authServer = origin;
@@ -84,7 +139,10 @@ export async function discoverAuthMetadata(serverUrl, { resourceMetadataUrl } =
     const prUrl =
       resourceMetadataUrl || `${origin}/.well-known/oauth-protected-resource`;
     const pr = await fetchJson(prUrl);
-    if (Array.isArray(pr.authorization_servers) && pr.authorization_servers[0]) {
+    if (
+      Array.isArray(pr.authorization_servers) &&
+      pr.authorization_servers[0]
+    ) {
       authServer = String(pr.authorization_servers[0]).replace(/\/$/, "");
     }
   } catch {
@@ -118,9 +176,14 @@ export async function discoverAuthMetadata(serverUrl, { resourceMetadataUrl } =
 }
 
 /** RFC 7591 dynamic client registration → client_id (public client). */
-export async function registerClient(metadata, { redirectUri, clientName = "chainlesschain-cli" } = {}) {
+export async function registerClient(
+  metadata,
+  { redirectUri, clientName = "chainlesschain-cli" } = {},
+) {
   if (!metadata.registration_endpoint) {
-    throw new Error("server has no registration_endpoint and no --client-id was given");
+    throw new Error(
+      "server has no registration_endpoint and no --client-id was given",
+    );
   }
   const reg = await fetchJson(metadata.registration_endpoint, {
     method: "POST",
@@ -133,12 +196,16 @@ export async function registerClient(metadata, { redirectUri, clientName = "chai
       token_endpoint_auth_method: "none",
     }),
   });
-  if (!reg.client_id) throw new Error("registration did not return a client_id");
+  if (!reg.client_id)
+    throw new Error("registration did not return a client_id");
   return { clientId: reg.client_id, clientSecret: reg.client_secret || null };
 }
 
 /** Build the authorize URL (Authorization Code + PKCE). */
-export function buildAuthorizeUrl(metadata, { clientId, redirectUri, scope, codeChallenge, state, resource }) {
+export function buildAuthorizeUrl(
+  metadata,
+  { clientId, redirectUri, scope, codeChallenge, state, resource },
+) {
   const u = new URL(metadata.authorization_endpoint);
   u.searchParams.set("response_type", "code");
   u.searchParams.set("client_id", clientId);
@@ -157,7 +224,10 @@ function _tokenExpiresAt(tok) {
 }
 
 /** Exchange an authorization code for tokens. */
-export async function exchangeCodeForToken(metadata, { code, codeVerifier, clientId, clientSecret, redirectUri, resource }) {
+export async function exchangeCodeForToken(
+  metadata,
+  { code, codeVerifier, clientId, clientSecret, redirectUri, resource },
+) {
   const body = new URLSearchParams({
     grant_type: "authorization_code",
     code,
@@ -182,7 +252,10 @@ export async function exchangeCodeForToken(metadata, { code, codeVerifier, clien
 }
 
 /** Refresh an access token. */
-export async function refreshAccessToken(metadata, { refreshToken, clientId, clientSecret, resource }) {
+export async function refreshAccessToken(
+  metadata,
+  { refreshToken, clientId, clientSecret, resource },
+) {
   const body = new URLSearchParams({
     grant_type: "refresh_token",
     refresh_token: refreshToken,
@@ -249,7 +322,11 @@ export function deleteStoredToken(serverUrl) {
   if (!(key in store)) return false;
   delete store[key];
   try {
-    _deps.fs.writeFileSync(file, JSON.stringify(store, null, 2) + "\n", "utf-8");
+    _deps.fs.writeFileSync(
+      file,
+      JSON.stringify(store, null, 2) + "\n",
+      "utf-8",
+    );
   } catch {
     /* best-effort */
   }
@@ -292,8 +369,7 @@ function defaultOpenBrowser(url) {
   const platform = process.platform;
   const cmd =
     platform === "win32" ? "cmd" : platform === "darwin" ? "open" : "xdg-open";
-  const args =
-    platform === "win32" ? ["/c", "start", "", url] : [url];
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
     child.unref?.();
@@ -304,7 +380,12 @@ function defaultOpenBrowser(url) {
 }
 
 /** Wait for the OAuth redirect on a localhost callback server; resolve {code,state}. */
-function waitForCallback({ port, host = "127.0.0.1", path = "/callback", timeout = 300_000 }) {
+function waitForCallback({
+  port,
+  host = "127.0.0.1",
+  path = "/callback",
+  timeout = 300_000,
+}) {
   return new Promise((resolve, reject) => {
     const server = _deps.createServer((req, res) => {
       let u;
@@ -323,10 +404,8 @@ function waitForCallback({ port, host = "127.0.0.1", path = "/callback", timeout
       const code = u.searchParams.get("code");
       const state = u.searchParams.get("state");
       const error = u.searchParams.get("error");
-      res.writeHead(200, { "content-type": "text/html" });
-      res.end(
-        `<html><body style="font-family:sans-serif"><h3>${error ? "Authorization failed" : "Authorized — you can close this tab."}</h3></body></html>`,
-      );
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(renderCallbackPage(error));
       server.close();
       clearTimeout(timer);
       if (error) reject(new Error(`authorization error: ${error}`));
@@ -377,13 +456,22 @@ export async function authorizeInteractive(serverUrl, opts = {}) {
   const authorizeUrl = buildAuthorizeUrl(metadata, {
     clientId,
     redirectUri,
-    scope: scope || (metadata.scopes_supported ? metadata.scopes_supported.join(" ") : undefined),
+    scope:
+      scope ||
+      (metadata.scopes_supported
+        ? metadata.scopes_supported.join(" ")
+        : undefined),
     codeChallenge: pkce.challenge,
     state,
     resource: serverUrl,
   });
 
-  const callbackPromise = waitForCallback({ port, host, path: redirectPath, timeout });
+  const callbackPromise = waitForCallback({
+    port,
+    host,
+    path: redirectPath,
+    timeout,
+  });
   const opened = _deps.openBrowser(authorizeUrl);
   writeOut(
     (opened
@@ -393,7 +481,8 @@ export async function authorizeInteractive(serverUrl, opts = {}) {
   );
 
   const { code, state: returnedState } = await callbackPromise;
-  if (returnedState !== state) throw new Error("OAuth state mismatch (possible CSRF)");
+  if (returnedState !== state)
+    throw new Error("OAuth state mismatch (possible CSRF)");
 
   const tok = await exchangeCodeForToken(metadata, {
     code,

package/src/lib/mcp-serve.js

@@ -62,11 +62,14 @@ export function buildTools({ root, readOnly = false, deps = _deps }) {
         const text = (truncated ? buf.slice(0, MAX_READ_BYTES) : buf).toString(
           "utf-8",
         );
-        return ok(truncated ? `${text}\n… [truncated ${buf.length} bytes]` : text);
+        return ok(
+          truncated ? `${text}\n… [truncated ${buf.length} bytes]` : text,
+        );
       },
     },
     list_dir: {
-      description: "List a directory under the serve root (dirs get trailing /)",
+      description:
+        "List a directory under the serve root (dirs get trailing /)",
       inputSchema: {
         type: "object",
         properties: { path: { type: "string" } },
@@ -106,12 +109,14 @@ export function buildTools({ root, readOnly = false, deps = _deps }) {
             return;
           }
           for (const e of list) {
-            if (hits.length >= MAX_SEARCH_RESULTS || ++seen >= MAX_SEARCH_ENTRIES)
+            if (
+              hits.length >= MAX_SEARCH_RESULTS ||
+              ++seen >= MAX_SEARCH_ENTRIES
+            )
               return;
             const abs = deps.path.join(d, e.name);
             if (e.isDirectory()) {
-              if (!SKIP_DIRS.has(e.name) && !e.name.startsWith("."))
-                walk(abs);
+              if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) walk(abs);
             } else {
               const rel = deps.path.relative(root, abs).replace(/\\/g, "/");
               if (rel.toLowerCase().includes(q)) hits.push(rel);
@@ -125,7 +130,8 @@ export function buildTools({ root, readOnly = false, deps = _deps }) {
   };
   if (!readOnly) {
     tools.write_file = {
-      description: "Write a UTF-8 file under the serve root (creates parent dirs)",
+      description:
+        "Write a UTF-8 file under the serve root (creates parent dirs)",
       inputSchema: {
         type: "object",
         properties: {
@@ -138,7 +144,9 @@ export function buildTools({ root, readOnly = false, deps = _deps }) {
         const abs = confine(root, rel, deps);
         fs.mkdirSync(deps.path.dirname(abs), { recursive: true });
         fs.writeFileSync(abs, String(content), "utf-8");
-        return ok(`wrote ${Buffer.byteLength(String(content))} bytes to ${rel}`);
+        return ok(
+          `wrote ${Buffer.byteLength(String(content))} bytes to ${rel}`,
+        );
       },
     };
   }
@@ -163,11 +171,20 @@ export function startMcpServe(opts = {}) {
   const root = deps.path.resolve(opts.root || process.cwd());
   const readOnly = Boolean(opts.readOnly);
   const token =
-    opts.token === false
-      ? null
-      : opts.token || randomBytes(16).toString("hex");
+    opts.token === false ? null : opts.token || randomBytes(16).toString("hex");
   const tools = buildTools({ root, readOnly, deps });
 
+  // Guardrails for the request-collection phase: a JSON-RPC request is small,
+  // so cap the body and bound how long we wait for it. Without these a large
+  // body grows `raw` unbounded (memory) and a stalled client holds the socket
+  // forever (req.on("end") never fires). Both overridable for tests / tuning.
+  const maxRequestBytes = Number.isFinite(opts.maxRequestBytes)
+    ? opts.maxRequestBytes
+    : 1024 * 1024; // 1 MB
+  const requestTimeoutMs = Number.isFinite(opts.requestTimeoutMs)
+    ? opts.requestTimeoutMs
+    : 30000;
+
   const server = http.createServer((req, res) => {
     const send = (status, body) => {
       res.writeHead(status, { "Content-Type": "application/json" });
@@ -183,10 +200,49 @@ export function startMcpServe(opts = {}) {
       }
     }
     let raw = "";
+    let bytes = 0;
+    let aborted = false;
+    const collectTimer = setTimeout(() => {
+      if (aborted) return;
+      aborted = true;
+      try {
+        send(408, rpcError(null, -32001, "request timeout"));
+      } catch {
+        /* socket already gone */
+      }
+      req.destroy();
+    }, requestTimeoutMs);
+    req.on("error", () => {
+      if (aborted) return;
+      aborted = true;
+      clearTimeout(collectTimer);
+      // Request stream errored (client reset/dropped): no response is
+      // deliverable on a broken socket — just stop, don't crash the process.
+      try {
+        if (!res.writableEnded) res.destroy();
+      } catch {
+        /* ignore */
+      }
+    });
     req.on("data", (c) => {
+      if (aborted) return;
+      bytes += c.length;
+      if (bytes > maxRequestBytes) {
+        aborted = true;
+        clearTimeout(collectTimer);
+        try {
+          send(413, rpcError(null, -32600, "request too large"));
+        } catch {
+          /* socket already gone */
+        }
+        req.destroy();
+        return;
+      }
       raw += c;
     });
     req.on("end", () => {
+      if (aborted) return;
+      clearTimeout(collectTimer);
       let msg;
       try {
         msg = JSON.parse(raw);
@@ -224,7 +280,10 @@ export function startMcpServe(opts = {}) {
         if (method === "tools/call") {
           const tool = tools[params?.name];
           if (!tool) {
-            return send(200, rpcResult(id, fail(`unknown tool: ${params?.name}`)));
+            return send(
+              200,
+              rpcResult(id, fail(`unknown tool: ${params?.name}`)),
+            );
           }
           let result;
           try {

package/src/lib/multisig-runtime.js

@@ -150,11 +150,30 @@ export function readSecretKey(arg) {
 }
 
 /**
- * Read JSON from inline string or file path.
+ * Read JSON from an inline string or a file path. Errors name the file (or
+ * say it was inline) and carry the underlying parser reason, instead of a
+ * bare "Unexpected token …" / "ENOENT …" with no context.
  */
 export function readJsonArg(arg) {
+  if (arg == null || arg === "") {
+    throw new Error("Expected inline JSON or a path to a JSON file");
+  }
   if (fs.existsSync(arg)) {
-    return JSON.parse(fs.readFileSync(arg, "utf-8"));
+    let raw;
+    try {
+      raw = fs.readFileSync(arg, "utf-8");
+    } catch (e) {
+      throw new Error(`Cannot read JSON file "${arg}": ${e.message}`);
+    }
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`Invalid JSON in file "${arg}": ${e.message}`);
+    }
+  }
+  try {
+    return JSON.parse(arg);
+  } catch (e) {
+    throw new Error(`Invalid inline JSON argument: ${e.message}`);
   }
-  return JSON.parse(arg);
 }

package/src/lib/parse-json-option.js

@@ -0,0 +1,35 @@
+/**
+ * Parse a user-supplied JSON CLI option value.
+ *
+ * Many command actions pass raw `--flag` strings straight to `JSON.parse`,
+ * so malformed JSON surfaces as a raw `SyntaxError` — an ugly stack trace for
+ * actions without a try/catch, and a cryptic "Unexpected token …" for the rest.
+ * This helper turns that into a single, friendly `Invalid JSON for <label>: …`
+ * error, and consolidates the duplicated `_parseJsonArg` / `_parseMetaV2`
+ * helpers that several command files grew independently.
+ *
+ * @param {string|undefined|null} value  raw option string (e.g. `options.input`)
+ * @param {string} label                 user-facing label for errors (e.g. `"--input"`)
+ * @param {*} [fallback]                  returned when `value` is empty (default `undefined`)
+ * @returns the parsed JSON, or `fallback` when `value` is empty
+ * @throws {Error} `Invalid JSON for <label>: <reason>` when `value` is non-empty but unparseable
+ */
+export function parseJsonOption(value, label, fallback = undefined) {
+  if (value === undefined || value === null || value === "") return fallback;
+  // Defensive: a Commander custom parser may have already produced an object.
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch (e) {
+    const reason = e && e.message ? e.message : String(e);
+    // Friendly one-line message for the non-verbose error boundary, but keep the
+    // original SyntaxError reachable: chain it as `cause`, and append its stack
+    // to ours so `--verbose` (which prints err.stack) still surfaces the root
+    // SyntaxError type + location instead of swallowing it behind the wrapper.
+    const err = new Error(`Invalid JSON for ${label}: ${reason}`, { cause: e });
+    if (e && e.stack) err.stack += `\nCaused by: ${e.stack}`;
+    throw err;
+  }
+}
+
+export default parseJsonOption;

package/src/lib/parse-number-option.js

@@ -0,0 +1,27 @@
+/**
+ * Parse a user-supplied numeric CLI option value.
+ *
+ * Command actions often do `parseFloat(options.x)` / `parseInt(options.x)`
+ * straight into domain logic. When the flag is malformed (`--weight abc`,
+ * `--amount 1,5`) those yield `NaN`, which then flows silently into stored
+ * records and math (vote weights, amounts, thresholds) — corrupt data with no
+ * error. This helper validates the value is a finite number and otherwise
+ * throws a single friendly `Invalid number for <label>: <value>` error
+ * (which reads cleanly through the CLI entry boundary).
+ *
+ * @param {string|number|undefined|null} value  raw option (e.g. `options.weight`)
+ * @param {string} label                        user-facing label (e.g. `"--weight"`)
+ * @param {*} [fallback]                         returned when `value` is empty (default `undefined`)
+ * @returns {number|*} the parsed finite number, or `fallback` when empty
+ * @throws {Error} when `value` is non-empty but not a finite number
+ */
+export function parseNumberOption(value, label, fallback = undefined) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    throw new Error(`Invalid number for ${label}: ${JSON.stringify(value)}`);
+  }
+  return n;
+}
+
+export default parseNumberOption;