From 6c182ee9fa1490b9cd9511eb8c818a9dd3da82e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:14:15 +0100 Subject: [PATCH] docs: one true statement about what PHARN deletes (C4.2, CORE-175) Add docs/reference/deletes.md, the one list of every delete a pharn command makes (dropped capability directories in update/init, remove, uninstall, record pruning, and pharn's own download, lock, empty pharn/ and temp files), the check behind each, and what is never deleted. Link it from docs/README.md and the command pages, and replace the sentences that contradicted the code: "Nothing deletes an orphan", "no pharn command can clear one", the removed root-migration delete in README.md, "a record key never causes a write or a delete", the roadmap's "nothing is deleted", and uninstall "never touches .claude/settings.json". The ORPHANED note now says "`pharn update` never deletes them" instead of "pharn never deletes them": uninstall deletes unchanged orphans. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++ README.md | 14 +++-- docs/README.md | 1 + docs/architecture.md | 4 +- docs/commands/init.md | 3 +- docs/commands/remove.md | 3 +- docs/commands/status.md | 9 +-- docs/commands/uninstall.md | 1 + docs/commands/update.md | 15 ++--- docs/reference/deletes.md | 97 +++++++++++++++++++++++++++++++++ docs/reference/pharn-records.md | 5 +- docs/roadmap.md | 2 +- src/lib/orphans.ts | 10 ++-- tests/orphans.test.ts | 5 +- tests/root-migration.test.ts | 2 +- tests/status-report.test.ts | 2 +- 16 files changed, 147 insertions(+), 30 deletions(-) create mode 100644 docs/reference/deletes.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a3449df7..821c2613 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md). - **`pharn --help` no longer says each option belongs to one command.** `--json`, `--yes`, `--ref` and `--dry-run` are taken by several, as the lines below the header already showed. The header now reads "Options (each names the commands that take it; any other command refuses it):". - **`pharn status --help` now names every condition `--strict` fails on.** The `--strict` line said "exit 1 on any outdated/modified/missing file"; it now reads "exit 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook (under --no-drift, only outdated is checked)", on both `pharn --help` and `pharn status --help`. What `--strict` checks is unchanged. The one full list, including what is never a `--strict` input (orphans, the `PRETTIER`, `NODE` and `MODELS` notes, a hook wired only in `settings.local.json`), is the new "Strict conditions" section of `docs/commands/status.md`, and `docs/README.md`, the troubleshooting exit-code table, the `status --json` summary and the JSON output reference link to it. +### Fixed + +- **The `ORPHANED` note no longer says "pharn never deletes them".** `pharn uninstall` deletes an orphan that still equals its record, so `pharn update` and `pharn status` now print "`pharn update` never deletes them" instead. Every delete a `pharn` command makes, the check behind each, and what is never deleted are now listed on one page, [What PHARN deletes](docs/reference/deletes.md), which the command pages link to. + ## [0.21.0] — 2026-11-17 ### Changed diff --git a/README.md b/README.md index 80e73737..ca770d10 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,8 @@ deletes or mentions a root `memory-bank/` or `pharn.spec-template.md` (nothing proves they are PHARN's): move them yourself to `pharn/memory-bank/` and `pharn/spec-template.md` (`git mv`), or merge by hand when the `pharn/` copy already exists — see -[update](docs/commands/update.md#the-root-footprint-migration). +[update](docs/commands/update.md#the-root-footprint-migration) and +[What PHARN deletes](docs/reference/deletes.md). **Two version numbers, on purpose.** The npm package `@pharn-dev/pharn` carries the installer's version. The content it installs carries its own, @@ -306,7 +307,7 @@ Two commands sit outside the pipeline: | `pharn update` | Re-fetch and apply the latest PHARN content using drift-safe per-file decisions. `--force` overwrites files you changed; `--yes`/`-y` skips the confirmation prompt; `--dry-run` prints what it would do and writes nothing (add `--json` for the plan as one machine-readable object, and `--compact` to leave the unchanged files out of it). | | `pharn list` | Show installed archetypes and capabilities. Use `--json` for machine-readable output. | | `pharn status` | Read-only version and drift report. Use `--strict` to make drift fail CI, `--no-drift` to skip byte comparison, or `--json` for one machine-readable report. | -| `pharn uninstall` | Remove PHARN: deletes only the files `pharn` recorded and you did not change, then `pharn.records.json` and `pharn.config.json` (backed up first). Never touches `.claude/settings.json` or `pharn/.backup/`. `--yes`/`-y` skips the confirmation prompt. | +| `pharn uninstall` | Remove PHARN: deletes only the files `pharn` recorded and you did not change, then `pharn.records.json` and `pharn.config.json` (backed up first). Never touches `pharn/.backup/` or a `.claude/settings.json` it did not create. `--yes`/`-y` skips the confirmation prompt. | | `pharn --help` | Show every command, option and environment variable. `pharn --help` shows one command and only the options it takes. | | `pharn --version` | Show the installed CLI version. | @@ -369,11 +370,12 @@ PHARN is intentionally conservative about writes: and refuses the whole install — writing nothing — when a destination path crosses a symlinked directory. - `update` uses `pharn.records.json` to skip files it cannot prove are - untouched. The only thing it deletes is the directory of a capability it + untouched. In your project it deletes only the directory of a capability it drops from `pharn.config.json` (PHARN runs whatever capability directories are on disk), after backing up any file in it that `pharn` cannot prove it wrote; it never touches `.claude/settings.json`. A re-run `init` does the - same, after listing those directories in its prompt. + same, after listing those directories in its prompt. Every delete, and what + is never deleted: [What PHARN deletes](docs/reference/deletes.md). - `update --force` backs up overwritten files under `pharn/.backup//` before writing. `add` does the same for any destination file that differs from upstream, and refuses the whole install — writing nothing — when a destination @@ -441,7 +443,9 @@ PHARN is intentionally scoped: activities a structured record and repeatable workflow. - `status` reports modified, missing, and unreadable PHARN-owned paths, and the files upstream stopped shipping that are still in your project - (orphans). Nothing deletes an orphan; that is yours to do by hand. + (orphans). `update` never deletes an orphan; delete it by hand + (`pharn uninstall` removes the unchanged ones — see + [What PHARN deletes](docs/reference/deletes.md)). - **Supported installs: the current minor and the previous one.** v0.20.x works with installs made by 0.19.x or 0.20.x; re-run `pharn init` on an older install, and it keeps the capabilities you added. diff --git a/docs/README.md b/docs/README.md index 6772405c..4475e041 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,7 @@ The CLI version (`pharn --version`) and the content version it installs (`skills - [pharn.config.json](reference/pharn-config.md) — config file schema and overwrite behavior - [pharn.records.json](reference/pharn-records.md) — the per-file install hashes `pharn update` compares against - [JSON output](reference/json-output.md) — the `--json` reports of `init`, `update`, `status` and `list`: keys, stability rule, real examples +- [What PHARN deletes](reference/deletes.md) — every path a `pharn` command deletes, the check behind each, and what is never deleted - [Support policy](support-policy.md) — which installs and `pharn` versions are supported, and what is being retired when ## Other diff --git a/docs/architecture.md b/docs/architecture.md index bcdc9773..1de93e41 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -239,9 +239,9 @@ prompt was open (a file now byte-identical to upstream is not a change), then ap - **Executable unit** (`lib/executable-unit.ts`): floor files, hooks and product commands are written all-or-nothing. One skip holds the rest (`held`), so the floor never mixes two versions. - **Deletes**: only the directory of a capability dropped from the config, because PHARN enumerates capabilities from - disk. Nothing else is deleted. + disk. Nothing else is deleted ([the full list](reference/deletes.md)). - **Orphans** (`lib/orphans.ts`): a record key outside the new manifest that is still on disk is listed and keeps its - record. It is never deleted. + record. `update` never deletes it. - **Every run plans**: there is no same-version shortcut. `update` downloads and plans at the recorded version too, so a missing file, a pending ignore-file line, an old `models` block, a channel switch or a frozen capability is handled by the one planner. "Up to date" is a plan that changes nothing (`changesNothing`); only the diff --git a/docs/commands/init.md b/docs/commands/init.md index 8ecb2573..21b90fcd 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -431,7 +431,8 @@ not install again: one you added by hand that upstream no longer ships, an autom your archetypes no longer select, and a legacy entry (written before `source` existed) they no longer select. Each is **named** before the summary. PHARN's commands run every capability **directory** on disk, not what the config lists, so `init` also **deletes that directory** — the same treatment -[`pharn update`](update.md#dropped-capabilities-are-deleted) gives the capabilities it drops: +[`pharn update`](update.md#dropped-capabilities-are-deleted) gives the capabilities it drops (every +delete `pharn` makes is listed in [What PHARN deletes](../reference/deletes.md)): - **Listed first.** The overwrite prompt lists each directory under "will be DELETED", with how many of its files would be backed up, and asks (default No) even when nothing would be overwritten. Declining diff --git a/docs/commands/remove.md b/docs/commands/remove.md index e5921a73..2fac8a80 100644 --- a/docs/commands/remove.md +++ b/docs/commands/remove.md @@ -4,7 +4,8 @@ Remove a single installed **capability** — a griller or a lens — from an exi `pharn.config.json`). The inverse of [`add`](add.md): it deletes exactly that capability's directory and drops its entry from `pharn.config.json`. Any file in that directory that `pharn` cannot prove it wrote unchanged is copied to `pharn/.backup//` first — see -[What is backed up before the delete](#what-is-backed-up-before-the-delete). +[What is backed up before the delete](#what-is-backed-up-before-the-delete). Every delete `pharn` makes +is listed in [What PHARN deletes](../reference/deletes.md). ```bash pharn remove # e.g. pharn remove a11y diff --git a/docs/commands/status.md b/docs/commands/status.md index c4c33caa..654307d6 100644 --- a/docs/commands/status.md +++ b/docs/commands/status.md @@ -123,8 +123,8 @@ its drift section compares against the older source. On the drift path, `status` also lists the files `pharn` recorded writing that upstream no longer ships but that are still in your project — the same `ORPHANED` note, grouped `UNCHANGED` / `EDITED` / `UNREADABLE`, that `pharn update` prints (see [update](update.md#orphaned-files) for what each group -means and what is never listed). `pharn update` never deletes them; delete the ones you no longer need -by hand. +means and what is never listed). `pharn update` never deletes them +([What PHARN deletes](../reference/deletes.md)); delete the ones you no longer need by hand. It needs a usable [`pharn.records.json`](../reference/pharn-records.md) — present and valid (its `skillsVersion`/`commit` stamp does not matter). Without one, nothing is listed. A root @@ -132,8 +132,9 @@ It needs a usable [`pharn.records.json`](../reference/pharn-records.md) — pres copies of a `flat` install after a re-run `pharn init`, are listed here like any other leftover. Orphans are **not** a `--strict` input. `--strict` asks whether your install is current and intact. An -orphan is a leftover file beside it, and no `pharn` command can clear one — `update` never deletes — so -a red CI would wait on a manual delete for a file that changes nothing about the install. +orphan is a leftover file beside it that `update` never deletes (see +[What PHARN deletes](../reference/deletes.md)), so a red CI would wait on a manual delete for a file +that changes nothing about the install. ## Prettier diff --git a/docs/commands/uninstall.md b/docs/commands/uninstall.md index 0e2cff0b..dd172cc8 100644 --- a/docs/commands/uninstall.md +++ b/docs/commands/uninstall.md @@ -10,6 +10,7 @@ pharn uninstall --yes # no prompt — for scripts and CI (-y works too) ``` It needs **no network and no clone**: the proof is local — [`pharn.records.json`](../reference/pharn-records.md). +What every other command deletes is listed in [What PHARN deletes](../reference/deletes.md). ## What is deleted diff --git a/docs/commands/update.md b/docs/commands/update.md index e538624f..b19872da 100644 --- a/docs/commands/update.md +++ b/docs/commands/update.md @@ -223,9 +223,10 @@ inside the project lock, the way [`pharn remove`](remove.md) does: `pharn update --dry-run` lists the same directories under `WOULD DELETE` (and `plan.capabilities.removals` under `--json`) without asking. -This is the **only** thing `update` deletes. It never deletes a file upstream stops shipping inside a -capability it keeps, a tree left behind by a layout change, or anything else, and it never touches -`.claude/settings.json`. Directories that an older `pharn` left behind when it dropped a capability +Apart from its own lock and download, that directory is all `update` deletes: not a file upstream stops +shipping inside a capability it keeps, not the old top-level copies of a `flat` install, and never +`.claude/settings.json`. Every delete `pharn` makes, and what it never deletes, is listed in +[What PHARN deletes](../reference/deletes.md). Directories that an older `pharn` left behind when it dropped a capability (it removed only the config entry) have no config entry, so `update` cannot find them: `pharn list` does not show them, but PHARN still runs them. Delete them by hand. A re-run [`pharn init`](init.md#dropped-capabilities-are-deleted) deletes the directories of the capabilities it @@ -403,15 +404,15 @@ until you revert the edit or use `--force`. ## Orphaned files When upstream stops shipping a file `pharn` installed — a `pharn-*` command, a hook, a floor checker, a -trusted doc, or one file inside a capability you still have — `update` leaves it on disk: the only thing -it deletes is a dropped capability's directory. Such a file is an **orphan**: `pharn.records.json` says `pharn` wrote it, it is no longer +trusted doc, or one file inside a capability you still have — `update` leaves it on disk (see +[What PHARN deletes](../reference/deletes.md)). Such a file is an **orphan**: `pharn.records.json` says `pharn` wrote it, it is no longer part of your install, and it is still there. A leftover `.claude/commands/pharn-*.md` is still a live slash command, and a leftover hook or checker still runs if anything calls it, so `update` names every orphan in an `ORPHANED` note: ```text - Upstream no longer ships these files pharn installed. pharn never deletes - them, and keeps listing each one until it is gone. + Upstream no longer ships these files pharn installed. `pharn update` never + deletes them, and keeps listing each one until it is gone. UNCHANGED — unchanged since pharn wrote it .claude/commands/pharn-old.md diff --git a/docs/reference/deletes.md b/docs/reference/deletes.md new file mode 100644 index 00000000..f5ccccf8 --- /dev/null +++ b/docs/reference/deletes.md @@ -0,0 +1,97 @@ +# What PHARN deletes + +This page is the one list of everything `pharn` deletes, with the check that stands behind each delete. +The command pages link here instead of restating it. Anything not listed under +[In your project](#in-your-project) or [pharn's own state](#pharns-own-state) is never deleted by any +`pharn` command. + +## In your project + +### A capability dropped from the config: `pharn update` and a re-run `pharn init` + +The directory of each capability that leaves `pharn.config.json`, because your archetypes no longer +select it or upstream no longer ships it (for example `pharn/pharn-pipeline/grillers//`). It is +deleted because PHARN's commands run whatever capability directories are on disk, so a dropped one would +keep running. + +- Only the one directory of a capability your config lists, addressed by its validated name as a strict + child of its role directory. Siblings are never touched. +- Refused, with nothing changed, when the path to it crosses a symbolic link (checked when the run plans + and again at the delete) or when a file in it cannot be read. +- Every file in it that `pharn` cannot prove it wrote unchanged is copied to `pharn/.backup//` + first: a file with no record, a file whose bytes differ from its record, or every file when there is + no usable [`pharn.records.json`](pharn-records.md). +- Shown beforehand: `--dry-run` lists it under `WOULD DELETE`, and the confirm names it and defaults to + No. `pharn update --yes` skips that confirm; `pharn init --yes` refuses any re-install, so it never + deletes. + +Details: [`update`](../commands/update.md#dropped-capabilities-are-deleted) and +[`init`](../commands/init.md#dropped-capabilities-are-deleted). + +### The capability you remove: `pharn remove` + +The one capability directory you name (or pick), by the same address rule, the same symbolic-link +refusal and the same backup rule as above. Then its entries are pruned from `pharn.records.json` and its +entry from `pharn.config.json`. Details: [`remove`](../commands/remove.md). + +### The files pharn proves it wrote: `pharn uninstall` + +- Each file recorded in `pharn.records.json` whose path is one an install writes, that is a regular + file reached without a symbolic-linked directory, and whose bytes still equal its record. This + includes [orphans](../commands/update.md#orphaned-files) and `.claude/settings.json` when a fresh + `pharn init` created it. +- Then each directory those deletes left empty, deepest first, never the project root (a non-recursive + delete, so a directory that still holds anything stays). +- Then `pharn.records.json`, then `pharn.config.json` after it is copied to `pharn/.backup//`. +- Last, `pharn/` itself, but only if it is empty. + +Details: [`uninstall`](../commands/uninstall.md#what-is-deleted). + +### Record entries, never files + +`pharn update` writes `pharn.records.json` as a fresh map of the install it just applied, so the entry +of a file that is no longer part of your install and no longer on disk is dropped. `pharn remove` drops +the entries under the directory it removed. No file is touched. See +[Pruning](pharn-records.md#pruning). + +## pharn's own state + +- **The download.** Each command that fetches pharn-oss extracts it into a new directory under your + system's temp directory and deletes it when the command ends, when the download is refused or fails, + on exit, and on `SIGINT`/`SIGTERM`. +- **`pharn/.lock`.** The command that took the lock deletes it when it ends (also on `SIGINT`/`SIGTERM`), + and only when the lock still names that run. A lock judged stale is moved to + `pharn/.lock..`, checked and deleted by the run that moved it; a file of that name that a + killed run left behind is never deleted. See + [If the lock outlives its owner](../troubleshooting.md#if-the-lock-outlives-its-owner). +- **An empty `pharn/` the lock created.** When `pharn/` did not exist, the lock creates it and deletes it + again if it is still empty when the lock is released. +- **A write's temp file.** A file `pharn` replaces is first written to `...tmp` beside + it and renamed over it; that temp file is deleted when the write fails before the rename. + +## Overwrites are not deletes + +Replacing a file's bytes (an upgrade in `pharn update`, `update --force`, `pharn add`, an overwrite a +`pharn init` re-run confirms) is a write, not a delete. Whatever `pharn` cannot prove it wrote unchanged +is copied to `pharn/.backup//` before it is replaced, and an existing `.claude/settings.json` +is never overwritten. + +## What is never deleted + +- **A file with no record**, and **a recorded file you changed**, anywhere outside a capability directory + that `remove` deletes or that `update`/`init` drops. Inside one, such a file is backed up first and then + deleted with the directory. +- **Orphans** (files upstream stopped shipping, including the top-level copies a `flat` install left and + a root `THREAT-MODEL.md` or `LIMITS.md` from a pharn-oss older than 7.0.0). `update`, `init`, `add` and + `status` never delete one by itself; only a capability directory deleted as above takes the ones + inside it. `uninstall` deletes the ones still equal to their record. +- **`.claude/settings.json`**, except by `uninstall` when a fresh `pharn init` created it and it still + equals its record. A `settings.json` that existed before `init` is never recorded. +- **`.claude/settings.local.json`.** +- **Every `pharn/.backup/` directory**, including the one a run creates. +- **Your data:** `pharn/features//` work, `memory-bank/`, `pharn.spec-template.md`, an old + `.pharn/` and an old root `.pharn-backup/` directory. +- **The lines `pharn` added to `.gitignore` and `.prettierignore`.** Those files are only appended to. +- **Anything behind a symbolic link.** A delete whose path crosses a symbolic-linked directory refuses + the whole run instead. +- **A `pharn/.lock` that is a directory**, or a lock a live run holds. diff --git a/docs/reference/pharn-records.md b/docs/reference/pharn-records.md index d7d8b3e2..b2e765a5 100644 --- a/docs/reference/pharn-records.md +++ b/docs/reference/pharn-records.md @@ -187,12 +187,13 @@ listed, and a key outside `pharn`'s install paths is never deleted whatever its [`.claude/settings.json`](#claudesettingsjson)) and then checked the same way. With no usable store (absent or corrupt) `uninstall` refuses and deletes nothing; a store written for another `skillsVersion`/`commit` is still usable, since only a file whose hash equals its record is deleted. -The store itself is deleted after the files, before `pharn.config.json`. +The store itself is deleted after the files, before `pharn.config.json`. Every delete `pharn` makes is +listed in [What PHARN deletes](deletes.md). ## Trust The file is local but hand-editable, so it is treated as untrusted input: it is parsed defensively, -and a record **key never causes a write or a delete**. `update` iterates its own install manifest and +and a record **key never causes a write**, and causes a delete only in `uninstall` (below). `update` iterates its own install manifest and looks each path up here, so an invented key cannot cause a write. The one place a key becomes a path is orphan detection, and only for a **read** (an `lstat` and a hash): the key must name a path an install could have written (`.claude/commands/pharn-*.md`, `.claude/hooks/*.cjs` or `*.mjs`, a capability directory, diff --git a/docs/roadmap.md b/docs/roadmap.md index af243252..c7c9cd0c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -19,7 +19,7 @@ What the latest release does; the [CHANGELOG](../CHANGELOG.md) says which versio | `pharn uninstall` — delete the PHARN files pharn can prove it wrote and nobody changed (offline; edited and unrecorded files are kept and listed; `--yes`) | Shipped | | `pharn status` — read-only version + capability-drift report (modified/missing/unreadable PHARN-owned files; `--strict`, `--no-drift`) | Shipped | | `pharn.records.json` — a sha256 of every installed file, so `update` can tell pharn's bytes from your edits | Shipped | -| Orphaned-file detection — `update` and `status` name the files upstream stopped shipping that are still in your project (`ORPHANED` note, `orphans` in `--json`); nothing is deleted | Shipped | +| Orphaned-file detection — `update` and `status` name the files upstream stopped shipping that are still in your project (`ORPHANED` note, `orphans` in `--json`); `update` keeps them | Shipped | | Drift-safe `update` — per-file decisions, `--force` with `pharn/.backup//` (also written by `init`, `add`, `remove` and `uninstall`) | Shipped | | Single-writer lock (`pharn/.lock`) for `init`/`add`/`remove`/`update`/`uninstall`; `list`/`status` never take it | Shipped | | `MIN_CLI` forward-compatibility gate — refuses cleanly when upstream needs a newer CLI | Shipped | diff --git a/src/lib/orphans.ts b/src/lib/orphans.ts index dac1493e..4f313c09 100644 --- a/src/lib/orphans.ts +++ b/src/lib/orphans.ts @@ -9,8 +9,10 @@ import type { InstalledCapability } from '../types.js'; // Orphaned files — files pharn RECORDED writing that the install no longer // owns (upstream stopped shipping them) but that are still on disk. `update` // never deletes them (only a DROPPED capability's directory, whose keys are -// excluded here), so without this they would sit in `.claude/commands/` (still -// live slash commands), `.claude/hooks/` or the floor dir, unnamed. +// excluded here; `uninstall` deletes the unchanged ones — the full list is +// docs/reference/deletes.md), so without this they would sit in +// `.claude/commands/` (still live slash commands), `.claude/hooks/` or the +// floor dir, unnamed. // // Read-only. `findOrphans` returns the orphans' records so `update` / a re-run // `init` can CARRY them, which keeps an orphan listed until its file is gone. @@ -112,8 +114,8 @@ const GROUPS: readonly { state: OrphanState; heading: string }[] = [ export function orphanNoteLines(orphans: readonly Orphan[]): string[] | null { if (orphans.length === 0) return null; const lines: string[] = [ - ' Upstream no longer ships these files pharn installed. pharn never deletes', - ' them, and keeps listing each one until it is gone.', + ' Upstream no longer ships these files pharn installed. `pharn update` never', + ' deletes them, and keeps listing each one until it is gone.', '', ]; let capped = false; diff --git a/tests/orphans.test.ts b/tests/orphans.test.ts index 70525c5b..a0439283 100644 --- a/tests/orphans.test.ts +++ b/tests/orphans.test.ts @@ -508,7 +508,10 @@ describe('orphanNoteLines', () => { ); expect(text).toContain('c.md — the path is a symlink'); expect(text).toContain('git rm'); - expect(text).toMatch(/never deletes/); + // A true statement: `uninstall` deletes unchanged orphans, so the note + // names the command that never does (docs/reference/deletes.md). + expect(text).toContain('`pharn update` never\n deletes them'); + expect(text).not.toContain('pharn never deletes'); expect(text).not.toMatch(/\bsafe\b/i); expect(text).not.toContain('more —'); }); diff --git a/tests/root-migration.test.ts b/tests/root-migration.test.ts index 252c2c52..6beb29a0 100644 --- a/tests/root-migration.test.ts +++ b/tests/root-migration.test.ts @@ -534,7 +534,7 @@ describe('the ROOT MIGRATION note', () => { it('previews in the future tense', () => { expect(text()).toContain('THREAT-MODEL.md'); expect(text()).not.toContain('WOULD DELETE'); - expect(text()).toContain('pharn never deletes'); + expect(text()).toContain('`pharn update` never'); }); it('hints at a free destination with git mv (or mv), never moving it', () => { diff --git a/tests/status-report.test.ts b/tests/status-report.test.ts index 56dc1b2c..46cc3eb5 100644 --- a/tests/status-report.test.ts +++ b/tests/status-report.test.ts @@ -459,7 +459,7 @@ describe('buildStatusReport', () => { buildStatusReport(input({ drift: moved, strict: false })).strict, ).toEqual({ enabled: false, failed: false }); }); - // Orphans are leftovers no pharn command can clear (update never deletes): + // Orphans are leftovers `update` never deletes (docs/reference/deletes.md): // reported, never a --strict input. it('is not failed by orphans', () => { const drift = {