envsync-le: Instructions file for Codex

AGENTS.md — EnvSync-LE

Technical source of truth for this repo. README.md is the user-facing doc; this file is for anyone (human or agent) changing the code.

This repo hosts two products: the extension at the root (this document's scope) and the Rust CLI in crate/ (its own AGENTS.md + SPEC.md). The shared detection corpus lives at crate/fixtures/; scripts/check-detection-parity.ts fails CI when this extension drifts from it, and it also fails if any answer in the corpus carries a value rather than a key name.

The Rust CLI also ships a second way, through npm: src/cli/ is its terminal surface rebuilt over this extension's detection engine, bundled to cli/cli.js as the npm package envsync-le. Both install a command named envsync-le, so the npm one is held to the crate's surface byte for byte, which is a different contract from the detection parity above. src/cli/ follows crate/src/cli.rs, scan.rs, discover.rs, the template matching in detect/compare.rs and mcp/mod.rs, not the extension's commands, and scripts/check-cli-parity.ts runs both binaries over one generated tree and fails on any difference in stdout, stderr or exit code, and in what envsync-le mcp answers. Nothing is exempt. scripts/check-cli-pipes.ts, shared with every port, closes stdout or stderr before either binary writes and fails on any difference in what follows, on all three operating systems. A change to the crate's surface changes src/cli/ in the same commit.

What this is

A VS Code extension that compares the variable names (keys) across the .env files in a workspace and reports keys missing from some files. Values are never read into comparison output, files are never modified, and there is no network access. Comparison runs automatically on file changes (debounced), on demand (Show Issues, Compare Selected), and against an optional template file.

Architecture

extension.ts              activate(): build adapters -> createDetector -> registerAllCommands -> registerVSCodeWatchers -> initial checkSync
adapters/                 thin vscode wrappers, deps injected as typed bags:
  vscodeConfiguration     Configuration (get/has) over workspace.getConfiguration('envsync-le')
  vscodeFileSystem        findFiles/readFile/stat/asRelativePath
  vscodeNotifier          window messages, gated by notificationLevel
                          (all -> missing+extra+errors, important -> missing+errors, silent -> nothing)
  vscodeStatusBar         one status bar item; re-renders on config change
  vscodeTelemetry         local OutputChannel, only when telemetryEnabled
  vscodeUserInterface     quickPick (single + canPickMany), progress, messages
  vscodeWatcher           FileSystemWatcher per watchPattern; debounced checkSync;
                          rebuilt when watchPatterns changes
  vscodeCommand           CommandAdapter for openSettings
commands/                 one file per command; registerAllCommands wires the bag
detection/
  heuristics.ts           THE single place for basename/isEnvFileName/
                          detectFileType/shouldExcludeFile (glob matching)
  parser.ts               line-oriented key extraction; multiline quoted values
  comparator.ts           compareFiles(files, {mode, templatePath, caseSensitive})
                          -> SyncReport; extras only exist in template mode
  detector.ts             orchestrates discover -> parse -> compare -> notify/UI
config/config.ts          readConfig(configuration) snapshot; CONFIG_DEFAULTS table
utils/errors.ts           sanitizeErrorMessage/errorMessage — wired into every
                          user-facing error
types.ts                  shared types only — no logic
cli/                      the npm command line: args, discover + ignoreRules
                          (ripgrep's precedence, off by default as in the
                          crate), scan (the crate's report and template
                          matching over comparator.ts), run, and checkTool
                          for `envsync-le mcp`. No `vscode`, ever