[pyjeebz]

Closes #25. Phase 2: fewer things, done well.

None of these were ever released. v0.1.0 shipped ports, find, free, kill, --json, --force and --version, with no --format at all (checked against git show v0.1.0:main.go). So they go with no deprecation cycle:

• ports diff and --format snapshot. They're clever, but they don't answer the question ports exists for.
• --format csv and --format tsv. --json plus jq covers scripts.
• --tree.

That's about 980 lines out. --format is now table or json. --json, --sort, the filters and --watch are unchanged. ports --help lists doctor, find, here, list, stop and wait, and its usage section is 28 lines.

Anyone who tries a removed feature gets a clear exit 2, with stdout empty:

Command	Message
ports diff before.json	unknown command "diff" — run ports --help for the list
ports --tree	unknown flag: --tree
ports --format csv	unknown format "csv" (want table or json)
ports find x --format tsv	the same, before the scan

That last row fixes a quirk found along the way. Listing commands used to check the format only when rendering, so find x --format tsv said "nothing matching" and hid the real problem. find, here, list and --watch now check it before scanning.

One rule for --format. A format that doesn't exist is exit 2 on every command, with or without --json. stop used to let --json win over a bad format; the reviewer caught the inconsistency.

How it was verified

• Gate, locally with CI's versions: unit ✓, build ✓, integration ✓ (uncached), installers ✓, gofmt ✓, vet ✓, lint ✓ (v2.13.2). Site: npm run lint ✓, npm run build ✓.
• The docs check (docs: every documented command parses, and the site's terminals match the CLI #20) now asserts the cut. ports diff before.json and ports --tree are on its must-fail list, so they can't creep back into the docs.
• Tests that only covered removed features are gone: TestDiffCommand, the tree tests and the TSV pin test.
• Tests for surviving behaviour moved: TestSortFlag reads the table instead of csv, and the exit-code and watch-rejection cases use commands and flags that still exist.

Risk

Tier: risky (internal/inspect/output.go, --format values).
Public surface: removed commands, flags and formats that were never released. --json output is unchanged.
Rollback: revert the squash commit.

A fresh-context review said ok to ship. It confirmed nothing removed was released, and that the man pages, shell completion and site links have no leftovers. Its should-fixes are the second commit:

• the --json + bad --format inconsistency (now one rule);
• an exit-code case still using --tree;
• a stale comment.

Notes for the release

--format takes table or json.

---

Generated by Claude Code