diff --git a/README.md b/README.md index 9dc5f4b..4f4ada2 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,8 @@ ![Code Health against a project folder: deptry 1, vulture 0, ruff 56, grouped by file with rule codes and "fixable" badges on the ones ruff can repair itself.](screenshot/health.png) +![The About tab: version 1.0.0, licence GPL-3.0-only, the SHA-256 the legal-document acceptance was recorded against, a button that puts the first-run screen back, and two contact addresses with copy buttons.](screenshot/about.png) +
Environments, Updates, Search, Pins, Settings @@ -104,7 +106,9 @@ pipdock snapshot rollback latest | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Crate layout, Engine trait, IPC surface, storage | | [docs/DATA-FLOW.md](docs/DATA-FLOW.md) | State machines for update / install / uninstall, engine command mapping | | [docs/UI-SPEC.md](docs/UI-SPEC.md) | Terminal-tech design system, screens, click budgets | -| [docs/CLI-SPEC.md](docs/CLI-SPEC.md) | Commands, flags, exit codes, JSON contracts | +| [docs/CLI-GUIDE.md](docs/CLI-GUIDE.md) | **Start here for the CLI** — what to type, in the order you need it | +| [docs/CLI-SPEC.md](docs/CLI-SPEC.md) | The CLI contract: every flag, exit code and JSON shape | +| [docs/AI-DISCLOSURE.md](docs/AI-DISCLOSURE.md) | Which AI model helped build this, what it did, and how it was reviewed | | [docs/CODE-HEALTH-SPEC.md](docs/CODE-HEALTH-SPEC.md) | deptry / vulture / ruff integration | | [docs/ERROR-CATALOG.md](docs/ERROR-CATALOG.md) | Error codes, stderr detection patterns, user guidance | | [docs/SECURITY.md](docs/SECURITY.md) | Threat model, PEP 668 policy, supply-chain hygiene | @@ -114,6 +118,14 @@ pipdock snapshot rollback latest | [docs/ROADMAP.md](docs/ROADMAP.md) | Spike week, milestones, exit criteria | | [legal/](legal/) | EULA, Disclaimer, Privacy Policy, Third-Party Notices (linked by the in-app legal gate) | +## How this was built + +PipDock was written with substantial help from an AI coding assistant — **Claude Opus 5**, made by [Anthropic](https://www.anthropic.com), through [Claude Code](https://claude.com/claude-code) — under human review. It wrote source code, tests, debugging work and the Vietnamese translation. Every change reached `main` through a pull request the maintainer read and merged, `main` is protected and cannot be bypassed, and the built application was driven by hand on three machines before 1.0.0 shipped. + +That review mattered: **thirty-four defects** reached or nearly reached `main`, and not one was caught by the test suite that was green at the time. They were found by running the thing. + +Copyright and the GPL-3.0-only licence are unchanged. The full statement — model, vendor, what was and was not delegated, and how to verify any of it from `git log` — is in [docs/AI-DISCLOSURE.md](docs/AI-DISCLOSURE.md). + ## License Copyright © 2026 Kokone (poli0981). PipDock is free software under **GPL-3.0-only** — see [LICENSE](LICENSE). The legal documents in [legal/](legal/) are committed publicly so the in-app legal gate and the About tab can link to them on GitHub. diff --git a/crates/pipdock-cli/src/run.rs b/crates/pipdock-cli/src/run.rs index 00cbf6a..80536b3 100644 --- a/crates/pipdock-cli/src/run.rs +++ b/crates/pipdock-cli/src/run.rs @@ -1353,10 +1353,13 @@ pub async fn report_bug(opts: &GlobalOpts) -> Result { println!("{url}"); if !opts.quiet { + // Concatenated rather than a multi-line literal: a bare string literal keeps the source + // indentation, which shipped this line with fourteen stray spaces in the middle of a + // sentence. Found by reading the actual output while writing docs/CLI-GUIDE.md. eprintln!( - " -Open that in a browser to review the prefilled issue. Nothing is sent until you submit it yourself. -Check the log excerpt for paths or names you would rather not make public." + "\nOpen that in a browser to review the prefilled issue. \ + Nothing is sent until you submit it yourself.\n\ + Check the log excerpt for paths or names you would rather not make public." ); } Ok(Exit::Success) diff --git a/docs/AI-DISCLOSURE.md b/docs/AI-DISCLOSURE.md new file mode 100644 index 0000000..6665e38 --- /dev/null +++ b/docs/AI-DISCLOSURE.md @@ -0,0 +1,95 @@ +# AI disclosure + +*Last updated 2026-08-14, for PipDock 1.0.0.* + +**PipDock was written with substantial help from an AI coding assistant, under human review.** This +page says which model, what it did, what it did not do, and how you can check any of it yourself. + +It exists because the fact is not obvious from the outside and you should not have to infer it from +commit trailers. Nothing here changes the licence or the warranty position — see +[`legal/EULA.md`](../legal/EULA.md) for those. + +## The model + +| | | +|---|---| +| Model | **Claude Opus 5** | +| Vendor | **Anthropic** ([anthropic.com](https://www.anthropic.com)) | +| Interface | [Claude Code](https://claude.com/claude-code), Anthropic's CLI/desktop coding agent | +| Period | 2026-07-27 → 2026-08-14 (first commit to 1.0.0) | + +Earlier work in the same repository used earlier Claude models; the trailer on each commit records +which one, and `git log` is the authoritative history. + +## What it was used for + +- **Source code** — Rust core, CLI, Tauri bridge, React frontend. Most of the implementation. +- **Tests** — unit, integration and the CLI golden snapshots. +- **Debugging** — reading failing CI logs, reproducing defects, and diagnosing them. +- **Translation** — the Vietnamese catalogue (`ui/src/locales/vi/`), reviewed by a native speaker + who is also the project owner. +- **Documentation** — the specifications under `docs/`, this page included. + +## What review meant in practice + +Every change reached `main` through a pull request that the owner read and merged. Beyond reading +diffs, four things were load-bearing, and all four caught real defects the review-by-reading did +not: + +1. **A green test suite was never sufficient.** Thirty-four defects reached `main` or nearly did, + and *not one* was caught by the suite that was green at the time. They were found by running + the thing — against a real interpreter, a real CI runner, a real browser, a real installer. + `docs/ROADMAP.md` records each one against the stage it was found in. +2. **Specifications were treated as claims, not facts.** Several were wrong about the tools they + described: all three Code Health tools exit non-zero on findings and vulture uses 3; deptry + reports a *module* name rather than the distribution providing it; ruff's rule URL is keyed by + rule name, not code. Each is now pinned by a test because a document was not enough. +3. **CI is a second reviewer that cannot be talked round.** `cargo clippy -D warnings`, + `cargo audit`, `npm audit`, CodeQL, and integration tests against real pip and uv in disposable + venvs, all blocking on every pull request. `main` is protected and the owner cannot bypass it. +4. **The owner drove the built application by hand** before 1.0.0 — on a real machine, in Windows + Sandbox and in a Windows 10 VM — following `docs/TESTING.md` §4's charter. Several defects were + found that way and only that way. + +## What was not delegated + +- **Product decisions.** Scope, the feature matrix, the non-goals, and what 1.0 would and would not + ship are the owner's. So is the decision to remove the self-updater, which is why PipDock has no + auto-update path (see [`SECURITY.md`](SECURITY.md) §5). +- **Merging, tagging and publishing.** Every release is a human action. +- **Anything requiring a legal or security judgment** was raised for a decision rather than taken — + for example the PEP 668 override's default, and whether a `mailto:` scheme belonged in the + browser-launch allowlist. + +## Copyright and licence + +Copyright in PipDock is held by **Kokone (poli0981)**, and the work is licensed **GPL-3.0-only**. +Using an AI assistant does not change either. Commits carry a +`Co-Authored-By: Claude Opus 5 ` trailer as an accurate record of how the +work was produced — it is attribution, not an assignment of rights, and Anthropic claims no +ownership of output produced with its models. + +## Third-party code + +PipDock's dependencies are other people's work under their own licences, listed in +[`legal/THIRD-PARTY-NOTICES.md`](../legal/THIRD-PARTY-NOTICES.md). Nothing in this repository was +copied from another project. Where an approach came from upstream documentation or a specification +— PEP 508, PEP 440, PEP 668, PEP 691, PEP 514 — the relevant document is cited in the code or in +`docs/`. + +## Checking any of this + +```bash +git log --format='%h %an %s' # every commit and its author +git log --format=%b | grep -c 'Co-Authored-By' # how many carry the trailer +gh pr list --state merged # every change, and the review it went through +``` + +At 1.0.0: **172 commits, 163 of them carrying the trailer.** The remainder are Dependabot bumps and +a handful of hand-written mechanical commits. + +## Questions + +`code@poli0981.dev`, or open a discussion at +[github.com/poli0981/pipdock](https://github.com/poli0981/pipdock/discussions). If you think +something in this page is inaccurate, that is worth an issue. diff --git a/docs/CLI-GUIDE.md b/docs/CLI-GUIDE.md new file mode 100644 index 0000000..79b45dd --- /dev/null +++ b/docs/CLI-GUIDE.md @@ -0,0 +1,343 @@ +# PipDock CLI — a guide + +`docs/CLI-SPEC.md` is the contract: every flag, every exit code, every JSON shape. This is the +guide — what you actually type, in the order you would need it. + +Everything here was run against `pipdock 1.0.0` on Windows. Where a number or a code appears, it +came out of a real invocation, not out of the spec. + +--- + +## Installing it + +The installer puts `pipdock.exe` next to the GUI, in `%LOCALAPPDATA%\PipDock\`. **PipDock does not +edit your `PATH`.** Add that folder yourself if you want to type `pipdock` from anywhere: + +```powershell +$dir = "$env:LOCALAPPDATA\PipDock" +[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));$dir", 'User') +``` + +Open a new terminal afterwards — the current one keeps the old `PATH`. + +```powershell +pipdock --version +``` + +--- + +## The two flags that apply to everything + +**`--env `** picks the interpreter. It accepts either the interpreter itself +(`C:\proj\.venv\Scripts\python.exe`) or the environment directory (`C:\proj\.venv`). Omit it and +PipDock uses the last environment you selected, falling back to a `.venv` in the working directory. + +**`--json`** switches to machine-readable output. Streaming commands emit NDJSON — one JSON +document per line — so a long update can be consumed as it runs rather than at the end. + +Two more worth knowing early: + +- **`-y` / `--yes`** assumes the default answer at every prompt. Conflicts resolve to **skip**, + never to force. There is deliberately no flag that makes `--yes` mean "force latest". +- **`--engine pip|uv`** overrides the configured engine for one invocation, without changing your + setting. + +--- + +## Finding environments + +```powershell +pipdock env list +``` + +Discovery covers venvs in the working directory, the PEP 514 registry and the `py` launcher. Real +output on a machine with two registry Pythons: + +```json +[ + { + "envHash": "06a8abde…", + "externallyManaged": false, + "hiddenUserSite": "C:\\Users\\you\\AppData\\Roaming\\Python\\Python314\\site-packages", + "interpreter": "C:\\Python314\\python.exe", + "packages": 352, + "pipVersion": "26.2.1", + "python": "3.14.7", + "source": "registry" + } +] +``` + +**`hiddenUserSite` is not an error.** PipDock reads a non-venv Python in isolated mode, which skips +the per-user site-packages directory — so its package count can be lower than `pip list`. The field +is non-null exactly when that applies, and null inside a venv. See CLI-SPEC §7. + +**`venv_scan` matches exactly four directory names**: `.venv`, `venv`, `env`, `.env`. A virtual +environment called anything else is invisible to `env list`, and you have to name it with `--env`. + +Make one the default so you can stop typing `--env`: + +```powershell +pipdock env use C:\proj\.venv +``` + +--- + +## Looking before you touch anything + +```powershell +pipdock list +pipdock list --outdated +``` + +`list` is local and fast. `--outdated` asks PyPI for each package's latest release, so it is the +networked one — on a 352-package environment it is the slower of the two by a wide margin. + +```powershell +pipdock doctor +``` + +`doctor` checks the engine, the interpreter and the environment's sanity, and **exits 1 when it +finds real problems** rather than 0 with a warning. That is what makes it usable as a gate. + +--- + +## Updating + +```powershell +# Everything outdated. Pins still apply. +pipdock update --all + +# Named packages only. +pipdock update requests urllib3 + +# See the plan, change nothing. +pipdock update --all --dry-run +``` + +Every mutating command runs the engine in dry-run first, prints what would change, takes a +snapshot, and only then executes. `--dry-run` stops after the first step. + +### When a version conflict appears + +```powershell +pipdock update --all --strategy compatible # default: take the resolver's compatible version +pipdock update --all --strategy latest # force the latest, breaking whatever depends on it +``` + +`--strategy latest` off a TTY requires an explicit acknowledgement — it will not silently break an +environment because a script passed `--yes`. + +### Excluding things for one run + +```powershell +pipdock update --all --except black,mypy +``` + +`--except` is additive on top of the pin list; it does not replace it. + +--- + +## Installing and removing + +```powershell +pipdock install requests +pipdock install "django==5.0.1" +pipdock install requests --dry-run +``` + +Specs are `name` or `name==version`. Names are validated against PEP 508 and versions against PEP +440 **before** they reach a command line — PipDock never builds a shell string, so there is nothing +for a crafted package name to escape into. + +```powershell +pipdock uninstall requests +``` + +Removal runs the reverse-dependency guard first. If something still needs the package, the command +**stops and exits 2** rather than removing it. `--force` proceeds anyway, and prints what will +break before it does. + +--- + +## Pins + +A pin excludes a package from bulk updates. It is per-environment. + +```powershell +pipdock pin add numpy --reason "pytorch build is pinned to this" +pipdock pin list +pipdock pin remove numpy +``` + +Pins are enforced at the plan boundary, not in the display layer — an update that would move a +pinned package never reaches the engine. + +--- + +## Snapshots and rollback + +A snapshot is taken automatically before every batch. You can also take one by hand: + +```powershell +pipdock snapshot create +pipdock snapshot list +pipdock snapshot diff +pipdock snapshot rollback +pipdock snapshot rollback latest +``` + +Two things worth knowing before you rely on this: + +- **`diff` lists entries a rollback cannot restore** — editable installs and direct-URL installs. + That is deliberate: they are excluded from the pin set and reported separately rather than + silently dropped. Restoring an editable install means re-running `pip install -e` yourself. +- **A rollback snapshots the current state first**, so one rollback creates a second timeline + entry. The trigger label on each entry is how you tell them apart — `latest` moves twice. + +--- + +## Code Health + +```powershell +pipdock health +pipdock health --path C:\proj +pipdock health --tool ruff --tool vulture +pipdock health --fix +``` + +deptry, vulture and ruff run from PipDock's own isolated tools environment, never from the +environment being inspected — so analysing a project never installs anything into it. + +**`health` exits 1 when it finds something.** A linter that exits 0 on findings is useless in a +pre-commit hook, so this is the intended behaviour, not a failure. + +`--fix` applies **ruff's safe fixes only**, and prompts first. It is the one operation in PipDock +that writes outside site-packages and `%LOCALAPPDATA%` — it rewrites your source. There is no +snapshot for it, because no snapshot in PipDock describes a source tree; your version control is +the safety net, and the confirm says so. It refuses entirely, before writing a byte, if any target +file cannot be written. + +The tools environment is built on first use. To manage it directly: + +```powershell +pipdock tools status +pipdock tools sync +``` + +Two facts about the tools that are pinned by tests because the specs had them wrong: all three +exit non-zero on findings (**vulture uses 3**), and **deptry reports a module name, not the +distribution that provides it** — `PIL`, not `pillow`. deptry also cannot be told which environment +to compare against, which is disclosed wherever its findings are shown. + +--- + +## Search and metadata + +```powershell +pipdock index refresh +pipdock search hello +pipdock info requests +``` + +`search` runs against a locally cached PyPI name index (PEP 691) — no network per keystroke. The +index is around 864,000 projects and 42 MB on the wire; `index refresh` re-pulls it. + +--- + +## pip upkeep + +```powershell +pipdock pip-upgrade +``` + +Upgrades pip **inside the selected environment**, which PipDock is otherwise careful never to +modify without a plan. Worth knowing: every pip below 22.2 is broken on Python 3.12+ +(`distutils`, `pkgutil.ImpImporter`), so the one case this command exists for is also a pip that +cannot run — it falls back to `ensurepip`, and decides by asking `pip --version` rather than by +matching a traceback. + +--- + +## Scripting it + +### Exit codes + +Verified by running, not copied from the spec: + +| Code | Meaning | +|---|---| +| 0 | success | +| 1 | completed with per-package failures — see `counts.failed` in the JSON; **or `health`/`doctor` found something** | +| 2 | plan aborted, nothing executed (resolution impossible, or the uninstall guard tripped without `--force`) | +| 3 | environment error, including a PEP 668 block | +| 4 | engine unavailable or too old | +| 5 | snapshot failed — **nothing was executed** | +| 6 | network or index error | +| 10 | internal error; the log path is printed | +| 130 | cancelled (Ctrl-C); child processes are reaped and a partial summary is printed | + +Code **5** is the one to special-case in CI: it means the snapshot could not be written, so PipDock +refused to run the plan at all. Nothing changed. + +### Pinning against the JSON shapes + +```powershell +pipdock schema ResolutionReport +pipdock schema ExecutionSummary +pipdock schema HealthReport +``` + +`schema` prints the JSON Schema for a core type, generated from the same Rust definitions the +commands serialize — so a script can validate against it instead of guessing. An unknown type name +exits 1. + +### A CI-shaped invocation + +```powershell +pipdock update --all --env C:\proj\.venv --strategy compatible --yes --json +``` + +`--yes` with `--strategy compatible` never forces anything; a package that cannot be updated +compatibly is skipped and reported, and one failure does not abort the batch — you get +`"13 successful, 2 failed"` with a reason per package. + +**`--no-snapshot` exists and you almost certainly do not want it.** It is the only documented +escape from the snapshot-before-mutation rule, it prints a warning, and it is there for throwaway +CI containers that have nothing to roll back to. + +### Isolating the store + +Every path PipDock writes lives under `%LOCALAPPDATA%\PipDock\data\`. Point `LOCALAPPDATA` +somewhere else and you get a throwaway store — useful for testing a workflow without touching your +real index, settings or snapshots: + +```powershell +$env:LOCALAPPDATA = 'C:\tmp\pipdock-test' +pipdock env list +``` + +--- + +## When something goes wrong + +Every user-visible failure carries exactly one catalog code — `PD-ENV-001`, `PD-NET-002`, and so +on. `docs/ERROR-CATALOG.md` lists all 34, what causes each and what to do about it. The code is +stable; the message around it is localised. + +```powershell +pipdock --verbose --log-file pipdock.log update --all +pipdock self report-bug +``` + +`self report-bug` prints a prefilled GitHub issue URL carrying the version, OS and engine. +**Nothing is transmitted** — you open it, read what it filled in, and submit it yourself. + +--- + +## See also + +- [CLI-SPEC.md](CLI-SPEC.md) — the contract: exhaustive flags, JSON shapes, exit codes +- [ERROR-CATALOG.md](ERROR-CATALOG.md) — all 34 codes and what to do about each +- [SECURITY.md](SECURITY.md) — threat model, PEP 668 policy, what PipDock connects to +- [CODE-HEALTH-SPEC.md](CODE-HEALTH-SPEC.md) — how deptry, vulture and ruff are invoked diff --git a/screenshot/about.png b/screenshot/about.png new file mode 100644 index 0000000..d82a56c Binary files /dev/null and b/screenshot/about.png differ diff --git a/ui/src/locales/en/common.json b/ui/src/locales/en/common.json index a9c6e35..650231d 100644 --- a/ui/src/locales/en/common.json +++ b/ui/src/locales/en/common.json @@ -345,6 +345,9 @@ "license": "Licence", "docsHash": "Legal documents", "docsHashDetail": "Your acceptance is recorded against this value. Editing any of the documents changes it, and the acceptance screen appears once more on the next launch.", + "aiTitle": "How this was built", + "aiBody": "PipDock was written with substantial help from an AI coding assistant — Claude Opus 5, made by Anthropic — under human review. It wrote source code, tests and translations; every change was read and merged by the maintainer, and the built application was driven by hand before release. Copyright and the GPL-3.0-only licence are unchanged.", + "aiRead": "Read the full disclosure", "openRepo": "Open the repository", "reopen": "Show the documents again", "reopenDetail": "Puts the first-run screen back so you can read the five documents. It changes nothing: your acceptance stays as it is, and closing that screen returns you here.", diff --git a/ui/src/locales/vi/common.json b/ui/src/locales/vi/common.json index 99dcea3..e615bb4 100644 --- a/ui/src/locales/vi/common.json +++ b/ui/src/locales/vi/common.json @@ -317,6 +317,9 @@ "license": "Giấy phép", "docsHash": "Tài liệu pháp lý", "docsHashDetail": "Việc bạn chấp nhận được ghi lại kèm giá trị này. Sửa bất kỳ tài liệu nào cũng làm nó đổi, và màn hình chấp nhận sẽ hiện lại một lần ở lần mở tiếp theo.", + "aiTitle": "Ứng dụng này được làm ra thế nào", + "aiBody": "PipDock được viết với sự hỗ trợ đáng kể của một trợ lý lập trình AI — Claude Opus 5, do Anthropic phát triển — dưới sự rà soát của con người. Nó viết mã nguồn, kiểm thử và bản dịch; mọi thay đổi đều do người bảo trì đọc và hợp nhất, và bản dựng hoàn chỉnh được chạy tay trước khi phát hành. Bản quyền và giấy phép GPL-3.0-only không thay đổi.", + "aiRead": "Đọc bản công bố đầy đủ", "openRepo": "Mở kho mã nguồn", "reopen": "Xem lại các tài liệu", "reopenDetail": "Đưa màn hình chạy lần đầu trở lại để bạn đọc năm tài liệu. Nó không thay đổi gì cả: việc bạn đã chấp nhận vẫn giữ nguyên, và đóng màn hình đó sẽ đưa bạn về đây.", diff --git a/ui/src/screens/PdAbout.tsx b/ui/src/screens/PdAbout.tsx index e6121e9..2d10bb2 100644 --- a/ui/src/screens/PdAbout.tsx +++ b/ui/src/screens/PdAbout.tsx @@ -38,6 +38,15 @@ const CONTACT = { /** The one page listing every other channel. Scoped in `capabilities/external-links.json`. */ const LINKS = 'https://poli0981.dev/links/' +/** + * The AI disclosure, in the app rather than only in the repository. + * + * Someone who installs PipDock and never opens GitHub is exactly the person the disclosure is for, + * and `docs/` is not a place they will look. It sits under *This build* because that is where the + * other facts about how this binary came to exist already are. + */ +const DISCLOSURE = `${REPO}/blob/main/docs/AI-DISCLOSURE.md` + function CopyableAddress({ address, label }: { address: string; label: string }) { const { t } = useTranslation() const [copied, setCopied] = useState(false) @@ -103,7 +112,21 @@ export function PdAbout() { -
+

{t('about.aiTitle')}

+

{t('about.aiBody')}

+

+ +

+ +