freeharness 0.4.1 → 0.4.2

package/dist/cli/hard-cleanup.js

@@ -0,0 +1,552 @@
+// Hard cleanup moves stale artifacts into `<home>/Archive/freeharness-<date>/`, never deleting one.
+// A project checkout is untrusted: no locator descends through a symlinked root, and a guard, run at
+// plan and again at apply, confines each source to its locator root and refuses protected paths.
+// The only removals: a source after its verified cross-device copy, and partial output of this call.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PLUGIN_KEY, UPSTREAM_PLUGIN_KEY } from "../adapters/memory/vendored.js";
+import { configDir, dataDir } from "../adapters/memory/doctor.js";
+import { FREE_DIR_NAME, LEGACY_DIR_NAME, resolveMemoryPaths } from "../adapters/memory/paths.js";
+import { removeJsonKey } from "./json-key-edit.js";
+/** Memory logs younger than this many days (by the date in the name) stay. */
+export const LOG_RETENTION_DAYS = 14;
+/** Build and OS junk moved out of a FreeHarness checkout's canonical/. */
+const CANONICAL_JUNK = new Set(["node_modules", "__pycache__", ".venv", ".DS_Store"]);
+const LOG_NAME = /^claude-mem-(\d{4})-(\d{2})-(\d{2})\.log$/;
+/** `<file>.<stamp>.bak`, the stamp being `toISOString()` (always with milliseconds) with `:` and `.` replaced by `-`. */
+const BACKUP_NAME = /^(.+)\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)\.bak$/;
+const REINSTALL = "freeharness init --scope user --only memory";
+/** The default filesystems of these platforms fold case, so path comparisons must too. */
+const FOLDS_CASE = process.platform === "darwin" || process.platform === "win32";
+const realFs = {
+    rename: (from, to) => fs.renameSync(from, to),
+    copy: (from, to) => {
+        const st = fs.lstatSync(from);
+        if (st.isFile()) {
+            // Onto the empty reservation `to`, so the name is never free between check and copy.
+            fs.copyFileSync(from, to);
+            fs.chmodSync(to, st.mode & 0o7777);
+            fs.utimesSync(to, st.atime, st.mtime);
+        }
+        else if (st.isSymbolicLink()) {
+            fs.unlinkSync(to);
+            fs.symlinkSync(fs.readlinkSync(from), to);
+        }
+        else {
+            fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true, errorOnExist: true, force: false });
+        }
+    },
+};
+/** Node reports an existing copy target as `EEXIST` from fs calls and `ERR_FS_CP_EEXIST` from `cpSync`. */
+function targetExists(e) {
+    const code = errCode(e);
+    return code === "EEXIST" || code === "ERR_FS_CP_EEXIST";
+}
+/** Escapes C0/C1, format (bidi, zero-width) and line-separator controls, so a file name cannot drive or reorder the terminal. */
+export function printable(s) {
+    return s.replace(/[\u0000-\u001f\u007f-\u009f\p{Cf}\p{Zl}\p{Zp}]/gu, (c) => {
+        const cp = c.codePointAt(0) ?? 0;
+        return cp <= 0xff ? `\\x${cp.toString(16).padStart(2, "0")}` : `\\u{${cp.toString(16)}}`;
+    });
+}
+function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function localDate(d) {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+function errCode(e) {
+    return e?.code;
+}
+/** `CODE: message` of an error; Node fs messages already open with their code. */
+function errText(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const code = errCode(e);
+    return !code || message.startsWith(code) ? message : `${code}: ${message}`;
+}
+/** Entry names of a dir, sorted; empty when it is absent, and noted when it is unreadable. */
+function names(dir, notes) {
+    try {
+        return fs.readdirSync(dir).sort();
+    }
+    catch (e) {
+        if (errCode(e) !== "ENOENT")
+            notes.push(`${dir} is unreadable (${errCode(e) ?? errText(e)}): not scanned`);
+        return [];
+    }
+}
+/** True, with a note, when a locator root is a symlink. */
+function linkedRoot(dir, notes) {
+    try {
+        if (!fs.lstatSync(dir).isSymbolicLink())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    notes.push(`skipped: ${dir} is a symlink; hard cleanup never follows one`);
+    return true;
+}
+/** Entry count and file bytes under a path, without following symlinks. */
+function treeStats(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (!st.isDirectory())
+            return { entries: 1, bytes: st.isFile() ? st.size : 0 };
+        return fs.readdirSync(p).reduce((sum, n) => {
+            const child = treeStats(path.join(p, n));
+            return { entries: sum.entries + child.entries, bytes: sum.bytes + child.bytes };
+        }, { entries: 1, bytes: 0 });
+    }
+    catch {
+        return { entries: 0, bytes: 0 };
+    }
+}
+function humanSize(n) {
+    if (n >= 1048576)
+        return `${(n / 1048576).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+/** First free name of `dest`, `dest.2`, ...; locators never share a destination. */
+export function freeDestination(dest) {
+    let candidate = dest;
+    for (let n = 2; lexists(candidate); n++)
+        candidate = `${dest}.${n}`;
+    return candidate;
+}
+function key(p) {
+    return FOLDS_CASE ? p.toLowerCase() : p;
+}
+/** Native realpath of the longest existing prefix, plus the missing rest. */
+function realOr(p) {
+    const abs = path.resolve(p);
+    try {
+        return fs.realpathSync.native(abs);
+    }
+    catch {
+        const parent = path.dirname(abs);
+        return parent === abs ? abs : path.join(realOr(parent), path.basename(abs));
+    }
+}
+/** The path with its parent dir resolved; the last segment is not followed, as a link moves as itself. */
+function resolveParent(p) {
+    const abs = path.resolve(p);
+    return path.join(realOr(path.dirname(abs)), path.basename(abs));
+}
+function same(a, b) {
+    return key(a) === key(b);
+}
+function within(child, parent) {
+    const rel = path.relative(key(parent), key(child));
+    // A child named `..x` is inside; only `..` itself or a `../` prefix leaves the parent.
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+/** Segments of `p` below `parent`, in `p`'s own case. */
+function below(p, parent) {
+    return p.split(path.sep).slice(parent.split(path.sep).length);
+}
+/** Why a path must be neither removed nor moved as itself: it is, lies in, or holds the plugin cache. The last segment is not followed. */
+export function pluginCacheOverlap(target, cfg) {
+    const p = resolveParent(target);
+    const cache = realOr(path.join(cfg, "plugins", "cache"));
+    if (same(p, cache) || within(p, cache))
+        return `resolves under the plugin cache (${cache})`;
+    if (within(cache, p))
+        return `is an ancestor of the plugin cache (${cache})`;
+    return undefined;
+}
+/** Same resolution as the data-dir guard below. */
+export function isOrHolds(candidate, dir) {
+    const p = resolveParent(candidate);
+    const d = realOr(dir);
+    return same(p, d) || within(d, p);
+}
+/** Why a source must stay, or undefined when it may move. */
+function protectedReason(source, ctx, projectRoot) {
+    const p = resolveParent(source);
+    if (path.isAbsolute(ctx.configDir)) {
+        const cached = pluginCacheOverlap(source, ctx.configDir);
+        if (cached)
+            return cached;
+    }
+    const inUseAndBothDefaults = [ctx.dataDir, path.join(ctx.home, FREE_DIR_NAME), path.join(ctx.home, LEGACY_DIR_NAME)];
+    for (const dir of inUseAndBothDefaults.filter((d) => path.isAbsolute(d))) {
+        const data = realOr(dir);
+        if (same(p, data))
+            return "is the memory data dir";
+        if (within(data, p))
+            return `is an ancestor of the memory data dir (${data})`;
+        if (within(p, data)) {
+            const rel = below(p, data);
+            const allowed = (rel.length === 2 && key(rel[0]) === "logs" && LOG_NAME.test(rel[1])) || (rel.length === 1 && BACKUP_NAME.exec(rel[0])?.[1] === "settings.json");
+            if (!allowed)
+                return `resolves into the memory data dir (${data}) outside logs/ and the settings backups`;
+        }
+    }
+    if (projectRoot) {
+        const changes = path.join(projectRoot, "openspec", "changes");
+        const sdd = realOr(path.join(projectRoot, ".freeharness", "sdd"));
+        if (within(p, sdd)) {
+            const change = below(p, sdd)[0];
+            if (lexists(path.join(changes, change)))
+                return `SDD workspace of the active change ${change}`;
+        }
+        for (const change of names(sdd, [])) {
+            if (lexists(path.join(changes, change)) && within(path.join(sdd, change), p))
+                return `is an ancestor of the SDD workspace of the active change ${change}`;
+        }
+    }
+    return undefined;
+}
+/** Why a source escapes its locator root (a symlink on the way, or a realpath outside), or undefined. */
+function escapeReason(source, base) {
+    if (!base || !within(source, base))
+        return `is outside its locator root${base ? ` ${base}` : ""}`;
+    let dir = base;
+    for (const segment of path.relative(base, source).split(path.sep).slice(0, -1)) {
+        dir = path.join(dir, segment);
+        if (lexists(dir) && fs.lstatSync(dir).isSymbolicLink())
+            return `is reached through the symlink ${dir}`;
+    }
+    const parent = realOr(path.dirname(source));
+    const root = realOr(base);
+    return same(parent, root) || within(parent, root) ? undefined : `resolves outside ${root}`;
+}
+/** The project root, or the deepest user dir holding the source. */
+function baseOf(g, source) {
+    if (g.scope === "project")
+        return g.projectRoot;
+    const dirs = [g.ctx.dataDir, g.ctx.configDir].filter((d) => path.isAbsolute(d) && within(source, d));
+    return dirs.sort((a, b) => b.length - a.length)[0] ?? "";
+}
+function guard(g, source) {
+    return protectedReason(source, g.ctx, g.scope === "project" ? g.projectRoot : "") ?? escapeReason(source, baseOf(g, source));
+}
+/** Stamped backups of `file` in `dir` except the newest, as `[name, ...]`. */
+function staleBackups(dir, file, notes) {
+    const own = names(dir, notes).filter((n) => BACKUP_NAME.exec(n)?.[1] === file);
+    // One prefix and one stamp width (BACKUP_NAME): lexical order is chronological.
+    return own.slice(0, -1);
+}
+function planUser(ctx, archiveRoot, items, notes, add) {
+    const logs = path.join(ctx.dataDir, "logs");
+    const cutoff = new Date(ctx.now.getFullYear(), ctx.now.getMonth(), ctx.now.getDate() - LOG_RETENTION_DAYS);
+    if (!linkedRoot(logs, notes)) {
+        for (const n of names(logs, notes)) {
+            const m = LOG_NAME.exec(n);
+            if (!m)
+                continue;
+            const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+            const day = new Date(y, mo - 1, d);
+            // Date rolls an out-of-range month or day over; such a name carries no real date.
+            if (day.getFullYear() !== y || day.getMonth() !== mo - 1 || day.getDate() !== d)
+                continue;
+            if (day < cutoff)
+                add(path.join(logs, n), path.join(archiveRoot, "memory", "logs", n), `memory log older than ${LOG_RETENTION_DAYS} days`);
+        }
+    }
+    for (const n of staleBackups(ctx.dataDir, "settings.json", notes)) {
+        add(path.join(ctx.dataDir, n), path.join(archiveRoot, "memory", "settings-bak", n), "memory settings backup (a newer one is kept)");
+    }
+    for (const n of staleBackups(ctx.configDir, "settings.json", notes)) {
+        add(path.join(ctx.configDir, n), path.join(archiveRoot, "claude-code", n), "Claude Code settings backup (a newer one is kept)");
+    }
+    const plugins = path.join(ctx.configDir, "plugins");
+    if (linkedRoot(plugins, notes))
+        return;
+    for (const file of ["installed_plugins.json", "known_marketplaces.json"]) {
+        for (const n of staleBackups(plugins, file, notes))
+            add(path.join(plugins, n), path.join(archiveRoot, "claude-code", n), `${file} backup (a newer one is kept)`);
+    }
+    const registry = path.join(plugins, "installed_plugins.json");
+    if (!fs.existsSync(registry))
+        return;
+    let entries;
+    try {
+        const raw = JSON.parse(fs.readFileSync(registry, "utf8"));
+        entries = raw.plugins && typeof raw.plugins === "object" ? raw.plugins : {};
+    }
+    catch {
+        notes.push(`${registry} is unreadable or not JSON: registry entries not checked`);
+        return;
+    }
+    const stamp = ctx.now.toISOString().replace(/[:.]/g, "-");
+    for (const pluginKey of [UPSTREAM_PLUGIN_KEY, PLUGIN_KEY]) {
+        if (!deadEntry(entries[pluginKey]))
+            continue;
+        items.push({
+            kind: "registry-entry",
+            source: registry,
+            destination: path.join(archiveRoot, "claude-code", `installed_plugins.json.${stamp}.pre-cleanup`),
+            reason: `${pluginKey} registry entry whose every install path is missing`,
+            key: pluginKey,
+            // Our own entry means a broken install, fixed by reinstalling rather than by forgetting it.
+            refused: pluginKey === PLUGIN_KEY ? `reinstall with \`${REINSTALL}\`` : undefined,
+        });
+    }
+}
+/** True when a registry value lists at least one install path and every one is absolute and missing. */
+function deadEntry(value) {
+    if (!Array.isArray(value))
+        return false;
+    const paths = value.map((v) => (v && typeof v === "object" ? v.installPath : undefined)).filter((p) => typeof p === "string");
+    // A relative path would resolve against this process's cwd.
+    return paths.length > 0 && paths.every((p) => path.isAbsolute(p) && !fs.existsSync(p));
+}
+function planProject(projectRoot, archiveRoot, notes, add) {
+    const base = path.basename(path.resolve(projectRoot));
+    const changes = path.join(projectRoot, "openspec", "changes");
+    const fh = path.join(projectRoot, ".freeharness");
+    if (!linkedRoot(fh, notes)) {
+        const sdd = path.join(fh, "sdd");
+        if (!linkedRoot(sdd, notes)) {
+            const archived = names(path.join(changes, "archive"), notes);
+            for (const change of names(sdd, notes)) {
+                const dir = path.join(sdd, change);
+                if (!isDir(dir) || lexists(path.join(changes, change)))
+                    continue;
+                if (archived.some((a) => a === change || (/^\d{4}-\d{2}-\d{2}-/.test(a) && a.slice(11) === change))) {
+                    add(dir, path.join(archiveRoot, base, "sdd", change), `SDD workspace of the archived change ${change}`);
+                }
+                else {
+                    notes.push(`kept: ${dir} (no active or archived change ${change}; it may belong to another branch)`);
+                }
+            }
+        }
+        const parked = path.join(fh, "parked");
+        if (!linkedRoot(parked, notes) && lexists(parked))
+            add(parked, path.join(archiveRoot, base, "parked"), "parked patches");
+    }
+    const canonical = path.join(projectRoot, "canonical");
+    if (linkedRoot(canonical, notes) || !fs.existsSync(path.join(canonical, "PROVENANCE.yaml")))
+        return;
+    const walk = (rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(canonical, rel), { withFileTypes: true });
+        }
+        catch (e) {
+            if (errCode(e) !== "ENOENT")
+                notes.push(`${path.join(canonical, rel)} is unreadable (${errCode(e) ?? errText(e)}): not scanned`);
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const child = path.join(rel, e.name);
+            if (CANONICAL_JUNK.has(e.name))
+                add(path.join(canonical, child), path.join(archiveRoot, base, "canonical-junk", child), `build or OS junk under canonical/`);
+            else if (e.isSymbolicLink()) {
+                if (isDir(path.join(canonical, child)))
+                    linkedRoot(path.join(canonical, child), notes);
+            }
+            else if (e.isDirectory())
+                walk(child);
+        }
+    };
+    walk("");
+}
+/** The dated archive every cleanup move lands in: `<home>/Archive/freeharness-<local date>`. */
+export function archiveRootFor(home, now) {
+    return path.join(home, "Archive", `freeharness-${localDate(now)}`);
+}
+/**
+ * Why a plugin-cache item must stay: its realpath is not strictly inside the plugin cache.
+ * The hard list's guard refuses every cache path by design, so cache items get this check instead.
+ */
+export function pluginCacheEscape(source, cfg) {
+    const cache = realOr(path.join(cfg, "plugins", "cache"));
+    return within(realOr(source), cache) ? undefined : `resolves outside the plugin cache (${cache})`;
+}
+/**
+ * Archive destination of a plugin-cache path, `<archiveRoot>/plugins-cache/<path below the cache>`; reads only.
+ * A source not spelled below the cache would map outside `plugins-cache`, so it is refused and gets
+ * the `plugins-cache` dir itself, which the apply-time check never accepts.
+ */
+export function pluginCacheArchive(source, cfg, archiveRoot) {
+    const cache = path.join(cfg, "plugins", "cache");
+    const rel = path.relative(cache, source);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        return { destination: path.join(archiveRoot, "plugins-cache"), refused: `is not below the plugin cache (${cache})` };
+    }
+    return { destination: freeDestination(path.join(archiveRoot, "plugins-cache", rel)), refused: pluginCacheEscape(source, cfg) };
+}
+/** Why a planned plugin-cache move must not run now: no archive root, a destination outside `<archiveRoot>/plugins-cache`, or a source escaping the cache. */
+export function pluginCacheRefusal(source, destination, cfg, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    const inbox = path.join(archiveRoot, "plugins-cache");
+    if (!within(destination, inbox))
+        return `destination ${destination} is outside ${inbox}`;
+    return pluginCacheEscape(source, cfg);
+}
+/** Builds the hard-item plan for a scope; reads only. */
+export function planHard(scope, projectRoot, ctx = {}) {
+    const home = ctx.home ?? os.homedir();
+    // An injected home without its own dirs must never fall through to the real config or data dir.
+    const full = {
+        home,
+        configDir: ctx.configDir ?? (ctx.home ? path.join(home, ".claude") : configDir()),
+        dataDir: ctx.dataDir ?? (ctx.home ? resolveMemoryPaths({}, home).dataDir : dataDir()),
+        now: ctx.now ?? new Date(),
+    };
+    const archiveRoot = archiveRootFor(home, full.now);
+    const items = [];
+    const notes = [];
+    const g = { scope, ctx: full, projectRoot };
+    const add = (source, dest, reason) => {
+        items.push({ kind: "move", source, destination: freeDestination(dest), reason, bytes: treeStats(source).bytes, refused: guard(g, source) });
+    };
+    // A relative dir would resolve against this process's cwd, not where its owner looks.
+    const relative = [["memory data dir", full.dataDir], ["config dir", full.configDir]].filter(([, d]) => !path.isAbsolute(d));
+    for (const [label, d] of relative)
+        notes.push(`${label} ${JSON.stringify(d)} is not absolute: ${scope === "user" ? "no user item planned" : "not checked as a protected path"}`);
+    if (scope === "project")
+        planProject(projectRoot, archiveRoot, notes, add);
+    else if (relative.length === 0)
+        planUser(full, archiveRoot, items, notes, add);
+    return { scope, archiveRoot, items, notes, ctx: full, projectRoot };
+}
+/** Takes the first free name of `dest`, `dest.2`, ... by creating it empty. */
+function reserve(dest, dir) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    for (let n = 1;; n++) {
+        const candidate = n === 1 ? dest : `${dest}.${n}`;
+        try {
+            if (dir)
+                fs.mkdirSync(candidate);
+            else
+                fs.closeSync(fs.openSync(candidate, "wx"));
+            return candidate;
+        }
+        catch (e) {
+            if (errCode(e) !== "EEXIST")
+                throw e;
+        }
+    }
+}
+/** Drops a reservation that is still the empty dir or file `reserve` made. */
+function release(dest, dir) {
+    try {
+        if (dir)
+            fs.rmdirSync(dest);
+        else if (fs.lstatSync(dest).isFile() && fs.lstatSync(dest).size === 0)
+            fs.unlinkSync(dest);
+    }
+    catch {
+        // Not empty, or gone: not ours to remove.
+    }
+}
+/**
+ * Moves one path to a reserved archive name; a failure before the source removal keeps the source
+ * whole. Across devices the source goes only after the copy matches it in entries and bytes; if that
+ * removal fails, part of the source may be gone, and the full copy is at the path the error names.
+ */
+function moveOne(source, planned, ops) {
+    const dir = fs.lstatSync(source).isDirectory();
+    const dest = reserve(planned, dir);
+    try {
+        ops.rename(source, dest);
+        return dest;
+    }
+    catch (e) {
+        if (errCode(e) !== "EXDEV") {
+            release(dest, dir);
+            throw e;
+        }
+    }
+    try {
+        ops.copy(source, dest);
+        const from = treeStats(source);
+        const to = treeStats(dest);
+        if (from.entries !== to.entries || from.bytes !== to.bytes)
+            throw Object.assign(new Error(`copy of ${source} is incomplete`), { code: "ESIZE" });
+    }
+    catch (e) {
+        // An existing target means another writer's content: it stays.
+        if (!targetExists(e)) {
+            try {
+                fs.rmSync(dest, { recursive: true, force: true });
+            }
+            catch (rmErr) {
+                throw Object.assign(new Error(`${errText(e)}; partial copy left at ${dest} (${errText(rmErr)})`), { code: errCode(e) });
+            }
+        }
+        throw e;
+    }
+    try {
+        fs.rmSync(source, { recursive: true });
+    }
+    catch (e) {
+        throw new Error(`copied to ${dest}, but removing the source failed (${errText(e)})`);
+    }
+    return dest;
+}
+/** Moves one path to a reserved name at or after `destination` with the hard mover's guarantees; returns where it landed. */
+export function archiveMove(source, destination, fsOps = {}) {
+    return moveOne(source, destination, { ...realFs, ...fsOps });
+}
+/** The WARN line of a failed move: a source gone since planning reads as such, anything else keeps its error code. */
+export function moveWarning(source, e) {
+    return errCode(e) === "ENOENT" && !lexists(source) ? `${source}: gone, nothing moved` : `${source}: ${errText(e)}`;
+}
+/** Removes a dead registry key through the shared config edit; an entry that came back to life stays. */
+function dropRegistryKey(item, ops) {
+    const r = removeJsonKey(item.source, ["plugins", item.key], item.destination, { stillMatches: deadEntry, rename: (from, to) => ops.rename(from, to) });
+    if (!r.ok)
+        throw new Error(`${item.key} not removed (${r.reason})`);
+    return r.copy;
+}
+/** Moves the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */
+export function applyHard(plan, confirmed = () => true, fsOps = {}) {
+    const ops = { ...realFs, ...fsOps };
+    const out = { moved: [], skipped: [], warnings: [] };
+    for (const item of plan.items) {
+        if (item.refused || !confirmed(item)) {
+            out.skipped.push(item.source);
+            continue;
+        }
+        const refused = within(item.destination, plan.archiveRoot) ? guard(plan, item.source) : `destination ${item.destination} is outside the archive root ${plan.archiveRoot}`;
+        if (refused) {
+            out.skipped.push(item.source);
+            out.warnings.push(`${item.source}: refused (${refused})`);
+            continue;
+        }
+        try {
+            if (item.kind === "registry-entry") {
+                const copy = dropRegistryKey(item, ops);
+                out.moved.push(`${item.source} (removed ${item.key}; original copied to ${copy})`);
+            }
+            else {
+                out.moved.push(`${item.source} -> ${moveOne(item.source, item.destination, ops)}`);
+            }
+        }
+        catch (e) {
+            out.warnings.push(moveWarning(item.source, e));
+        }
+    }
+    return out;
+}
+/** Renders a hard item for the preview, one line, without the OK/WARN prefix; the caller escapes it. */
+export function describeHard(item) {
+    if (item.refused)
+        return `keep: ${item.source}${item.kind === "registry-entry" ? ` (${item.key})` : ""} — ${item.reason} — ${item.refused}`;
+    if (item.kind === "registry-entry")
+        return `edit: ${item.source} (remove ${item.key}; original to ${item.destination}) — ${item.reason}`;
+    return `move: ${item.source} -> ${item.destination} (${humanSize(item.bytes)}) — ${item.reason}`;
+}

package/dist/cli/install-facts.d.ts

@@ -0,0 +1,28 @@
+import type { InstallManifest } from "../infra/manifest.js";
+/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`). */
+export declare const RETIRED: {
+    readonly skills: readonly ["local-code-intel"];
+    readonly agents: readonly ["mle-reviewer", "mle-evaluator", "implementer-medium", "implementer-high"];
+    readonly hooks: readonly ["freeharness-auto-memory.mjs"];
+};
+export type RetiredKind = "skill" | "agent" | "hook";
+export interface RetiredFinding {
+    kind: RetiredKind;
+    name: string;
+    path: string;
+    /** Manifest lists `path` (agent, hook) or a file under it (skill dir). */
+    recorded: boolean;
+}
+/** Whether a settings hook command runs a retired hook script; the entries `cleanup` prunes beside the script. */
+export declare function runsRetiredHook(command: string): boolean;
+/** Retired names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
+export declare function retiredFindings(claudeDir: string, manifest: InstallManifest | undefined): RetiredFinding[];
+/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
+export declare function canonicalNames(canonicalDir: string): {
+    agents: string[];
+    skills: string[];
+};
+/** Whether free-mem is enabled: only the settings key set to true counts, since an installed but disabled plugin keeps no memory. */
+export declare function freeMemEnabled(claudeDir: string): boolean;
+/** Whether free-mem is enabled or registered in installed_plugins.json; the hook-conflict and cleanup checks count a registered plugin too. */
+export declare function memoryPluginInstalled(claudeDir: string): boolean;

package/dist/cli/install-facts.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PLUGIN_KEY } from "../adapters/memory/vendored.js";
+/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`). */
+export const RETIRED = {
+    skills: ["local-code-intel"],
+    agents: ["mle-reviewer", "mle-evaluator", "implementer-medium", "implementer-high"],
+    hooks: ["freeharness-auto-memory.mjs"],
+};
+/** Whether a settings hook command runs a retired hook script; the entries `cleanup` prunes beside the script. */
+export function runsRetiredHook(command) {
+    return RETIRED.hooks.some((name) => command.includes(name));
+}
+/** Retired names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
+export function retiredFindings(claudeDir, manifest) {
+    const groups = [
+        { kind: "skill", dir: "skills", names: RETIRED.skills },
+        { kind: "agent", dir: "agents", names: RETIRED.agents },
+        { kind: "hook", dir: path.join("freeharness", "hooks"), names: RETIRED.hooks },
+    ];
+    const found = [];
+    for (const { kind, dir, names } of groups) {
+        for (const name of names) {
+            const fileName = kind === "agent" ? `${name}.md` : name;
+            const p = path.join(claudeDir, dir, fileName);
+            if (!fs.existsSync(p))
+                continue;
+            const under = `${p}${path.sep}`;
+            const recorded = manifest?.files.some((f) => f.path === p || f.path.startsWith(under)) ?? false;
+            found.push({ kind, name, path: p, recorded });
+        }
+    }
+    return found;
+}
+/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
+export function canonicalNames(canonicalDir) {
+    const list = (dir, dirsOnly) => {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => (dirsOnly ? e.isDirectory() : e.isFile() && e.name.endsWith(".md") && e.name !== "README.md"))
+            .map((e) => e.name);
+    };
+    return { agents: list(path.join(canonicalDir, "agents"), false), skills: list(path.join(canonicalDir, "skills"), true) };
+}
+function readJsonObject(f) {
+    try {
+        return JSON.parse(fs.readFileSync(f, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Whether free-mem is enabled: only the settings key set to true counts, since an installed but disabled plugin keeps no memory. */
+export function freeMemEnabled(claudeDir) {
+    const settings = readJsonObject(path.join(claudeDir, "settings.json"));
+    return settings?.enabledPlugins?.[PLUGIN_KEY] === true;
+}
+/** Whether free-mem is enabled or registered in installed_plugins.json; the hook-conflict and cleanup checks count a registered plugin too. */
+export function memoryPluginInstalled(claudeDir) {
+    if (freeMemEnabled(claudeDir))
+        return true;
+    const ip = readJsonObject(path.join(claudeDir, "plugins", "installed_plugins.json"));
+    return Boolean(ip.plugins && PLUGIN_KEY in ip.plugins);
+}

package/dist/cli/json-key-edit.d.ts

@@ -0,0 +1,18 @@
+/** A refusal carries a short token (`key-gone`, `copy-failed: EACCES`) the caller prints as is. */
+export type JsonKeyResult = {
+    ok: true;
+    copy: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface JsonKeyOptions {
+    /** Pass 2 re-checks the value, so an entry another program rewrote since pass 1 stays. */
+    stillMatches?: (value: unknown) => boolean;
+    rename?: (from: string, to: string) => void;
+}
+/**
+ * Removes `keyPath` from the JSON object in `file` after a verified copy of the unedited bytes
+ * lands at the first free name of `copyDest`. Every refusal leaves `file` byte-equal.
+ */
+export declare function removeJsonKey(file: string, keyPath: readonly string[], copyDest: string, options?: JsonKeyOptions): JsonKeyResult;