xlsx-for-ai 2.25.2 → 2.26.1

package/index.js

@@ -151,6 +151,7 @@ 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
@@ -214,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`);
@@ -342,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);
 

package/lib/annotations.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * MCP tool annotations — canonical source.
+ *
+ * Per MCP spec (2025-06-18+) tool annotations describe runtime behavior:
+ *   - title           Human-readable tool name
+ *   - readOnlyHint    Tool does NOT modify its environment
+ *   - destructiveHint Tool may perform irreversible side-effects
+ *
+ * The annotations live here rather than inline on each tool definition so:
+ *   1. They overlay onto tools regardless of source — static fallback,
+ *      cached catalog, or freshly-fetched remote. The remote /api/v1/tools/list
+ *      currently returns minimal entries; this overlay restores the
+ *      annotations the wire format would otherwise drop.
+ *   2. They drive manifest generation downstream (MCPB, M365 declarative
+ *      agent, future OpenAPI). One annotation change → all manifests
+ *      regenerate consistently.
+ *
+ * Classification rules:
+ *   - readOnlyHint: true  → tool only reads; never writes a file or causes
+ *                            an externally observable side-effect.
+ *   - destructiveHint: true → tool causes an irreversible external action
+ *                              (e.g., posts to a third-party system).
+ *     Note: tools that write a NEW file (Save-As shape) are NOT destructive
+ *     even though readOnlyHint is false — the source workbook is preserved.
+ *     destructiveHint is reserved for actions that cannot be undone by
+ *     deleting the output, which means external side-effects.
+ */
+
+const TOOL_ANNOTATIONS = Object.freeze({
+  // ---- Reading / inspection: 35 read-only tools -------------------------
+  xlsx_read:                { title: 'Read Excel file',                       readOnlyHint: true,  destructiveHint: false },
+  xlsx_list_sheets:         { title: 'List Excel sheets',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_schema:              { title: 'Infer Excel column types',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_diff:                { title: 'Diff two Excel workbooks',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_describe:            { title: 'Summarize Excel columns',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_filter:              { title: 'Filter Excel rows',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_aggregate:           { title: 'Group-by aggregate Excel rows',         readOnlyHint: true,  destructiveHint: false },
+  xlsx_named_ranges:        { title: 'List Excel named ranges',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_sort:                { title: 'Sort Excel rows',                       readOnlyHint: true,  destructiveHint: false },
+  xlsx_value_counts:        { title: 'Count Excel column values',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_formulas:            { title: 'Inspect Excel formulas',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_tables:              { title: 'List Excel tables',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_pivot:               { title: 'Pivot Excel data',                      readOnlyHint: true,  destructiveHint: false },
+  xlsx_eval:                { title: 'Evaluate Excel formula',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_validate:            { title: 'Cross-engine validate Excel',           readOnlyHint: true,  destructiveHint: false },
+  xlsx_data_validations:    { title: 'List Excel data-validation rules',      readOnlyHint: true,  destructiveHint: false },
+  xlsx_hyperlinks:          { title: 'List Excel hyperlinks',                 readOnlyHint: true,  destructiveHint: false },
+  xlsx_topology:            { title: 'Map Excel sheet topology',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_conditional_formats: { title: 'List Excel conditional formats',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_comments:            { title: 'List Excel comments',                   readOnlyHint: true,  destructiveHint: false },
+  xlsx_doctor:              { title: 'Audit Excel workbook health',           readOnlyHint: true,  destructiveHint: false },
+  xlsx_form_controls:       { title: 'List Excel form controls',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_macros:              { title: 'List Excel VBA macros',                 readOnlyHint: true,  destructiveHint: false },
+  xlsx_merged_cells:        { title: 'List Excel merged cells',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_workbook_views:      { title: 'List Excel workbook views',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_print_settings:      { title: 'List Excel print settings',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_properties:          { title: 'Read Excel document properties',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_external_links:      { title: 'List Excel external links',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_slicers_timelines:   { title: 'List Excel slicers and timelines',      readOnlyHint: true,  destructiveHint: false },
+  xlsx_pivot_tables:        { title: 'List Excel pivot tables',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_images:              { title: 'List Excel embedded images',            readOnlyHint: true,  destructiveHint: false },
+  xlsx_charts:              { title: 'List Excel charts',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_protection:          { title: 'List Excel protection settings',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_styles:              { title: 'List Excel cell styles',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_verify_stamp:        { title: 'Verify Excel integrity stamp',          readOnlyHint: true,  destructiveHint: false },
+
+  // ---- Writing — non-destructive: 5 Save-As-shape tools -----------------
+  // Source workbook is preserved; output goes to a new path or returned bytes.
+  xlsx_write:               { title: 'Write Excel file',                      readOnlyHint: false, destructiveHint: false },
+  xlsx_redact:              { title: 'Redact Excel file',                     readOnlyHint: false, destructiveHint: false },
+  xlsx_convert:             { title: 'Convert Excel to other format',         readOnlyHint: false, destructiveHint: false },
+  xlsx_data_clean:          { title: 'Clean Excel data',                      readOnlyHint: false, destructiveHint: false },
+  xlsx_stamp:               { title: 'Stamp Excel with integrity verification', readOnlyHint: false, destructiveHint: false },
+
+  // ---- External side-effects — destructive: 2 tools ---------------------
+  // A post can't be undone; the message lands in a third-party system.
+  xlsx_post_slack:          { title: 'Post Excel summary to Slack',           readOnlyHint: false, destructiveHint: true },
+  xlsx_post_teams:          { title: 'Post Excel summary to Teams',           readOnlyHint: false, destructiveHint: true },
+});
+
+/**
+ * Overlay annotations onto an MCP-shaped tool array.
+ *
+ * Returns a new array with each tool extended with an `annotations` object
+ * pulled from TOOL_ANNOTATIONS by name. Tools without a known annotation
+ * pass through unchanged — this is intentional so that a dynamically-
+ * discovered tool the client doesn't recognize still appears, just without
+ * the annotation hints. The annotation map should be updated whenever
+ * a new tool is added to the server.
+ */
+// Keys we refuse to copy from upstream annotation objects — guards against
+// prototype-pollution if a remote /api/v1/tools/list ever returns hostile
+// data. Our overlay map is a frozen const so it's safe to spread directly;
+// the danger is only the foreign `existing` object.
+const POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+function applyAnnotations(tools) {
+  if (!Array.isArray(tools)) return tools;
+  return tools.map((t) => {
+    if (!t || typeof t.name !== 'string') return t;
+    const ann = TOOL_ANNOTATIONS[t.name];
+    if (!ann) return t;
+    // Preserve any annotations the upstream source already carries; ours fill
+    // in the gaps without clobbering richer remote data. Reject pollution
+    // keys and non-plain-object inputs.
+    const merged = { ...ann };
+    if (t.annotations && typeof t.annotations === 'object' && !Array.isArray(t.annotations)) {
+      for (const [k, v] of Object.entries(t.annotations)) {
+        if (POLLUTION_KEYS.has(k)) continue;
+        merged[k] = v;
+      }
+    }
+    return { ...t, annotations: merged };
+  });
+}
+
+module.exports = {
+  TOOL_ANNOTATIONS,
+  applyAnnotations,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.25.2",
+  "version": "2.26.1",
   "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": {
@@ -12,11 +12,12 @@
   "files": [
     "index.js",
     "mcp.js",
+    "lib/annotations.js",
     "lib/client.js",
     "lib/config.js",
-    "lib/register.js",
-    "lib/fallback-read.js",
     "lib/discover.js",
+    "lib/fallback-read.js",
+    "lib/register.js",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -25,6 +26,8 @@
     "test": "node --test test/v2/*.test.js",
     "build-manifests": "node scripts/build-manifests.js",
     "check-manifests": "node scripts/build-manifests.js --check",
+    "check-publish-allowlist": "node scripts/check-publish-allowlist.js",
+    "prepublishOnly": "node scripts/check-publish-allowlist.js && node scripts/build-manifests.js --check",
     "prepare": "husky"
   },
   "keywords": [