Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and

### Added

- M4 ENV-024–ENV-026: scrolling Bubble Tea reports with plain fallback, explicit
`--format text|markdown|json`, `--plain` and escaped, bounded Markdown export.
- Version-1 diagnostic bundles with typed allowlisted sharing evidence, opaque path/host aliases,
Git identity presence facts, explicit omissions, strict archive/JSON bounds and atomic publication.
`--include-logs` contains only structured collector statuses/timings.
- Offline `diagnose --from-bundle`, recomputing current builtin findings from validated evidence with
capture/evaluator provenance and no collectors or network work.
- Accepted [ADR 0006](docs/adr/0006-m4-reports-and-bundles.md), sharing schemas, archive/privacy/renderer/
CLI tests, a real terminal capture and [M4 validation](docs/testing/m4-validation.md).
Local gates and native M4 Windows/Ubuntu/macOS GitHub CI passed;
[PR #4](https://github.com/Shellghostt/EnvDoctor/pull/4) is open for review.
- 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.
Expand All @@ -21,7 +32,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.

Expand All @@ -35,6 +46,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and

### Changed

- Optional bundle-source metadata extends report schema v1 and stays absent from ordinary reports.
- Terminal dependencies are pinned/audited, including Bubble Tea v1.3.10, x/term v0.48.0,
x/sys v0.50.0 and x/text v0.44.0; see [M4 dependency review](docs/testing/m4-dependencies.md).
- Optional M3 snapshot evidence extends schema v1 compatibly; project and rule-registry JSON have
separate version-1 schemas. Explicit typed partial collector evidence retains degraded notices
and disables dependent rules.
Expand Down Expand Up @@ -72,7 +86,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and

### Planned

- M4 reports and bundles; later rules ENV013–ENV018, confirmed fixes and signed releases.
- Rules ENV013–ENV018, confirmed fixes and signed releases.

## [0.1.0] - 2026-11-13

Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) - report/bundle contracts, dependency order and acceptance gates;
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.

Expand All @@ -36,6 +36,8 @@ the CLI and runs all 172 golden cases through it, including the unchanged 54 M2
Each new rule needs positive, negative and edge snapshots for Windows, Linux and macOS. Expected
findings are reviewed evidence, not output regenerated from the implementation. See
[M3 validation](docs/testing/m3-validation.md) for native Windows and Linux race commands and limits.
[M4 validation](docs/testing/m4-validation.md) records terminal, sharing, archive, offline and resource
cases. M4 local gates and native Windows/Ubuntu/macOS GitHub CI pass.
Windows race tests need a 64-bit MinGW-w64-compatible GCC configured in Go's CC/CXX; ordinary static
builds use `make build`, which disables CGO only for that target.

Expand Down
94 changes: 78 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,21 @@

> A cross-platform CLI that detects, diagnoses and helps resolve development environment problems.

![status](https://img.shields.io/badge/status-M3_complete-green)
![status](https://img.shields.io/badge/status-M4_verified-green)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
![Go](https://img.shields.io/badge/go-1.26-00ADD8?logo=go&logoColor=white)

**Status: M3 complete on `feat/m3-implementation`; Windows, Ubuntu and macOS CI passed.**
**Status: M1–M3 merged; M4 implemented and verified on `feat/m4-implementation`.**
Native Windows/Ubuntu/macOS race, tests and builds, lint and the vulnerability scan passed in
[M4 CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/44421272870).
[PR #4](https://github.com/Shellghostt/EnvDoctor/pull/4) is open for review.
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.
Reports support a scrolling terminal viewer, plain text, Markdown and versioned JSON.
Redacted diagnostic bundles can be evaluated offline; `explain` and `rules --json` also work offline.
Diagnosis never applies fixes or executes interpreters found on PATH. The
[M3 validation record](docs/testing/m3-validation.md) records commands, live checks and limits.
[M4 validation record](docs/testing/m4-validation.md) records commands, live checks and limits;
[M3 validation](docs/testing/m3-validation.md) preserves the merged baseline evidence.

## Why this exists

Expand All @@ -35,8 +40,8 @@ explains the cause instead of dumping raw output.
| Detect virtualenv/interpreter mismatch | M3 | **Implemented**, known canonical environment metadata |
| Inspect proxy configuration and optional reachability | M3 | **Implemented**, redacted and offline by default |
| Explain rules and export the rule registry | M3 | **Implemented**, no collectors invoked |
| Generate diagnostic bundles | M4 | Not started |
| Human-readable reports | M2/M4 | **Done** plain text; interactive polish is M4 |
| Generate redacted diagnostic bundles and evaluate them offline | M4 | **Implemented and verified** locally and in native CI |
| Human-readable reports | M2/M4 | Plain text, scrolling terminal viewer and escaped Markdown |
| JSON export | M1 | **Done** |
| Safe, opt-in automated remediation | M5 | Not started |
| Windows, Linux and macOS support | M2/M6 | Three-OS code and fixtures; signed release/clean-host verification is M6 |
Expand All @@ -49,7 +54,10 @@ flowchart TD
COL --> SNAP[Typed snapshot and redaction]
SNAP --> ENGINE[Pure diagnostic engine]
REG[Rule registry] --> ENGINE
ENGINE --> REPORT[Plain text or JSON with manual advice]
ENGINE --> REPORT[Terminal, text, Markdown or JSON report]
SNAP --> BUNDLE[Allowlisted sharing evidence and bounded ZIP]
BUNDLE --> OFFLINE[Validated captured evidence]
OFFLINE --> ENGINE
META[explain and rules] --> REG
REG --> PAGES[Generated rule pages]
```
Expand Down Expand Up @@ -110,6 +118,51 @@ in the test suite; the snapshot inside it is described by
[docs/schema/snapshot-v1.schema.json](docs/schema/snapshot-v1.schema.json). Home directories are replaced
with `~`, and credential-bearing URLs are redacted before anything is written.

## Terminal reports and sharing bundles

The default report opens a scrolling viewer when stdin, stdout and stderr are terminals. Use arrows,
Page Up/Page Down and `q`; quitting retains the diagnosis exit code and leaves a plain report behind.
Interrupts and rendering failures exit 3 and restore terminal state. Redirects, `TERM=dumb`, `NO_COLOR`
(including an empty value), `--plain` and explicit text select plain output.

![EnvDoctor M4 terminal viewer](docs/images/m4-terminal.jpg)

This is real Windows PTY output from the implemented CLI, displayed in xterm.js with the committed
synthetic [viewer fixture](docs/testing/fixtures/m4-viewer/snapshot.json). Its identities and paths are
examples. The browser display is a captured terminal preview; native console restoration and resize
were checked separately.

```powershell
.\bin\envdoctor.exe diagnose --plain
.\bin\envdoctor.exe diagnose --format markdown > diagnosis.md
.\bin\envdoctor.exe diagnose --format json > diagnosis.json
.\bin\envdoctor.exe bundle --output envdoctor-bundle.zip --include-logs
.\bin\envdoctor.exe diagnose --from-bundle envdoctor-bundle.zip --json
```

JSON and Markdown bypass the viewer. `--json` remains an alias for `--format json`; conflicting formats
or `--plain` with JSON/Markdown exit 4 before collection. Markdown includes evidence, manual suggestions,
verification, limitations, degraded collectors and skipped prerequisites, with dynamic markup escaped.

Bundle export uses a separate typed allowlist: Git identity becomes presence booleans, paths and hosts
become deterministic capture-local aliases, and unsupported required evidence is explicitly omitted and
degraded. Raw environment values, identities, project contents and free-text logs/errors are excluded.
`--include-logs` adds only structured collector statuses and bounded timings. Numeric versions, ports and
diagnostic facts still describe the captured setup; review the bundle before sharing it.

The ZIP is below 2,000,000 bytes, with independent member, decompression and JSON-work bounds. Publication
stages a private file and replaces the destination atomically after validation. The bounded `Writing...`
status precedes replacement; exit 0 confirms publication, including captures with findings or degradation.
Usage exits 4; capture, archive, cancellation, output and file failures exit 3.

`--from-bundle` validates evidence and evaluates the current builtin rules without collectors or network
work. It preserves capture provenance and omissions; saved verdicts and commands remain reference data.
It conflicts with `--fixture-dir`, `--port`, `--probe-network` and `--package-manager`. Valid offline
diagnosis retains exits 0/1/2/3, including 3 for unavailable required evidence. Ordinary JSON keeps its
existing fields and Git identity; bundle-source metadata is an optional addition used by offline reports.
Read [ADR 0006](docs/adr/0006-m4-reports-and-bundles.md) and the
[sharing schemas](docs/schema/bundle-snapshot-v1.schema.json) for the exact policy and limits.

Exit codes: `0` nothing at or above warning, `1` warnings, `2` at least one error, `3` the tool itself failed
(including a collector timeout), `4` invalid usage. Captured collector errors retain exit 3 during offline
diagnosis. A degraded report still contains the findings that could be evaluated.
Expand Down Expand Up @@ -188,7 +241,7 @@ Different Docker product versions alone do not establish API incompatibility. Wi
opaque shims and protected package paths remain unresolved metadata.

Home paths and credential-bearing URLs are redacted, including error notices. JSON includes Git identity;
review it before sharing. Diagnostic bundles with broader redaction remain M4.
review it before sharing. Use the M4 bundle command for the separate allowlisted sharing representation.

## Testing

Expand All @@ -206,8 +259,10 @@ The suite includes 172 exact golden cases, preserving all 54 original M2 snapsho
It builds the CLI and checks those cases through real subprocesses, validating JSON and exit codes.
Native Windows and Linux race suites passed locally. The native Windows, Ubuntu and macOS race/test/build
matrix, lint and vulnerability scan passed in [M3 CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978).
Both macOS architectures also cross-build. Commands, allocation measurements,
socket lifecycle evidence and limits are in [docs/testing/m3-validation.md](docs/testing/m3-validation.md).
M4 passes local Windows/Linux race, all canonical targets, bounded fuzzing, archive/privacy tests and
all six static build targets. Native Windows/Ubuntu/macOS M4 CI also passed. Commands, terminal evidence,
allocation measurements and limits are in [M4 validation](docs/testing/m4-validation.md);
[M3 validation](docs/testing/m3-validation.md) records the earlier socket and CI evidence.

`make docs` regenerates all twelve rule pages from the same registry as findings, `explain` and `rules`.
`make check-docs` and CI detect documentation drift. Do not edit generated pages directly.
Expand All @@ -218,7 +273,8 @@ A local release build of all six targets:
goreleaser build --snapshot --clean
```

`goreleaser check` and the local six-target snapshot build passed. A snapshot build does not publish a release.
M3 validation records the passing GoReleaser check and six-target snapshot build. M4 verifies static
builds separately; packaging, signed releases and clean-host checks remain M6.

## Repository layout

Expand All @@ -230,9 +286,10 @@ goreleaser build --snapshot --clean
| `internal/config` | Resolved options, schema version, collector timeout |
| `internal/collector` | Parallel runner and nine collectors, including project and proxy evidence |
| `internal/diagnostic` | Rule registry, pure engine, severity model, fixture harness |
| `internal/report` | Terminal renderer, JSON renderer |
| `internal/report` | Terminal lifecycle, plain text, Markdown and JSON renderers |
| `internal/bundle` | Allowlisted export, strict bounded reader and atomic publication |
| `internal/fix` | Remediation plans, dry-run by default (empty until M5) |
| `internal/system` | Thin wrappers over OS facilities, the only place syscalls live |
| `internal/system` | Machine-inspection wrappers; bundle file I/O and terminal control have separate boundaries |
| `docs/schema` | Committed JSON schemas, enforced by tests |
| `tests/golden` | 172 snapshot-to-diagnosis fixtures |
| `tests/integration` | Built CLI tests against all golden cases |
Expand All @@ -241,16 +298,21 @@ 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.
M4 ENV-024–ENV-026 are implemented and verified under the
[M4 requirements](docs/phases/M4.md) and [accepted ADR 0006](docs/adr/0006-m4-reports-and-bundles.md).
[Validation](docs/testing/m4-validation.md) records local evidence and passing native GitHub CI;
[PR #4](https://github.com/Shellghostt/EnvDoctor/pull/4) is open for review.

| 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 | Terminal viewer, Markdown, redacted bundles and offline diagnosis | Verified; [PR #4](https://github.com/Shellghostt/EnvDoctor/pull/4) open |
| M5 | Safe, confirmed automated remediation | Not started |
| M6 | Windows, Linux, macOS packaging and signed releases | Not started |

Expand Down
16 changes: 12 additions & 4 deletions cmd/envdoctor/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@
package main

import (
"context"
"os"
"os/signal"
"syscall"

"github.com/shellghostt/envdoctor/internal/cli"
)
Expand All @@ -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,
}))
}
Loading
Loading