promptdock 1.2.1 → 1.2.2

package/dist/leftovers.js

@@ -0,0 +1,175 @@
+// Leftover temporary folders from an interrupted install or update (I5, DX-A2, ENG-A4).
+//
+// An install downloads into `.promptdock-staging-<start ms>-<random>` and, when it
+// replaces an existing copy, first renames that copy to `.promptdock-old-<start ms>-
+// <random>` beside a `.json` sidecar naming where it came from. A process killed at the
+// wrong moment leaves one of them behind, and this module is what every later command
+// runs first:
+//   - a staging folder older than an hour is removed (younger ones may be another
+//     command's install in progress);
+//   - an old folder whose skill folder is MISSING is renamed back, and only that: it may
+//     be the member's only copy of their files;
+//   - an old folder is removed only when its skill folder exists with a receipt written
+//     at or after the old folder's start time, i.e. the update that set it aside
+//     finished;
+//   - a folder whose name carries no start time (1.2.1 and older named them with a
+//     random suffix only) is reported and left alone.
+//
+// ⚠️ Ages come from the NAME, never from mtime: a rename keeps the folder's old mtime on
+// APFS and ext4, so a skill last edited days ago would look days old.
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { readReceipt } from "./receipts.js";
+import { TARGETS, targetBaseDir } from "./registry.js";
+import { SERVER_PATH_MAX, terminalLine } from "./terminal-text.js";
+/** A staging folder younger than this may belong to an install still running. */
+export const STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+const ANY = /^\.promptdock-(staging|old)-/;
+const DATED = /^\.promptdock-(staging|old)-(\d{10,16})-[0-9a-f]+$/;
+/** Both folders an install's temporary folders for `targetDir` can be in. */
+export function tempRootsFor(targetDir) {
+    const parent = dirname(targetDir);
+    const grand = dirname(parent);
+    return grand === parent ? [parent] : [grand, parent];
+}
+/** The temporary-folder roots for every skills folder a lifecycle command can see. */
+export function sweepRoots(opts) {
+    if (opts.dir)
+        return tempRootsFor(join(opts.dir));
+    const scopes = opts.scope === "both" ? [false, true] : [opts.scope === "global"];
+    const targets = opts.targetId ? TARGETS.filter((t) => t.id === opts.targetId) : TARGETS;
+    const roots = new Set();
+    for (const global of scopes) {
+        for (const t of targets) {
+            const base = targetBaseDir(t, { cwd: opts.cwd, home: opts.home, global });
+            roots.add(dirname(base));
+            roots.add(base);
+        }
+    }
+    return [...roots];
+}
+/**
+ * Is `target` a skill folder this root could have held the old copy of? The sidecar is
+ * a file on disk, so it is untrusted: a crafted one must never turn a restore into a
+ * rename to anywhere. A skill folder sits one level under the root (the root is the
+ * skills folder) or two (the root is the folder above it).
+ */
+function plausibleTarget(root, target) {
+    if (typeof target !== "string" || !isAbsolute(target))
+        return false;
+    if (resolvePath(target) !== target)
+        return false;
+    const rel = relative(root, target);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return false;
+    const parts = rel.split(sep);
+    if (parts.length > 2)
+        return false;
+    return parts.every((p) => p !== "" && p !== "." && p !== ".." && !p.startsWith(".promptdock-"));
+}
+function exists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Sweep `roots` (deduplicated). Never throws: a leftover must not block the command. */
+export function sweepLeftovers(roots, now) {
+    const notes = [];
+    for (const root of new Set(roots)) {
+        let names;
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (!ANY.test(name))
+                continue;
+            const path = join(root, name);
+            try {
+                if (name.endsWith(".json")) {
+                    // A sidecar whose folder is gone (the update finished, or failed before the
+                    // rename): harmless, removed once it is clearly not mid-operation.
+                    const m = DATED.exec(name.slice(0, -".json".length));
+                    if (m && now - Number(m[2]) > STAGING_MAX_AGE_MS && !exists(path.slice(0, -".json".length))) {
+                        rmSync(path, { force: true });
+                    }
+                    continue;
+                }
+                if (!lstatSync(path).isDirectory())
+                    continue;
+                const m = DATED.exec(name);
+                if (!m) {
+                    notes.push({ kind: "undated", path });
+                    continue;
+                }
+                const startedAt = Number(m[2]);
+                if (m[1] === "staging") {
+                    if (now - startedAt > STAGING_MAX_AGE_MS) {
+                        rmSync(path, { recursive: true, force: true });
+                        notes.push({ kind: "removed", path });
+                    }
+                    continue;
+                }
+                // An old copy: where does it belong?
+                let target = null;
+                try {
+                    target = JSON.parse(readFileSync(`${path}.json`, "utf8")).target;
+                }
+                catch {
+                    /* no readable sidecar */
+                }
+                if (!plausibleTarget(root, target)) {
+                    if (now - startedAt > STAGING_MAX_AGE_MS)
+                        notes.push({ kind: "unclaimed", path });
+                    continue;
+                }
+                if (!exists(target)) {
+                    mkdirSync(dirname(target), { recursive: true });
+                    renameSync(path, target);
+                    rmSync(`${path}.json`, { force: true });
+                    notes.push({ kind: "restored", path: target });
+                    continue;
+                }
+                const read = readReceipt(target);
+                const installedAt = read.kind === "ok" ? Date.parse(String(read.receipt.installed_at)) : NaN;
+                if (Number.isFinite(installedAt) && installedAt >= startedAt) {
+                    rmSync(path, { recursive: true, force: true });
+                    rmSync(`${path}.json`, { force: true });
+                    notes.push({ kind: "removed", path });
+                }
+                else if (now - startedAt > STAGING_MAX_AGE_MS) {
+                    notes.push({ kind: "unclaimed", path });
+                }
+            }
+            catch {
+                /* one unreadable leftover never stops the sweep or the command */
+            }
+        }
+    }
+    return notes;
+}
+/** The line each note prints on stderr (stdout stays the command's own, `--json` or not). */
+export function leftoverLine(note) {
+    const p = terminalLine(note.path, SERVER_PATH_MAX);
+    switch (note.kind) {
+        case "removed":
+            return `Removed a leftover temporary folder from an interrupted install: ${p}`;
+        case "restored":
+            return `Restored ${p} from an interrupted update.`;
+        case "undated":
+            return `Found a temporary folder from an interrupted install that this CLI can't date: ${p}. It may hold your files; check it, then delete it.`;
+        case "unclaimed":
+            return `Found the previous copy of a skill from an interrupted update: ${p}. Check it, then move it back or delete it.`;
+    }
+}
+/** Sweep and report: what every skill-touching command runs before it reads a receipt. */
+export function sweepAndReport(ctx, roots) {
+    for (const note of sweepLeftovers(roots, ctx.now()))
+        ctx.io.err(leftoverLine(note));
+}

package/dist/local-changes.d.ts

@@ -0,0 +1,108 @@
+import { CliError } from "./errors.js";
+import { type Receipt } from "./receipts.js";
+/** Why a path blocks an install. Stable: `--json` consumers switch on it. */
+export type ChangeReason = "modified" | "path_conflict" | "not_regular_file";
+export type LocalChange = {
+    /** relative, `/`-separated, as the receipt and the manifest spell paths */
+    path: string;
+    reason: ChangeReason;
+    /** `path_conflict` only: whether the new version ships a file or a folder there */
+    ships?: "file" | "folder";
+};
+/** One thing on disk the receipt does not list. Directories are listed only when empty. */
+export type UnlistedEntry = {
+    path: string;
+    kind: "file" | "link" | "dir" | "special";
+};
+/**
+ * The path comparison a volume actually uses (ENG-A5).
+ *
+ * APFS and NTFS are case-insensitive by default, so a member's `Notes.md` and a shipped
+ * `notes.md` are ONE file there, and treating them as two would let the new version
+ * overwrite the member's file silently. NFD and NFC spellings of one name are always the
+ * same path here (macOS stores NFD, most editors type NFC), on every volume.
+ */
+export type PathKey = (p: string) => string;
+export declare function pathKeyFor(caseInsensitive: boolean): PathKey;
+/** The platform's default volume rule, for the checks that must not write (dry run). */
+export declare function defaultPathKey(platform: NodeJS.Platform): PathKey;
+/**
+ * Is the volume holding `dir` case-insensitive? Probed once per install by creating a
+ * mixed-case file and looking for its lowercase spelling. `dir` must exist and be
+ * writable; when the probe cannot run, the platform default is assumed (darwin and
+ * win32 ship case-insensitive by default), which errs toward reporting a conflict.
+ */
+export declare function probeCaseInsensitive(dir: string, platform: NodeJS.Platform): boolean;
+/**
+ * Everything in `dir` the receipt does not list, as leaves: files, symlinks (never
+ * followed), FIFO/socket/device files, and EMPTY directories (so an empty folder the
+ * member made survives too). A directory holding anything is walked, not listed.
+ *
+ * `receipt` is null for a folder this CLI did not install (no receipt, or another
+ * skill's): then every entry is unlisted. The receipt file itself is never an entry.
+ */
+export declare function unlistedEntries(dir: string, receipt: Receipt | null, key: PathKey): UnlistedEntry[];
+/**
+ * The changes the RECEIPT can see, checked before the confirm prompt and before the
+ * metered install request (DX-A1's order), and again right before the swap (ENG-A36):
+ * a receipt-listed file whose bytes differ (line endings aside), or a symlink, folder
+ * or special file where it should be; and an unlisted FIFO, socket or device file.
+ *
+ * A receipt-listed file that is MISSING is not a change: an update that brings it back
+ * destroys nothing, so it never blocks.
+ */
+export declare function receiptSideChanges(dir: string, receipt: Receipt, unlisted: UnlistedEntry[]): LocalChange[];
+/** The unlisted FIFO, socket and device files: what blocks when there is no receipt. */
+export declare function specialChanges(unlisted: UnlistedEntry[]): LocalChange[];
+/**
+ * Unlisted entries that collide with what the new version ships (DX-A1, ENG-A5):
+ *   - an entry at a path the new version ships as a file;
+ *   - an entry where the new version ships a folder (`notes` vs `notes/a.md`);
+ *   - an entry inside a folder the member made where the new version ships a FILE
+ *     (`notes/mine.md` vs a shipped `notes`), reported once, as the folder.
+ * Paths compare through `key`, so case and Unicode normalization follow the volume.
+ * Special files are left to `specialChanges`: they never carry, so they never collide.
+ */
+export declare function conflictChanges(unlisted: UnlistedEntry[], shippedPaths: string[], key: PathKey): LocalChange[];
+/** One row per path, in argument order; a path two checks both report keeps its first reason. */
+export declare function mergeChanges(...lists: LocalChange[][]): LocalChange[];
+/** Should `entry` be carried, given the conflicts `--force` is about to replace? */
+export declare function isCarried(entry: UnlistedEntry, conflicts: LocalChange[], key: PathKey): boolean;
+/**
+ * Carry one unlisted entry from the current folder into the staging folder (ENG-A6):
+ * a regular file by HARD LINK when both sit on one filesystem (no doubled disk use, and
+ * the original stays in the old folder until the swap is verified), else a copy with its
+ * mode bits and times; a symlink verbatim (readlink + symlink, never followed); an empty
+ * folder recreated. Throws on failure, so the caller can abort with nothing changed.
+ */
+export declare function carryEntry(fromDir: string, toDir: string, entry: UnlistedEntry): void;
+/** The refusal's human rows (at most `limit`, then a "+N more" line), one per change. */
+export declare function changeRows(changes: LocalChange[], toVersion: string | null, limit?: number): string[];
+/** `{path, reason}` pairs for `--json` (the `ships` hint stays human-only). */
+export declare function changesJson(changes: LocalChange[]): {
+    path: string;
+    reason: ChangeReason;
+}[];
+/**
+ * The `local_changes` refusal (DX-A1): what blocked, that nothing changed, both ways
+ * out, and (from the error's footer) the docs link. Exit 4. The message is printed in
+ * red and the two ways out follow it as the hint, so the order on screen is the
+ * contract's: rows, "Nothing was changed.", keep, discard, docs.
+ */
+export declare function localChangesRefusal(o: {
+    verb: "install" | "update" | "uninstall";
+    /** terminal-safe already */
+    title: string;
+    from: string | null;
+    to: string | null;
+    dir: string;
+    changes: LocalChange[];
+}): CliError;
+/** "Kept {n} of your files: a, b, c +2 more." — or nothing when nothing was carried. */
+export declare function keptLine(kept: string[]): string | null;
+/** What `--force` replaced or removed, one line each, at most `limit` then "+N more". */
+export declare function forceLines(replaced: {
+    path: string;
+    reason: ChangeReason;
+    shipped: boolean;
+}[], removed: string[], limit?: number): string[];

package/dist/local-changes.js

@@ -0,0 +1,334 @@
+// The local-changes contract (1.2.2, I1/I8/ENG-A5/ENG-A6): what a member has done to an
+// installed skill folder, and what an install or update may and may not touch.
+//
+// ⚠️ THE DEFECT THIS EXISTS FOR. 1.2.1 swapped the whole directory on every install and
+// update, so a re-run of the install command over an edited skill overwrote the edits
+// and deleted every file the member had added, with exit 0. Two rules close it:
+//   1. A change the receipt can see (an edited receipt-listed file, or an unlisted
+//      FIFO, socket or device) refuses the operation unless --force, BEFORE the confirm
+//      prompt and the metered install request.
+//   2. Everything else the member put in the folder (regular files, symlinks, folders)
+//      is CARRIED into the new version, never left behind in the swapped-out folder.
+// A file the new version also ships at the same path cannot be both, so it refuses too
+// (`path_conflict`), after the manifest is known and before any download.
+import { chmodSync, copyFileSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { CliError, EXIT } from "./errors.js";
+import { matchesReceiptHash } from "./integrity.js";
+import { RECEIPT_NAME } from "./receipts.js";
+import { SERVER_PATH_MAX, terminalLine } from "./terminal-text.js";
+export function pathKeyFor(caseInsensitive) {
+    return caseInsensitive
+        ? (p) => p.normalize("NFC").toLowerCase()
+        : (p) => p.normalize("NFC");
+}
+/** The platform's default volume rule, for the checks that must not write (dry run). */
+export function defaultPathKey(platform) {
+    return pathKeyFor(platform === "darwin" || platform === "win32");
+}
+/**
+ * Is the volume holding `dir` case-insensitive? Probed once per install by creating a
+ * mixed-case file and looking for its lowercase spelling. `dir` must exist and be
+ * writable; when the probe cannot run, the platform default is assumed (darwin and
+ * win32 ship case-insensitive by default), which errs toward reporting a conflict.
+ */
+export function probeCaseInsensitive(dir, platform) {
+    const name = `.promptdock-case-Pr0bE-${randomBytes(4).toString("hex")}`;
+    const probe = join(dir, name);
+    try {
+        writeFileSync(probe, "");
+    }
+    catch {
+        return platform === "darwin" || platform === "win32";
+    }
+    try {
+        lstatSync(join(dir, name.toLowerCase()));
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(probe, { force: true });
+    }
+}
+/**
+ * Everything in `dir` the receipt does not list, as leaves: files, symlinks (never
+ * followed), FIFO/socket/device files, and EMPTY directories (so an empty folder the
+ * member made survives too). A directory holding anything is walked, not listed.
+ *
+ * `receipt` is null for a folder this CLI did not install (no receipt, or another
+ * skill's): then every entry is unlisted. The receipt file itself is never an entry.
+ */
+export function unlistedEntries(dir, receipt, key) {
+    const listed = new Set((receipt?.files ?? []).map((f) => key(f.path)));
+    const out = [];
+    const walk = (rel) => {
+        const abs = rel === "" ? dir : join(dir, rel);
+        let names;
+        try {
+            names = readdirSync(abs);
+        }
+        catch {
+            return;
+        }
+        if (rel !== "" && names.length === 0) {
+            out.push({ path: rel, kind: "dir" });
+            return;
+        }
+        for (const name of names.sort()) {
+            if (rel === "" && name === RECEIPT_NAME)
+                continue;
+            const childRel = rel === "" ? name : `${rel}/${name}`;
+            let st;
+            try {
+                st = lstatSync(join(dir, childRel));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(childRel);
+                continue;
+            }
+            if (listed.has(key(childRel)))
+                continue;
+            out.push({
+                path: childRel,
+                kind: st.isSymbolicLink() ? "link" : st.isFile() ? "file" : "special",
+            });
+        }
+    };
+    walk("");
+    return out;
+}
+/**
+ * The changes the RECEIPT can see, checked before the confirm prompt and before the
+ * metered install request (DX-A1's order), and again right before the swap (ENG-A36):
+ * a receipt-listed file whose bytes differ (line endings aside), or a symlink, folder
+ * or special file where it should be; and an unlisted FIFO, socket or device file.
+ *
+ * A receipt-listed file that is MISSING is not a change: an update that brings it back
+ * destroys nothing, so it never blocks.
+ */
+export function receiptSideChanges(dir, receipt, unlisted) {
+    const changes = [];
+    for (const f of receipt.files) {
+        const abs = join(dir, f.path);
+        let st;
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile()) {
+            changes.push({ path: f.path, reason: "modified" });
+            continue;
+        }
+        let buf;
+        try {
+            buf = readFileSync(abs);
+        }
+        catch {
+            changes.push({ path: f.path, reason: "modified" });
+            continue;
+        }
+        if (!matchesReceiptHash(buf, f.sha256))
+            changes.push({ path: f.path, reason: "modified" });
+    }
+    changes.push(...specialChanges(unlisted));
+    return changes;
+}
+/** The unlisted FIFO, socket and device files: what blocks when there is no receipt. */
+export function specialChanges(unlisted) {
+    return unlisted
+        .filter((e) => e.kind === "special")
+        .map((e) => ({ path: e.path, reason: "not_regular_file" }));
+}
+/**
+ * Unlisted entries that collide with what the new version ships (DX-A1, ENG-A5):
+ *   - an entry at a path the new version ships as a file;
+ *   - an entry where the new version ships a folder (`notes` vs `notes/a.md`);
+ *   - an entry inside a folder the member made where the new version ships a FILE
+ *     (`notes/mine.md` vs a shipped `notes`), reported once, as the folder.
+ * Paths compare through `key`, so case and Unicode normalization follow the volume.
+ * Special files are left to `specialChanges`: they never carry, so they never collide.
+ */
+export function conflictChanges(unlisted, shippedPaths, key) {
+    const shippedFiles = new Set(shippedPaths.map(key));
+    const shippedFolders = new Set();
+    for (const p of shippedPaths) {
+        let d = dirname(p);
+        while (d !== "." && d !== "/") {
+            shippedFolders.add(key(d));
+            d = dirname(d);
+        }
+    }
+    const changes = [];
+    const reportedFolders = new Set();
+    for (const e of unlisted) {
+        if (e.kind === "special")
+            continue;
+        const k = key(e.path);
+        if (shippedFiles.has(k)) {
+            changes.push({ path: e.path, reason: "path_conflict", ships: "file" });
+            continue;
+        }
+        if (shippedFolders.has(k)) {
+            // An empty folder of the member's where the new version ships a folder simply
+            // merges with it; anything else at that path cannot share it.
+            if (e.kind !== "dir")
+                changes.push({ path: e.path, reason: "path_conflict", ships: "folder" });
+            continue;
+        }
+        // A member folder at a shipped FILE path: the shortest ancestor that is one.
+        let d = dirname(e.path);
+        const ancestors = [];
+        while (d !== "." && d !== "/") {
+            ancestors.unshift(d);
+            d = dirname(d);
+        }
+        const hit = ancestors.find((a) => shippedFiles.has(key(a)));
+        if (hit && !reportedFolders.has(key(hit))) {
+            reportedFolders.add(key(hit));
+            changes.push({ path: hit, reason: "path_conflict", ships: "file" });
+        }
+    }
+    return changes;
+}
+/** One row per path, in argument order; a path two checks both report keeps its first reason. */
+export function mergeChanges(...lists) {
+    const seen = new Set();
+    const out = [];
+    for (const list of lists) {
+        for (const c of list) {
+            if (seen.has(c.path))
+                continue;
+            seen.add(c.path);
+            out.push(c);
+        }
+    }
+    return out;
+}
+/** Should `entry` be carried, given the conflicts `--force` is about to replace? */
+export function isCarried(entry, conflicts, key) {
+    if (entry.kind === "special")
+        return false;
+    const k = key(entry.path);
+    for (const c of conflicts) {
+        if (c.reason !== "path_conflict")
+            continue;
+        const ck = key(c.path);
+        if (k === ck || k.startsWith(`${ck}/`))
+            return false;
+    }
+    return true;
+}
+/**
+ * Carry one unlisted entry from the current folder into the staging folder (ENG-A6):
+ * a regular file by HARD LINK when both sit on one filesystem (no doubled disk use, and
+ * the original stays in the old folder until the swap is verified), else a copy with its
+ * mode bits and times; a symlink verbatim (readlink + symlink, never followed); an empty
+ * folder recreated. Throws on failure, so the caller can abort with nothing changed.
+ */
+export function carryEntry(fromDir, toDir, entry) {
+    const src = join(fromDir, entry.path);
+    const dst = join(toDir, entry.path);
+    mkdirSync(dirname(dst), { recursive: true });
+    if (entry.kind === "dir") {
+        mkdirSync(dst, { recursive: true });
+        return;
+    }
+    if (entry.kind === "link") {
+        symlinkSync(readlinkSync(src), dst);
+        return;
+    }
+    if (entry.kind !== "file")
+        return;
+    try {
+        linkSync(src, dst);
+        return;
+    }
+    catch {
+        /* another filesystem, or links unsupported: copy below */
+    }
+    copyFileSync(src, dst);
+    const st = statSync(src);
+    chmodSync(dst, st.mode & 0o7777);
+    utimesSync(dst, st.atime, st.mtime);
+}
+/** A path from the member's own disk, made safe for a terminal row (names may hold anything). */
+const shown = (p) => terminalLine(p, SERVER_PATH_MAX);
+/** The refusal's human rows (at most `limit`, then a "+N more" line), one per change. */
+export function changeRows(changes, toVersion, limit = 10) {
+    const rows = changes.slice(0, limit).map((c) => {
+        if (c.reason === "modified")
+            return `  modified    ${shown(c.path)}`;
+        if (c.reason === "not_regular_file") {
+            return `  special     ${shown(c.path)}   a special file this install didn't create`;
+        }
+        const v = toVersion ? `v${toVersion}` : "the new version";
+        return `  conflicts   ${shown(c.path)}   ${v} adds a ${c.ships === "folder" ? "folder" : "file"} at this path`;
+    });
+    if (changes.length > limit)
+        rows.push(`  +${changes.length - limit} more; --json lists all`);
+    return rows;
+}
+/** `{path, reason}` pairs for `--json` (the `ships` hint stays human-only). */
+export function changesJson(changes) {
+    return changes.map((c) => ({ path: c.path, reason: c.reason }));
+}
+const plural = (n, one, many) => (n === 1 ? one : many);
+/**
+ * The `local_changes` refusal (DX-A1): what blocked, that nothing changed, both ways
+ * out, and (from the error's footer) the docs link. Exit 4. The message is printed in
+ * red and the two ways out follow it as the hint, so the order on screen is the
+ * contract's: rows, "Nothing was changed.", keep, discard, docs.
+ */
+export function localChangesRefusal(o) {
+    const versions = o.from !== null && o.to !== null && o.from !== o.to
+        ? ` (v${o.from} → v${o.to})`
+        : o.to !== null
+            ? ` (v${o.to})`
+            : o.from !== null
+                ? ` (v${o.from})`
+                : "";
+    const n = o.changes.length;
+    const head = `✖ Didn't ${o.verb} "${o.title}"${versions}: ${n} local ${plural(n, "change", "changes")} in ${shown(o.dir)}`;
+    const discard = o.verb === "uninstall"
+        ? "Discard these changes: add --force. It deletes the files listed above and keeps every other file you added."
+        : "Discard these changes: add --force. It replaces the files listed above and keeps every other file you added.";
+    return new CliError([head, ...changeRows(o.changes, o.to), "Nothing was changed."].join("\n"), EXIT.INTEGRITY, {
+        footer: "local_changes",
+        hint: `Keep your work: move these out of the folder, then run the same command again.\n${discard}`,
+        changes: changesJson(o.changes),
+    });
+}
+/** "Kept {n} of your files: a, b, c +2 more." — or nothing when nothing was carried. */
+export function keptLine(kept) {
+    if (kept.length === 0)
+        return null;
+    const names = kept.slice(0, 3).map(shown).join(", ");
+    const more = kept.length > 3 ? ` +${kept.length - 3} more` : "";
+    // "1 of your files" is the English for one: the noun counts the member's files.
+    return `Kept ${kept.length} of your files: ${names}${more}.`;
+}
+/** What `--force` replaced or removed, one line each, at most `limit` then "+N more". */
+export function forceLines(replaced, removed, limit = 10) {
+    const lines = replaced.map((r) => {
+        if (r.reason === "not_regular_file")
+            return `Removed ${shown(r.path)} (a special file)`;
+        if (!r.shipped)
+            return `Removed ${shown(r.path)} (you had edited it; the new version no longer ships it)`;
+        return r.reason === "modified"
+            ? `Replaced ${shown(r.path)} (you had edited it)`
+            : `Replaced ${shown(r.path)} (the new version ships this path)`;
+    });
+    for (const p of removed)
+        lines.push(`Removed ${shown(p)}`);
+    if (lines.length <= limit)
+        return lines;
+    return [...lines.slice(0, limit), `+${lines.length - limit} more; --json lists all`];
+}

package/dist/receipts.d.ts

@@ -53,6 +53,7 @@ export declare function scanReceipts(opts: {
 /**
  * DX5 local-edit guard: diff on-disk hashes vs the receipt manifest. A missing
  * file or a symlink where a regular file should be counts as modified (the
- * guard's job is "would uninstall/update destroy human work?").
+ * guard's job is "would uninstall/update destroy human work?"). Line endings
+ * alone never count (I8: a CRLF checkout is not an edit).
  */
 export declare function modifiedFiles(dir: string, receipt: Receipt): string[];

package/dist/receipts.js

@@ -4,7 +4,7 @@
 // is a "run npx promptdock@latest" refusal, never a guessy uninstall (DX F16).
 import { lstatSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { sha256Hex } from "./integrity.js";
+import { matchesReceiptHash } from "./integrity.js";
 import { TARGETS, targetBaseDir } from "./registry.js";
 export const RECEIPT_NAME = ".promptdock.json";
 export const RECEIPT_SCHEMA = 1;
@@ -75,6 +75,12 @@ export function scanReceipts(opts) {
                 continue;
             }
             for (const name of entries) {
+                // ⚠️ An install's temporary folders (`.promptdock-staging-*`, `.promptdock-old-*`)
+                // hold a receipt by design (1.2.2 writes it before the swap), and when the folder
+                // above the skills folder is not writable they sit HERE. Read as skills they would
+                // be listed, updated and uninstalled as if a member had installed them.
+                if (name.startsWith(".promptdock-"))
+                    continue;
                 const dir = join(base, name);
                 if (seenDirs.has(dir))
                     continue; // claude local==global base when cwd==home
@@ -98,7 +104,8 @@ export function scanReceipts(opts) {
 /**
  * DX5 local-edit guard: diff on-disk hashes vs the receipt manifest. A missing
  * file or a symlink where a regular file should be counts as modified (the
- * guard's job is "would uninstall/update destroy human work?").
+ * guard's job is "would uninstall/update destroy human work?"). Line endings
+ * alone never count (I8: a CRLF checkout is not an edit).
  */
 export function modifiedFiles(dir, receipt) {
     const modified = [];
@@ -110,7 +117,7 @@ export function modifiedFiles(dir, receipt) {
                 modified.push(f.path);
                 continue;
             }
-            if (sha256Hex(readFileSync(abs)) !== f.sha256.toLowerCase())
+            if (!matchesReceiptHash(readFileSync(abs), f.sha256))
                 modified.push(f.path);
         }
         catch {