flecto 2.1.0 → 3.0.0

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, realpathSync } from 'fs';
 import { resolve, relative, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
@@ -9,20 +9,37 @@ import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 
 import { parseFile, isSupported, parseContent } from './src/parser.js';
-import { diffTrees } from './src/differ.js';
+import { diffTrees, secretMatchPath } from './src/differ.js';
+import { documentKeysOf, withDocumentKeys } from './src/documents.js';
 import { startWatcher } from './src/watcher.js';
 import {
   renderChanges,
   renderDiff,
   renderError,
   renderInfo,
+  renderNote,
   renderWarn,
   renderPolicyFindings,
   maskChangeEvent,
+  maskSensitiveValue,
 } from './src/renderer.js';
+import { deliverPrComment, renderPrComment } from './src/pr-comment.js';
+import {
+  diffTerraformPlan,
+  formatPlanSummary,
+  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 { evaluatePolicies, highestSeverity, listPolicyPacks } from './src/policy.js';
+import {
+  evaluatePolicies,
+  highestSeverity,
+  listPolicyPacks,
+  addPolicyPackFromPackage,
+} from './src/policy.js';
 import { testPolicyFixture } from './src/policy-test.js';
 import {
   loadRcConfig,
@@ -38,6 +55,17 @@ const PKG = JSON.parse(
 );
 
 const SNAPSHOT_DIR = '.flecto-snapshots';
+const FAIL_ON_CHOICES = ['changed', 'added', 'removed', 'policy', 'error', 'warn'];
+
+/**
+ * `flecto plan` defaults. A plan is expected to contain changes — that is the
+ * point of running one — so gating on `changed` the way `ci` does would fail
+ * every non-empty plan. The `terraform` pack reserves `error` for the patterns
+ * that genuinely should block a merge and leaves cost and sizing advice at
+ * `warn`, so `error` is the default gate; `--fail-on policy` or `warn` widens it.
+ */
+const PLAN_DEFAULT_FAIL_ON = 'error';
+const PLAN_DEFAULT_POLICIES = 'terraform';
 
 function snapshotIdForPath(absPath) {
   const normalized = absPath.replaceAll('\\', '/');
@@ -60,14 +88,27 @@ function snapshotHistoryPathForFile(absPath) {
   return path;
 }
 
-function hasSnapshotHistoryForFile(absPath) {
-  if (!existsSync(SNAPSHOT_DIR)) return false;
-  const id = snapshotIdForPath(absPath);
-  return readdirSync(SNAPSHOT_DIR).some((name) => new RegExp(`^${id}\\.\\d+\\.json$`).test(name));
+/**
+ * Snapshot ids that already have at least one timestamped history entry.
+ *
+ * Listed once per run and threaded through the snapshot loop: probing the
+ * directory per file made writing N baselines cost N listings of O(N) entries
+ * each, which is quadratic in the number of tracked files.
+ * @returns {Set<string>}
+ */
+function snapshotIdsWithHistory() {
+  /** @type {Set<string>} */
+  const ids = new Set();
+  if (!existsSync(SNAPSHOT_DIR)) return ids;
+  for (const name of readdirSync(SNAPSHOT_DIR)) {
+    const match = /^([a-f0-9]{16})\.\d+\.json$/.exec(name);
+    if (match) ids.add(match[1]);
+  }
+  return ids;
 }
 
-function preserveLegacySnapshotForHistory(absPath, snapshotPath) {
-  if (!existsSync(snapshotPath) || hasSnapshotHistoryForFile(absPath)) return;
+function preserveLegacySnapshotForHistory(absPath, snapshotPath, idsWithHistory) {
+  if (!existsSync(snapshotPath) || idsWithHistory.has(snapshotIdForPath(absPath))) return;
 
   const legacy = JSON.parse(readFileSync(snapshotPath, 'utf8'));
   writeFileSync(
@@ -75,6 +116,7 @@ function preserveLegacySnapshotForHistory(absPath, snapshotPath) {
     JSON.stringify({
       file: legacy.file ?? absPath,
       state: legacy.state ?? legacy,
+      ...(Array.isArray(legacy.documents) ? { documents: legacy.documents } : {}),
       createdAt: legacy.createdAt ?? statSync(snapshotPath).mtime.toISOString(),
     }, null, 2),
     'utf8',
@@ -95,7 +137,7 @@ function readLocalSnapshotHistory() {
   return snapshotEntries.map((entry) => {
     const path = resolve(SNAPSHOT_DIR, entry.name);
     const snapshot = JSON.parse(readFileSync(path, 'utf8'));
-    const state = snapshot?.state ?? snapshot;
+    const state = restoreSnapshotDocumentKeys(snapshot?.state ?? snapshot, snapshot);
     if (typeof snapshot?.file !== 'string') {
       throw new Error(`Invalid snapshot file: ${path}`);
     }
@@ -119,11 +161,18 @@ function summarizeSnapshotHistory(snapshots, limit, diffOpts = {}) {
   for (const records of byFile.values()) {
     records.sort((a, b) => new Date(a.createdAt) - new Date(b.createdAt));
     for (let index = 0; index < records.length; index += 1) {
+      // The previous snapshot of the *same file* is the baseline, and it may
+      // fall outside the limit window — so carry it here rather than letting
+      // callers infer it from the truncated result.
+      const previous = index === 0 ? null : records[index - 1];
+      const changes = previous
+        ? diffTrees(previous.state, records[index].state, diffOpts)
+        : [];
       summaries.push({
         ...records[index],
-        changeCount: index === 0
-          ? 0
-          : diffTrees(records[index - 1].state, records[index].state, diffOpts).length,
+        previousCreatedAt: previous ? previous.createdAt : null,
+        changes,
+        changeCount: changes.length,
       });
     }
   }
@@ -139,6 +188,18 @@ function parseCsv(value) {
   return String(value).split(',').map((s) => s.trim()).filter(Boolean);
 }
 
+function parseFailOn(value) {
+  const rules = parseCsv(value);
+  const invalid = rules.filter((rule) => !FAIL_ON_CHOICES.includes(rule));
+  if (invalid.length > 0) {
+    throw new Error(
+      `--fail-on contains unknown trigger${invalid.length === 1 ? '' : 's'}: ${invalid.join(', ')}. `
+      + `Valid triggers: ${FAIL_ON_CHOICES.join(', ')}`,
+    );
+  }
+  return new Set(rules);
+}
+
 function parseHeaders(headerList) {
   const webhookHeaders = {};
   if (!Array.isArray(headerList)) return webhookHeaders;
@@ -188,6 +249,32 @@ function maybeMaskChanges(events, maskSecrets) {
   return events.map(maskChangeEvent);
 }
 
+/**
+ * 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
+ * @returns {import('./src/policy.js').PolicyFinding[]}
+ */
+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) };
+  });
+}
+
 async function resolveTargetFiles(cliFiles, rcConfig) {
   if (cliFiles && cliFiles.length > 0) {
     const direct = [];
@@ -212,14 +299,62 @@ async function resolveTargetFiles(cliFiles, rcConfig) {
 
   return resolveFiles({
     cwd: process.cwd(),
-    files: rcConfig?.files ?? rcConfig?.include ?? [],
+    files: rcConfig?.files ?? [],
+    include: rcConfig?.include ?? [],
     exclude: rcConfig?.exclude ?? [],
   });
 }
 
+/**
+ * Restore the parser's multi-document signal onto a state read back from a
+ * snapshot. A snapshot is plain JSON, so the in-memory marking is gone; a
+ * snapshot written before this field existed simply leaves the provenance
+ * unknown, which is what it is.
+ * @param {unknown} state
+ * @param {unknown} snapshot the parsed snapshot envelope
+ * @returns {unknown} the same state
+ */
+function restoreSnapshotDocumentKeys(state, snapshot) {
+  const documents = /** @type {{ documents?: unknown }} */ (snapshot)?.documents;
+  if (!Array.isArray(documents)) return state;
+  return withDocumentKeys(state, documents.map(String));
+}
+
 function readSnapshotStateFromFile(snapshotPath) {
   const snap = JSON.parse(readFileSync(snapshotPath, 'utf8'));
-  return snap?.state ?? snap;
+  return restoreSnapshotDocumentKeys(snap?.state ?? snap, snap);
+}
+
+/**
+ * Resolve a file to a path relative to its git repository root.
+ *
+ * `git show <rev>:<path>` interprets <path> from the repository root, so a
+ * cwd-relative path breaks whenever Flecto runs from a subdirectory. Both sides
+ * are canonicalized first: process.cwd() reports a symlink-resolved path while
+ * CLI arguments keep the symlinks the user typed, and on macOS /tmp and
+ * /var/folders are symlinks, so comparing the two forms directly misresolves.
+ * @param {string} filePath
+ * @returns {string} POSIX-style path relative to the repository root
+ */
+function gitRepoRelativePath(filePath) {
+  const top = execFileSync('git', ['-C', dirname(filePath), 'rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+  }).trim();
+  return relative(canonicalPath(top), canonicalPath(filePath)).replaceAll('\\', '/');
+}
+
+/**
+ * Resolve symlinks where possible, falling back to the input when the path does
+ * not exist on disk.
+ * @param {string} path
+ * @returns {string}
+ */
+function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
 }
 
 function readSnapshotStateFromRef(filePath, snapshotRef) {
@@ -229,7 +364,7 @@ function readSnapshotStateFromRef(filePath, snapshotRef) {
     return readSnapshotStateFromFile(maybePath);
   }
 
-  const rel = relative(process.cwd(), filePath).replaceAll('\\', '/');
+  const rel = gitRepoRelativePath(filePath);
   const raw = execFileSync('git', ['show', `${snapshotRef}:${rel}`], { encoding: 'utf8' });
   return parseContent(filePath, raw);
 }
@@ -291,6 +426,26 @@ function printCiOutput(results, format) {
   }
 }
 
+/**
+ * Deliver the sticky PR comment without ever changing the CI outcome: a
+ * delivery problem warns, and the exit code stays with the diff/policy result.
+ * @param {string} body
+ * @param {boolean} enabled
+ */
+async function deliverPrCommentSafely(body, enabled) {
+  if (!enabled) return;
+  try {
+    const result = await deliverPrComment(body, { enabled: true });
+    if (result.posted) {
+      renderNote(`PR comment ${result.action}${result.url ? `: ${result.url}` : ''}`);
+      return;
+    }
+    renderWarn(`Could not post the PR comment: ${result.reason}`);
+  } catch (err) {
+    renderWarn(`Could not post the PR comment: ${err.message}`);
+  }
+}
+
 program
   .name('flecto')
   .description('Flecto — semantic config watcher for meaningful structured file changes')
@@ -309,6 +464,7 @@ program
     acc.push(v);
     return acc;
   }, [])
+  .option('--webhook-format <service>', `Webhook payload format: ${WEBHOOK_FORMAT_CHOICES.join(' | ')}`)
   .option('--delivery-mode <mode>', 'Alert delivery mode: best-effort | at-least-once', 'best-effort')
   .option('--on-alert-failure <mode>', 'Alert failure behavior: warn | exit | retry', 'warn')
   .option('--webhook-timeout <ms>', 'Webhook timeout in ms', '5000')
@@ -343,10 +499,12 @@ program
       validateMode(mode);
       const maskSecrets = Boolean(effective.maskSecrets);
       const maskSecretsWebhooks = Boolean(effective.maskSecretsWebhooks);
+      const webhookFormat = resolveWebhookFormat(effective.webhookFormat, effective.webhook);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
       if (effective.snapshot) {
         mkdirSync(SNAPSHOT_DIR, { recursive: true });
+        const idsWithHistory = snapshotIdsWithHistory();
         let written = 0;
         for (const filepath of targets) {
           if (!existsSync(filepath)) {
@@ -359,10 +517,21 @@ program
           }
           const state = parseFile(filepath);
           const snapshotPath = snapshotPathForFile(filepath);
-          preserveLegacySnapshotForHistory(filepath, snapshotPath);
-          const snapshot = { file: filepath, state, createdAt: new Date().toISOString() };
+          preserveLegacySnapshotForHistory(filepath, snapshotPath, idsWithHistory);
+          // Only a multi-document file records `documents`, so an ordinary
+          // snapshot is byte-for-byte what it was before this field existed.
+          const documents = documentKeysOf(state) ?? [];
+          const snapshot = {
+            file: filepath,
+            state,
+            ...(documents.length > 0 ? { documents: [...documents] } : {}),
+            createdAt: new Date().toISOString(),
+          };
           writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf8');
           writeFileSync(snapshotHistoryPathForFile(filepath), JSON.stringify(snapshot, null, 2), 'utf8');
+          // Keep the set in step with what this run has written, so a repeated
+          // target behaves exactly as it did when the check hit the disk.
+          idsWithHistory.add(snapshotIdForPath(filepath));
           console.log(chalk.green(`✓ Snapshot saved: ${snapshotPath}`));
           written += 1;
         }
@@ -393,6 +562,33 @@ program
       }
 
       const watchers = [];
+      let closing = false;
+      const closeAll = async (exitCode) => {
+        if (closing) return;
+        closing = true;
+        await Promise.all(watchers.map((w) => w.close()));
+        if (exitCode === 0) {
+          console.log(chalk.dim('\nflecto stopped.'));
+        }
+        process.exit(exitCode);
+      };
+      const alertOptions = {
+        command: effective.command,
+        webhook: effective.webhook,
+        webhookHeaders,
+        webhookTimeoutMs: parseInt(String(effective.webhookTimeout ?? '5000'), 10),
+        webhookRetries: parseInt(String(effective.webhookRetries ?? '2'), 10),
+        webhookFormat,
+        deliveryMode: effective.deliveryMode,
+        onAlertFailure: effective.onAlertFailure,
+      };
+      const deliverAlert = async (envelope) => {
+        const result = await fireAlerts(alertOptions, envelope);
+        if (!result.ok && effective.onAlertFailure === 'exit') {
+          await closeAll(1);
+        }
+      };
+
       for (const filepath of targets) {
         if (!existsSync(filepath)) {
           renderWarn(`Skipping missing file: ${filepath}`);
@@ -425,24 +621,20 @@ program
                 renderError(`policy evaluation failed: ${err.message}`);
                 process.exit(1);
               }
-              renderPolicyFindings(policyFindings);
+              renderPolicyFindings(maybeMaskFindings(policyFindings, event.events, maskSecrets));
               if (effective.command || effective.webhook) {
                 const outboundChanges = maybeMaskChanges(event.events, maskSecretsWebhooks);
                 const envelope = createEnvelope({
                   source: 'watch',
                   file: event.filepath,
                   changes: outboundChanges,
-                  policies: policyFindings,
+                  policies: maybeMaskFindings(
+                    policyFindings,
+                    event.events,
+                    maskSecretsWebhooks,
+                  ),
                 });
-                await fireAlerts({
-                  command: effective.command,
-                  webhook: effective.webhook,
-                  webhookHeaders,
-                  webhookTimeoutMs: parseInt(String(effective.webhookTimeout ?? '5000'), 10),
-                  webhookRetries: parseInt(String(effective.webhookRetries ?? '2'), 10),
-                  deliveryMode: effective.deliveryMode,
-                  onAlertFailure: effective.onAlertFailure,
-                }, envelope);
+                await deliverAlert(envelope);
               }
             } else {
               renderInfo(`[lifecycle] ${event.filepath}: ${event.lifecycle.type} - ${event.lifecycle.message}`);
@@ -452,15 +644,7 @@ program
                   file: event.filepath,
                   lifecycle: event.lifecycle,
                 });
-                await fireAlerts({
-                  command: effective.command,
-                  webhook: effective.webhook,
-                  webhookHeaders,
-                  webhookTimeoutMs: parseInt(String(effective.webhookTimeout ?? '5000'), 10),
-                  webhookRetries: parseInt(String(effective.webhookRetries ?? '2'), 10),
-                  deliveryMode: effective.deliveryMode,
-                  onAlertFailure: effective.onAlertFailure,
-                }, envelope);
+                await deliverAlert(envelope);
               }
             }
           }
@@ -473,13 +657,6 @@ program
       }
       renderInfo('Press Ctrl+C to stop.\n');
 
-      const closeAll = async (exitCode) => {
-        await Promise.all(watchers.map((w) => w.close()));
-        if (exitCode === 0) {
-          console.log(chalk.dim('\nflecto stopped.'));
-        }
-        process.exit(exitCode);
-      };
       process.on('SIGINT', () => void closeAll(0));
       process.on('SIGTERM', () => void closeAll(0));
     } catch (err) {
@@ -538,12 +715,104 @@ program
     }
   });
 
+program
+  .command('report [files...]')
+  .description('Render local snapshot history as a self-contained HTML report')
+  .option('-o, --output <path>', 'Write the report to this path', 'flecto-report.html')
+  .option('-l, --limit <n>', 'Number of recent snapshots to include', '10')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
+  .option('--policies <ids>', 'Comma-separated policy pack ids (default: default)')
+  .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)
+  .option('--mask-secrets', 'Mask secret-like values in the report', false)
+  .action(async (files, opts, command) => {
+    try {
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
+
+      const limit = Number.parseInt(String(effective.limit ?? '10'), 10);
+      if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error('--limit must be a positive integer');
+      }
+      const ignorePaths = parseCsv(effective.ignore);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const outputPath = resolve(String(effective.output ?? 'flecto-report.html'));
+
+      // Same snapshot source, filtering, and errors as `flecto history` — this
+      // command only changes how that history is rendered.
+      const allSnapshots = readLocalSnapshotHistory();
+      let snapshots = allSnapshots;
+      if (files.length > 0) {
+        const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
+        snapshots = snapshots.filter((snapshot) => targets.has(resolve(snapshot.file)));
+      }
+
+      const summaries = summarizeSnapshotHistory(snapshots, limit, dOpts);
+      if (summaries.length === 0) {
+        if (files.length > 0 && allSnapshots.length > 0) {
+          throw new Error(
+            'No local snapshots matched the given files. Omit files to report on all saved snapshot history.',
+          );
+        }
+        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+      }
+
+      const reportSnapshots = [];
+      for (const summary of summaries) {
+        // Policies run on the unmasked events: masking first would hide the
+        // very values the secret rules match on. Redaction happens after, on
+        // everything that reaches the page.
+        const findings = await evaluatePolicies(summary.changes, {
+          cwd: process.cwd(),
+          file: summary.file,
+          profile: profile ?? null,
+          source: 'diff',
+          policies: packIds,
+          plugins,
+          severityRemap,
+        });
+        reportSnapshots.push({
+          file: summary.file,
+          createdAt: summary.createdAt,
+          previousCreatedAt: summary.previousCreatedAt,
+          changeCount: summary.changeCount,
+          changes: maybeMaskChanges(summary.changes, maskSecrets),
+          policies: maybeMaskFindings(findings, summary.changes, maskSecrets),
+        });
+      }
+
+      const html = renderReportHtml({
+        snapshots: reportSnapshots,
+        generatedAt: new Date().toISOString(),
+        cwd: process.cwd(),
+        version: PKG.version,
+        limit,
+        maskSecrets,
+      });
+      mkdirSync(dirname(outputPath), { recursive: true });
+      writeFileSync(outputPath, html, 'utf8');
+      console.log(chalk.green(
+        `✓ Report written: ${outputPath} (${summaries.length} snapshot${summaries.length === 1 ? '' : 's'})`,
+      ));
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 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('--format <type>', 'Output format: json | ndjson | github-annotations', 'json')
+  .option('--format <type>', 'Output format: json | ndjson | github-annotations | pr-comment', 'json')
+  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs GITHUB_TOKEN + PR context)', false)
   .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', 'changed,policy,error')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore')
   .option('--policies <ids>', 'Comma-separated policy pack ids')
@@ -565,10 +834,14 @@ program
       }
 
       const ignorePaths = parseCsv(effective.ignore);
-      const failOn = new Set(parseCsv(effective.failOn ?? 'changed,policy,error'));
+      const failOn = parseFailOn(effective.failOn ?? 'changed,policy,error');
       const format = String(effective.format ?? 'json');
-      if (!['json', 'ndjson', 'github-annotations'].includes(format)) {
-        throw new Error('--format must be json, ndjson, or github-annotations');
+      if (!['json', 'ndjson', 'github-annotations', 'pr-comment'].includes(format)) {
+        throw new Error('--format must be json, ndjson, github-annotations, or pr-comment');
+      }
+      const prCommentPost = Boolean(effective.prCommentPost);
+      if (prCommentPost && format !== 'pr-comment') {
+        renderWarn('Ignoring --pr-comment-post: it only applies to --format pr-comment.');
       }
       const maskSecrets = Boolean(effective.maskSecrets);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
@@ -608,13 +881,14 @@ program
           severityRemap,
         });
         const outboundChanges = maybeMaskChanges(events, maskSecrets);
+        const outboundFindings = maybeMaskFindings(policyFindings, events, maskSecrets);
         const envelope = createEnvelope({
           source: 'ci',
           file: filepath,
           changes: outboundChanges,
-          policies: policyFindings,
+          policies: outboundFindings,
         });
-        results.push({ file: filepath, envelope, policies: policyFindings });
+        results.push({ file: filepath, envelope, policies: outboundFindings });
         diffed += 1;
 
         if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policyFindings, failOn)) {
@@ -629,7 +903,203 @@ program
         );
       }
 
-      printCiOutput(results, format);
+      if (format === 'pr-comment') {
+        const body = renderPrComment(results, { cwd: process.cwd(), failed: shouldFail });
+        console.log(body);
+        await deliverPrCommentSafely(body, prCommentPost);
+      } else {
+        printCiOutput(results, format);
+      }
+      process.exit(shouldFail ? 1 : 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')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--format <type>', 'Output format: human | json | ndjson | github-annotations | pr-comment', 'human')
+  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs GITHUB_TOKEN + PR context)', false)
+  .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', PLAN_DEFAULT_FAIL_ON)
+  .option('--ignore <keys>', 'Comma-separated key paths to ignore, e.g. "**.tags_all,**.#action"')
+  .option('--policies <ids>', `Comma-separated policy pack ids (default: ${PLAN_DEFAULT_POLICIES})`)
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--mask-secrets', 'Also mask Flecto-detected secret-like values (Terraform-sensitive values are always redacted)', false)
+  .action(async (planFiles, opts, command) => {
+    try {
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      // A plan carries Terraform-shaped paths, so the config-file packs are not
+      // the useful default here; `terraform` is. An explicit --policies or a
+      // .flectorc entry still wins.
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(
+        effective.policies === undefined
+          ? { ...effective, policies: PLAN_DEFAULT_POLICIES }
+          : effective,
+      );
+
+      const ignorePaths = parseCsv(effective.ignore);
+      const failOn = new Set(parseCsv(effective.failOn ?? PLAN_DEFAULT_FAIL_ON));
+      const format = String(effective.format ?? 'human');
+      if (!['human', 'json', 'ndjson', 'github-annotations', 'pr-comment'].includes(format)) {
+        throw new Error('--format must be human, json, ndjson, github-annotations, or pr-comment');
+      }
+      const prCommentPost = Boolean(effective.prCommentPost);
+      if (prCommentPost && format !== 'pr-comment') {
+        renderWarn('Ignoring --pr-comment-post: it only applies to --format pr-comment.');
+      }
+      const maskSecrets = Boolean(effective.maskSecrets);
+
+      /** @type {any[]} */
+      const results = [];
+      let shouldFail = false;
+
+      for (const planFile of planFiles) {
+        const filepath = resolve(planFile);
+        if (!existsSync(filepath)) {
+          throw new Error(`File not found: ${filepath}`);
+        }
+        const plan = readTerraformPlanFile(filepath);
+        const { changes, summary, formatVersion, terraformVersion, warnings } =
+          diffTerraformPlan(plan, { ignorePaths });
+        for (const warning of warnings) renderWarn(warning);
+
+        // Terraform-sensitive values were already replaced during conversion,
+        // so policies never see them. --mask-secrets adds Flecto's own
+        // value-shaped detection on top, for credentials Terraform did not mark.
+        const policyFindings = await evaluatePolicies(changes, {
+          cwd: process.cwd(),
+          file: filepath,
+          profile: profile ?? null,
+          source: 'ci',
+          policies: packIds,
+          plugins,
+          severityRemap,
+        });
+        const outboundChanges = maybeMaskChanges(changes, maskSecrets);
+        const envelope = createEnvelope({
+          source: 'ci',
+          file: filepath,
+          changes: outboundChanges,
+          policies: maybeMaskFindings(policyFindings, maskSecrets),
+        });
+        results.push({ file: filepath, envelope, policies: envelope.policies });
+
+        if (format === 'human') {
+          const version = [
+            formatVersion ? `plan format ${formatVersion}` : null,
+            terraformVersion ? `terraform ${terraformVersion}` : null,
+          ].filter(Boolean).join(', ');
+          renderInfo(`${filepath}${version ? ` — ${version}` : ''}`);
+          renderInfo(formatPlanSummary(summary));
+          renderDiff(filepath, outboundChanges, { maskSecrets, baseline: 'the current state' });
+          renderPolicyFindings(envelope.policies);
+        }
+
+        if (shouldFailFromChanges(changes, failOn) || shouldFailFromPolicy(policyFindings, failOn)) {
+          shouldFail = true;
+        }
+      }
+
+      if (format === 'pr-comment') {
+        const body = renderPrComment(results, { cwd: process.cwd(), failed: shouldFail });
+        console.log(body);
+        await deliverPrCommentSafely(body, prCommentPost);
+      } else if (format !== 'human') {
+        printCiOutput(results, format);
+      }
+      process.exit(shouldFail ? 1 : 0);
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('compare <fileA> <fileB>')
+  .description('Diff two config files against each other (fileA is the baseline)')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--format <type>', 'Output format: human | json | ndjson | github-annotations', 'human')
+  .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', 'changed,added,removed,policy,error')
+  .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)
+  .option('--mask-secrets', 'Mask secret-like values in output', false)
+  .action(async (fileA, fileB, opts, command) => {
+    try {
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
+
+      const ignorePaths = parseCsv(effective.ignore);
+      const failOn = parseFailOn(effective.failOn ?? 'changed,added,removed,policy,error');
+      const format = String(effective.format ?? 'human');
+      if (!['human', 'json', 'ndjson', 'github-annotations'].includes(format)) {
+        throw new Error('--format must be human, json, ndjson, or github-annotations');
+      }
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
+
+      const baselinePath = resolve(fileA);
+      const targetPath = resolve(fileB);
+      // Both sides are named explicitly, so a missing one is an error rather
+      // than the skip-and-warn `ci` applies to expanded globs.
+      for (const filepath of [baselinePath, targetPath]) {
+        if (!existsSync(filepath)) {
+          throw new Error(`File not found: ${filepath}`);
+        }
+      }
+
+      // fileA is the baseline: "removed" is present only in fileA, "added" only
+      // in fileB. Every format parses to a plain tree, so the two sides need not
+      // share one — parseFile rejects unsupported extensions with the same
+      // message every other command uses.
+      const before = parseFile(baselinePath);
+      const after = parseFile(targetPath);
+      const events = diffTrees(before, after, dOpts);
+      const policyFindings = await evaluatePolicies(events, {
+        cwd: process.cwd(),
+        file: targetPath,
+        profile: profile ?? null,
+        source: 'diff',
+        policies: packIds,
+        plugins,
+        severityRemap,
+      });
+      const outboundFindings = maybeMaskFindings(policyFindings, events, maskSecrets);
+
+      if (format === 'human') {
+        if (events.length > 0) {
+          renderInfo('"+" exists only in the compared file, "-" only in the baseline, "~" differs');
+        }
+        renderDiff(targetPath, events, { maskSecrets, baseline: baselinePath });
+        renderPolicyFindings(outboundFindings);
+      } else {
+        const envelope = createEnvelope({
+          source: 'diff',
+          file: targetPath,
+          changes: maybeMaskChanges(events, maskSecrets),
+          policies: outboundFindings,
+        });
+        // Same envelope and printer as `ci`, so machine consumers see one shape.
+        // `baseline` rides on the result wrapper rather than the envelope, which
+        // is closed by schemas/flecto-envelope-2.0.json.
+        printCiOutput(
+          [{ file: targetPath, baseline: baselinePath, envelope, policies: outboundFindings }],
+          format,
+        );
+      }
+
+      const shouldFail = shouldFailFromChanges(events, failOn)
+        || shouldFailFromPolicy(policyFindings, failOn);
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
       renderError(err.message);
@@ -671,10 +1141,10 @@ program
         }
 
         console.log('Resolution order: policies/<id>.json, .yaml, .yml, then built-in packs.');
-        console.log('id\tsource path\trules\toverrides builtin');
+        console.log('id\tsource path\trules\toverrides builtin\tpackage');
         for (const pack of packs) {
           console.log(
-            `${pack.id}\t${pack.sourcePath}\t${pack.ruleCount}\t${pack.overridesBuiltin ? 'yes' : 'no'}`,
+            `${pack.id}\t${pack.sourcePath}\t${pack.ruleCount}\t${pack.overridesBuiltin ? 'yes' : 'no'}\t${pack.package ?? '-'}`,
           );
         }
       } catch (err) {
@@ -682,14 +1152,62 @@ program
         process.exit(1);
       }
     });
+
+  policies
+    .command('add <name>')
+    .description('Install a policy pack from an installed flecto-pack-* npm package')
+    .option('--force', 'Overwrite an existing local pack with the same id')
+    .action((name, opts) => {
+      try {
+        const added = addPolicyPackFromPackage(name, {
+          cwd: process.cwd(),
+          force: Boolean(opts.force),
+        });
+        const version = added.packageVersion ? `@${added.packageVersion}` : '';
+        const verb = added.overwritten ? 'Updated' : 'Added';
+        renderInfo(
+          `${verb} policy pack "${added.id}" from ${added.packageName}${version} `
+          + `→ ${relative(process.cwd(), added.targetPath)} `
+          + `(${added.ruleCount} rule${added.ruleCount === 1 ? '' : 's'})`,
+        );
+        if (added.overridesBuiltin) {
+          renderWarn(`Pack "${added.id}" now overrides the built-in pack of the same id.`);
+        }
+        for (const path of added.shadowed) {
+          renderWarn(`${relative(process.cwd(), path)} is no longer used: ${added.id}.json wins.`);
+        }
+        if (added.shipsCode) {
+          renderInfo(
+            `${added.packageName} also ships JavaScript. It was ignored: only the declarative `
+            + 'pack file is read, and no package code is ever imported or run.',
+          );
+        }
+        renderInfo(`Activate it with: flecto ci <files> --policies ${added.id}`);
+      } catch (err) {
+        renderError(err.message);
+        process.exit(1);
+      }
+    });
 }
 
 program
   .command('init')
-  .description('Create starter .flectorc configuration')
+  .description('Create starter .flectorc configuration from detected stack signals')
   .action(() => {
-    const path = initRcFile(process.cwd());
+    const { path, created, detection } = initRcFile(process.cwd());
+    if (!created) {
+      renderWarn(`Config already exists: ${path} (left unchanged)`);
+      return;
+    }
     renderInfo(`Initialized config: ${path}`);
+    if (detection.signals.length === 0) {
+      renderInfo('No stack signals detected — wrote the generic starter config.');
+      return;
+    }
+    for (const signal of detection.signals) {
+      renderInfo(signal.summary);
+    }
+    renderInfo(`Policy packs: ${detection.packs.join(', ')}`);
   });
 
 program