flecto 3.1.0 → 4.1.0

package/index.js

@@ -2,13 +2,13 @@
 
 import { program } from 'commander';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'fs';
-import { resolve, relative, dirname, join } from 'path';
+import { resolve, relative, dirname, basename, join, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 
 import { parseFile, isSupported, parseContent } from './src/parser.js';
-import { diffTrees, secretMatchPath } from './src/differ.js';
+import { diffTrees } from './src/differ.js';
 import { documentKeysOf, withDocumentKeys } from './src/documents.js';
 import { startWatcher } from './src/watcher.js';
 import {
@@ -20,7 +20,7 @@ import {
   renderWarn,
   renderPolicyFindings,
   maskChangeEvent,
-  maskSensitiveValue,
+  maskFindings,
 } from './src/renderer.js';
 import { deliverPrComment, renderPrComment } from './src/pr-comment.js';
 import { PR_PROVIDER_IDS } from './src/pr-providers.js';
@@ -30,10 +30,10 @@ import {
   readTerraformPlanFile,
 } from './src/terraform.js';
 import { renderReportHtml } from './src/report.js';
-import { redactSecretString } from './src/secrets.js';
 import { fireAlerts } from './src/alerter.js';
 import { resolveWebhookFormat, WEBHOOK_FORMAT_CHOICES } from './src/notifiers.js';
 import { createEnvelope } from './src/envelope.js';
+import { startLanguageServer } from './src/lsp.js';
 import { buildSarif } from './src/sarif.js';
 import {
   maskState,
@@ -60,6 +60,18 @@ import {
   addPolicyPackFromPackage,
 } from './src/policy.js';
 import { testPolicyFixture } from './src/policy-test.js';
+import { makeCliRunner, runStdioServer } from './src/mcp.js';
+import {
+  assertExplainNotFromRc,
+  buildExplainPayload,
+  buildExplainRequest,
+  describeRequest,
+  estimateInputTokens,
+  EXPLAIN_PROVIDERS,
+  formatNarration,
+  narrate,
+  resolveExplainConfig,
+} from './src/explain.js';
 import {
   loadRcConfig,
   resolveEffectiveOptions,
@@ -69,6 +81,9 @@ import {
   resolvePolicyOptions,
   assertTargetContained,
   assertWriteDestinationContained,
+  assertAlertActionsFromCli,
+  assertSnapshotRefFromCli,
+  assertSafeGitRef,
 } from './src/config.js';
 
 const PKG = JSON.parse(
@@ -227,11 +242,6 @@ function maybeMaskChanges(events, maskSecrets) {
 }
 
 /**
- * Redact secret-shaped text from policy messages. A rule using
- * `messageTemplate` can interpolate `{before}` / `{after}`, so a finding can
- * carry a credential even when the change events beside it are masked. Replace
- * exact interpolated values using the same path-aware masking as change events,
- * then catch any other recognizable secret fragments in free-form messages.
  * @param {import('./src/policy.js').PolicyFinding[]} findings
  * @param {import('./src/differ.js').ChangeEvent[]} changes
  * @param {boolean} maskSecrets
@@ -239,17 +249,7 @@ function maybeMaskChanges(events, maskSecrets) {
  */
 function maybeMaskFindings(findings, changes, maskSecrets) {
   if (!maskSecrets) return findings;
-  return findings.map((finding) => {
-    let message = String(finding.message ?? '');
-    for (const change of changes.filter((event) => event.path === finding.path)) {
-      for (const value of [change.before, change.after]) {
-        const original = String(value);
-        const masked = String(maskSensitiveValue(value, secretMatchPath(change)));
-        if (original && original !== masked) message = message.replaceAll(original, masked);
-      }
-    }
-    return { ...finding, message: redactSecretString(message) };
-  });
+  return maskFindings(findings, changes);
 }
 
 /**
@@ -309,6 +309,37 @@ function restoreSnapshotDocumentKeys(state, snapshot) {
   return withDocumentKeys(state, documents.map(String));
 }
 
+/**
+ * Read a snapshot named as a path, with the containment every other read in
+ * Flecto already has.
+ *
+ * A baseline path is attacker-reachable in the shape that matters: the
+ * operator names an in-repo snapshot such as `.flecto/baseline.json`, and the
+ * pull request replaces that file with a symlink. Without this check the
+ * contents of any JSON file on the runner became the "baseline" and were
+ * printed as `removed` changes -- the same read-outside-the-repo leak that
+ * `assertTargetContained` was added for, and that `src/mcp.js` already refuses
+ * for a ref naming a file. This was the one remaining surface without the rule.
+ *
+ * `assertTargetContained` is about escape, not location, so an operator's
+ * deliberate absolute path to a snapshot outside the project still works.
+ * @param {string} given
+ * @param {string} option the flag to name in an error
+ * @returns {unknown}
+ */
+function readSnapshotFile(given, option) {
+  if (given === '') {
+    // An unset CI variable expands to this. Everything else here refuses
+    // loudly; silently falling back to the local store would be the one path
+    // that quietly compares against something the operator did not choose.
+    throw new Error(`${option} was given an empty value`);
+  }
+  const resolved = resolve(given);
+  assertTargetContained(resolved, process.cwd());
+  if (!existsSync(resolved)) throw new Error(`no snapshot file at "${given}"`);
+  return readSnapshotStateFromFile(resolved);
+}
+
 function readSnapshotStateFromFile(snapshotPath) {
   const snap = JSON.parse(readFileSync(snapshotPath, 'utf8'));
   return restoreSnapshotDocumentKeys(snap?.state ?? snap, snap);
@@ -329,7 +360,41 @@ function gitRepoRelativePath(filePath) {
   const top = execFileSync('git', ['-C', dirname(filePath), 'rev-parse', '--show-toplevel'], {
     encoding: 'utf8',
   }).trim();
-  return relative(canonicalPath(top), canonicalPath(filePath)).replaceAll('\\', '/');
+  // Canonicalize the *directory* and keep the name as written. Canonicalizing
+  // the file itself resolved its final symlink, so the path handed to
+  // `git show` was the link's destination rather than the path the operator
+  // gated -- and a pull request that replaced the gated file with a link to any
+  // other file unchanged in the baseline got `before == after`, a genuinely
+  // empty diff that no --fail-on value catches. Every reason the comment above
+  // gives for canonicalizing (Windows 8.3 and case, the macOS /tmp and /var
+  // links) is a property of directories, so none of it is lost.
+  const nominal = join(canonicalPath(dirname(filePath)), basename(filePath));
+  return relative(canonicalPath(top), nominal).replaceAll('\\', '/');
+}
+
+/**
+ * Is the entry at this path, in this commit, a symbolic link?
+ *
+ * Git stores a link as mode 120000 whose blob is the *target path*, so reading
+ * one as a config file yields the target string rather than any configuration.
+ * That is a baseline Flecto cannot honestly compare against, and saying so
+ * beats emitting a diff between a filename and a document.
+ * @param {string} commit
+ * @param {string} rel
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function baselineEntryIsSymlink(commit, rel, dir) {
+  try {
+    const entry = execFileSync(
+      'git',
+      ['-C', dir, 'ls-tree', '--format=%(objectmode)', '--end-of-options', commit, '--', rel],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return entry === '120000';
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -364,7 +429,109 @@ function canonicalPath(path) {
   }
 }
 
-function readSnapshotStateFromRef(filePath, snapshotRef, store) {
+function gitFailureReason(err) {
+  if (err?.code === 'ENOENT') return 'git is not installed or not on PATH';
+  if (err?.status === 128) return 'this is not a git repository';
+  // The most likely remaining cause by far: `--end-of-options` arrived in git
+  // 2.24 (2019), and an older git rejects it as an unknown option. Naming a
+  // version someone can check beats printing the raw spawn failure.
+  return 'git rejected the command -- Flecto needs git 2.24 or newer'
+    + ` (${String(err?.message ?? 'unknown error').split('\n')[0]})`;
+}
+
+/**
+ * Resolve a ref to the single commit it names, or null when it names none.
+ *
+ * `git show` accepts far more than a commit: `A..B` is a *range*, and asking
+ * it to show one succeeds while printing nothing. An empty read then parses as
+ * an empty document, every key looks `added` rather than `changed`, and the
+ * default `--fail-on changed,policy,error` never fires -- the same silent-pass
+ * chain as the `--output=` injection, reached without a single dash.
+ * `rev-parse --verify <ref>^{commit}` refuses anything that is not exactly one
+ * commit, which closes the whole shape rather than the one spelling of it.
+ *
+ * Resolving also means the value handed to `git show` afterwards is a hex SHA
+ * this function produced, not a string the attacker wrote.
+ * @param {string} ref
+ * @param {string} dir a directory inside the repository
+ * @returns {string | null} the commit SHA, or null when `ref` is not a revision
+ */
+function resolveGitCommit(ref, dir) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['-C', dir, 'rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return { usable: true, commit: out || null };
+  } catch (err) {
+    // Exactly one failure means "git works, that revision is not here": exit 1
+    // from `--verify --quiet`. Everything else -- git missing (ENOENT), not a
+    // repository (128), an option this git does not know (pre-2.24) -- means
+    // Flecto cannot tell whether the ref exists. Collapsing those into "not a
+    // revision" is what let a missing git turn a baseline into whatever file
+    // happened to share the ref's name.
+    if (err?.status === 1) return { usable: true, commit: null };
+    return { usable: false, commit: null, reason: gitFailureReason(err) };
+  }
+}
+
+/**
+ * Is this value written the way a *path* is written, rather than a revision?
+ *
+ * `--snapshot-ref` has always accepted either a git revision or a snapshot
+ * file, and that ambiguity is the vulnerability: the file is resolved against
+ * the checkout root, whose file names an untrusted pull request controls. A
+ * pull request that commits a file named after the operator's ref replaces the
+ * baseline with one the attacker wrote, and since they can make it match their
+ * own tip exactly, the diff is genuinely empty -- no `--fail-on` setting
+ * catches it.
+ *
+ * The first attempt at this asked "does the value look like a revision?" and
+ * refused the file branch when it did. That is a denylist over a value space
+ * identical to the one it is trying to exclude: branch and tag names are
+ * ordinary words, so `origin/main`, `main`, and `v1.2.3` all fell through it
+ * and stayed exploitable -- and `origin/main` is the form this project's own
+ * documentation puts in a workflow.
+ *
+ * So the polarity is inverted. The *file* branch must prove itself, and the
+ * proof is a shape the git ref grammar cannot produce: an absolute path, or an
+ * explicit `./` or `../`. Everything else must resolve as a revision or the run
+ * fails, pointing at `--snapshot-file`. The failure mode is now "a snapshot
+ * file named like a ref is refused, and says which flag to use" rather than
+ * "an attacker's file is read as the baseline".
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isExplicitPath(value) {
+  // git-check-ref-format forbids a ref whose component begins with `.` and a
+  // ref beginning with `/`, so none of these can name a revision. An earlier
+  // version of this also accepted a `.json`/`.yaml` suffix, which was the same
+  // mistake a third time: those ARE legal in a ref name, so `release/v1.json`
+  // skipped git entirely and read an attacker's committed file in preference to
+  // a real, resolvable tag of that name. A suffix is a convention; these are a
+  // grammar.
+  return isAbsolute(value)
+    || value.startsWith('./')
+    || value.startsWith('../')
+    || value.startsWith('.\\')
+    || value.startsWith('..\\');
+}
+
+function readSnapshotStateFromRef(filePath, snapshotRef, store, snapshotFile) {
+  if (snapshotRef === '') {
+    // The same unset-CI-variable case readSnapshotFile refuses. Falling back to
+    // the store here would compare against something the operator did not
+    // choose -- and on an untrusted pull request a committed shared store is
+    // something the change under review wrote.
+    throw new Error('--snapshot-ref was given an empty value');
+  }
+  // `--snapshot-file` is the unambiguous form: a path, never a revision. It
+  // exists because overloading one flag with both is what made an
+  // attacker-committed file able to stand in for the operator's baseline.
+  if (snapshotFile !== undefined) {
+    return readSnapshotFile(String(snapshotFile), '--snapshot-file');
+  }
   if (!snapshotRef) {
     // Failing closed here is right — a diff with no baseline is not a clean
     // diff — but an ENOENT on a hashed filename explains nothing. The default
@@ -377,13 +544,54 @@ function readSnapshotStateFromRef(filePath, snapshotRef, store) {
     }
     return record.state;
   }
-  const maybePath = resolve(snapshotRef);
-  if (existsSync(maybePath)) {
-    return readSnapshotStateFromFile(maybePath);
+  // The path decision comes before assertSafeGitRef, which refuses `..` -- a
+  // legitimate `../snapshots/base.json` is a path, not a commit range.
+  if (isExplicitPath(String(snapshotRef))) {
+    return readSnapshotFile(String(snapshotRef), '--snapshot-ref');
+  }
+
+  const ref = assertSafeGitRef(snapshotRef);
+  const repoDir = dirname(resolve(filePath));
+  const { usable, commit, reason } = resolveGitCommit(ref, repoDir);
+  if (!usable) {
+    // Never fall through to a file here. Not knowing whether the revision
+    // exists is exactly when reading a same-named file is most dangerous.
+    throw new Error(
+      `cannot resolve "${ref}" as a git revision: ${reason}.`
+      + ' Pass --snapshot-file <path> if you meant a snapshot file.',
+    );
+  }
+  if (!commit) {
+    const shadow = resolve(ref);
+    throw new Error(
+      `"${ref}" does not resolve to a git revision here`
+      + ' (a shallow clone is the usual reason -- on a pull request, actions/checkout does not'
+      + ' create origin/<base> unless you fetch it; try fetch-depth: 0).'
+      + (existsSync(shadow)
+        ? ` A file named "${ref}" exists and was NOT read as the baseline: a pull request can`
+        + ' commit such a file, and reading it would let the change under review choose what it'
+        + ' is compared against. Pass --snapshot-file if you genuinely meant that file.'
+        : ' Pass --snapshot-file <path> if you meant a snapshot file.'),
+    );
   }
 
   const rel = gitRepoRelativePath(filePath);
-  const raw = execFileSync('git', ['show', `${snapshotRef}:${rel}`], { encoding: 'utf8' });
+  if (baselineEntryIsSymlink(commit, rel, repoDir)) {
+    throw new Error(
+      `"${rel}" is a symbolic link in ${ref}, so the baseline there is a path, not a configuration.`
+      + ' Point --snapshot-ref at a revision where it is a regular file, or gate the file the link'
+      + ' resolves to.',
+    );
+  }
+  // `-C repoDir` matches where the revision was resolved, and the operand is a
+  // SHA this process produced rather than any string the attacker wrote.
+  // maxBuffer matches the LSP's reader: a megabyte-scale baseline blob is
+  // ordinary, and the default 1 MB dies with a raw ENOBUFS.
+  const raw = execFileSync(
+    'git',
+    ['-C', repoDir, 'show', '--end-of-options', `${commit}:${rel}`],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 },
+  );
   return parseContent(filePath, raw);
 }
 
@@ -610,6 +818,50 @@ async function deliverPrCommentSafely(body, enabled, provider) {
   }
 }
 
+/**
+ * `ci --explain` (#143): narration for the run, or null.
+ *
+ * Called only after the gate is decided, and it cannot change it: every failure
+ * here — no provider configured, over budget, network, refusal — is a warning
+ * and a null, never a thrown error. Status goes to stderr, so the machine
+ * output on stdout is byte-for-byte what it is without the flag.
+ * @param {import('./src/explain.js').ExplainInputFile[]} files unmasked; the payload builder masks
+ * @param {{ dryRun: boolean, cwd: string }} options
+ * @returns {Promise<{ text: string, provider: string, model: string, cached: boolean, truncated: boolean } | null>}
+ */
+async function narrateForCi(files, { dryRun, cwd }) {
+  try {
+    const payload = buildExplainPayload(files, { cwd });
+    if (payload.files.length === 0) {
+      renderNote('flecto explain: nothing to narrate — no changes and no findings.');
+      return null;
+    }
+    const resolved = resolveExplainConfig({}, process.env, { dryRun });
+    if (!resolved.ok) {
+      renderWarn(`No narration: ${resolved.reason}.`);
+      return null;
+    }
+    if (dryRun) {
+      const request = describeRequest(buildExplainRequest(payload, resolved.config), resolved.config);
+      renderNote(
+        `flecto explain --explain-dry-run: nothing was sent. ~${estimateInputTokens(request.body)} input`
+        + ` tokens (estimated), output capped at ${resolved.config.maxTokens}. The request:`,
+      );
+      process.stderr.write(`${JSON.stringify(request, null, 2)}\n`);
+      return null;
+    }
+    const result = await narrate(payload, resolved.config, { onNote: renderNote });
+    if (!result.ok) {
+      renderWarn(`No narration: ${result.reason}.`);
+      return null;
+    }
+    return result;
+  } catch (err) {
+    renderWarn(`No narration: ${err.message}.`);
+    return null;
+  }
+}
+
 program
   .name('flecto')
   .description('Flecto — semantic config watcher for meaningful structured file changes')
@@ -654,6 +906,7 @@ program
       const profile = resolveProfileName(opts.profile);
       const cliOverrides = stripUnsetCliOverrides(opts, command);
       const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertAlertActionsFromCli(effective, cliOverrides);
       const { policies, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
@@ -1054,7 +1307,8 @@ program
   .command('ci [files...]')
   .description('Run semantic diff in CI mode')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
-  .option('--snapshot-ref <ref>', 'Snapshot reference: snapshot path or git ref')
+  .option('--snapshot-ref <ref>', 'Baseline git revision (a snapshot path also works if it is path-shaped)')
+  .option('--snapshot-file <path>', 'Baseline snapshot file, never consulted as a git revision')
   .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
   .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('--format <type>', 'Output format: json | ndjson | sarif | github-annotations | pr-comment', 'json')
@@ -1073,12 +1327,18 @@ program
   .option('--show-suppressed', 'List inline-suppressed findings instead of only counting them', false)
   .option('--changed-only', 'With --format json|ndjson, replace envelopes for unchanged files with one scanned manifest', false)
   .option('--allow-empty', 'Allow CI to succeed when no files were diffed', false)
+  .option('--explain', 'Add model-generated narration of the masked diff (advisory; provider set by FLECTO_EXPLAIN_* env)', false)
+  .option('--explain-dry-run', 'Print the narration request that --explain would send, and send nothing', false)
   .action(async (files, opts, command) => {
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
       const cliOverrides = stripUnsetCliOverrides(opts, command);
       const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertExplainNotFromRc(effective, cliOverrides);
+      assertSnapshotRefFromCli(effective, cliOverrides);
+      const explainDryRun = Boolean(cliOverrides.explainDryRun);
+      const explainRequested = Boolean(cliOverrides.explain) || explainDryRun;
       const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
@@ -1139,7 +1399,7 @@ program
         throw new Error('--update-baseline requires --baseline <file> naming the file to write.');
       }
 
-      /** @type {Array<{ filepath: string, relFile: string, outboundChanges: any[], outboundFindings: any[], changesFail: boolean }>} */
+      /** @type {Array<{ filepath: string, relFile: string, events: any[], outboundChanges: any[], outboundFindings: any[], changesFail: boolean }>} */
       const perFile = [];
       /** @type {Array<{ file: string, finding: any, reason: string }>} */
       const allSuppressed = [];
@@ -1156,12 +1416,12 @@ program
         }
         // A `--snapshot-ref` baseline is read straight from git, so it is never
         // masked; only a store-provided baseline needs the live side aligned.
-        const after = effective.snapshotRef
+        const after = (effective.snapshotRef || effective.snapshotFile)
           ? parseFile(filepath)
           : alignStateWithStore(parseFile(filepath), snapshotStore);
         let before;
         try {
-          before = readSnapshotStateFromRef(filepath, effective.snapshotRef, snapshotStore);
+          before = readSnapshotStateFromRef(filepath, effective.snapshotRef, snapshotStore, effective.snapshotFile);
         } catch (err) {
           throw new Error(
             `Failed to resolve snapshot baseline for "${filepath}"` +
@@ -1191,6 +1451,7 @@ program
         perFile.push({
           filepath,
           relFile: baselineRelativePath(filepath, cwd),
+          events,
           outboundChanges: maybeMaskChanges(events, maskSecrets),
           outboundFindings: maybeMaskFindings(policyFindings, events, maskSecrets),
           changesFail: shouldFailFromChanges(events, failOn),
@@ -1292,13 +1553,24 @@ program
         }
       }
 
+      // Asked for only once `shouldFail` is settled, and handed nothing that
+      // could change it. Narration covers the findings the gate sees — active
+      // ones, after baseline and suppressions.
+      const narration = explainRequested
+        ? await narrateForCi(
+          perFile.map((f) => ({ file: f.filepath, changes: f.events, findings: activeByFile.get(f.relFile) ?? [] })),
+          { dryRun: explainDryRun, cwd },
+        )
+        : null;
+
       if (format === 'pr-comment') {
-        const body = renderPrComment(results, { cwd, failed: shouldFail });
+        const body = renderPrComment(results, { cwd, failed: shouldFail, narration });
         await writeStdout(body);
         await deliverPrCommentSafely(body, prCommentPost, effective.prProvider);
       } else {
         const collapsible = changedOnly && (format === 'json' || format === 'ndjson');
         await printCiOutput(collapsible ? collapseUnchangedResults(results) : results, format);
+        if (narration) process.stderr.write(`\n${formatNarration(narration)}\n`);
       }
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
@@ -1307,6 +1579,161 @@ program
     }
   });
 
+program
+  .command('explain [files...]')
+  .description('Narrate the masked semantic diff with a model you configure — advisory, opt-in, bring your own key (#143)')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--snapshot-ref <ref>', 'Baseline git revision (a snapshot path also works if it is path-shaped)')
+  .option('--snapshot-file <path>', 'Baseline snapshot file, never consulted as a git revision')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
+  .option('--provider <id>', `Model provider: ${EXPLAIN_PROVIDERS.join(' | ')} (else FLECTO_EXPLAIN_PROVIDER)`)
+  .option('--model <name>', 'Model id (else FLECTO_EXPLAIN_MODEL; anthropic defaults to claude-opus-5)')
+  .option('--max-tokens <n>', 'Output token cap (else FLECTO_EXPLAIN_MAX_TOKENS; default 16000)')
+  .option('--format <type>', 'Output format: human | json', 'human')
+  .option('--dry-run', 'Print the exact request that would be sent, and send nothing', false)
+  .option('--no-cache', 'Neither read nor write the narration cache')
+  .option('--ignore <keys>', 'Comma-separated key paths to ignore')
+  .option('--policies <ids>', 'Comma-separated policy pack ids')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key')
+  .option('--no-array-id', 'Diff arrays by index instead of object identity')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .action(async (files, opts, command) => {
+    try {
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertExplainNotFromRc(effective, cliOverrides);
+      assertSnapshotRefFromCli(effective, cliOverrides);
+      // Everything that shapes the request is read from the command line, never
+      // from the merged options: `.flectorc` can name a `format` or `model` for
+      // other commands, and none of it may steer where the diff goes.
+      const format = String(cliOverrides.format ?? 'human');
+      if (!['human', 'json'].includes(format)) {
+        throw new Error('--format must be human or json');
+      }
+      const dryRun = Boolean(cliOverrides.dryRun);
+      const snapshotRef = cliOverrides.snapshotRef;
+      const snapshotFile = cliOverrides.snapshotFile;
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
+      const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
+      if (targets.length === 0) {
+        throw new Error('No files matched. Provide files or configure .flectorc files/include.');
+      }
+      const dOpts = diffOptionsFromEffective(effective, parseCsv(effective.ignore));
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const cwd = process.cwd();
+
+      /** @type {import('./src/explain.js').ExplainInputFile[]} */
+      const diffed = [];
+      for (const filepath of targets) {
+        if (!existsSync(filepath)) {
+          renderWarn(`Skipping missing file: ${filepath}`);
+          continue;
+        }
+        if (!isSupported(filepath)) {
+          renderWarn(`Skipping unsupported file: ${filepath}`);
+          continue;
+        }
+        const after = (snapshotRef || snapshotFile)
+          ? parseFile(filepath)
+          : alignStateWithStore(parseFile(filepath), snapshotStore);
+        let before;
+        try {
+          before = readSnapshotStateFromRef(filepath, snapshotRef, snapshotStore, snapshotFile);
+        } catch (err) {
+          throw new Error(
+            `Failed to resolve snapshot baseline for "${filepath}"`
+            + `${snapshotRef ? ` (ref: ${snapshotRef})` : ''}: ${err.message}`,
+          );
+        }
+        const events = diffTrees(before, after, dOpts);
+        const rawFindings = await evaluatePolicies(events, {
+          cwd,
+          file: filepath,
+          profile: profile ?? null,
+          source: 'diff',
+          policies: packIds,
+          plugins,
+          severityRemap,
+        });
+        const { active } = resolveSuppressed(filepath, rawFindings);
+        diffed.push({ file: filepath, changes: events, findings: active });
+      }
+      if (diffed.length === 0) {
+        throw new Error('No files were diffed — all targets were missing or unsupported.');
+      }
+
+      // The operator sees what is narrated, masked the way it is sent.
+      if (format === 'human') {
+        for (const { file, changes, findings } of diffed) {
+          renderDiff(file, changes, { maskSecrets: true, baseline: snapshotRef ?? 'snapshot' });
+          renderPolicyFindings(maskFindings(findings, changes));
+        }
+      }
+
+      const payload = buildExplainPayload(diffed, { cwd });
+      if (payload.files.length === 0) {
+        if (format === 'json') {
+          await writeStdout(JSON.stringify({ advisory: true, narration: null, reason: 'no changes and no findings', payload }, null, 2));
+        } else {
+          renderInfo('Nothing to narrate: no semantic changes and no policy findings.');
+        }
+        process.exit(0);
+      }
+
+      const resolved = resolveExplainConfig(
+        {
+          provider: cliOverrides.provider,
+          model: cliOverrides.model,
+          maxTokens: cliOverrides.maxTokens,
+          cache: cliOverrides.cache,
+        },
+        process.env,
+        { dryRun },
+      );
+      if (!resolved.ok) throw new Error(`Cannot narrate: ${resolved.reason}.`);
+
+      if (dryRun) {
+        const request = describeRequest(buildExplainRequest(payload, resolved.config), resolved.config);
+        renderNote(
+          `flecto explain --dry-run: nothing was sent. ~${estimateInputTokens(request.body)} input tokens`
+          + ` (estimated), output capped at ${resolved.config.maxTokens}.`,
+        );
+        await writeStdout(JSON.stringify(request, null, 2));
+        process.exit(0);
+      }
+
+      const result = await narrate(payload, resolved.config, { onNote: renderNote });
+      if (format === 'json') {
+        await writeStdout(JSON.stringify({
+          advisory: true,
+          narration: result.ok
+            ? {
+              model_generated: true,
+              provider: result.provider,
+              model: result.model,
+              cached: result.cached,
+              truncated: result.truncated,
+              text: result.text,
+            }
+            : null,
+          reason: result.ok ? undefined : result.reason,
+          payload,
+        }, null, 2));
+      } else if (result.ok) {
+        await writeStdout(`\n${formatNarration(result)}`);
+      }
+      if (!result.ok) renderWarn(`No narration: ${result.reason}.`);
+      process.exit(0);
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('plan <planFiles...>')
   .description('Diff Terraform plan JSON (terraform show -json) and run policies on it')
@@ -1607,6 +2034,75 @@ program
     renderInfo(`Policy packs: ${detection.packs.join(', ')}`);
   });
 
+program
+  .command('mcp')
+  .description('Run Flecto as a read-only Model Context Protocol server over stdio (#140)')
+  .action(async () => {
+    // The server writes JSON-RPC to stdout and nothing else, so diagnostics go
+    // to stderr. Tools invoke the read-only `ci` path as a subprocess of this
+    // same CLI; the seam is the JSON envelope, so this lifts cleanly into a
+    // standalone flecto-mcp package later without touching the protocol code.
+    const cliPath = fileURLToPath(import.meta.url);
+    const runFlecto = makeCliRunner({ nodeExec: process.execPath, cliPath, cwd: process.cwd() });
+    // Readiness goes to stderr — stdout must carry JSON-RPC and nothing else.
+    renderNote('flecto mcp: read-only server ready (stdio). Secrets masked by default.');
+    await runStdioServer({ version: PKG.version, cwd: process.cwd(), runFlecto });
+  });
+
+program
+  .command('lsp')
+  .description('Run a Language Server Protocol server over stdio: findings and changes as editor diagnostics (#142)')
+  .option('--stdio', 'Talk LSP over stdin/stdout (the only transport; accepted because editors pass it)')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--snapshot-ref <ref>', 'Git ref to diff open files against', 'HEAD')
+  .option('--snapshot-store <id>', `Diff against a snapshot store instead of git: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store')
+  .option('--plugins <paths>', 'Comma-separated absolute paths of ESM policy plugins to load (never read from .flectorc)')
+  .option('--changes <level>', 'How semantic changes appear: hint | info | none', 'hint')
+  .option('--debounce <ms>', 'Wait this long after the last edit before analyzing', '250')
+  .option('--timeout <ms>', 'Stop an analysis that runs longer than this', '10000')
+  .action(async (opts) => {
+    try {
+      const changes = String(opts.changes);
+      if (!['hint', 'info', 'none'].includes(changes)) {
+        throw new Error('--changes must be hint, info, or none');
+      }
+      const debounceMs = Number(opts.debounce);
+      const timeoutMs = Number(opts.timeout);
+      if (!Number.isInteger(debounceMs) || debounceMs < 0) throw new Error('--debounce must be a whole number of milliseconds');
+      if (!Number.isInteger(timeoutMs) || timeoutMs < 100) throw new Error('--timeout must be at least 100 milliseconds');
+      const plugins = opts.plugins === undefined ? undefined : parseCsv(opts.plugins);
+      // A relative path would resolve against whichever repository the editor
+      // opens — including one that ships a file at exactly that path.
+      for (const plugin of plugins ?? []) {
+        if (!isAbsolute(plugin)) {
+          throw new Error(`--plugins must be absolute paths in the language server (got "${plugin}"): a relative path would resolve inside whatever repository is open.`);
+        }
+      }
+      renderNote('flecto lsp: ready (stdio). Plugins from .flectorc are never loaded here.');
+      const { done } = startLanguageServer({
+        input: process.stdin,
+        output: process.stdout,
+        version: PKG.version,
+        cwd: process.cwd(),
+        debounceMs,
+        timeoutMs,
+        settings: {
+          profile: resolveProfileName(opts.profile),
+          plugins,
+          snapshotRef: opts.snapshotRef,
+          snapshotStore: opts.snapshotStore,
+          snapshotDir: opts.snapshotDir,
+          changes: /** @type {'hint' | 'info' | 'none'} */ (changes),
+        },
+      });
+      process.exit(await done);
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('Check Flecto setup, config, and environment')