From 2be420ae806c95e5e921c6d797fe236cf8e19a57 Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:54:28 +0530 Subject: [PATCH 1/5] docs: prepare M4 requirements and acceptance gates --- CHANGELOG.md | 5 +- CONTRIBUTING.md | 4 +- README.md | 11 +- docs/ARCHITECTURE.md | 10 +- docs/DEVELOPMENT-TOOLS.md | 14 ++- docs/PLAN.md | 39 +++++-- docs/adr/0006-m4-reports-and-bundles.md | 68 ++++++++++++ docs/adr/README.md | 3 +- docs/phases/M3.md | 7 +- docs/phases/M4.md | 136 ++++++++++++++++++++++++ 10 files changed, 274 insertions(+), 23 deletions(-) create mode 100644 docs/adr/0006-m4-reports-and-bundles.md create mode 100644 docs/phases/M4.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e5b83c..90392cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and ### Added +- [M4 preparation](docs/phases/M4.md) and [proposed ADR 0006](docs/adr/0006-m4-reports-and-bundles.md) + for terminal/Markdown reports, versioned bounded bundles, redaction and offline evidence. Documentation + only; M4 remains not started. Current status records merged M3 and successful main CI. - M3 rules ENV007–ENV012: known Docker API incompatibility, explicitly required dependency absence, package-manager/lockfile disagreements, effective Git identity/explicit autocrlf policy, canonical virtualenv/interpreter mismatch and opt-in proxy refusal/no-route evidence. @@ -21,7 +24,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and CLI, cancellation and socket lifecycle regressions. - Accepted [ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md), [M3 acceptance requirements](docs/phases/M3.md), [validation evidence](docs/testing/m3-validation.md) - and [development-tool audit](docs/DEVELOPMENT-TOOLS.md). M3 is complete on the feature branch; + and [development-tool audit](docs/DEVELOPMENT-TOOLS.md). M3 is complete and merged through PR #3; [CI 43723839978](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978) passed native Windows/Ubuntu/macOS race, tests and builds, plus lint and the vulnerability scan. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d139b3e..9462f76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,8 +9,8 @@ Thanks for taking the time. This document is deliberately short and specific. 2. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - how the pieces fit together. 3. [docs/adr/](docs/adr/) - decisions that have already been argued about. Do not relitigate them without a new ADR. -4. [docs/phases/M3.md](docs/phases/M3.md) and [ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md) - - implemented M3 evidence contracts and verified three-OS CI gate. +4. [docs/phases/M4.md](docs/phases/M4.md) - planned reports/bundles, dependency order and acceptance gates; + preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADR 0005. ADR 0006 remains proposed. 5. [docs/DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) - CodeGraph freshness, static-analysis coverage and profiling appropriate to this repository's runtime. diff --git a/README.md b/README.md index 9af01b7..2568d1b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [](LICENSE)  -**Status: M3 complete on `feat/m3-implementation`; Windows, Ubuntu and macOS CI passed.** +**Status: M1–M3 complete and merged into main; Windows, Ubuntu and macOS CI passed.** Nine collectors feed twelve rules covering platform, shell, PATH, Python/Node runtime, requested TCP ports, effective Git config, local Docker/API metadata, explicit project dependencies and proxy configuration. Reports are plain text or versioned JSON; `explain` and `rules --json` work offline. @@ -241,16 +241,19 @@ goreleaser build --snapshot --clean ## Roadmap -M3 is **complete on the feature branch, including three-OS CI**. Read the +M3 is **complete and merged** through [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with +successful [main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). Read the [M3 acceptance gates](docs/phases/M3.md), [accepted ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md) and [validation record](docs/testing/m3-validation.md) for its contracts and evidence. +The [M4 requirements](docs/phases/M4.md) and [proposed report/bundle ADR](docs/adr/0006-m4-reports-and-bundles.md) +prepare the next phase; M4 implementation has not started. | Milestone | Deliverable | Status | |---|---|---| | M1 | CLI foundation, collector interface, system information | **Done** (v0.1.0) | | M2 | Cross-platform collectors and rules ENV001–ENV006 | **Done (merged)** | -| M3 | Rules ENV007–ENV012, Docker/dependency/proxy evidence, offline registry commands | **Done (feature branch, CI passed)** | -| M4 | Polished terminal output, Markdown export, diagnostic bundles | Not started | +| M3 | Rules ENV007–ENV012, Docker/dependency/proxy evidence, offline registry commands | **Done (merged)** | +| M4 | Polished terminal output, Markdown export, diagnostic bundles | Not started; documents prepared | | M5 | Safe, confirmed automated remediation | Not started | | M6 | Windows, Linux, macOS packaging and signed releases | Not started | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2a76f08..79b0e56 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,6 @@ # EnvDoctor Architecture -**Status: M3 complete on the feature branch; three-OS CI passed.** Nine collectors feed +**Status: M1–M3 complete and merged into main; three-OS CI passed.** Nine collectors feed twelve pure rules and a plain-text/JSON report. Offline metadata commands and generated pages share the same rule registry. Bundles, automatic fixes and interactive output remain planned. The authoritative specification is [PLAN.md](PLAN.md); [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) @@ -91,3 +91,11 @@ Read [phase requirements](phases/M3.md), [ADR 0005](adr/0005-m3-evidence-and-rul and Linux race suites passed locally; native Windows/Ubuntu/macOS tests and race suites also passed in [M3 CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978). [Development tools](DEVELOPMENT-TOOLS.md) records navigation and runtime-profiling coverage. + +## M4 preparation + +[M4 requirements](phases/M4.md) and [proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare +Bubble Tea/plain/Markdown output and bounded versioned bundles. A separate export policy must remove +identifying/free-text data and expose resulting evidence omissions. Offline bundle diagnosis evaluates +captured facts under the current registry without inspecting the receiving machine. These paths are +planned; existing plain/JSON/fixture contracts remain the implemented behavior. diff --git a/docs/DEVELOPMENT-TOOLS.md b/docs/DEVELOPMENT-TOOLS.md index e8db8f6..e0670fe 100644 --- a/docs/DEVELOPMENT-TOOLS.md +++ b/docs/DEVELOPMENT-TOOLS.md @@ -2,7 +2,8 @@ Initial audit: 2026-11-14; M3 verification refresh: 2026-11-15. These are development aids, not product features or substitutes for tests. -Read [PLAN.md](PLAN.md), the [M3 requirements](phases/M3.md) and accepted [ADRs](adr/) first. +Read [PLAN.md](PLAN.md), the [M4 requirements](phases/M4.md), implemented [M3 contract](phases/M3.md) +and accepted [ADRs](adr/) first. M4 ADR 0006 remains proposed. ## CodeGraph @@ -15,6 +16,9 @@ codegraph status codegraph sync ``` +On 2026-11-17, `codegraph status` reported the existing index up to date against merged M3 source. +No new index or generated source was created for M4 preparation. + For indexed code, use the CodeGraph MCP exploration tool with this repository's absolute `projectPath` and the symbol/flow you need. Read its returned source and callers before edits; use direct source/config searches for areas the graph does not capture. Unresolved references remain, @@ -42,6 +46,13 @@ Profile only when the change or suspected fault justifies it; a documentation ed profile, goroutine counts and local diagnosis timings. Those are bounded Go workload measurements; MemGuard/MAT were not treated as Go runtime gates or evidence of universal leak freedom. +## M4 implementation validation + +Use Go heap/RSS/goroutine measurements for repeated archive read/write, rejection, cancellation and +terminal resize/exit. Bound decompression and report buffers independently; use synthetic captures and +measure cleanup after failures. Terminal dependencies remain Go code, so JS static tools do not replace +these checks. M4 resource/renderer evidence is planned, not measured by this documentation pass. + ## Memory Analyzer The locally installed analyzer is Eclipse MAT 1.17.0, configured with Java 21 and a 4 GiB analyzer heap. @@ -55,4 +66,3 @@ State the branch and commit, read the phase/ADRs, refresh the graph after source the exact failing command, output and minimal synthetic fixture. Keep implementation on a feature branch. A skipped integration test must be reported as skipped, with its missing dependency; it is not a passing check. Preserve local Docker volumes and use disposable databases for migration tests. - diff --git a/docs/PLAN.md b/docs/PLAN.md index 66c4d97..e2974b8 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,7 +12,7 @@ depends_on: - No runtime dependencies (single static binary) - Docker (optional, only for testing rules that inspect Docker) created: 2026-11-13 -updated: 2026-11-15 +updated: 2026-11-17 --- # EnvDoctor — Implementation Plan @@ -24,12 +24,16 @@ updated: 2026-11-15 ## 0. Machine context -M2 is complete and merged into `main`. M3 is **complete on `feat/m3-implementation`, including -[three-OS CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978)**. +M1–M3 are complete and merged into `main`. [M3 PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3) +merged at `6cf358138ecd3bedf086f22536a30562fb673e4e`; its +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915) passed. [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) was accepted and committed before implementation. The [M3 requirements](phases/M3.md) define the evidence and acceptance contract; [M3 validation](testing/m3-validation.md) records the final commands and limits. The [development-tool audit](DEVELOPMENT-TOOLS.md) records actual coverage and profiling limits. +M4 is **Not started**. [M4 requirements](phases/M4.md) and +[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare report formats, bundle export/redaction +and offline diagnosis; they do not claim new commands or acceptance results. ```yaml project: EnvDoctor @@ -65,6 +69,7 @@ implemented: not_implemented: - diagnostic rules ENV013-ENV018 + - markdown report export - bubble tea output - diagnostic bundles - fixes and undo @@ -295,6 +300,10 @@ Implemented as of M3: `diagnose`, `version`, offline `explain` and `rules`/`rule `bundle` and `fix` remain planned; see section 0 for the authoritative list. Unknown rule IDs and invalid metadata arguments exit 4; output failures exit 3. +M4 format/plain/bundle-input flags and bundle command semantics are proposed in +[ADR 0006](adr/0006-m4-reports-and-bundles.md). They are not implemented. Bundle export must use a +separate sharing policy; ordinary JSON continues to include effective Git identity. + | Exit code | Meaning | |---|---| | 0 | No findings at or above `warning` | @@ -484,7 +493,7 @@ See [testing/m1-m2-validation.md](testing/m1-m2-validation.md) for commands, mea **Deliverable:** rules ENV007–ENV012, Docker and dependency inspectors, `explain` and `rules --json`. -Status: **Complete on `feat/m3-implementation`, including native Windows/Ubuntu/macOS CI.** +Status: **Complete and merged into main**, including native Windows/Ubuntu/macOS CI. Follow [M3 requirements](phases/M3.md), [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) and [M3 validation](testing/m3-validation.md) for evidence, tests and limits. @@ -511,12 +520,20 @@ tests and records local measurements without claiming M6 clean-host/release cove **Deliverable:** polished terminal output (Bubble Tea when TTY), Markdown export, `bundle` command. +Status: **Not started; documentation prepared.** Follow [M4 requirements](phases/M4.md) and resolve +[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) before dependent code. Bundle input/export has +its own version/redaction/omission policy; copying the current report is not sufficient. + **Acceptance criteria** - [ ] Non-TTY output is plain text, stable, and contains no ANSI codes -- [ ] `envdoctor bundle` produces a zip under 2 MB containing report, redacted snapshot and tool versions -- [ ] Bundle never contains environment variable values, tokens or usernames (test asserts this) -- [ ] A bundle from another machine can be diagnosed offline with `envdoctor diagnose --from-bundle` +- [ ] TTY/NO_COLOR/redirect/format and Markdown escaping cases preserve reports/exits and terminal cleanup +- [ ] `envdoctor bundle` produces a versioned zip below 2,000,000 compressed bytes with independent entry/decompression limits +- [ ] Allowlisted export removes synthetic raw environment values, tokens and identities from every member/error path +- [ ] Removed evidence is explicitly omitted/inconclusive; saved report verdicts never override validated captured evidence +- [ ] Cross-OS `diagnose --from-bundle` runs no collectors, commands or network and preserves capture/evaluator provenance +- [ ] Corrupt/traversal/bomb/duplicate/version/oversize archives and atomic write failures are tested +- [ ] M1–M3 golden/JSON/registry/probe regressions and native CI pass, with all M4 evidence recorded - [ ] One screenshot in the README, taken from a real run ### M5 — Safe remediation @@ -573,8 +590,8 @@ tests and records local measurements without claiming M6 clean-host/release cove | ENV-023A | Opt-in bounded proxy evidence collector and offline-default regression checks | ENV-005 | M3 | | ENV-022 | Rules ENV007–ENV012 | ENV-020, ENV-021, ENV-023A | M3 | | ENV-023 | Rule registry, `explain`, `rules --json` and docs generation | ENV-022 | M3 | -| ENV-024 | Bubble Tea renderer with plain fallback | ENV-019 | M4 | -| ENV-025 | Bundle writer with redaction tests | ENV-005 | M4 | +| ENV-024 | Bubble Tea/plain selection and escaped Markdown export | ENV-019 | M4 | +| ENV-025 | Versioned bounded bundle writer/reader and allowlisted redaction | ENV-005, ENV-024 | M4 | | ENV-026 | `diagnose --from-bundle` | ENV-025 | M4 | | ENV-027 | Fix planner and dry run | ENV-022 | M5 | | ENV-028 | Fix apply, logging and undo | ENV-027 | M5 | @@ -678,7 +695,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. | Rule | Pure function from snapshot to findings. Has a permanent id. | | Finding | One diagnosis: severity, evidence, cause, fix. | | Fix | A proposed remediation with explicit safety properties. | -| Bundle | A zip of report, snapshot and logs, safe to share publicly. | +| Bundle | Versioned export of redacted captured evidence/reports under a documented sharing policy. | | Degraded | A collector failed; its rules are skipped, not guessed. | --- @@ -688,5 +705,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. 1. Read sections 0, 3 and 9. Ten minutes. 2. `make build && ./bin/envdoctor diagnose`; compare what it prints with section 0's `functional` field. 3. Pick the next unchecked item in the current milestone. Rules come with fixtures or they do not come. + M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 remains proposed. This preparation + authorizes documents only; implementation needs a later request and accepted export/CLI decisions. 4. Run `make test` — golden fixtures will tell you immediately if a rule change broke another platform. 5. Never add a fix without the safety model. If in doubt, print the command instead of running it. diff --git a/docs/adr/0006-m4-reports-and-bundles.md b/docs/adr/0006-m4-reports-and-bundles.md new file mode 100644 index 0000000..714a6e5 --- /dev/null +++ b/docs/adr/0006-m4-reports-and-bundles.md @@ -0,0 +1,68 @@ +# ADR 0006 — M4 report formats and shareable diagnostic evidence + +- Status: proposed; documentation only +- Date: 2026-11-17 +- Required by: [M4 requirements](../phases/M4.md), ENV-024–ENV-026 +- Would extend: ADRs 0004/0005 with a separate bundle export/offline-input contract + +## Context + +M3 plain/JSON reports and fixture-directory diagnosis are implemented. Report JSON intentionally retains +Git identity; home/credential-URL redaction is not a general sharing scrubber. The PLAN requires zip +bundles below 2 MB without raw environment values, tokens or usernames, yet does not specify a format, +decompression limit or how removed evidence affects pure rules. A saved report is not evidence of the +receiving machine, and bundled suggestions are untrusted strings rather than commands to run. + +## Recommended design, pending acceptance + +1. Use one renderer selection path over the existing report. Propose `--format text|markdown|json`, with + current `--json` retained as an alias and an explicit plain choice for terminal use. JSON/Markdown + never enter Bubble Tea. Default non-TTY output stays plain and stable; dumb terminals/NO_COLOR use + plain fallback. Conflicting explicit formats exit 4 before collection. +2. Add a separate versioned allowlisted export model and redaction policy. Export only bounded diagnostic + facts with identifying/free-text fields sanitized or omitted. Generate every report member from that + export. Preserve omissions as explicit evidence limitations; dependent rules cannot treat redaction + as proof that a setting is missing. Existing ordinary JSON/fixture formats remain compatible. +3. Bundle v1 is a zip with manifest, snapshot, JSON/Markdown reports and normalized tool versions; optional + diagnostics are the tool's own allowlisted structured notices. No arbitrary log files are read. + The manifest records capture/tool/schema/redaction versions and member sizes/digests. It is integrity + metadata, not a machine attestation or authentication mechanism. +4. Publish only complete archives below 2,000,000 compressed bytes, at most eight entries and 8 MiB total + decompressed data. Bound each member and JSON parser separately. Reject overflow rather than truncating + evidence or relaxing the budget. Read expected members directly without filesystem extraction. +5. `--from-bundle` evaluates exported captured evidence under the current registry, records capture and + evaluator versions and exposes omissions. It executes no collectors/commands/network work and cannot + trust a saved verdict. Live-evidence flags and fixture input are mutually exclusive with bundle input. +6. Preserve diagnosis exits 0/1/2/3/4. Propose writer exit 0 for a successfully published archive, storing + the capture's own exit code inside it; usage is 4 and archive/tool/I/O failures are 3. Valid offline + diagnosis can still exit 3 for captured degradation or missing required export evidence. + +## Choices that must be resolved before acceptance + +- Field-by-field export schema for all twelve rules, including Git identities, proxy endpoints, runtime + and dependency paths, errors and rule prerequisites. Decide where opaque local replacements preserve + comparison and where omission requires explicit inconclusive evaluation. +- Report/source metadata and schema-version compatibility, capture-local replacement stability, JSON + duplicate/depth/token/string limits and exact manifest/member schemas. Do not alter fixture v1 silently. +- Per-member limits and supported zip methods/features; bounded directory preflight, size/integrity + validation, archive errors and output replacement behavior on Windows and POSIX. +- Final format/plain flags, TTY stream detection, NO_COLOR precedence, cancellation semantics and the + writer-vs-diagnosis exit distinction. Document current JSON behavior before adding new formats. +- Pinned Bubble Tea/terminal dependencies, Markdown escaping, native terminal test method, and whether + optional structured diagnostics can meet the same export policy. Unsupported log export stays absent. + +## Alternatives considered + +- Zip the current report: retains Git identity and unreviewed free text; does not meet bundle policy. +- Remove fields without omission metadata: can turn a real configuration into a false missing-setting + finding or a falsely healthy result when dependent evidence disappears. +- Extract a supplied zip before diagnosis: introduces path/symlink hazards with no need for extraction. +- Run captured verification commands: lets untrusted bundles execute on the maintainer's machine and + confuses captured evidence with a new observation. Pure offline evaluation is sufficient. + +## Consequences and validation + +ENV-024 explicitly includes Markdown. ENV-025 must implement a strict writer and reader plus an evidence +sharing policy before ENV-026 can reuse them. Size/redaction/abuse/cross-OS fixtures, terminal cleanup, +existing JSON/golden/probe regressions and native CI gates are required by the phase document. +This record remains a proposal and does not authorize edits to accepted ADRs or claim implementation. diff --git a/docs/adr/README.md b/docs/adr/README.md index ff673ea..485d16b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,7 +8,8 @@ Each file records one decision that was expensive to make and would be expensive | [0002](0002-m1-implementation-decisions.md) | M1 implementation decisions | accepted, partly superseded by 0003 and 0005 | | [0003](0003-go-126-floor-and-ci-contract.md) | Go 1.26 floor and CI contract | accepted | | [0004](0004-m2-collectors-and-rules.md) | M2 collectors and rules | accepted, scoped extensions in 0005 | -| [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted for the M3 feature branch | +| [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted; merged M3 | +| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | proposed; no implementation | New ADRs are numbered sequentially and never edited after acceptance. A changed mind gets a new ADR that supersedes the old one. diff --git a/docs/phases/M3.md b/docs/phases/M3.md index fb64f40..2f4ff1b 100644 --- a/docs/phases/M3.md +++ b/docs/phases/M3.md @@ -1,6 +1,8 @@ # M3 requirements: evidence-based rules and inspectors -Status: **Complete on `feat/m3-implementation`, including native Windows/Ubuntu/macOS CI.** +Status: **Complete and merged into main** through [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), +2026-11-16. Native Windows/Ubuntu/macOS CI and +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915) passed. Prepared 2026-11-14 from merged M2 commit `c7e2c84c730edca814a44580cdfc9abaf630b457`. The [plan](../PLAN.md) defines scope; this is its M3 acceptance contract. @@ -86,7 +88,8 @@ The [M1/M2 record](../testing/m1-m2-validation.md) preserves historical results ## Handoff -ENV-020–ENV-023A and all M3 acceptance gates are verified on the feature branch. The recorded CI run +ENV-020–ENV-023A and all M3 acceptance gates are verified and merged. The recorded feature-branch CI run verifies M3 source at `fbf79dd`, including native macOS execution. Follow [development tools](../DEVELOPMENT-TOOLS.md) and provide the branch, fixture/reproducer, exact command and redacted output for debugging in another editor. +Planned report/bundle work is defined by [M4 requirements](M4.md), with ADR 0006 still proposed. diff --git a/docs/phases/M4.md b/docs/phases/M4.md new file mode 100644 index 0000000..a5db8cc --- /dev/null +++ b/docs/phases/M4.md @@ -0,0 +1,136 @@ +# M4 requirements: terminal reports and diagnostic bundles + +Status: **Not started; documentation prepared 2026-11-17.** No M4 command, renderer or test result is claimed. +Baseline: merged M3 main commit `6cf358138ecd3bedf086f22536a30562fb673e4e`, +[PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with successful +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). +Read the [plan](../PLAN.md), [architecture](../ARCHITECTURE.md), [M3 requirements](M3.md) and +accepted [ADR 0005](../adr/0005-m3-evidence-and-rule-registry.md). +[ADR 0006](../adr/0006-m4-reports-and-bundles.md) is proposed; resolve its export and CLI choices first. + +## Scope and compatibility + +Implement ENV-024–ENV-026: Bubble Tea with a plain fallback, Markdown export, a redacted bundle writer, +and `diagnose --from-bundle`. Include Markdown rendering explicitly in ENV-024; it currently has no +separate backlog item. Rules ENV013–ENV018, fix/apply/undo and signed packaging remain later milestones. + +Preserve the nine collectors, twelve pure rules, immutable registry, evidence prerequisites, generated +rule pages, schema-v1 fixture support, deterministic finding ordering and existing JSON/exit behavior. +Ordinary `--json` still writes one report document to stdout; diagnostics/progress belong on stderr. +Diagnosis applies no fixes. Default collection remains offline, and proxy probing remains an explicit, +bounded live opt-in. No export or offline input enables a command supplied by a bundle. + +## Renderer contract + +- Interactive output is selected only when the required streams are terminals and terminal capabilities + permit it. Define explicit plain-output/format flags, precedence and invalid combinations in ADR 0006. + A redirect, pipe, `TERM=dumb`, `NO_COLOR` or explicit plain choice must have a documented fallback. +- Non-TTY/default plain output remains stable and contains no ANSI/cursor-control codes. JSON and + Markdown bypass Bubble Tea, even in a terminal. Findings/collector failures retain their exit codes. +- Markdown includes severity, rule ID, evidence, limitations, manual suggestions and verification text + from the same report/registry. Escape hostile labels, pipes, HTML, links and backtick/fence sequences; + never turn captured commands or paths into executable behavior or active content. +- Do not present missing/denied/redacted evidence as a healthy result. Show degraded collectors and + skipped rules alongside findings. Export progress/timings must not corrupt stdout formats. +- Resize, cancellation and output failure must restore terminal state and release timers/goroutines. + An interactive rendering failure must have an explicit failure/fallback path, not discard the report. + +## Bundle format and bounds + +The zip is a versioned sharing format, separate from the existing fixture-directory snapshot contract. +Proposed v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and +optional structured `diagnostics.json`. A manifest records bundle/schema/tool versions, original capture +time, redaction policy, omitted evidence and member names/sizes/digests. Digests detect corruption; +they do not authenticate the machine or its author. + +Retain the PLAN's under-2-MB requirement: define this as **fewer than 2,000,000 compressed bytes**. +The proposal also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented +per-member, JSON-depth/token and string bounds. Enforce limits before allocation/decompression where +possible and while streaming. A too-large capture fails explicitly; no partial archive or silently +truncated evidence is published. Stage output locally and replace it atomically after successful checks. + +Read archives as data without extraction. Reject unsupported versions/methods, encrypted or ZIP64 input +unless explicitly supported, duplicate/unknown member names, directory/symlink entries, absolute paths, +drive/UNC names, backslash paths and traversal. Bound compressed data, directory metadata, decompressed +bytes and parse work independently. Verify member integrity and required schemas before diagnosis. +Never follow member paths, load a plugin, execute a verification/fix command or fetch a URL from a bundle. + +## Export/redaction policy + +Today's report redaction removes home paths and credential-bearing URLs, but retains effective Git +identity. Copying an existing JSON report is not a sharing policy. Define a separate allowlisted export +model before implementation, including the treatment of each field needed by ENV001–ENV012. + +- Exclude raw environment values, tokens, usernames/emails, hostname, original home paths, process + arguments, project file contents and arbitrary logs. Tool versions may be normalized metadata only. +- Sanitize or omit free text, paths, URL components, errors, notices, hints and report metadata before + writing any member. Build report JSON/Markdown from sanitized evidence, rather than embedding the + original report and relying on a final string-replacement pass. +- Preserve diagnostic distinctions where possible with nonidentifying facts or capture-local opaque + replacements. If removing an identity/path loses required evidence, mark it omitted and skip or report + the dependent rule as inconclusive; absence caused by redaction is not proof of a missing setting. +- Apply the same policy to optional tool diagnostics. `--include-logs` must not collect shell history, + arbitrary files or unstructured command output; specify its allowlisted meaning or leave it unsupported. +- Test synthetic secrets/identities through every exported member, entry name, error path and stdout/ + stderr, including encoded URLs, Windows/Unix paths and degraded collectors. An unsupported field + cannot fall back to raw export. Describe the actual policy and its limits; do not promise universal + secret detection or that every arbitrary future string is safe to publish. + +## Offline diagnosis and CLI behavior + +`diagnose --from-bundle FILE` loads validated exported evidence and evaluates the current builtin registry +without running collectors, git/Docker, PATH tools, project scripts or network probes. Do not inspect +the receiving host to fill capture gaps. Retain original capture time/platform and identify captured +evidence, current evaluator version and omissions. Captured findings are reference data; recomputed +findings come from validated evidence, not the saved report's verdict or instructions. + +Keep `--fixture-dir` unchanged. Define mutual exclusion with `--from-bundle` and live-evidence arguments +(`--port`, `--probe-network`, `--package-manager`). Output/evaluation filters may remain available. +Invalid usage exits 4; malformed/unsupported/bounded-out bundles or I/O failure exit 3. Valid offline +diagnosis uses the existing finding/degraded exit mapping 0/1/2/3, including redaction-related omissions. +The proposed writer exits 0 when it successfully publishes an archive; the captured report retains its +own diagnosis exit code, even if degraded. Settle that new-command distinction before coding. + +## Dependency order + +| Task | Work | Prerequisites | +|---|---|---| +| ENV-024 | Renderer selection, plain fallback, Bubble Tea and Markdown | Accepted format/TTY/exit policy; M3 report/registry | +| ENV-025 | Versioned allowlisted export, bounded zip writer/reader and redaction cases | Accepted bundle schema/security policy; ENV-024 report formats | +| ENV-026 | Offline `--from-bundle`, source/omission reporting and CLI tests | ENV-025; accepted evidence/flag/exit semantics | + +## Acceptance and future evidence + +- [ ] Non-TTY, redirected stdout/stderr, dumb terminals, `NO_COLOR`, explicit plain, JSON and Markdown + combinations have deterministic CLI tests; structured output contains no ANSI/progress contamination. +- [ ] A real interactive run handles narrow width, resize, interrupt and output failure without leaving + the terminal altered or retaining goroutines/timers after exit. +- [ ] Markdown goldens cover every severity, collector errors, omitted evidence, hostile HTML/links, + pipes/backticks and long paths, without changing finding order or severity. +- [ ] Every successful bundle is below 2,000,000 compressed bytes; exact boundary/oversize cases, + atomic output failure and independent decompression/entry/parse limits are tested. +- [ ] The export policy removes synthetic tokens, raw environment values and identities from all members + and diagnostics, including Git identity, errors and optional logs; unknown export fields fail closed. +- [ ] Malformed, corrupt, duplicate, traversal/symlink, compressed-bomb and unsupported-version archives + are rejected without extraction or unbounded memory growth. +- [ ] Windows/Linux/macOS captures can be diagnosed on another OS offline; retained evidence reproduces + applicable results while redacted prerequisites remain explicitly inconclusive. +- [ ] Offline diagnosis executes no collectors/commands/network calls, ignores saved verdict instructions, + distinguishes original capture/evaluator versions and rejects conflicting live-evidence flags. +- [ ] Existing 172 golden cases, M3 JSON/schema/exit, registry generation, purity, probe and race gates pass. +- [ ] Terminal dependencies are pinned/audited; canonical build/test/lint/race/docs gates and + native Windows/Ubuntu/macOS CI pass for the final M4 branch. +- [ ] One README screenshot is captured from the implemented interactive CLI with synthetic identities. +- [ ] The eventual M4 validation record maps every criterion to executed cases, commands, limits and skips. + +Use existing `make test`, `make race`, `make lint`, `make build` and `make check-docs`, with Go 1.26.11. +Native Windows race needs the x64 GCC configuration in [M3 validation](../testing/m3-validation.md). +Add archive/redaction/renderer/CLI cases during implementation; they do not exist by virtue of this plan. +Profile repeated bundle read/write, cancellation and renderer lifecycles with synthetic captures, retaining +the existing diagnosis time/memory budgets. Application checks were not rerun for this preparation. + +## Handoff + +First settle the sharing schema and omissions, then the renderer/CLI flags; add reviewed redaction and +archive abuse fixtures before the writer/reader. Preserve accepted ADRs and generated rule pages. +M4 implementation and publication require a later request; this preparation changes documents only. From 32da338b5bca57f687d9da05a3a1e66afdcc2e5e Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:38:03 +0530 Subject: [PATCH 2/5] docs(adr): accept M4 report and bundle contracts --- CONTRIBUTING.md | 2 +- docs/ARCHITECTURE.md | 4 +- docs/DEVELOPMENT-TOOLS.md | 2 +- docs/PLAN.md | 20 +-- docs/adr/0006-m4-reports-and-bundles.md | 185 +++++++++++++++++------- docs/adr/README.md | 2 +- docs/phases/M4.md | 14 +- 7 files changed, 151 insertions(+), 78 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9462f76..a72520e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Thanks for taking the time. This document is deliberately short and specific. 3. [docs/adr/](docs/adr/) - decisions that have already been argued about. Do not relitigate them without a new ADR. 4. [docs/phases/M4.md](docs/phases/M4.md) - planned reports/bundles, dependency order and acceptance gates; - preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADR 0005. ADR 0006 remains proposed. + preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADRs 0005/0006. 5. [docs/DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) - CodeGraph freshness, static-analysis coverage and profiling appropriate to this repository's runtime. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 79b0e56..4794c19 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -94,8 +94,8 @@ and Linux race suites passed locally; native Windows/Ubuntu/macOS tests and race ## M4 preparation -[M4 requirements](phases/M4.md) and [proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare +[M4 requirements](phases/M4.md) and [accepted ADR 0006](adr/0006-m4-reports-and-bundles.md) define Bubble Tea/plain/Markdown output and bounded versioned bundles. A separate export policy must remove identifying/free-text data and expose resulting evidence omissions. Offline bundle diagnosis evaluates captured facts under the current registry without inspecting the receiving machine. These paths are -planned; existing plain/JSON/fixture contracts remain the implemented behavior. +being implemented on `feat/m4-implementation`; existing plain/JSON/fixture contracts remain compatible. diff --git a/docs/DEVELOPMENT-TOOLS.md b/docs/DEVELOPMENT-TOOLS.md index e0670fe..1fcafe9 100644 --- a/docs/DEVELOPMENT-TOOLS.md +++ b/docs/DEVELOPMENT-TOOLS.md @@ -3,7 +3,7 @@ Initial audit: 2026-11-14; M3 verification refresh: 2026-11-15. These are development aids, not product features or substitutes for tests. Read [PLAN.md](PLAN.md), the [M4 requirements](phases/M4.md), implemented [M3 contract](phases/M3.md) -and accepted [ADRs](adr/) first. M4 ADR 0006 remains proposed. +and accepted [ADRs](adr/) first. M4 ADR 0006 is accepted; implementation evidence is still pending. ## CodeGraph diff --git a/docs/PLAN.md b/docs/PLAN.md index e2974b8..9ae0663 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,7 +12,7 @@ depends_on: - No runtime dependencies (single static binary) - Docker (optional, only for testing rules that inspect Docker) created: 2026-11-13 -updated: 2026-11-17 +updated: 2026-11-19 --- # EnvDoctor — Implementation Plan @@ -31,9 +31,9 @@ merged at `6cf358138ecd3bedf086f22536a30562fb673e4e`; its was accepted and committed before implementation. The [M3 requirements](phases/M3.md) define the evidence and acceptance contract; [M3 validation](testing/m3-validation.md) records the final commands and limits. The [development-tool audit](DEVELOPMENT-TOOLS.md) records actual coverage and profiling limits. -M4 is **Not started**. [M4 requirements](phases/M4.md) and -[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare report formats, bundle export/redaction -and offline diagnosis; they do not claim new commands or acceptance results. +M4 is **in progress** on `feat/m4-implementation`, including the published preparation commit `2be420a`. +[M4 requirements](phases/M4.md) and accepted [ADR 0006](adr/0006-m4-reports-and-bundles.md) define +formats, allowlisted bundle export and offline diagnosis. No M4 acceptance result is claimed yet. ```yaml project: EnvDoctor @@ -300,8 +300,8 @@ Implemented as of M3: `diagnose`, `version`, offline `explain` and `rules`/`rule `bundle` and `fix` remain planned; see section 0 for the authoritative list. Unknown rule IDs and invalid metadata arguments exit 4; output failures exit 3. -M4 format/plain/bundle-input flags and bundle command semantics are proposed in -[ADR 0006](adr/0006-m4-reports-and-bundles.md). They are not implemented. Bundle export must use a +M4 format/plain/bundle-input flags and bundle command semantics are accepted in +[ADR 0006](adr/0006-m4-reports-and-bundles.md). Implementation is in progress. Bundle export must use a separate sharing policy; ordinary JSON continues to include effective Git identity. | Exit code | Meaning | @@ -520,8 +520,8 @@ tests and records local measurements without claiming M6 clean-host/release cove **Deliverable:** polished terminal output (Bubble Tea when TTY), Markdown export, `bundle` command. -Status: **Not started; documentation prepared.** Follow [M4 requirements](phases/M4.md) and resolve -[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) before dependent code. Bundle input/export has +Status: **In progress; ADR 0006 accepted before dependent code.** Follow [M4 requirements](phases/M4.md) and +[accepted ADR 0006](adr/0006-m4-reports-and-bundles.md). Bundle input/export has its own version/redaction/omission policy; copying the current report is not sufficient. **Acceptance criteria** @@ -705,7 +705,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. 1. Read sections 0, 3 and 9. Ten minutes. 2. `make build && ./bin/envdoctor diagnose`; compare what it prints with section 0's `functional` field. 3. Pick the next unchecked item in the current milestone. Rules come with fixtures or they do not come. - M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 remains proposed. This preparation - authorizes documents only; implementation needs a later request and accepted export/CLI decisions. + M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 is accepted. Implementation was requested + on 2026-11-19; preserve the accepted export/CLI decisions and verify each acceptance gate. 4. Run `make test` — golden fixtures will tell you immediately if a rule change broke another platform. 5. Never add a fix without the safety model. If in doubt, print the command instead of running it. diff --git a/docs/adr/0006-m4-reports-and-bundles.md b/docs/adr/0006-m4-reports-and-bundles.md index 714a6e5..dedc5b3 100644 --- a/docs/adr/0006-m4-reports-and-bundles.md +++ b/docs/adr/0006-m4-reports-and-bundles.md @@ -1,68 +1,141 @@ # ADR 0006 — M4 report formats and shareable diagnostic evidence -- Status: proposed; documentation only -- Date: 2026-11-17 +- Status: accepted +- Proposed: 2026-11-17; accepted: 2026-11-19 - Required by: [M4 requirements](../phases/M4.md), ENV-024–ENV-026 -- Would extend: ADRs 0004/0005 with a separate bundle export/offline-input contract +- Extends: ADRs 0004/0005 with a separate bundle export/offline-input contract ## Context -M3 plain/JSON reports and fixture-directory diagnosis are implemented. Report JSON intentionally retains -Git identity; home/credential-URL redaction is not a general sharing scrubber. The PLAN requires zip -bundles below 2 MB without raw environment values, tokens or usernames, yet does not specify a format, -decompression limit or how removed evidence affects pure rules. A saved report is not evidence of the -receiving machine, and bundled suggestions are untrusted strings rather than commands to run. - -## Recommended design, pending acceptance - -1. Use one renderer selection path over the existing report. Propose `--format text|markdown|json`, with - current `--json` retained as an alias and an explicit plain choice for terminal use. JSON/Markdown - never enter Bubble Tea. Default non-TTY output stays plain and stable; dumb terminals/NO_COLOR use - plain fallback. Conflicting explicit formats exit 4 before collection. -2. Add a separate versioned allowlisted export model and redaction policy. Export only bounded diagnostic - facts with identifying/free-text fields sanitized or omitted. Generate every report member from that - export. Preserve omissions as explicit evidence limitations; dependent rules cannot treat redaction - as proof that a setting is missing. Existing ordinary JSON/fixture formats remain compatible. -3. Bundle v1 is a zip with manifest, snapshot, JSON/Markdown reports and normalized tool versions; optional - diagnostics are the tool's own allowlisted structured notices. No arbitrary log files are read. - The manifest records capture/tool/schema/redaction versions and member sizes/digests. It is integrity - metadata, not a machine attestation or authentication mechanism. -4. Publish only complete archives below 2,000,000 compressed bytes, at most eight entries and 8 MiB total - decompressed data. Bound each member and JSON parser separately. Reject overflow rather than truncating - evidence or relaxing the budget. Read expected members directly without filesystem extraction. -5. `--from-bundle` evaluates exported captured evidence under the current registry, records capture and - evaluator versions and exposes omissions. It executes no collectors/commands/network work and cannot - trust a saved verdict. Live-evidence flags and fixture input are mutually exclusive with bundle input. -6. Preserve diagnosis exits 0/1/2/3/4. Propose writer exit 0 for a successfully published archive, storing - the capture's own exit code inside it; usage is 4 and archive/tool/I/O failures are 3. Valid offline - diagnosis can still exit 3 for captured degradation or missing required export evidence. - -## Choices that must be resolved before acceptance - -- Field-by-field export schema for all twelve rules, including Git identities, proxy endpoints, runtime - and dependency paths, errors and rule prerequisites. Decide where opaque local replacements preserve - comparison and where omission requires explicit inconclusive evaluation. -- Report/source metadata and schema-version compatibility, capture-local replacement stability, JSON - duplicate/depth/token/string limits and exact manifest/member schemas. Do not alter fixture v1 silently. -- Per-member limits and supported zip methods/features; bounded directory preflight, size/integrity - validation, archive errors and output replacement behavior on Windows and POSIX. -- Final format/plain flags, TTY stream detection, NO_COLOR precedence, cancellation semantics and the - writer-vs-diagnosis exit distinction. Document current JSON behavior before adding new formats. -- Pinned Bubble Tea/terminal dependencies, Markdown escaping, native terminal test method, and whether - optional structured diagnostics can meet the same export policy. Unsupported log export stays absent. +M3 plain/JSON reports and fixture-directory diagnosis are implemented. Ordinary JSON intentionally +retains effective Git identity. Home/credential-URL redaction is not a sharing policy. Bundles must be +smaller than 2 MB, remove identifying/raw data and preserve the meaning of absent diagnostic evidence. +Saved reports are reference data, not verdicts or instructions to execute on another machine. + +## Decision + +Implement ENV-024–ENV-026 below. Preserve collectors, twelve builtin rules, registry pages, fixture-v1 +input, ordinary JSON and diagnosis exits. No command in this phase applies a fix. + +### Formats and terminal lifecycle + +- `diagnose --format text|markdown|json` selects an explicit format. `--json` remains a JSON alias. + `--plain` forces text, as does explicit text. `--json --format json` is compatible; conflicting + formats, plain with JSON/Markdown and unknown formats exit 4 before collection. +- Without an explicit format/plain choice, use Bubble Tea only when stdin, stdout **and stderr** are + terminals, TERM is not `dumb`, and NO_COLOR is not set. Missing TERM on Windows does not preclude a + terminal. Pipes, redirects and non-file test streams fall back to stable plain output. JSON/Markdown + bypass the viewer. Verbose collector timings remain on stderr. +- Pin `github.com/charmbracelet/bubbletea v1.3.10` and `golang.org/x/term v0.48.0`; commit exact + transitive module versions/checksums and audit/review licenses before completion. +- The viewer scrolls the completed report, handles narrow dimensions/resize and uses an alternate screen. + Quit returns the diagnosis exit; interruption/render failure returns 3. Every exit restores terminal + state and prints the plain report. Output errors cancel the viewer and propagate as failures. + No viewer action executes advice, collects evidence or changes a finding. +- Text makes terminal controls visible. Markdown emits repository-owned structure and escapes dynamic + punctuation/controls, including HTML, links, fences and commands/paths. Include severity/ID, evidence, + limitations, manual advice/verification, degraded collectors and skipped prerequisites from the same + report/registry. Missing evidence is not displayed as healthy. + +### Separate sharing snapshot + +Bundle snapshots have a separate version-1 typed allowlist. Convert approved facts into existing pure +engine input; generate JSON/Markdown/versions from that evidence, never from saved finding text. + +| Captured field | Sharing representation and rule effect | +|---|---| +| Timestamp/platform | Original UTC capture time; known OS/architecture, elevation and bounded numeric version metadata. Unknown platform stays absent/degraded. | +| Shell | Known shell-name enum; path removed. Unknown names are unavailable with an omission. | +| PATH | Order/existence/directory/duplicate facts; raw locations become capture-local opaque path tokens. | +| Runtimes | Python/Node names, numeric versions, known manager/resolution enums and active/expected/missing facts. Exact path aliases preserve comparisons; separate normalized environment aliases preserve ENV011 equality under the captured OS. | +| Requested ports/listeners | Port/protocol/state facts; PID/process labels omitted. Ownership detail is unavailable while ENV005 can still detect an occupied requested port. | +| Docker | Installed/local probe/API-range/override facts and numeric versions. Selected context names/endpoint URLs omitted; they never select a connection target. | +| Git | Version, identity-checked and nonempty-name/email **presence booleans**, autocrlf policy and opaque origin markers. Reconstruct fixed presence markers for ENV010; redaction is not an unset identity. | +| Dependencies | Supported tool/library names, present/missing/unknown status, opaque paths/project/requirements markers and allowed Git policy. Keep supported package-manager names/exact versions and known lockfile names. | +| Python environment | Metadata-known and capture-local canonical environment tokens; no receiving-host canonicalization or lookup. | +| Proxies | Known variable/scheme/port/probe facts; original host/URL become capture-local `.invalid` aliases. No userinfo, hostname, path, query or fragment. Offline evaluation never resolves/dials aliases. | +| Failures/timings | Known collector identifier, bounded milliseconds and a fixed unavailable notice. Original errors/stdout/stderr/free-text logs omitted. | +| Report/tool metadata | Fixed tool name and normalized version metadata. Captured findings/advice come from the builtin registry after export, not the original report's free text. | + +Aliases are deterministic in field traversal order and local to a capture; they contain no hash or raw +path/identity. They preserve only the documented equality and are not filesystem locations. Omissions +use fixed field/reason identifiers. Removing required evidence marks that collector unavailable and +skips dependent rules under existing prerequisites. Removing non-prerequisite labels stays visible +without fabricating an error. Unknown/future export fields fail closed; unsupported values are omitted +or rejected rather than copied through. + +No raw environment values, tokens, usernames/emails, hostname, home paths, process arguments, project +contents or arbitrary logs are exported. This is a current-field allowlist, not universal secret +detection. Numeric versions/ports, platform and diagnostic facts still describe the captured setup. + +### Bundle v1 and independent bounds + +Required ZIP members: `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json`. +Optional `diagnostics.json`: `bundle --include-logs` means only allowlisted structured collector +statuses/timings, never shell history, files or command output. Every member uses the sharing policy. + +The manifest identifies bundle/snapshot/report/redaction/tool versions, original capture time and +diagnosis exit, omissions, and every other member's exact size/SHA-256. It excludes its own digest. +Digests detect corruption; they do not authenticate a machine/author. The exported report exposes the +original exit as reference metadata and its recomputed exit, including omitted-prerequisite degradation. + +| Limit | Contract | +|---|---| +| Compressed archive, including directory | Fewer than **2,000,000 bytes** | +| Total decompressed members | At most **8 MiB** | +| Entries | At most eight; exactly five required names plus optional diagnostics | +| Manifest / versions | At most 64 KiB each | +| Snapshot / Markdown | At most 2 MiB each | +| JSON report / diagnostics | At most 3 MiB / 512 KiB | +| JSON work | One document; no duplicate/unknown fields; depth ≤32, tokens ≤200,000, strings ≤4,096 UTF-8 bytes; arrays ≤4,096 elements | +| Evidence collections | PATH ≤1,024; runtimes ≤128; listeners/requested ports ≤1,024; dependencies ≤32; proxies ≤3; errors ≤32; omissions ≤256 | + +Preflight file/directory limits before constructing an unbounded ZIP/JSON graph; enforce actual +streamed decompressed sizes. Accept only Store/Deflate regular entries. Reject encryption, +ZIP64/multi-disk/unsupported flags, extra/comment records, duplicate/unknown or nonliteral names, +directories/symlinks, absolute/drive/UNC/backslash/traversal paths, inconsistent local/central headers, +overlaps, size/digest/CRC mismatches and trailing data. Never extract. Validate required structures and +cross-member capture metadata before evaluation. + +An oversized capture fails explicitly without truncation, partial publication or relaxed limits. +Stage a private temporary file beside the requested destination, finish/sync/close and validate it, +then replace the named regular destination by same-directory rename (Windows replacement API). +Never follow a destination symlink. Failure/cancellation removes only the owned temporary file and +keeps the previous destination. Atomic namespace replacement assumes a supporting local filesystem; +network-filesystem semantics and power-loss durability are not guarantees of this format. + +### Commands, provenance and exits + +- `bundle --output FILE` defaults to `envdoctor-bundle.zip`; `-o` is an alias. Existing capture controls + `--fixture-dir`, `--port`, `--probe-network`, `--package-manager` and optional `--include-logs` apply. + It captures the complete builtin report; format/rule filters do not select archive members. + Successful publication exits 0 and prints bounded status/byte count, even for captured warnings/errors/ + degradation. Capture/archive/cancellation/output/I/O failures exit 3; usage exits 4. +- `diagnose --from-bundle FILE` validates and evaluates sharing evidence using the current builtin registry. + It runs no collectors, PATH/Git/Docker/project commands, home/path inspection or network work. Preserve + capture time/platform, label capture-tool/current-evaluator versions, and expose omissions. Saved + verdicts/suggestions/Markdown are reference members and cannot influence evaluation. +- Bundle input conflicts with fixture input and requested-port/network-probe/package-manager live flags. + Format/component/rule/verbose filters remain available. Fixture behavior, including its existing + requested-port selection, stays unchanged. Invalid combinations fail before I/O. +- Malformed/unsupported/bounded-out/corrupt input and read failures exit 3; usage exits 4. Valid offline + evaluation preserves 0/1/2/3, including 3 for unavailable required evidence. Bundle errors have fixed + reason text and do not interpolate untrusted fields/member names/captured errors. +- Ordinary JSON remains schema v1 with existing fields/values and Git identity. Optional bundle-source + metadata is absent from ordinary runs and documented as a compatible report-schema addition. ## Alternatives considered -- Zip the current report: retains Git identity and unreviewed free text; does not meet bundle policy. -- Remove fields without omission metadata: can turn a real configuration into a false missing-setting - finding or a falsely healthy result when dependent evidence disappears. -- Extract a supplied zip before diagnosis: introduces path/symlink hazards with no need for extraction. -- Run captured verification commands: lets untrusted bundles execute on the maintainer's machine and - confuses captured evidence with a new observation. Pure offline evaluation is sufficient. +- Zip ordinary JSON: retains identity/unreviewed free text and fails the sharing contract. +- Remove paths/identities without presence/equality/omissions: causes false missing-setting or healthy results. +- Extract ZIP or run captured commands: unnecessary filesystem/execution authority; pure evaluation suffices. +- Reuse saved verdicts: loses evaluator provenance and turns untrusted instructions into findings. ## Consequences and validation -ENV-024 explicitly includes Markdown. ENV-025 must implement a strict writer and reader plus an evidence -sharing policy before ENV-026 can reuse them. Size/redaction/abuse/cross-OS fixtures, terminal cleanup, -existing JSON/golden/probe regressions and native CI gates are required by the phase document. -This record remains a proposal and does not authorize edits to accepted ADRs or claim implementation. +Renderer/Markdown cases precede export. Add reviewed redaction/archive-abuse cases before writer/reader +and offline CLI. Verify all original 172 cases, strict schemas, deterministic cross-OS evidence, privacy +across every member/error, exact size boundaries and rejection cleanup. Measure repeated archive/viewer +lifecycles using synthetic captures. Record native terminal/Windows/Ubuntu/macOS CI, dependency/licenses +and a real interactive screenshot separately from cross-builds/model-only tests. Check acceptance boxes +only after named evidence exists. diff --git a/docs/adr/README.md b/docs/adr/README.md index 485d16b..ae1361b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -9,7 +9,7 @@ Each file records one decision that was expensive to make and would be expensive | [0003](0003-go-126-floor-and-ci-contract.md) | Go 1.26 floor and CI contract | accepted | | [0004](0004-m2-collectors-and-rules.md) | M2 collectors and rules | accepted, scoped extensions in 0005 | | [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted; merged M3 | -| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | proposed; no implementation | +| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | accepted; implementation in progress | New ADRs are numbered sequentially and never edited after acceptance. A changed mind gets a new ADR that supersedes the old one. diff --git a/docs/phases/M4.md b/docs/phases/M4.md index a5db8cc..63f2e74 100644 --- a/docs/phases/M4.md +++ b/docs/phases/M4.md @@ -1,12 +1,12 @@ # M4 requirements: terminal reports and diagnostic bundles -Status: **Not started; documentation prepared 2026-11-17.** No M4 command, renderer or test result is claimed. +Status: **In progress on `feat/m4-implementation`, 2026-11-19.** No M4 acceptance result is claimed yet. Baseline: merged M3 main commit `6cf358138ecd3bedf086f22536a30562fb673e4e`, [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with successful [main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). Read the [plan](../PLAN.md), [architecture](../ARCHITECTURE.md), [M3 requirements](M3.md) and accepted [ADR 0005](../adr/0005-m3-evidence-and-rule-registry.md). -[ADR 0006](../adr/0006-m4-reports-and-bundles.md) is proposed; resolve its export and CLI choices first. +[ADR 0006](../adr/0006-m4-reports-and-bundles.md) was accepted before dependent implementation. ## Scope and compatibility @@ -38,13 +38,13 @@ bounded live opt-in. No export or offline input enables a command supplied by a ## Bundle format and bounds The zip is a versioned sharing format, separate from the existing fixture-directory snapshot contract. -Proposed v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and +Accepted v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and optional structured `diagnostics.json`. A manifest records bundle/schema/tool versions, original capture time, redaction policy, omitted evidence and member names/sizes/digests. Digests detect corruption; they do not authenticate the machine or its author. Retain the PLAN's under-2-MB requirement: define this as **fewer than 2,000,000 compressed bytes**. -The proposal also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented +ADR 0006 also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented per-member, JSON-depth/token and string bounds. Enforce limits before allocation/decompression where possible and while streaming. A too-large capture fails explicitly; no partial archive or silently truncated evidence is published. Stage output locally and replace it atomically after successful checks. @@ -88,8 +88,8 @@ Keep `--fixture-dir` unchanged. Define mutual exclusion with `--from-bundle` and (`--port`, `--probe-network`, `--package-manager`). Output/evaluation filters may remain available. Invalid usage exits 4; malformed/unsupported/bounded-out bundles or I/O failure exit 3. Valid offline diagnosis uses the existing finding/degraded exit mapping 0/1/2/3, including redaction-related omissions. -The proposed writer exits 0 when it successfully publishes an archive; the captured report retains its -own diagnosis exit code, even if degraded. Settle that new-command distinction before coding. +The writer exits 0 when it successfully publishes an archive. The original diagnosis exit remains +reference metadata; the exported report records its recomputed exit, including omitted prerequisites. ## Dependency order @@ -133,4 +133,4 @@ the existing diagnosis time/memory budgets. Application checks were not rerun fo First settle the sharing schema and omissions, then the renderer/CLI flags; add reviewed redaction and archive abuse fixtures before the writer/reader. Preserve accepted ADRs and generated rule pages. -M4 implementation and publication require a later request; this preparation changes documents only. +M4 implementation was requested on 2026-11-19. Publication/CI remains separate acceptance work. From c532dc33bd16271fb19298cf600a5dd6b05cceb9 Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Thu, 19 Nov 2026 04:19:27 +0530 Subject: [PATCH 3/5] feat(m4): add terminal reports and redacted offline bundles --- cmd/envdoctor/main.go | 16 +- docs/images/m4-terminal.jpg | Bin 0 -> 67960 bytes docs/schema/bundle-common-v1.schema.json | 238 +++++++ docs/schema/bundle-diagnostics-v1.schema.json | 46 ++ docs/schema/bundle-manifest-v1.schema.json | 85 +++ docs/schema/bundle-report-v1.schema.json | 37 ++ docs/schema/bundle-snapshot-v1.schema.json | 627 ++++++++++++++++++ docs/schema/bundle-versions-v1.schema.json | 50 ++ docs/schema/diagnose-v1.schema.json | 111 +++- docs/testing/fixtures/m4-viewer/snapshot.json | 21 + go.mod | 21 +- go.sum | 47 +- internal/bundle/archive.go | 385 +++++++++++ internal/bundle/archive_test.go | 326 +++++++++ internal/bundle/compression_test.go | 132 ++++ internal/bundle/export.go | 528 +++++++++++++++ internal/bundle/export_test.go | 161 +++++ internal/bundle/file.go | 130 ++++ internal/bundle/file_test.go | 104 +++ internal/bundle/file_unix.go | 8 + internal/bundle/file_windows.go | 39 ++ internal/bundle/file_windows_test.go | 65 ++ internal/bundle/json.go | 196 ++++++ internal/bundle/model.go | 198 ++++++ internal/bundle/model_coverage.go | 47 ++ internal/bundle/parser_test.go | 65 ++ internal/bundle/roundtrip_test.go | 213 ++++++ internal/bundle/schema_test.go | 129 ++++ internal/bundle/validate.go | 274 ++++++++ internal/cli/bundle.go | 61 ++ internal/cli/cli.go | 84 ++- internal/cli/diagnose.go | 117 +++- internal/cli/m4_test.go | 330 +++++++++ internal/config/config.go | 4 + internal/report/document.go | 16 + internal/report/format.go | 70 ++ internal/report/interactive.go | 230 +++++++ internal/report/interactive_test.go | 167 +++++ internal/report/json.go | 16 +- internal/report/m4_test.go | 144 ++++ internal/report/markdown.go | 155 +++++ internal/report/testdata/markdown-m4.golden | 54 ++ internal/report/text.go | 12 +- tests/terminal/main_windows.go | 150 +++++ 44 files changed, 5853 insertions(+), 56 deletions(-) create mode 100644 docs/images/m4-terminal.jpg create mode 100644 docs/schema/bundle-common-v1.schema.json create mode 100644 docs/schema/bundle-diagnostics-v1.schema.json create mode 100644 docs/schema/bundle-manifest-v1.schema.json create mode 100644 docs/schema/bundle-report-v1.schema.json create mode 100644 docs/schema/bundle-snapshot-v1.schema.json create mode 100644 docs/schema/bundle-versions-v1.schema.json create mode 100644 docs/testing/fixtures/m4-viewer/snapshot.json create mode 100644 internal/bundle/archive.go create mode 100644 internal/bundle/archive_test.go create mode 100644 internal/bundle/compression_test.go create mode 100644 internal/bundle/export.go create mode 100644 internal/bundle/export_test.go create mode 100644 internal/bundle/file.go create mode 100644 internal/bundle/file_test.go create mode 100644 internal/bundle/file_unix.go create mode 100644 internal/bundle/file_windows.go create mode 100644 internal/bundle/file_windows_test.go create mode 100644 internal/bundle/json.go create mode 100644 internal/bundle/model.go create mode 100644 internal/bundle/model_coverage.go create mode 100644 internal/bundle/parser_test.go create mode 100644 internal/bundle/roundtrip_test.go create mode 100644 internal/bundle/schema_test.go create mode 100644 internal/bundle/validate.go create mode 100644 internal/cli/bundle.go create mode 100644 internal/cli/m4_test.go create mode 100644 internal/report/format.go create mode 100644 internal/report/interactive.go create mode 100644 internal/report/interactive_test.go create mode 100644 internal/report/m4_test.go create mode 100644 internal/report/markdown.go create mode 100644 internal/report/testdata/markdown-m4.golden create mode 100644 tests/terminal/main_windows.go diff --git a/cmd/envdoctor/main.go b/cmd/envdoctor/main.go index 3646498..7c21c78 100644 --- a/cmd/envdoctor/main.go +++ b/cmd/envdoctor/main.go @@ -6,7 +6,10 @@ package main import ( + "context" "os" + "os/signal" + "syscall" "github.com/shellghostt/envdoctor/internal/cli" ) @@ -17,10 +20,15 @@ import ( var version = "dev" func main() { + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() os.Exit(cli.Main(os.Args, cli.App{ - Version: version, - Stdout: os.Stdout, - Stderr: os.Stderr, - Getenv: os.Getenv, + Version: version, + Stdin: os.Stdin, + Stdout: os.Stdout, + Stderr: os.Stderr, + Getenv: os.Getenv, + LookupEnv: os.LookupEnv, + Context: ctx, })) } diff --git a/docs/images/m4-terminal.jpg b/docs/images/m4-terminal.jpg new file mode 100644 index 0000000000000000000000000000000000000000..91d20d86e19a0e99e3cf460eed59193a8483d052 GIT binary patch literal 67960 zcmeFZRZv{P*XTQh03lciK?j$Rpuu4VNrFotKyV8Tn!(*I2@qtkV8KFg_Zi$_aDuxJ zK0t5=z5LIq`_+9qbx+lItM0?;{nC4P@9wUymbF&@R^QLuuK=DY$tlVKu&@9CtcM41 zKM#-w;6BE|#d(a2i-U`Yhx_E|v!_q-@t?jRCLw%A`GSgy@&yG24ILW;4UmPFf`XBY zk>w@(YmV2{4BT(HU%g>__4?I+3c
61rw*jU(D
z%z#IvSlFak_gw(m|1=ZlKh6EGfQyCw7zgjslZRB*X8^3nj~@QOd5nkm2pjhi0T$rV
zLnNaI_W5A_6BY@c
0!R#NKi9ITOxZayBd8R|Ea$JO}$udHQDx5HYa{K
ziB^My{Q>A<#9zf;DQYZiE~(rD5Jp;>N_p%9@+1AGK`SCv3w|jnRi3s+_^hr@QY_F>
z{zS|U+GFJ&&=DH^?y(m^wN-QOCfm6|n6Fp=;h_F6Py3#!_vWW9j7xd0H!S)G0K=*9
zTtxJoeD-wlgld8uVm8f!a$KB*H#`^VB;-ts1VU+dnZ-Ets*U-85&o;uV|#y(5Q=yG
zoE=qb3|7fk3(|2bqIX8|3J$k9n|vp}CiuiIsy(&GQXir`c5ff2ws@vdZho3Rnr`*q
zpC{G|T=#HEzG?1v2&!1yyY9Nn4r6P+7I}+4my*pjDxX#3Z^lto{Eq13tI4-@mST{I
z2Qrb>AMkj3IXEif$@?|oWTN*3EJK-5@s
CGkXOB#%g
z|5Ba1+w}lb!uL{)DpmT!IjFPo)0+T5jsG4Ti+`6D;
B274mR(w@e^rjIYFP3YfW%70oUpUTKvb>x06}2+;?`$
z=b&SG-g1brJeNsAbsXxMb~NSdG>%Q*GJn?~HFV2G;vo3oBzC=`J2T9n`!E&&?=tKh
zhd<$myP~Yq$&6@Es!AZEK`))U+EB~Z$+UUh#@f+#
dV_odpYJg!U#
z$W$Lgr=vK(R##YH?a6icrs{*o`JHHa?x(XUuWeLUwZCPKvX1GzGqN8bCpNnd*`m%M
zY~|Jar1~VbIvd(JSSa9R|8QeK%2hkgYFKV{
z)HD+dRf@@Mno5OcXWSRpH)i8K7?!O-J^@i2*Z#-ElCg(~0pn>$tDTp&zvO4=pS$fm
z)M{JeJFW{C_NoMpWhKVc%Ih6|>R6m6ldLviauz0