5 Commits
Author SHA1 Message Date
poli0981andClaude Opus 5.5 7124227262 docs: the specs say what the code does; 1.4.0 recorded, with its audit backlog
Every spec checked against the code rather than against itself, in four passes that each read the
branch's commits and then the source:
- CLI-SPEC/CLI-GUIDE: one JSON document per command (with the per-command table and the paths
  that print nothing), environment selection, logging, Ctrl-C and exit 130, the prompts as they
  are rather than the [A]bort and countdown that never existed, `.heldBack`, a `pipdock audit`
  section, and the rules every mutating command now follows.
- ARCHITECTURE/DATA-FLOW/ERROR-CATALOG: the Engine trait's real signatures, Requires-Python's
  three checkpoints, store v4 and the log folder, §7's return types and events, the state machine
  with re-probing and Force latest, where each §9 invariant is enforced, and 35 codes in 32 rows.
- SECURITY/TESTING/RELEASE-CI/CODE-HEALTH-SPEC: the PEP 668 override as built, four browser hosts
  and the exact capability set, attested releases, the new CI, the tools constraints, and test
  tiers that describe what runs rather than what was planned.
- UI-SPEC/PRD/README/I18N: the screens as they render, the keyboard, tokens and their contrast
  sweep, the feature matrix's status, attestation instructions, and I18N's one stated exception.

ROADMAP gets the 1.4.0 record — what was wrong, what running found that reading did not, what was
deliberately not done — and the **Audit backlog**: every finding not fixed, with where it is and
why it waited. CLAUDE.md's counts and contradictions are corrected, with the rules this release
left behind. changelog/1.x.md has the 1.4.0 entry, including "Changed for scripts" and "You will
see this once". AI-DISCLOSURE, README and About say which model and who released what. The legal
documents' effective date moves to the release date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5 57c365e36a feat(ui): About — what PipDock is, and a way back to the documents you accepted
UI-SPEC §4 has specified *Legal & About* since the spec was written, as a section
inside Settings, and four milestones shipped without it. That is what folding a
read-only surface into a screen of controls does. It is now the ninth tab.

**The ninth tab cost nothing.** `App.tsx` reads `NAV_KEYS[key - 1]`, so appending
`about` made it Ctrl+9 without moving one existing binding. UI-SPEC's warning was
about *inserting* — which is still true, and is still why Snapshots is a mode of
Environments: it would have to sit beside Environments to read as related. The
comments in four files said "a ninth entry would renumber Ctrl+1..8"; they now say
what the rule actually is.

Contents: what PipDock does and what it does not collect; version and the legal-docs
hash from `app_info` — a command that has existed since M1 with no consumer, so the
version on screen cannot drift from CARGO_PKG_VERSION; the SPDX identifier
`GPL-3.0-only` rather than the looser "GPL-3.0" elsewhere; a control that puts the
gate back; and contact.

**Addresses are copied, not opened.** `mailto:` would widen the opener capability by
a whole URL scheme, and the scope's real job is bounding the two call sites that pass
data — one of which hands over a URL that came out of ruff's JSON. Clipboard-write is
already granted, works with no mail client, and the address has to be on screen
anyway. Only `https://poli0981.dev/*` was added, for the links page. They are also TS
constants rather than catalog entries: an address is data (I18N §2), and a catalog is
a thing a translator is invited to change.

**`review` is a flag of its own, not `accepted = false`.** Re-using the latter was
one line and would have made a review indistinguishable from a revocation — offering
Accept, and a Decline that closes the application, to someone who wanted to re-read
their privacy policy. The gate takes a presentational prop instead; first-run
rendering is untouched and `PdLegalGate.test.tsx` (its first test, ever) pins that.

Two things found by running rather than by the suite:

- `app_info` fired **twice** per mount under `npm run dev`. StrictMode's doubling is
  dev-only, but it drew attention to the real one: `key={nav}` remounts `<main>`, so
  every visit to About was a fresh call for a value baked in at compile time. Now
  cached per process in `useAppInfo`. Verified against the bridge log: one call.
- The whole seam — About, re-open, Ctrl+3 refused behind the modal, Close, back on
  About — with zero IPC calls, confirming consent is never touched.

VI catalog complete and checked in the running app; the parity gate gets the rest.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 17:32:20 +07:00
poli0981andClaude Opus 5 91ba7bcc19 feat(core): the dirty tree, the third waiver, and PD-PRM-003
`health::fix` — everything that gates PipDock's **first write outside site-packages and
`%LOCALAPPDATA%`**.

DATA-FLOW §9.1 and §9.2 do not reach it. Both are scoped to a mutating **engine** call, and
ruff is a tool run from PipDock's own venv; more to the point, a fix rewrites the user's
*source tree*, which no snapshot in this application describes. A snapshot is a freeze and
§8's rollback is uninstall-the-added/install-the-removed, so one taken to protect source
files would have no consumer that could use it — invariant 2's own argument for the pip
upkeep exemption, a second time. The safety net CODE-HEALTH-SPEC §5 names is the user's own
version control, which is why the dirty finding lives *inside* `FixConsent` rather than
beside it.

`consent_ok` builds the waiver from what the **server** observed, so a frontend claiming a
clean tree against one the server just found dirty is refused. Same shape as `ack_ok`
checking a `GuardAck` against the guard that produced it. A tree that *was* dirty and is
clean by the time the fix runs needs no acknowledgement — the thing waived no longer exists,
and refusing there would cost the user the fix for having committed.

`git --no-optional-locks status --porcelain --untracked-files=no`, and neither flag is
decoration. Plain `git status` refreshes and **writes `.git/index`** on a stat-dirty tree —
writing into the user's repository while checking whether it is safe to write would be a
poor first act for the write path. Untracked files are excluded because `git checkout .`
restores tracked files regardless, so warning about a scratch file is how a warning stops
being read. `None` covers no-repo, no-git, git-failed and timed-out, because all four leave
the caller with the same options.

**A security question answered by running it.** This is the one place PipDock runs a
PATH-resolved program with a user-controlled working directory, so a `git.exe` planted in a
cloned repository would matter if Windows' legacy `CreateProcess` search order applied. I
planted one and watched which ran: the real git. Rust's `Command` does its own resolution and
does not include the current directory. Recorded on the function, with a note to re-check if
the process layer ever changes.

**`PD-PRM-003`, not a reused `PD-PRM-001`.** That code is scoped to site-packages and its
catalogued action is "use a venv", which is nonsense for a read-only `util.py` — the same
class of wrong answer P3 removed when a corrupted `ruff.exe` reported "install the engine".
Raised internally, so it needs no classifier, only a corpus entry.

And the real hazard is worse than mis-coding: **ruff can fail to write a file and still exit
1**, which `is_findings_exit` accepts as a clean run — so the failure can be *silent*, with
the fix reporting success over a file it never touched. `ensure_writable` therefore refuses
the whole fix before the first byte, checking both the read-only attribute and an append
probe for the ACL case. A partial rewrite of a source tree is the worst thing this design can
produce, because nothing here can undo half of one.

The checklist is **nine** places and CLAUDE.md said eight: `HealthReport` embeds `Code`
through `ToolProblem`, so a new code re-blesses four schema goldens, not three. Corrected
there, along with the count in I18N §1 that was already stale.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 46c1936650 feat(i18n): a one-liner for every catalog code, in both locales
**26 of the 32 codes had no copy at all.** A PEP 668 refusal, an MSVC-missing
build failure and a full disk all rendered as "An unexpected error occurred."
with a code beside them — and silently, because `PdErrorRow` falls back
deliberately rather than leaking `PdError.message`, which is English developer
text. Nothing failed; the app simply had nothing to say about five sixths of what
can go wrong.

The codes move to `locales/{en,vi}/errors.json`, merged into the single `common`
namespace at init. I18N §1 named seven namespaces; the app ships one, because a
real second namespace means `t('errors:PD-NET-001')` at every call site —
i18next's `nsSeparator` is `:` — bought with lazy loading a desktop app that
bundles both catalogs cannot use. The error codes still earn their own *file*:
there are 32, they are the only keys whose names are a contract with Rust rather
than with a screen, and keeping them reviewable is worth one import. §1 is
amended to say so rather than left describing something that was never built.

`i18n.test.ts` now checks them against `codes.json`, generated from `Code::ALL`.
A hand-written list in TypeScript would drift the moment a code was added and go
on passing over an incomplete catalog. It asserts both directions — no code
without copy, no copy without a code — and the ≤ 90-char cap I18N §4 states,
which was aspiration until now. Verified by breaking the catalog deliberately:
both directions fail, then pass again once restored.

Adding a code is now an eight-place change, and CLAUDE.md says which eight.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-09 21:46:25 +07:00
poli0981andClaude Opus 5 5e8d78bb27 docs: add design documentation baseline
Commits the full v0.1 design suite written during the design phase:
PRD, architecture, data flow, UI/CLI specs, code-health spec, error
catalog, security, testing, release/CI and i18n docs, plus the roadmap.

The legal documents (EULA, disclaimer, privacy policy, third-party
notices) must be committed publicly because the in-app legal gate links
to their GitHub URLs at first run.

Also adds .gitignore, which the repo was missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 17:08:14 +07:00