From 1f1093aa3dc59a4e562a44d1c6b6116fe5188536 Mon Sep 17 00:00:00 2001 From: markmybytes Date: Tue, 27 Oct 2026 21:56:26 +0800 Subject: [PATCH 1/2] feat(porter): manifest hashes and import preview diff Backups now carry SHA-1 digests of their content in the manifest (hashes: {settings, data}; sha1 computed during export streaming, manifest written last), and the import preview shows a per-target diff between the machine's current content and the backup: settings and data (db + drivers folded) each get an identical/changed/new state with sizes and counts. - pkg/porter: hash fold recipe (UTF-8 byte-length framing, frame-string sort, last-wins arcname dedupe, empty keys omitted), ValidateZip split into a ZIP-only core (imports never re-hash the disk) plus a synchronous live-FS compare that degrades to "unavailable" on read errors; legacy backups without hashes hide the diff rows. - it-claws (separate repo, mirrored there): the same recipe writes hashes when building exports; cross-repo parity is pinned by a golden test on a CJK-arcname fixture. - frontend: diff rows on the preview checklist, `compare` step in the download stepper, re-entrancy guard on validate, en + zh_Hant_HK i18n; bindings regenerated. Verified: go test ./pkg/... green, frontend type-check/lint/vitest (121) green, wails generate clean. --- HANDOFF-porter-preview-diff.md | 83 ++++++ frontend/src/components/ProgressModal.vue | 2 +- frontend/src/components/ProgressStepper.vue | 1 + frontend/src/i18n/en.json | 7 + frontend/src/i18n/zh_Hant_HK.json | 7 + frontend/src/pages/porter.vue | 151 +++++++++-- frontend/wailsjs/go/models.ts | 48 ++++ pkg/porter/action.go | 25 +- pkg/porter/diff_internal_test.go | 109 ++++++++ pkg/porter/hash.go | 133 ++++++++++ pkg/porter/hash_golden_test.go | 20 ++ pkg/porter/manifest.go | 9 + pkg/porter/porter.go | 169 ++++++++++-- pkg/porter/porter_test.go | 279 +++++++++++++++++++- 14 files changed, 983 insertions(+), 60 deletions(-) create mode 100644 HANDOFF-porter-preview-diff.md create mode 100644 pkg/porter/diff_internal_test.go create mode 100644 pkg/porter/hash.go create mode 100644 pkg/porter/hash_golden_test.go diff --git a/HANDOFF-porter-preview-diff.md b/HANDOFF-porter-preview-diff.md new file mode 100644 index 0000000..749f2c7 --- /dev/null +++ b/HANDOFF-porter-preview-diff.md @@ -0,0 +1,83 @@ +# Handoff — Import Preview Diff (manifest hashes) + +Status: implemented + verified, **uncommitted** in both repos. Branch: none yet (install-it is on `main`; PR #76 was merged earlier). + +## Feature + +The Import Preview modal (匯入預覽) now compares the machine's current content against the backup ZIP per import target, using manifest-carried SHA-1 digests. Granularity rule: **one hash per import target** (`ImportOptions`: `settings`, `data`), nothing more. + +## Frozen spec + +`manifest.json` (format_version stays `1`, `exported_at` unchanged) gains: + +```json +"hashes": { "settings": "", "data": "" } +``` + +Recipe (byte-identical in both repos; golden digest below): + +- `settings` = sha1 of the `conf/setting.json` entry/file bytes; last-wins dedupe. +- `data` = fold over entries with arcname `conf/data.db` or under `drivers/` (files only): + 1. dedupe by arcname, **last occurrence wins** + 2. frame = decimal(**UTF-8 byte length** of arcname) + `":"` + arcname + `":"` + per-file-sha1-hex + `"\n"` + 3. sort **full frame strings** lexicographically + 4. sha1 over the concatenation of sorted frames +- Empty key set ⇒ key **omitted** (never `sha1("")`). +- No `contents` hash, no db/drivers split, no mtime/size in hash logic, no `creation_date` field. + +**Cross-repo golden** (pinned in Go `pkg/porter/hash_golden_test.go` and Python `tests/test_hashes.py`): fixture `{conf/data.db, drivers/中文/файл.bin, drivers/gpu/amd.bin}` → `data = cb58163e3c641021b923f1268ff49f09eb8082e5`, `settings = 238d439d319aa77425457bf63cbeb3c48c9e91fa`. + +## Files changed + +### install-it (Go backend + frontend) +- `pkg/porter/manifest.go` — `Hashes struct { Settings, Data string }` added to `Manifest`. +- `pkg/porter/hash.go` (new) — fold recipe, local file/dir hashing, test seam `localFileHashFn`. +- `pkg/porter/action.go` — `toZip`: per-entry sha1 via `io.MultiWriter` during copy, fold after walk, **manifest written last** (order-independence confirmed; aborted exports no longer ship a manifest). +- `pkg/porter/porter.go` — `TargetDiff` value struct (bools + int64 counts/sizes), `ImportPreview.Settings/.Data`; `scanZip` core (ZIP+manifest only) vs `ValidateZip` (core + synchronous live-FS diff); `DownloadAndValidate` sets `step="compare"` + msg before hashing; **imports never re-hash local disk**. +- `pkg/porter/hash_golden_test.go`, `pkg/porter/diff_internal_test.go`, `pkg/porter/porter_test.go` — golden pin, seam tests, settings-only omission test, manifest-last order test. +- `frontend/wailsjs/go/models.ts` — regenerated (`TargetDiff`, `ImportPreview.settings/data`); binding generation clean (no `Not found` warning). +- `frontend/src/pages/porter.vue` — diff state rows on existing Settings/Data checklist lines (`identical`/`changed`/`new`, gray guard reuses `labelNotAvailable`), facts via `formatBytes` + plural `labelDiffFileCount`, `validating` re-entrancy guard on validate/download. +- `frontend/src/components/ProgressModal.vue`, `ProgressStepper.vue` — `compare` step registered between download/complete. +- `frontend/src/i18n/en.json`, `zh_Hant_HK.json` — `labelDiff*` keys + `stepCompare` ("Compare" / "比對"). + +### it-claws (separate repo) +- `src/it_claws/engine.py` — computes `hashes` from the final `(Path, arcname)` entry list before writing `manifest.json` (which stays last-in-ZIP); streaming 1 MiB chunked `_sha1_file` (kept `usedforsecurity=False`; `hashlib.file_digest` rejected — can't pass the flag). +- `tests/test_hashes.py` (new) — CJK byte-length framing, last-wins dedupe, key omission, rerun stability, integration (manifest last entry). +- `README.md` — "Manifest hashes" section + standalone `python - <