Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(uninstall): revise spec after design review
wlechbf241f1c98e8
diff --git a/docs/superpowers/specs/2026-05-25-uninstall-dryrun-purge-preview-design.md b/docs/superpowers/specs/2026-05-25-uninstall-dryrun-purge-preview-design.mdindex 51972cd3..7bac34db 100644--- a/docs/superpowers/specs/2026-05-25-uninstall-dryrun-purge-preview-design.md+++ b/docs/superpowers/specs/2026-05-25-uninstall-dryrun-purge-preview-design.md@@ -2,6 +2,7 @@> Date: 2026-05-25 · Branch: `feat/uninstall-command`> Follow-on to [`2026-05-24-uninstall-command-design.md`](2026-05-24-uninstall-command-design.md).+> Revised after subagent design review (see "Review resolutions" at the end).## Problem@@ -16,20 +17,22 @@ Two issues surfaced while exercising `ai-memory uninstall --purge-data`:2. **Duplicated wipe logic.** The data-wipe primitive — the subdir list`["wiki","db","raw"]` plus the `remove_dir_all` + `create_dir_all` loop —- exists in both `commands/reset.rs` and `commands/uninstall.rs`. It was- duplicated when `--purge-data` landed (commit `3e3d44a`). The subdir list- is a semantic contract ("what constitutes ai-memory data"); having it in- two places risks drift on a destructive operation (e.g. a future 4th subdir- updated in `reset` but not `uninstall`).+ exists in both `commands/reset.rs` and `commands/uninstall.rs`. `reset` is+ the original (commit `5e29909`, M1-D); `uninstall` **copied** it when+ `--purge-data` landed (commit `3e3d44a`). The subdir list is a semantic+ contract ("what constitutes ai-memory data for a wipe"); having it in two+ places risks drift on a destructive operation.## Goals- `uninstall --purge-data` dry-run previews the data wipe, mirroring `reset`'sper-subdir style.-- The wipe primitive lives in exactly one place, shared by `reset` and- `uninstall`, without coupling their divergent orchestration.-- No regression to `reset` (which currently has **zero tests**).-- Coverage on touched/new code: domain (pure logic) ≥ 90%, rest ≥ 80%.+- The `reset`↔`uninstall` wipe primitive lives in exactly one place, shared by+ both, without coupling their divergent orchestration (guard, output).+- No behavioral regression to `reset` (which currently has **zero tests**),+ and no loss of `uninstall`'s per-path error context.+- Coverage on touched/new code across this branch: critical logic ≥ 90%,+ rest ≥ 80% (line coverage, local inspection — see Coverage).## Non-goals@@ -39,48 +42,64 @@ Two issues surfaced while exercising `ai-memory uninstall --purge-data`:routing the wipe through the shared helper.- No unification of `reset`'s "would remove" wording with `uninstall`'s"would purge" / "✓ purged" — each command keeps its own phrasing.+- **No unification with `init`/`restore`.** Those declare *different* subdir+ sets on purpose (`init` = `wiki,raw,db,models`; `restore` = `wiki,db`); the+ shared helper is scoped to the `reset`↔`uninstall` set `wiki,db,raw` only.+- The `remove_dir_all` → `create_dir_all` sequence is **not atomic** (a crash+ between the two leaves a deleted-but-not-recreated subdir). This is+ pre-existing behavior shared by `reset` and `restore`; making it atomic is+ out of scope.## Design### 1. New module `commands/data_purge.rs` (mute helper)-Single home for the knowledge "which subdirs are data, and how to wipe one".-**No logging, no printing, no process check** — callers own output and the-process guard. Sits alongside the existing shared command helpers-(`apply_shared.rs`, `render_shared.rs`, `purge_project.rs`).+Single home for the `reset`↔`uninstall` knowledge "which subdirs are wiped,+and how to wipe one". **No logging, no printing, no process check** — callers+own output and the live-process guard. Returns `anyhow::Result` with per-path+context so callers keep meaningful error messages. Sits alongside the existing+shared command helpers (`apply_shared.rs`, `render_shared.rs`,+`purge_project.rs`); it stays **CLI-local** (not in `ai-memory-core`) because+the wiped set is operation-specific, not a single domain-wide constant.```rust//! Shared data-dir wipe primitive used by `reset` and `uninstall --purge-data`.//! Mute by design: returns the affected paths; callers own logging/printing-//! and the live-process guard (invariant #9).+//! and the live-process guard (invariant #9). The remove+recreate is not+//! atomic — pre-existing, matches reset/restore.use std::path::{Path, PathBuf};+use anyhow::Context;-/// The subdirectories that constitute ai-memory's local state.-/// `logs/` is intentionally excluded and never wiped.-pub(crate) const DATA_SUBDIRS: &[&str] = &["wiki", "db", "raw"];+/// The subdirectories wiped by `reset` / `uninstall --purge-data`.+/// `logs/` and `models/` are intentionally excluded and never wiped.+/// NOTE: this is the reset/uninstall set only — `init` and `restore` declare+/// their own (different) sets by design; do not converge them here.+pub(crate) const WIPE_SUBDIRS: &[&str] = &["wiki", "db", "raw"];-/// Paths that WOULD be purged (existing data subdirs), for dry-run preview.+/// Paths that WOULD be purged (existing wipe subdirs), for dry-run preview.pub(crate) fn purge_preview(data_dir: &Path) -> Vec<PathBuf> {- DATA_SUBDIRS+ WIPE_SUBDIRS.iter().map(|s| data_dir.join(s)).filter(|p| p.exists()).collect()}-/// Wipe each existing data subdir (remove + recreate empty). Returns the+/// Wipe each existing wipe-subdir (remove + recreate empty). Returns the/// paths actually purged (the subset that existed). Missing subdirs are-/// skipped, not errors.-pub(crate) fn purge_data_dirs(data_dir: &Path) -> std::io::Result<Vec<PathBuf>> {+/// skipped, not errors. Carries per-path context on failure.+pub(crate) fn purge_data_dirs(data_dir: &Path) -> anyhow::Result<Vec<PathBuf>> {let mut purged = Vec::new();- for sub in DATA_SUBDIRS {+ for sub in WIPE_SUBDIRS {let path = data_dir.join(sub);if !path.exists() {continue;}- std::fs::remove_dir_all(&path)?;- std::fs::create_dir_all(&path)?;+ std::fs::remove_dir_all(&path)+ .with_context(|| format!("removing {}", path.display()))?;+ std::fs::create_dir_all(&path)+ .with_context(|| format!("recreating {}", path.display()))?;purged.push(path);}Ok(purged)@@ -94,7 +113,9 @@ Registered with `mod data_purge;` in `commands/mod.rs`.- Remove the local `const SUBDIRS`.- Dry-run branch: `for p in data_purge::purge_preview(&config.data_dir) { println!("would remove {}", p.display()); }` then keep `(dry-run; pass --confirm to wipe)`.- Apply branch: `for p in data_purge::purge_data_dirs(&config.data_dir)? { tracing::info!(path = %p.display(), "reset"); }` then keep `tracing::info!("reset complete")`.-- The `bail!` process guard at the top is **unchanged**.+- The `bail!` process guard at the top is **unchanged**. (`reset::run` already+ returns `anyhow::Result`, so the helper's `anyhow::Result` slots in; reset+ *gains* per-path error context it lacked.)### 3. `uninstall.rs` — fix the dry-run gap + use the helper@@ -107,8 +128,7 @@ Registered with `mod data_purge;` in `commands/mod.rs`.}}```- This makes the data wipe visible in the dry-run output.-- **Apply.** Replace the inline wipe loop with:+- **Apply.** Replace the inline wipe loop (with its own `with_context`) with:```rust} else {for p in data_purge::purge_data_dirs(&config.data_dir)? {@@ -116,7 +136,8 @@ Registered with `mod data_purge;` in `commands/mod.rs`.}}```- The sibling-process guard, `purge_refused` flag, and end-of-run `bail!` are+ The per-path error context is preserved (now inside the helper). The+ sibling-process guard, `purge_refused` flag, and end-of-run `bail!` are**unchanged** — the "remove wiring, then skip purge if a process is alive"behavior is preserved.@@ -149,40 +170,94 @@ purge lines cover *data*. Technically correct; left as-is for simplicity.and **nothing is deleted**.- apply (`--confirm`): asserts `wiki`/`db`/`raw` end empty (dirs remain,files gone), `logs/` untouched, absent subdir skipped without error.- - guard: with a live sibling process, `reset` bails (refusal path).+ - **The process-guard refusal path is NOT characterized here.**+ `process_guard::sibling_processes()` inspects the live OS process table+ via `sysinfo` with no injection seam; testing the refusal deterministically+ would require spawning a real long-lived `ai-memory` process (flaky) or+ refactoring `process_guard` (forbidden by rule #6). The guard is untouched+ by this refactor, so a refactor-invariance test of it adds nothing.2. **Unit test `data_purge`** (fails: module absent) → create helper → green:- `purge_data_dirs`: seed `wiki`/`db`/`raw` + `logs/` → returns the 3 paths,those dirs emptied, `logs/` intact; missing subdir skipped (not returned,no error).- `purge_preview`: returns only existing subdirs.+ - missing `data_dir` entirely: `purge_preview` → empty; `purge_data_dirs`+ → `Ok(vec![])`, creates nothing.3. **Refactor** `reset.rs` and `uninstall.rs` to use the helper → step 1 + 2tests stay green.4. **Integration test `uninstall --purge-data` dry-run** (fails) → implementpreview → green: stdout contains `would purge …/wiki|db|raw` AND the seededfiles still exist on disk afterward.+Symlinked subdirs are out of scope; behavior matches existing `reset`+(pre-existing) and is not tested.+### Coverage-- Tool: **`cargo llvm-cov`** (`cargo install cargo-llvm-cov`; add to the- CI-parity command list in docs).-- Targets for touched/new code on this branch:- - **Domain (pure logic) ≥ 90%**: `data_purge` (helper, const, preview),- `uninstall`'s `strip_*` functions, `build_plan`.- - **Rest ≥ 80%**: `reset::run`, `uninstall::run`, dispatch, print paths.-- Measure with `cargo llvm-cov --lcov` and inspect per-file coverage for the- files this change touches; add tests until thresholds are met.+- Tool: **`cargo llvm-cov`** (`cargo install cargo-llvm-cov`). It is a+ **local inspection, not a CI gate** (CI runs fmt/clippy/test/deny/audit+ only); documented under a "Coverage (local)" note, NOT the "CI parity" list.+- Metric: **line coverage** via `cargo llvm-cov --lcov` (or `--summary-only`),+ inspected per file for the files this branch touches.+- Targets for touched/new code across the whole branch (per the maintainer's+ requirement — this includes already-committed uninstall code):+ - **Critical logic ≥ 90%** (criticality, not purity): `data_purge`+ (helper, const, preview) and `uninstall`'s pure `strip_*` /+ `*_is_ours` functions.+ - **Rest ≥ 80%**: `reset::run`, `uninstall::run`, `build_plan` (it does+ filesystem IO — orchestration, not pure), dispatch, print paths.+- Add tests until thresholds are met for the touched files.## Project-rule checks- **Invariant #9 (live-process guard before destructive op):** preserved —- guard stays in each caller; the mute helper performs no guard itself.+ the guard stays in each caller; the mute helper performs no guard itself.+- **Invariant #10 (atomic file writes: tmp + rename + fsync):** **N/A here.**+ #10 governs *file-content* writes (config files, wiki pages, via+ `apply_shared`); this is a *directory-tree wipe*. There is no meaningful+ atomic rmdir+mkdir primitive, and `reset` (reset.rs:42-43) and `restore`+ (restore.rs:56,60) already use raw `remove_dir_all`. The wipe is+ intentionally non-atomic and matches existing behavior.+- **Invariant #16 (CLI is a thin HTTP client):** unaffected — `reset` and+ `--purge-data` are listed #16 exceptions (server-stopped lifecycle ops); the+ helper is local-FS by design and not reachable from any server-backed command.- **Workflow rule #5 (test before implementation):** honored via thecharacterization-first then TDD order above.- **Workflow rule #6 (no refactor outside the milestone):** touching- `reset.rs` is in-scope because the duplication was *introduced by this- feature*; consolidating it finishes the feature cleanly. Change to `reset`- is mechanical and pinned by new characterization tests.+ `reset.rs` is in-scope because *this feature* created the drift (uninstall+ copied reset's wipe in `3e3d44a`); consolidating both call sites onto one+ primitive is the minimal way to remove that risk. `reset` is the original and+ is touched deliberately, pinned by the characterization tests written first.- **CLAUDE.md gate (rule #3):** `cargo fmt --all -- --check`,`cargo clippy --workspace --all-targets -- -D warnings`,`cargo test --workspace` all green before commit.-```++## Out-of-scope findings (logged, not addressed here)++- **`models/` is created but never wiped.** `init.rs:13` creates+ `wiki,raw,db,models`, but `reset`/`--purge-data` wipe only `wiki,db,raw` —+ `models/` survives a reset (like `logs/`). Likely intentional (downloaded+ embedding models), but undocumented. Candidate for a separate issue;+ not changed here.++## Review resolutions (subagent critique → disposition)++- **H1 (helper would drop uninstall's `with_context`):** accepted — helper+ returns `anyhow::Result` with per-path context (reset *gains* context).+- **H2 (#10 not addressed):** accepted — explicit N/A note added.+- **H3 (guard test infeasible):** accepted — guard refusal removed from the+ characterization set with rationale.+- **M1 (coverage scope/metric):** partially — kept the whole-branch scope (a+ maintainer requirement, not scope creep); specified line coverage + local+ (non-CI) inspection.+- **M2 (`build_plan` is not "pure"):** accepted — moved to the ≥80% bucket;+ 90% bucket reframed as "critical logic", not "pure".+- **M3 (reset-rationale inverted):** accepted — corrected (reset is the+ original; uninstall copied it).+- **M4 (move const to core?):** rejected as stated — the grep found *four*+ divergent sets (`init` adds `models`, `restore` is `wiki,db` only), so the+ sets legitimately differ; helper stays CLI-local and scoped to the+ reset↔uninstall set. Surfaced the `models/` discrepancy as an out-of-scope+ finding.+- **M5 / L1 / L2 / L4:** accepted — #16 note, missing-`data_dir` test,+ symlink sentence, and llvm-cov placed under "local, not CI-gated".