flecto 3.0.2 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,256 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-23
+
+**A security release.** Every breaking change below exists because a pull
+request could otherwise make `flecto ci` report a clean run on a change that was
+not clean. If you run Flecto on untrusted pull requests, upgrading is not
+optional.
+
+See **[docs/migrating-to-4.md](docs/migrating-to-4.md)** for what to change, and
+the [security advisories](https://github.com/myselfsiddharth/Flecto/security/advisories)
+for what was wrong.
+
+### Breaking
+
+- `snapshotRef` and `snapshotFile` declared in `.flectorc` are refused
+  (`FLECTO_ALLOW_RC_BASELINE=1` opts back in).
+- `--snapshot-ref` takes a git revision. A bare snapshot filename needs
+  `--snapshot-file`, or a `./` prefix. The bundled `flecto-ci` Action gains a
+  `snapshot-file:` input.
+- Policy-pack regular expressions outside `src/packs/` are compiled with RE2:
+  lookaround, backreferences, `\uXXXX` escapes, and `v`-flag set subtraction now
+  fail at load, and a few constructs match differently.
+- `.flecto-queue/` is keyed by destination. A 3.x backlog is kept but not
+  auto-delivered.
+- The `--command` spill file is deleted when the command exits, so a script must
+  read `FLECTO_CHANGES_FILE` while the command is still running.
+- Flecto now requires git 2.24 or newer.
+
+### Added
+
+- **`flecto explain` and `ci --explain`: opt-in, advisory narration of a diff by
+  a model you configure** ([#143]). `pool_size: 5 → 20` is mechanical; "this
+  quadruples connections per replica, so check `max_connections`" is judgment,
+  and it is what a reviewer wants at 2 AM. Bring your own key: `anthropic`
+  (Messages API, default model `claude-opus-5`) or `openai`, which covers any
+  OpenAI-compatible server, including a local one. Each is a single `fetch`, so
+  no vendor SDK and no new dependency.
+
+  The constraints are the feature. **Only the masked semantic diff is sent**,
+  masked unconditionally while the payload is built, never file contents, with
+  encrypted values as sentinels. `--dry-run` / `--explain-dry-run` print the exact
+  request and send nothing. **It never touches an exit code**: `ci` decides the
+  gate first, and every failure (no provider, over budget, timeout, HTTP error,
+  refusal) is a warning. `ci`'s stdout is byte-identical except under
+  `--format pr-comment`, where the narration goes in its own labeled section,
+  fenced so links, images, mentions, and HTML render as text. **The operator
+  configures it and the repository cannot**: `explain*` options in `.flectorc`
+  are refused, provider, endpoint, and key come only from the CLI and
+  `FLECTO_EXPLAIN_*` variables, redirects are refused rather than forwarding
+  `x-api-key`, and `FLECTO_EXPLAIN=0` is a runner-wide kill switch. **Cost is
+  stated before the call**, with estimated input tokens and the output cap.
+  Diffs over an input budget are skipped, not truncated. Identical requests are
+  served from a cache outside the repository, keyed with an HMAC of the API key
+  so a pull request cannot plant an entry. See [docs/explain.md](docs/explain.md).
+
+- **`flecto mcp` — a read-only Model Context Protocol server over stdio**
+  ([#140]). An agent asked to debug a config incident no longer has to read a
+  two-thousand-line manifest into its context to learn that `pool_size` doubled;
+  Flecto already computes that small answer and now hands it over as a structured
+  tool result. Three read-only tools — `flecto_diff`, `flecto_check`, and
+  `flecto_explain` — each run the same `ci` path a pull request triggers and
+  return the JSON envelope.
+
+  The security posture is inherited from `ci` by construction: the tools can only
+  reach what `ci` reaches (no `--command`, no writes, no webhooks, no plugins —
+  the last enforced regardless of `FLECTO_ALLOW_RC_PLUGINS`), no tool argument is
+  ever parsed as a CLI option, tool-argument paths — including a `ref` that names
+  a snapshot file — are contained before anything spawns, and results are
+  bounded. **Secrets are masked by default here, inverted from the CLI**,
+  because the consumer is a model context that is transmitted and often logged;
+  `mask: false` is an explicit, documented opt-out. Adds no runtime dependency —
+  the stdio JSON-RPC framing is spoken directly. See [docs/mcp.md](docs/mcp.md).
+
+- **`flecto lsp`: findings and semantic changes as editor diagnostics while a
+  config file is being edited** ([#142]). It's a Language Server Protocol server
+  over stdio, compared against `HEAD` by default (`--snapshot-ref`,
+  `--snapshot-store`), and it **agrees with the merge gate**: it uses the same
+  `.flectorc`, packs, `severityRemap`, scope (`files`/`include`/`exclude`), inline
+  suppressions, and `--baseline` file as `ci`. A suppression missing its reason
+  is the error CI fails on. The hard part the issue named, positions, is a new
+  module (`src/positions.js`) that maps a diff path back into the source text for
+  YAML (including anchors, merge keys, and multi-document manifests), JSON/JSONC,
+  dotenv, INI, and TOML. A position is used only where an independent scan of
+  the text agrees with the parsed tree. Anything else anchors at the nearest
+  verified ancestor, never at a guess. Across every fixture and example in the
+  repository, no exact position lands on the wrong key. Analyses run in a worker
+  thread, debounced, cancelled by a newer edit, and stopped at `--timeout`, so a
+  catastrophic pack regex costs one warning instead of a wedged server.
+  **Plugins declared in `.flectorc` are never loaded**, even with
+  `FLECTO_ALLOW_RC_PLUGINS=1`, since opening a repository in an editor is the
+  untrusted-PR threat model. `--plugins` must be absolute paths. See
+  [docs/editor.md](docs/editor.md).
+
+### Security
+
+- **BREAKING: `snapshotRef` declared in `.flectorc` is refused** ([#121]). The
+  baseline decides what counts as a change, so a pull request that sets it
+  decides the verdict: a committed `{"defaults": {"snapshotRef": "HEAD"}}`
+  compared every file against the pull request's own tip and exited 0 on a
+  config that disabled TLS. Pass `--snapshot-ref` on the command line — the form
+  every example and the shipped Action already use — or set
+  `FLECTO_ALLOW_RC_BASELINE=1` if the rc file is trusted.
+- **`--snapshot-file <path>` is added, and `--snapshot-ref` is a git revision**
+  ([#121]). Overloading one flag with both is what let an attacker-committed
+  file stand in for the operator's baseline. **This is breaking**: only a value
+  that is unambiguously a path — absolute, or starting `./` or `../`, shapes
+  git's ref format cannot produce — is still read as a file by
+  `--snapshot-ref`. A bare `--snapshot-ref snapshots/base.json` now fails and
+  says to use `--snapshot-file`. The bundled `flecto-ci` Action gains a
+  `snapshot-file:` input for the same reason.
+  When git is missing, too old, or not looking at a repository, Flecto refuses
+  rather than falling back to a file.
+- **A baseline ref can no longer be crafted into a file write, a shadowed
+  baseline, or an empty diff** ([#121]). Three shapes, one property:
+  `--output=pwned` was read by git as an *option* and wrote a file while the
+  emptied read made every key look `added` so the default `--fail-on` never
+  fired; a committed file named after the operator's ref (`HEAD~1`, the shipped
+  Action's default) shadowed the baseline with one the attacker wrote; and a
+  commit range such as `HEAD:..` succeeded while printing nothing, for the same
+  silent pass. Refs now resolve through `git rev-parse --verify <ref>^{commit}`,
+  revision before file, and `git show` receives the resolved SHA.
+- **BREAKING: pack-supplied regular expressions are compiled with RE2**
+  ([#121]). A policy pack is attacker input on an untrusted pull request --
+  `policies/*.json` is committed and `.flectorc` selects which packs run -- and
+  Node's engine backtracks, so `^(a+)+$` took **97 seconds** against a 44-character
+  value and grew exponentially. No in-process timeout could help: the
+  backtracking happens inside one uninterruptible call into the engine. Packs
+  outside `src/packs/` now use a linear-time engine (`re2js`, pure JS, no native
+  build), which answers the same pattern in 3 ms. The packs Flecto ships keep
+  the native engine. RE2 does not support lookaround, backreferences, `\uXXXX`
+  escapes, or `v`-flag set subtraction, so a pack using them now fails to load
+  with a message naming the rule; a few constructs also *match* differently, and
+  [docs/policy-packs.md](docs/policy-packs.md#regular-expressions-in-packs)
+  tables both sets.
+- **A pack regex with the `g` flag no longer fires on alternate files.** Packs
+  are cached and shared across every file in a run, and a `g` regex carries a
+  mutable `lastIndex` that `.test()` advances, so such a rule matched every
+  other value it saw.
+### Added
+
+- **`flecto-drift`: compare a declared config file against what is actually
+  running** ([#144]). A **separate binary**, deliberately: every other Flecto
+  command authenticates to nothing, and reading live state cannot keep that
+  promise, so it does not share an entry point with the tool that can. `flecto
+  ci` cannot reach it and installing Flecto does not enable it.
+  It holds **no credentials** — Kubernetes and SSM are read through `kubectl`
+  and `aws`, which you have already authenticated, so Flecto inherits exactly
+  what those are entitled to. Read-only is structural: argv is built from a
+  fixed verb allowlist and nothing from the URI can reach it as a flag. Values
+  from a secret store are compared **by shape** (length and digest), never by
+  value, with no flag to change that; SSM is read without `--with-decryption`.
+  Terraform state exposes only `outputs`. See [docs/drift.md](docs/drift.md).
+
+### Fixed
+
+- **The shared snapshot store now refuses a Windows target on another drive or
+  a UNC share** ([#141], [#121]). The store keys a snapshot by its repo-relative
+  path and refuses a file outside the repository, but recognised "outside" only
+  as a `..`-prefixed path. On Windows, `path.relative` cannot reach another drive
+  or a share and returns the target absolute instead, which was accepted as a
+  key: a cross-drive write failed on a raw `ENOENT`, and a UNC one was written
+  under a meaningless `server/share/…` key. Neither left `.flecto/snapshots/`.
+  Both are now refused with the same message as any other outside target.
+
+- **`watch --command`/`--webhook`/`--webhook-header` declared in `.flectorc`
+  are refused, not honored** ([#121]). All three merge through the ordinary
+  options path with no other gate, unlike
+  `--plugins`/`--output`/`--baseline`/`--update-baseline`, which were already
+  refused there. `command` spawns a shell command on every change;
+  `.flectorc` is attacker-controlled on an untrusted pull request, so a
+  `.flectorc` naming one got arbitrary shell execution on the next `flecto
+  watch` — no `--command` flag required. Confirmed end to end: a hostile
+  `.flectorc` alone, with nothing passed on the command line, ran a command that
+  wrote a marker file outside anything the run otherwise touched. `webhook` is
+  the same shape one step down — it sends the change payload to a URL the
+  pull request chose. `webhook-header` is reachable even when `webhook` itself
+  is the operator's own flag: an rc-declared header rides along on that
+  already-approved request and can override it. All three are refused with the
+  message the plugin and write guards already use, `FLECTO_ALLOW_RC_ALERTS=1`
+  opts out for a repository that configures one in `.flectorc` on purpose, and
+  any of the three named on the command line is untouched, because that is the
+  operator. `--delivery-mode`/`--on-alert-failure` are untouched either way —
+  they only tune failure handling for an alert the operator already chose, the
+  same "operator delegates a setting" shape `--fail-on` already has, and
+  `flecto init` writes both into the config it generates.
+
+## [3.1.0] - 2026-09-15
+
+### Added
+
+- **A shared, git-tracked snapshot store** ([#141]). Snapshot history lived in
+  `.flecto-snapshots/`, keyed by each file's *absolute* path — right for a laptop
+  and meaningless anywhere else. An ephemeral runner starts with that directory
+  empty on every run, so `history` and `report` were local-only by construction
+  and `ci` had to be handed `--snapshot-ref`.
+
+  `--snapshot-store shared` (or `"snapshotStore": "shared"` in `.flectorc`, which
+  is the better place for it) writes `.flecto/snapshots/` instead: keyed by
+  repo-relative path, one file per config file with its history inside, keys
+  sorted at every level. Commit it and every runner reads the baseline the author
+  saved, with no cache, no ref, and no setup step. `watch`, `ci`, `history`, and
+  `report` all read whichever store is selected, and every "nothing found"
+  message names the store it looked in.
+
+  **Committing snapshots commits config values into git history permanently**, so
+  the shared store masks by default: values that trip Flecto's secret detection —
+  by shape *or* by key name, the same names `--mask-secrets` recognizes — are
+  stored as `flecto:sha256:<digest>`. The digest is a change detector, not a
+  vault — a rotated credential still reports as drift, because a store that
+  silently missed one would be worse than no store, and the live side of a diff is
+  masked the same way so an untouched secret produces no change.
+  `--snapshot-mask none` opts out and says so.
+
+  Retention (`--snapshot-retention`, 20 per file in the shared store) prunes
+  oldest-first, because an append-forever store inside a repository becomes its
+  own problem. The `local` store is untouched: same filenames, same JSON, same
+  unbounded history, still the default.
+
+### Security
+
+- **The merge gate could be turned green from `.flectorc`** ([#121]).
+  `--update-baseline` accepts every finding of the current run, and it resolved
+  through the ordinary options merge — so a pull request that added four lines of
+  `.flectorc` turned a failing `flecto ci --fail-on error` into a passing one,
+  overriding a `--fail-on` given on the command line. `updateBaseline` is now
+  refused from `.flectorc` (and from a profile) rather than honored: it is an
+  action, not a setting. `--update-baseline` on the command line is unchanged.
+
+- **Write destinations could be redirected out of the repository** ([#121]).
+  `--output` (`flecto report`) and `--baseline` (`flecto ci`) can both be declared
+  in `.flectorc`, so a pull request could point them at any file the job could
+  reach — through `..`, or through a symlink — and both files carry content that
+  pull request partly wrote. A destination declared in `.flectorc` must now
+  resolve inside the project (`FLECTO_ALLOW_RC_WRITES=1` opts out), and a
+  destination that leaves the project through a symlink is refused whoever named
+  it (`FLECTO_ALLOW_SYMLINK_TARGETS=1` opts out) — including a link whose target
+  does not exist yet, which `existsSync` reports as absent and which would have
+  Flecto *create* a file outside the repository rather than overwrite one. A
+  destination named on the command line is operator intent and is unchanged.
+
+- **The GitLab token followed redirects** ([#121]). `fetch` strips
+  `Authorization` when a redirect crosses origins and strips only that header;
+  GitLab authenticates with `PRIVATE-TOKEN`, which was forwarded to the redirect
+  target in full — verified against a local server. Provider API requests are now
+  issued with `redirect: 'manual'` and refuse a 3xx, naming the origin it pointed
+  at. Bitbucket workspace and repository segments are URL-encoded alongside,
+  matching GitLab's project id.
+
+  The API host comes from runner environment rather than pull request content, so
+  this needed a hostile or misconfigured API host to reach.
+
 ## [3.0.2] - 2026-09-06
 
 ### Security
@@ -972,7 +1222,9 @@ fixed — those runs were never actually gated — but the failure is new.
 - Misconfigured policy packs/plugins cause `watch` to exit non-zero instead of
   continuing with no policies.
 
-[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...HEAD
+[4.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...v4.0.0
+[3.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v2.1.0...v3.0.0
@@ -1059,8 +1311,12 @@ fixed — those runs were never actually gated — but the failure is new.
 [#159]: https://github.com/myselfsiddharth/Flecto/issues/159
 [#150]: https://github.com/myselfsiddharth/Flecto/issues/150
 [#125]: https://github.com/myselfsiddharth/Flecto/issues/125
+[#143]: https://github.com/myselfsiddharth/Flecto/issues/143
 [#141]: https://github.com/myselfsiddharth/Flecto/issues/141
+[#140]: https://github.com/myselfsiddharth/Flecto/issues/140
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [#138]: https://github.com/myselfsiddharth/Flecto/issues/138
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 [GHSA-wq8m-fc3q-8m5x]: https://github.com/myselfsiddharth/Flecto/security/advisories/GHSA-wq8m-fc3q-8m5x
+[#142]: https://github.com/myselfsiddharth/Flecto/issues/142
+[#144]: https://github.com/myselfsiddharth/Flecto/issues/144

package/README.md

@@ -263,7 +263,10 @@ flecto history config/prod.yaml --limit 10
 ```
 
 Snapshots stay on your machine in `.flecto-snapshots/`. Nothing is uploaded and
-no account is required. → **[CLI reference](docs/cli-reference.md#flecto-history-files)**
+no account is required. To read the same history on a CI runner, save it to the
+git-tracked store instead — `--snapshot-store shared` writes a committable
+`.flecto/snapshots/`, masking secret-like values into digests as it goes.
+→ **[CLI reference](docs/cli-reference.md#flecto-history-files)**
 
 ### Share what changed before the incident
 
@@ -498,6 +501,7 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 | `flecto watch --snapshot` | Save the current state as a baseline |
 | `flecto watch --diff` | Compare against the baseline and exit |
 | `flecto ci [files...]` | One-shot check with a gate-able exit code |
+| `flecto explain [files...]` | Advisory, model-generated narration of the masked diff (opt-in, your own key) |
 | `flecto compare <fileA> <fileB>` | Diff two files against each other (`fileA` is the baseline) |
 | `flecto plan <planFiles...>` | Review `terraform show -json` output and gate on it |
 | `flecto history [files...]` | Summarize drift across local snapshots |
@@ -506,6 +510,8 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 | `flecto policies list` | List available policy packs |
 | `flecto policies test <dir>` | Assert pack and plugin findings from fixtures |
 | `flecto init` | Create a `.flectorc` from detected stack signals |
+| `flecto mcp` | Serve read-only diff/check/explain tools to an agent over MCP |
+| `flecto lsp` | Show findings and changes as diagnostics while a config file is edited |
 | `flecto doctor` | Check setup, config, and environment |
 
 → **[Every flag, every command](docs/cli-reference.md)**
@@ -518,15 +524,20 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 |---|---|
 | **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
 | **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
+| **[Editor diagnostics](docs/editor.md)** | `flecto lsp` setup for Neovim, Helix, Emacs, and where diagnostics land |
 | **[Encrypted files](docs/encrypted-files.md)** | SOPS and age: what is detected, what is reported, why nothing is decrypted |
 | **[CI](docs/ci.md)** | Baselines, fail triggers, output formats, the bundled GitHub Actions |
 | **[Performance](docs/performance.md)** | Where time goes at scale, and how much smaller a diff is than the config |
 | **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
 | **[Terraform plans](docs/terraform.md)** | Reviewing `terraform show -json` output and the `terraform` pack |
 | **[Webhooks and commands](docs/webhooks.md)** | Envelope shape, delivery modes, command environment |
+| **[MCP server](docs/mcp.md)** | Read-only diff/check/explain tools for agents, and the security posture |
+| **[Explain](docs/explain.md)** | Opt-in model narration of a diff: what is sent, what it can never do, cost |
 | **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
 | **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
+| **[Live drift](docs/drift.md)** | `flecto-drift`: comparing a declared config against what is actually running |
 | **[Troubleshooting](docs/troubleshooting.md)** | When something doesn't behave |
+| **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and how to tell whether they affect you |
 | **[Changelog](CHANGELOG.md)** | Release history and migration notes |
 
 ---

package/drift.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * `flecto-drift` — compare what a repository declares against what is running.
+ *
+ * Flecto answers "what changed in this file". The question underneath it is
+ * usually "does what we declared still match what is running" — the config
+ * committed six months ago, against the value somebody hotfixed into the
+ * cluster at 3 AM and never backported (#144).
+ *
+ * **This is a separate binary on purpose.** Core Flecto authenticates to
+ * nothing, reads no key material, and shells out to nothing but `git`; every
+ * other command in this package keeps that promise. Reading live state cannot,
+ * so it does not share an entry point with the tool that can. `flecto ci`
+ * cannot reach this file, nothing in `src/` outside `drift-sources.js` imports
+ * it, and installing Flecto does not enable it. The intent is for it to become
+ * its own package with its own security review and release cadence; it lives
+ * here now for the same reason the MCP server did, which is that one repository
+ * is easier to review than two while the shape is still settling.
+ *
+ * It holds no credentials. Every source delegates to a tool the operator has
+ * already installed and authenticated (`kubectl`, `aws`), so Flecto inherits
+ * exactly what that tool is entitled to and nothing else — which is also what
+ * makes "give it a read-only role" advice an operator can enforce in their own
+ * IAM rather than a promise this code makes about itself.
+ *
+ * Values from a secret store are compared by **shape**, never by value, and
+ * there is no flag to change that.
+ */
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { resolve } from 'path';
+import { diffTrees } from './src/differ.js';
+import { assertTargetContained } from './src/config.js';
+import { documentKeysOf } from './src/documents.js';
+import { parseFile } from './src/parser.js';
+import { maskChangeEvent, renderDiff, renderError, renderInfo, renderNote, renderWarn } from './src/renderer.js';
+import { readLiveState, shapeOf, SHAPE_RE } from './src/drift-sources.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('./package.json');
+
+/**
+ * Keys a declared file carries that a live store never does.
+ *
+ * A Kubernetes ConfigMap's `data` block is what corresponds to a config file;
+ * the manifest around it (`apiVersion`, `metadata`, …) has no counterpart in
+ * the live read, and reporting all of it as "removed" would bury the one line
+ * that actually drifted. Descending into `data` when it is there is the whole
+ * of the normalization — anything cleverer would be guessing.
+ * @param {unknown} declared
+ * @returns {unknown}
+ */
+function declaredComparable(declared) {
+  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return declared;
+  let record = /** @type {Record<string, unknown>} */ (declared);
+
+  // A manifest carrying apiVersion + kind + metadata.name is wrapped by the
+  // parser under a synthetic `Kind/ns/name` document key, so the `data` block
+  // sits one level down. Looking only at the top level found nothing, and the
+  // documented headline case -- a committed ConfigMap against an identical live
+  // one -- reported the whole manifest as drift and exited 1 forever.
+  const documents = documentKeysOf(declared) ?? [];
+  // Refused *before* looking for `data`. A document's identity falls back to a
+  // top-level `id`/`name`, so a document can be keyed literally `data` -- and
+  // checking `record.data` first then matched that wrapper, compared the wrong
+  // subtree, and silently dropped every other document in the file.
+  if (documents.length > 1) {
+    throw new Error(
+      `drift: ${documents.length} documents in this file, and a live source is one object.`
+      + ' Point drift at a file holding a single manifest.',
+    );
+  }
+  if (documents.length === 1 && typeof record[documents[0]] === 'object' && record[documents[0]] !== null) {
+    record = /** @type {Record<string, unknown>} */ (record[documents[0]]);
+  }
+
+  // `stringData` as well as `data`: readKubernetes merges both, and a plaintext
+  // Secret manifest uses `stringData`, so looking only at `data` reported the
+  // whole manifest as drift -- the same failure, on the other key.
+  const blocks = ['data', 'stringData']
+    .filter((key) => record[key] && typeof record[key] === 'object' && !Array.isArray(record[key]));
+  if (blocks.length > 0) {
+    const merged = Object.assign({}, ...blocks.map((key) => record[key]));
+    const dropped = Object.keys(record).filter((key) => !blocks.includes(key));
+    if (dropped.length > 0 && !documents.length) {
+      // For a manifest the surrounding keys have no live counterpart, which is
+      // the point. For an ordinary config file that happens to carry `data`,
+      // they are real settings -- say so rather than quietly comparing a third
+      // of the file.
+      renderWarn(
+        `Comparing only the ${blocks.join(' and ')} block; `
+        + `${dropped.length} other top-level key(s) in this file were not compared.`,
+      );
+    }
+    return merged;
+  }
+  return record;
+}
+
+/**
+ * Compare declared values against live ones, shaping the declared side for
+ * exactly the keys the live side shaped.
+ *
+ * Comparing a plaintext declared value against a live *shape* would report that
+ * key as changed on every run, which is noise that trains people to ignore the
+ * tool. So a shaped key is shaped on both sides, and every other key is
+ * compared by value.
+ * @param {unknown} declared
+ * @param {Record<string, unknown>} live
+ * @param {Set<string>} shapedKeys the live keys compared by shape
+ * @param {(v: string) => string} shape
+ * @returns {{ before: unknown, after: unknown }}
+ */
+function alignForComparison(declared, live, shapedKeys, shape) {
+  const comparable = declaredComparable(declared);
+  if (shapedKeys.size === 0 || !comparable || typeof comparable !== 'object' || Array.isArray(comparable)) {
+    return { before: comparable, after: live };
+  }
+  // Per key, not per source. Shaping the whole declared side because *one*
+  // value was sensitive compared a shaped declared value against a raw live
+  // one, so every non-secret key drifted on every run -- the "trains people to
+  // ignore the tool" failure this function exists to prevent.
+  const shaped = Object.fromEntries(
+    Object.entries(/** @type {Record<string, unknown>} */ (comparable))
+      .map(([key, value]) => [key, shapedKeys.has(key) ? shape(stableString(value)) : value]),
+  );
+  return { before: shaped, after: live };
+}
+
+/**
+ * A value as a string, matching how the live side stringifies before hashing.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stableString(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return JSON.stringify(value);
+}
+
+program
+  .name('flecto-drift')
+  .description(
+    'Compare a declared config file against what is actually running.\n'
+    + 'Reads live state through a CLI you have already authenticated; holds no credentials.',
+  )
+  .version(version)
+  .argument('<file>', 'the declared configuration file')
+  .requiredOption('--against <uri>', 'live source: k8s://<ns>/configmap/<name>, k8s://<ns>/secret/<name>, ssm://<path>, tfstate://<path>')
+  .option('--format <type>', 'human or json', 'human')
+  .option('--fail-on-drift', 'exit 1 when the declared file and the live state differ', false)
+  .action(async (file, opts) => {
+    try {
+      const format = String(opts.format);
+      if (!['human', 'json'].includes(format)) {
+        throw new Error('--format must be human or json');
+      }
+
+      const filepath = resolve(file);
+      // The same containment every other read in Flecto has: file names and
+      // links are attacker-controlled on an untrusted pull request.
+      assertTargetContained(filepath, process.cwd());
+      const declared = parseFile(filepath);
+
+      const { state: live, meta } = readLiveState(opts.against);
+      const { before, after } = alignForComparison(declared, live, meta.shapedKeys, shapeOf);
+
+      // Declared is `before`, live is `after`, so the verbs read the way the
+      // question is asked: what has the running system done to what we wrote.
+      // Masked on both paths, not only the human one: a machine-readable report
+      // of live state is the likelier thing to be archived as a CI artifact, so
+      // leaving it raw would put those values somewhere they outlive the run.
+      //
+      // A shape is skipped, because it is already the safe form -- a keyed
+      // digest of a value this process never prints -- and masking it again
+      // would replace it with `***` on both sides, throwing away the one thing
+      // it exists to show: that the credential rotated.
+      //
+      // The test is on the **value**, not on the key it sits under. Keying it
+      // on `shapedKeys` trusted metadata that can fall out of step with the
+      // value beside it, and when it did, a live plaintext printed unmasked
+      // because its key was still marked as shaped. Every present side must be
+      // a shape, so a shape-to-plaintext change is masked rather than exempted.
+      const changes = diffTrees(before, after, {}).map((event) => {
+        const sides = [event.before, event.after].filter((value) => value !== undefined);
+        const allShaped = sides.length > 0
+          && sides.every((value) => typeof value === 'string' && SHAPE_RE.test(value));
+        return allShaped ? event : maskChangeEvent(event);
+      });
+
+      if (format === 'json') {
+        process.stdout.write(`${JSON.stringify({
+          file: filepath,
+          against: opts.against,
+          source: meta.label,
+          // Named, so a consumer never has to guess whether a value in here is
+          // a real value or a digest of one.
+          comparison: meta.sensitive ? 'shape-only' : 'values',
+          drifted: changes.length > 0,
+          changes,
+        }, null, 2)}\n`);
+      } else if (changes.length === 0) {
+        renderInfo(`No drift: ${filepath} matches ${meta.label}.`);
+      } else {
+        // Masked, like every other render path in Flecto. Drift prints values
+        // read out of a live system into a CI log, so it needs this more than
+        // the others, not less -- a ConfigMap value under a secret-shaped key
+        // is still a secret.
+        renderDiff(filepath, changes, { baseline: meta.label });
+        if (meta.sensitive) {
+          renderNote(
+            'Values from a secret store are compared by shape (length and digest), never by value.',
+          );
+        }
+      }
+
+      if (changes.length > 0 && opts.failOnDrift) process.exitCode = 1;
+    } catch (err) {
+      renderError(err.message);
+      process.exitCode = 1;
+    }
+  });
+
+program.parseAsync(process.argv);