xlsx-for-ai 2.25.0 → 2.26.0

package/index.js

@@ -83,8 +83,8 @@ async function runClean(opts, absPath) {
   try {
     result = await callTool('xlsx_data_clean', body);
   } catch (err) {
-    process.stderr.write(`xlsx-for-ai --clean error: ${err.message}\n`);
-    process.exit(1);
+    process.stderr.write(friendlyCliError('xlsx-for-ai --clean', err) + '\n');
+    process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
   }
 
   const meta = (result && result._meta) || {};
@@ -151,6 +151,46 @@ async function runClean(opts, absPath) {
 // ---------------------------------------------------------------------------
 
 const STAMP_SUBCOMMANDS = new Set(['stamp', 'verify-stamp', 'receipt', 'verify-receipt']);
+const HEAL_SUBCOMMANDS = new Set(['heal']);
+
+// Strip _meta.file_b64 before writing the meta block to stdout. The
+// stamped/receipted workbook can be megabytes; dumping it to a terminal
+// or CI log clobbers scrollback AND leaks PII-bearing workbook contents
+// to whatever consumes stdout. The file is already saved to disk via
+// the sidecar / --out path; the b64 in stdout serves no consumer.
+// Pre-Friday-external CRITICAL per the Tier-1 audit.
+function metaForStdout(meta) {
+  if (!meta || typeof meta !== 'object') return meta;
+  const out = { ...meta };
+  delete out.file_b64;
+  return out;
+}
+
+// CLI-side error formatter. Same posture as friendlyErrorMessage in
+// mcp.js: known operational codes get short, client-safe text; everything
+// else collapses to a generic message. err.message can carry absolute
+// file paths, upstream stack traces, and third-party HTTP response
+// bodies — none of those belong in user-facing CLI stderr or in CI logs.
+// Set XFA_DEBUG=1 to see the raw underlying message (for incident triage).
+function friendlyCliError(prefix, err) {
+  const code = err && err.code;
+  const showRaw = process.env.XFA_DEBUG === '1';
+  const base = (() => {
+    switch (code) {
+      case 'API_UNREACHABLE':       return `${prefix}: API is unreachable — check network connectivity.`;
+      case 'API_SERVER_ERROR':      return `${prefix}: API returned a server error — retry shortly.`;
+      case 'DISALLOWED_EXTENSION':  return `${prefix}: file must be a workbook (allowed: .xlsx/.xls/.xlsm/.xlsb/.csv/.ods/.fods/.numbers/.tsv).`;
+      case 'FILE_TOO_LARGE':        return `${prefix}: file exceeds the XFA_MAX_FILE_MB cap (default 50 MB).`;
+      case 'FILE_NOT_FOUND':        return `${prefix}: file not found.`;
+      case 'MISSING_TOKEN':         return `${prefix}: required token env var is not set.`;
+      case 'RATE_LIMITED':          return `${prefix}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
+      case 'TIER_UPGRADE_REQUIRED': return `${prefix}: this capability requires a paid tier.`;
+      case 'FALLBACK_ENGINE_MISSING': return `${prefix}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
+      default:                      return `${prefix}: request failed${code ? ` (code=${code})` : ''}.`;
+    }
+  })();
+  return showRaw && err && err.message ? `${base}\nRaw: ${err.message}` : base;
+}
 
 function nextRequiredArg(argv, i, flag) {
   const v = argv[i + 1];
@@ -175,6 +215,172 @@ function loadChecksFile(checksPath) {
   return parsed;
 }
 
+// ---------------------------------------------------------------------------
+// Heal subcommand — exposes the healer-deep HTTP routes from the CLI.
+//
+//   xlsx-for-ai heal <path>                    diagnose-only (default)
+//   xlsx-for-ai heal <path> --diagnose-only    explicit form of the default
+//   xlsx-for-ai heal <path> --operation <op> --params <json> [--mode <m>] [--out <path>]
+//   xlsx-for-ai heal <path> --format text|json [other flags]
+//
+// `--intent`/`--from`/`--to` are reserved for v1.1 once the
+// /api/v1/tools/xlsx_healer_intent route ships; the CLI rejects
+// those flags today so callers see a clean "v1.1" message rather
+// than a server 404.
+// ---------------------------------------------------------------------------
+
+async function runHealSubcommand(rest) {
+  if (rest.length === 0 || rest[0].startsWith('-')) {
+    process.stderr.write(
+      'Usage: xlsx-for-ai heal <file.xlsx> [--diagnose-only | --operation <op> --params <json>] [--mode as_copy|in_place] [--out <path>] [--format text|json]\n',
+    );
+    process.exit(2);
+  }
+  const filePath = path.resolve(rest[0]);
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`File not found: ${filePath}\n`);
+    process.exit(4);
+  }
+
+  // Parse flags
+  let diagnoseOnly = false;
+  let operation = null;
+  let paramsJson = null;
+  let mode = 'as_copy';
+  let outPath = null;
+  let format = 'text';
+  for (let i = 1; i < rest.length; i++) {
+    const a = rest[i];
+    if      (a === '--diagnose-only')   diagnoseOnly = true;
+    else if (a === '--operation')       operation = nextRequiredArg(rest, i++, '--operation');
+    else if (a === '--params')          paramsJson = nextRequiredArg(rest, i++, '--params');
+    else if (a === '--mode')            mode       = nextRequiredArg(rest, i++, '--mode');
+    else if (a === '--out')             outPath    = nextRequiredArg(rest, i++, '--out');
+    else if (a === '--format')          format     = nextRequiredArg(rest, i++, '--format');
+    else if (a === '--intent' || a === '--from' || a === '--to') {
+      process.stderr.write(`xlsx-for-ai heal: ${a} is reserved for v1.1 (intent-driven cures via /xlsx_healer_intent); not yet wired\n`);
+      process.exit(2);
+    } else {
+      process.stderr.write(`Unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+
+  // Validate mutually-exclusive shapes early — clearer than letting
+  // the server emit `conflicting_repair_directives` on its O8 check.
+  if (diagnoseOnly && operation) {
+    process.stderr.write('xlsx-for-ai heal: --diagnose-only and --operation are mutually exclusive\n');
+    process.exit(2);
+  }
+  if (!diagnoseOnly && !operation) {
+    // Default to diagnose-only — first-touch use of `xlsx-for-ai heal`
+    // should show the user what's wrong before they pick a cure.
+    diagnoseOnly = true;
+  }
+  if (mode !== 'as_copy' && mode !== 'in_place') {
+    process.stderr.write(`xlsx-for-ai heal: --mode must be 'as_copy' or 'in_place' (got '${mode}')\n`);
+    process.exit(2);
+  }
+  if (format !== 'text' && format !== 'json') {
+    process.stderr.write(`xlsx-for-ai heal: --format must be 'text' or 'json' (got '${format}')\n`);
+    process.exit(2);
+  }
+
+  await ensureRegistered();
+  const fileB64 = fs.readFileSync(filePath).toString('base64');
+
+  // ---- diagnose path -----------------------------------------------------
+  if (diagnoseOnly) {
+    let result;
+    try {
+      result = await callTool('xlsx_healer_diagnose', { file_b64: fileB64 });
+    } catch (err) {
+      // friendlyCliError (defined above in this file) maps known
+      // API error codes to short canned messages — raw err.message
+      // is suppressed unless XFA_DEBUG=1 is set, so internal server
+      // detail / paths / stack traces never reach the user's
+      // terminal or CI logs by default. Same sanitization shape
+      // the other subcommands use for API failures.
+      process.stderr.write(friendlyCliError('xlsx-for-ai heal --diagnose-only', err) + '\n');
+      process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
+    }
+    const meta = (result && result._meta) || {};
+    if (format === 'json') {
+      // metaForStdout strips file_b64 if present — diagnose has none,
+      // but the helper is safe to call unconditionally.
+      process.stdout.write(JSON.stringify(metaForStdout(meta) || {}, null, 2) + '\n');
+    } else {
+      const text = (result.content || []).map((c) => c.text).join('\n');
+      process.stdout.write(text + '\n');
+    }
+    return 0;
+  }
+
+  // ---- cure path ---------------------------------------------------------
+  let cureParams = {};
+  if (paramsJson !== null) {
+    try {
+      cureParams = JSON.parse(paramsJson);
+    } catch (e) {
+      process.stderr.write(`xlsx-for-ai heal: --params is not valid JSON: ${e.message}\n`);
+      process.exit(2);
+    }
+    if (cureParams === null || typeof cureParams !== 'object' || Array.isArray(cureParams)) {
+      process.stderr.write('xlsx-for-ai heal: --params must be a JSON object\n');
+      process.exit(2);
+    }
+  }
+
+  const body = { file_b64: fileB64, operation, cure_params: cureParams, mode };
+  let result;
+  try {
+    result = await callTool('xlsx_healer_cure', body);
+  } catch (err) {
+    // Same sanitization shape as the diagnose path — friendlyCliError
+    // (above) maps known codes to canned messages; raw err.message
+    // only surfaces with XFA_DEBUG=1 for incident triage.
+    process.stderr.write(friendlyCliError(`xlsx-for-ai heal --operation ${operation}`, err) + '\n');
+    process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
+  }
+
+  const meta = (result && result._meta) || {};
+
+  // Write the cured workbook to disk when `as_copy` mode produced
+  // bytes. `in_place` mode is server-side conceptual; the client
+  // still receives the cured bytes here (we'd overwrite the input
+  // file). Refuse to overwrite the source unless the caller passed
+  // --out explicitly.
+  if (meta.file_b64) {
+    let resolvedOut = outPath;
+    if (!resolvedOut) {
+      const parsed = path.parse(filePath);
+      resolvedOut = path.join(parsed.dir, `${parsed.name}-healed${parsed.ext || '.xlsx'}`);
+    }
+    const sourceIsTarget = path.resolve(resolvedOut) === path.resolve(filePath);
+    if (sourceIsTarget && mode !== 'in_place') {
+      process.stderr.write(
+        'xlsx-for-ai heal: refusing to overwrite source — pass --out <other-path> or --mode in_place\n',
+      );
+      process.exit(2);
+    }
+    try {
+      fs.writeFileSync(resolvedOut, Buffer.from(meta.file_b64, 'base64'));
+    } catch (e) {
+      process.stderr.write(`xlsx-for-ai heal: failed to write ${resolvedOut}: ${e.message}\n`);
+      process.exit(4);
+    }
+    process.stderr.write(`Wrote ${resolvedOut}\n`);
+  }
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(metaForStdout(meta) || {}, null, 2) + '\n');
+  } else {
+    const text = (result.content || []).map((c) => c.text).join('\n');
+    process.stdout.write(text + '\n');
+  }
+  return 0;
+}
+
 async function runStampSubcommand(subcmd, rest) {
   if (rest.length === 0 || rest[0].startsWith('-')) {
     process.stderr.write(`Usage: xlsx-for-ai ${subcmd} <path> [...]\n`);
@@ -204,7 +410,7 @@ async function runStampSubcommand(subcmd, rest) {
     if (excludeSheets.length) body.exclude_sheets = excludeSheets;
     if (supervisor) body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor };
     const result = await callServerForStamp('xlsx_stamp', body, outPath, filePath, '.stamped.xlsx');
-    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(result._meta) || {}, null, 2) + '\n');
     return 0;
   }
 
@@ -212,7 +418,7 @@ async function runStampSubcommand(subcmd, rest) {
     const body = { file_b64: fileB64 };
     const result = await callTool('xlsx_verify_stamp', body);
     const meta = result._meta || {};
-    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
     return meta.valid === true ? 0 : 1;
   }
 
@@ -255,7 +461,7 @@ async function runStampSubcommand(subcmd, rest) {
     if (description) body.description = description;
     if (coverSheets.length) body.covers_sheets = coverSheets;
     const result = await callServerForStamp('xlsx_receipt', body, outPath, filePath, '.receipted.xlsx');
-    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(result._meta) || {}, null, 2) + '\n');
     return 0;
   }
 
@@ -263,7 +469,7 @@ async function runStampSubcommand(subcmd, rest) {
     const body = { file_b64: fileB64 };
     const result = await callTool('xlsx_verify_receipt', body);
     const meta = result._meta || {};
-    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
     return meta.valid === true ? 0 : 1;
   }
   return 2;
@@ -274,7 +480,7 @@ async function callServerForStamp(tool, body, explicitOutPath, sourcePath, sidec
   try {
     result = await callTool(tool, body);
   } catch (err) {
-    process.stderr.write(`xlsx-for-ai ${tool}: ${err.message}\n`);
+    process.stderr.write(friendlyCliError(`xlsx-for-ai ${tool}`, err) + '\n');
     process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
   }
   const meta = result._meta || {};
@@ -303,6 +509,10 @@ async function main() {
     const code = await runStampSubcommand(argv[0], argv.slice(1));
     process.exit(code);
   }
+  if (argv.length > 0 && HEAL_SUBCOMMANDS.has(argv[0])) {
+    const code = await runHealSubcommand(argv.slice(1));
+    process.exit(code);
+  }
 
   const opts = parseArgs(argv);
 
@@ -353,7 +563,7 @@ async function main() {
     if (err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR') {
       result = await fallbackRead(absPath, opts);
     } else {
-      process.stderr.write(`Error: ${err.message}\n`);
+      process.stderr.write(friendlyCliError('xlsx-for-ai', err) + '\n');
       process.exit(1);
     }
   }
@@ -363,6 +573,6 @@ async function main() {
 }
 
 main().catch((err) => {
-  process.stderr.write(`xlsx-for-ai: ${err.message}\n`);
+  process.stderr.write(friendlyCliError('xlsx-for-ai', err) + '\n');
   process.exit(1);
 });

package/mcp.js

@@ -1156,6 +1156,14 @@ function fileToB64(filePath) {
 // If out_path is not provided:                            leave response unchanged.
 // ---------------------------------------------------------------------------
 
+// Extensions an MCP tool is allowed to write via out_path. Tighter than the
+// READ allowlist (no .ods/.fods/.numbers/.tsv) because the server only ever
+// emits XLSX or XLSX-family workbook bytes — accepting unrelated extensions
+// would let a malicious / confused agent point out_path at /etc/profile.d/
+// or a shell startup script. The .json carve-out is for fixture/audit JSON
+// the redact + clean tools sometimes emit alongside the workbook.
+const ALLOWED_WRITE_EXTENSIONS = new Set(['.xlsx', '.xls', '.xlsm', '.xlsb', '.csv', '.json']);
+
 async function applyFileB64(result, outPath) {
   if (!outPath) {
     // No save requested — leave response untouched (b64 stays in _meta for caller)
@@ -1164,6 +1172,21 @@ async function applyFileB64(result, outPath) {
 
   const absPath = path.resolve(outPath);
 
+  // Containment: require an absolute path + a workbook-family extension.
+  // Reject path-traversal patterns and any non-workbook extension at the
+  // boundary so a malicious agent can't request a write to a shell-startup
+  // location or an arbitrary system file via out_path. Pre-Friday-external
+  // CRITICAL per the Tier-1 error-handling audit (2026-06-03).
+  const outExt = path.extname(absPath).toLowerCase();
+  if (!ALLOWED_WRITE_EXTENSIONS.has(outExt)) {
+    if (result.content && result.content[0] && result.content[0].type === 'text') {
+      result.content[0].text +=
+        `\n\nout_path rejected: extension "${outExt}" is not in the allowed write set ` +
+        `(${[...ALLOWED_WRITE_EXTENSIONS].join(', ')}). File was NOT written.`;
+    }
+    return result;
+  }
+
   if (result._meta && result._meta.file_b64) {
     await fsPromises.writeFile(absPath, Buffer.from(result._meta.file_b64, 'base64'));
     // Append save confirmation to first text content block
@@ -1181,6 +1204,51 @@ async function applyFileB64(result, outPath) {
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// Boundary error sanitization
+//
+// The MCP server is a public boundary — anything in err.message that flows
+// to the client can end up in the MCP client's conversation log and from
+// there into any LLM context window the operator never intended. Map the
+// known operational error codes to short, client-safe text; collapse
+// everything else to a generic message that names the tool but not the
+// internals. Tool name is safe to echo (the caller asked for it); paths,
+// upstream server stacks, and third-party response bodies are not.
+//
+// New codes added here as the client-side error surface grows. Default
+// branch is conservative on purpose — better to under-reveal than over-
+// reveal at the boundary.
+// ---------------------------------------------------------------------------
+
+function friendlyErrorMessage(toolName, code) {
+  switch (code) {
+    case 'DISALLOWED_EXTENSION':
+      return `${toolName}: file path must point at a workbook (allowed: .xlsx/.xls/.xlsm/.xlsb/.csv/.ods/.fods/.numbers/.tsv).`;
+    case 'SYMLINK_REJECTED':
+      return `${toolName}: file path resolves through a symlink — provide a direct path.`;
+    case 'FILE_TOO_LARGE':
+      return `${toolName}: file exceeds the XFA_MAX_FILE_MB cap (default 50 MB).`;
+    case 'FILE_NOT_FOUND':
+      return `${toolName}: file not found at the supplied path.`;
+    case 'NOT_REGULAR_FILE':
+      return `${toolName}: file path is not a regular file.`;
+    case 'MISSING_TOKEN':
+      return `${toolName}: required token env var is not set (see tool docs for which one).`;
+    case 'API_UNREACHABLE':
+      return `${toolName}: API is unreachable — check network connectivity.`;
+    case 'API_SERVER_ERROR':
+      return `${toolName}: API returned a server error — retry shortly.`;
+    case 'TIER_UPGRADE_REQUIRED':
+      return `${toolName}: this capability requires a paid tier.`;
+    case 'RATE_LIMITED':
+      return `${toolName}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
+    case 'FALLBACK_ENGINE_MISSING':
+      return `${toolName}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
+    default:
+      return `${toolName} failed — see server-side logs (request_id in response _meta) for details.`;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool dispatch
 // ---------------------------------------------------------------------------
@@ -1525,9 +1593,23 @@ async function main() {
   // server-side tools appear without re-publishing this npm package.
   // resolveCatalog returns the baked-in TOOLS as last-resort fallback so
   // we never fail-open on a transient network blip. See lib/discover.js.
+  //
+  // Hard timeout (8s) on top of any timeout inside resolveCatalog so that
+  // a network call which hangs forever (DNS sinkhole, TCP black hole, slow-
+  // loris-style stalled response) cannot block MCP server startup
+  // indefinitely. Pre-Friday-external CRITICAL per the Tier-1 audit.
+  const CATALOG_FETCH_TIMEOUT_MS = 8000;
   let catalog;
   try {
-    catalog = await resolveCatalog(TOOLS);
+    catalog = await Promise.race([
+      resolveCatalog(TOOLS),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`catalog fetch timed out after ${CATALOG_FETCH_TIMEOUT_MS}ms`)),
+          CATALOG_FETCH_TIMEOUT_MS
+        )
+      ),
+    ]);
   } catch (_) {
     catalog = { tools: TOOLS, source: 'static-fallback' };
   }
@@ -1568,8 +1650,19 @@ async function main() {
       // Pass API response through verbatim (citation footer + _meta preserved)
       return result;
     } catch (err) {
+      // Error message sanitization at the MCP boundary. Raw err.message
+      // can leak absolute file paths (FILE_NOT_FOUND), upstream server
+      // error stacks (any thrown Error inside dispatchTool), and upstream
+      // HTTP response bodies (callTool's API_SERVER_ERROR path may carry
+      // server internals). Translate the known operational codes into
+      // short, client-safe messages; everything else collapses to a
+      // generic "tool failed" with the tool name so callers can still
+      // route on it without leaking path/server detail. Pre-Friday-
+      // external CRITICAL per the Tier-1 audit.
+      const code = err && err.code;
+      const safeMessage = friendlyErrorMessage(name, code);
       return {
-        content: [{ type: 'text', text: `xlsx-for-ai error: ${err.message}` }],
+        content: [{ type: 'text', text: `xlsx-for-ai error: ${safeMessage}` }],
         isError: true,
       };
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
   "main": "index.js",
   "bin": {