@webpieces/rules-config 0.4.662 → 0.4.663

package/src/orphan-dir-archive.d.ts

@@ -0,0 +1,109 @@
+import { OrphanCandidate } from './orphan-dir-scan';
+/** Where every sweep's archive lands, under the repo-wide `.webpieces/` — never under a worktree's own. */
+export declare const TRASH_STATE_DIR = "trash";
+/** The per-sweep manifest, holding what moved and the command that brings each one back. */
+export declare const TRASH_MANIFEST_FILE = "manifest.json";
+/** Sweeps older than this are reaped by the next sweep. Matches RETENTION_DAYS for the aged-tree sweep. */
+export declare const TRASH_RETENTION_DAYS = 30;
+/**
+ * Moves orphan directories into `.webpieces/trash/<sweepId>/` and records how to bring each one back.
+ *
+ * ─── WHY `mv` AND NEVER `rm -rf` ──────────────────────────────────────────────────────────────────────
+ * This runs unattended, on other people's machines, against a predicate that is very good but is still a
+ * predicate. A `mv` makes the worst possible outcome — a false positive on a directory somebody actually
+ * wanted — a thing they undo in one command, instead of a thing they restore from a backup or lose. That
+ * single decision is what makes it defensible to run this automatically at all, and it is the same trade
+ * `wp-cleanup` already makes when it archives a branch to a tag before deleting the ref.
+ *
+ * ─── WHY ONE DIRECTORY PER SWEEP, TIMESTAMP-NAMED ─────────────────────────────────────────────────────
+ * `<sweepId>` is a UTC timestamp with `:` swapped for `-` (path-safe everywhere, Windows included). That
+ * spelling sorts LEXICALLY in chronological order, so `ls` reads oldest-first and `ls -r` newest-first,
+ * with no flags to remember and no dates to parse. Grouping by sweep also answers the only question
+ * anybody actually asks of this directory — "what did the run I just did take?" — which a single flat
+ * pile of moved directories cannot answer at all.
+ *
+ * Each sweep directory reproduces the repo-relative path of what it holds, so the manifest's `recover=`
+ * is an ordinary `mv` of one path to another, with no bookkeeping needed to reconstruct the destination.
+ */
+export declare class OrphanDirArchiver {
+    /**
+     * Move every candidate into a fresh sweep directory. `now` is a parameter so specs pin the sweep id
+     * instead of racing the clock.
+     */
+    archive(repoRoot: string, candidates: readonly OrphanCandidate[], now: Date): OrphanSweepResult;
+    /**
+     * Delete sweep directories older than TRASH_RETENTION_DAYS, and report how many went. Called by the
+     * sweeper AFTER a successful archive, so trash cannot grow without bound on a machine that has the
+     * flag on. This one really does delete — it is deleting the archive, which is the second copy.
+     */
+    reapAged(repoRoot: string, now: Date): number;
+    /** `<repo>/.webpieces/trash` — the SHARED state dir, so a worktree's trash is not stranded with it. */
+    trashRoot(repoRoot: string): string;
+    /**
+     * `2026-08-19T14-32-05Z`. ISO order with `:` replaced, and milliseconds dropped — a sweep is a
+     * human-scale event and a second is resolution enough to name one.
+     */
+    sweepId(now: Date): string;
+    /** The Date a sweep id names, or null when the entry is not one of ours (a stray file, say). */
+    private parseSweepId;
+    private listSweeps;
+    /**
+     * `mv` the directory, creating the destination's parent chain first. Returns null on success, or the
+     * failure's message — a directory we cannot move is REPORTED and skipped, never fatal.
+     *
+     * `fs.renameSync` first because it is atomic and instant within a filesystem; a cross-device rename
+     * (EXDEV — a repo whose `.webpieces` sits on a different mount) falls back to a recursive copy plus
+     * delete, which is what `mv` itself does in the same situation.
+     */
+    private move;
+    private moveAcrossDevices;
+    private isCrossDevice;
+    private removeTree;
+    /**
+     * The sweep's own record, beside what it took. Written even when every move failed, because "this
+     * sweep tried and could not" is exactly the state somebody debugging needs to find on disk.
+     *
+     * Returns the failure message, or null on success. It is REPORTED rather than swallowed: the manifest
+     * is the durable copy of every `recover=` command, so losing it silently is the one failure here that
+     * costs somebody the ability to undo what just happened. Still never fatal — the directories are
+     * already safely moved by this point, and the recover lines are still printed to the terminal.
+     */
+    private writeManifest;
+}
+/** One directory that was moved, and the exact command that undoes it. Data-only. */
+export declare class ArchivedOrphan {
+    /** Where it used to live, repo-relative. */
+    relativePath: string;
+    /** Where it lives now, absolute. */
+    archivedAt: string;
+    /** The `mv` that puts it back — printed to the human and stored in the manifest verbatim. */
+    recoverCommand: string;
+    constructor(relativePath: string, archivedAt: string, recoverCommand: string);
+}
+/** One directory the sweep found but could not move, with the reason. Data-only. */
+export declare class FailedOrphan {
+    relativePath: string;
+    reason: string;
+    constructor(relativePath: string, reason: string);
+}
+/** What one sweep did. Data-only. */
+export declare class OrphanSweepResult {
+    sweepId: string;
+    sweepDir: string;
+    moved: readonly ArchivedOrphan[];
+    failed: readonly FailedOrphan[];
+    /**
+     * Why the manifest could not be written, or null when it was. Non-null means the printed `recover=`
+     * lines are the ONLY copy — see writeManifest().
+     */
+    manifestError: string | null;
+    constructor(sweepId: string, sweepDir: string, moved: readonly ArchivedOrphan[], failed: readonly FailedOrphan[], manifestError: string | null);
+}
+/** The on-disk shape of `manifest.json`. Data-only. */
+export declare class OrphanSweepManifest {
+    sweepId: string;
+    repoRoot: string;
+    moved: readonly ArchivedOrphan[];
+    failed: readonly FailedOrphan[];
+    constructor(sweepId: string, repoRoot: string, moved: readonly ArchivedOrphan[], failed: readonly FailedOrphan[]);
+}

package/src/orphan-dir-archive.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrphanSweepManifest = exports.OrphanSweepResult = exports.FailedOrphan = exports.ArchivedOrphan = exports.OrphanDirArchiver = exports.TRASH_RETENTION_DAYS = exports.TRASH_MANIFEST_FILE = exports.TRASH_STATE_DIR = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const state_dir_1 = require("./state-dir");
+const to_error_1 = require("./to-error");
+/** Where every sweep's archive lands, under the repo-wide `.webpieces/` — never under a worktree's own. */
+exports.TRASH_STATE_DIR = 'trash';
+/** The per-sweep manifest, holding what moved and the command that brings each one back. */
+exports.TRASH_MANIFEST_FILE = 'manifest.json';
+/** Sweeps older than this are reaped by the next sweep. Matches RETENTION_DAYS for the aged-tree sweep. */
+exports.TRASH_RETENTION_DAYS = 30;
+const MILLIS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Moves orphan directories into `.webpieces/trash/<sweepId>/` and records how to bring each one back.
+ *
+ * ─── WHY `mv` AND NEVER `rm -rf` ──────────────────────────────────────────────────────────────────────
+ * This runs unattended, on other people's machines, against a predicate that is very good but is still a
+ * predicate. A `mv` makes the worst possible outcome — a false positive on a directory somebody actually
+ * wanted — a thing they undo in one command, instead of a thing they restore from a backup or lose. That
+ * single decision is what makes it defensible to run this automatically at all, and it is the same trade
+ * `wp-cleanup` already makes when it archives a branch to a tag before deleting the ref.
+ *
+ * ─── WHY ONE DIRECTORY PER SWEEP, TIMESTAMP-NAMED ─────────────────────────────────────────────────────
+ * `<sweepId>` is a UTC timestamp with `:` swapped for `-` (path-safe everywhere, Windows included). That
+ * spelling sorts LEXICALLY in chronological order, so `ls` reads oldest-first and `ls -r` newest-first,
+ * with no flags to remember and no dates to parse. Grouping by sweep also answers the only question
+ * anybody actually asks of this directory — "what did the run I just did take?" — which a single flat
+ * pile of moved directories cannot answer at all.
+ *
+ * Each sweep directory reproduces the repo-relative path of what it holds, so the manifest's `recover=`
+ * is an ordinary `mv` of one path to another, with no bookkeeping needed to reconstruct the destination.
+ */
+let OrphanDirArchiver = class OrphanDirArchiver {
+    /**
+     * Move every candidate into a fresh sweep directory. `now` is a parameter so specs pin the sweep id
+     * instead of racing the clock.
+     */
+    archive(repoRoot, candidates, now) {
+        const sweepId = this.sweepId(now);
+        const sweepDir = path.join(this.trashRoot(repoRoot), sweepId);
+        const moved = [];
+        const failed = [];
+        for (const candidate of candidates) {
+            const destination = path.join(sweepDir, candidate.relativePath);
+            const failure = this.move(candidate.absolutePath, destination);
+            if (failure !== null) {
+                failed.push(new FailedOrphan(candidate.relativePath, failure));
+                continue;
+            }
+            moved.push(new ArchivedOrphan(candidate.relativePath, destination, `mv '${destination}' '${candidate.absolutePath}'`));
+        }
+        const manifestError = this.writeManifest(sweepDir, sweepId, repoRoot, moved, failed);
+        return new OrphanSweepResult(sweepId, sweepDir, moved, failed, manifestError);
+    }
+    /**
+     * Delete sweep directories older than TRASH_RETENTION_DAYS, and report how many went. Called by the
+     * sweeper AFTER a successful archive, so trash cannot grow without bound on a machine that has the
+     * flag on. This one really does delete — it is deleting the archive, which is the second copy.
+     */
+    reapAged(repoRoot, now) {
+        const root = this.trashRoot(repoRoot);
+        const cutoff = now.getTime() - exports.TRASH_RETENTION_DAYS * MILLIS_PER_DAY;
+        let reaped = 0;
+        for (const entry of this.listSweeps(root)) {
+            const stamp = this.parseSweepId(entry);
+            if (stamp === null || stamp.getTime() >= cutoff)
+                continue;
+            if (this.removeTree(path.join(root, entry)))
+                reaped += 1;
+        }
+        return reaped;
+    }
+    /** `<repo>/.webpieces/trash` — the SHARED state dir, so a worktree's trash is not stranded with it. */
+    trashRoot(repoRoot) {
+        return path.join(state_dir_1.dotWebpieces.shared(repoRoot), exports.TRASH_STATE_DIR);
+    }
+    /**
+     * `2026-08-19T14-32-05Z`. ISO order with `:` replaced, and milliseconds dropped — a sweep is a
+     * human-scale event and a second is resolution enough to name one.
+     */
+    sweepId(now) {
+        return now.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/:/g, '-');
+    }
+    /** The Date a sweep id names, or null when the entry is not one of ours (a stray file, say). */
+    parseSweepId(entry) {
+        if (!SWEEP_ID_PATTERN.test(entry))
+            return null;
+        const iso = `${entry.slice(0, 10)}T${entry.slice(11, 19).replace(/-/g, ':')}Z`;
+        const parsed = new Date(iso);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    listSweeps(root) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: no trash directory yet is the normal
+        // state on every machine that has never swept, and it is not a condition anybody needs told about
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.readdirSync(root);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return [];
+        }
+    }
+    /**
+     * `mv` the directory, creating the destination's parent chain first. Returns null on success, or the
+     * failure's message — a directory we cannot move is REPORTED and skipped, never fatal.
+     *
+     * `fs.renameSync` first because it is atomic and instant within a filesystem; a cross-device rename
+     * (EXDEV — a repo whose `.webpieces` sits on a different mount) falls back to a recursive copy plus
+     * delete, which is what `mv` itself does in the same situation.
+     */
+    move(from, to) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: converts a per-directory move failure
+        // into a reported line, because one unmovable directory may not abandon the rest of the sweep
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.renameSync(from, to);
+            return null;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            return this.moveAcrossDevices(from, to, error);
+        }
+    }
+    moveAcrossDevices(from, to, cause) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the fallback's own failure becomes the
+        // reported message for this directory, the same contract move() has
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (!this.isCrossDevice(cause))
+                return cause.message;
+            fs.cpSync(from, to, { recursive: true });
+            fs.rmSync(from, { recursive: true, force: true });
+            return null;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            return error.message;
+        }
+    }
+    isCrossDevice(error) {
+        // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error
+        const code = error['code'];
+        return code === 'EXDEV';
+    }
+    removeTree(target) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: failing to reap OLD trash is cosmetic
+        // and may never surface as an error on a command whose real work already succeeded
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.rmSync(target, { recursive: true, force: true });
+            return true;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return false;
+        }
+    }
+    /**
+     * The sweep's own record, beside what it took. Written even when every move failed, because "this
+     * sweep tried and could not" is exactly the state somebody debugging needs to find on disk.
+     *
+     * Returns the failure message, or null on success. It is REPORTED rather than swallowed: the manifest
+     * is the durable copy of every `recover=` command, so losing it silently is the one failure here that
+     * costs somebody the ability to undo what just happened. Still never fatal — the directories are
+     * already safely moved by this point, and the recover lines are still printed to the terminal.
+     */
+    writeManifest(sweepDir, sweepId, repoRoot, moved, failed) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the directories are already safely
+        // moved by this point, and an unwritable manifest may not turn that success into a failure
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.mkdirSync(sweepDir, { recursive: true });
+            fs.writeFileSync(path.join(sweepDir, exports.TRASH_MANIFEST_FILE), `${JSON.stringify(new OrphanSweepManifest(sweepId, repoRoot, moved, failed), null, 2)}\n`, 'utf8');
+            return null;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            return error.message;
+        }
+    }
+};
+exports.OrphanDirArchiver = OrphanDirArchiver;
+exports.OrphanDirArchiver = OrphanDirArchiver = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], OrphanDirArchiver);
+/** One directory that was moved, and the exact command that undoes it. Data-only. */
+class ArchivedOrphan {
+    /** Where it used to live, repo-relative. */
+    relativePath;
+    /** Where it lives now, absolute. */
+    archivedAt;
+    /** The `mv` that puts it back — printed to the human and stored in the manifest verbatim. */
+    recoverCommand;
+    constructor(relativePath, archivedAt, recoverCommand) {
+        this.relativePath = relativePath;
+        this.archivedAt = archivedAt;
+        this.recoverCommand = recoverCommand;
+    }
+}
+exports.ArchivedOrphan = ArchivedOrphan;
+/** One directory the sweep found but could not move, with the reason. Data-only. */
+class FailedOrphan {
+    relativePath;
+    reason;
+    constructor(relativePath, reason) {
+        this.relativePath = relativePath;
+        this.reason = reason;
+    }
+}
+exports.FailedOrphan = FailedOrphan;
+/** What one sweep did. Data-only. */
+class OrphanSweepResult {
+    sweepId;
+    sweepDir;
+    moved;
+    failed;
+    /**
+     * Why the manifest could not be written, or null when it was. Non-null means the printed `recover=`
+     * lines are the ONLY copy — see writeManifest().
+     */
+    manifestError;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(sweepId, sweepDir, moved, failed, manifestError) {
+        this.sweepId = sweepId;
+        this.sweepDir = sweepDir;
+        this.moved = moved;
+        this.failed = failed;
+        this.manifestError = manifestError;
+    }
+}
+exports.OrphanSweepResult = OrphanSweepResult;
+/** The on-disk shape of `manifest.json`. Data-only. */
+class OrphanSweepManifest {
+    sweepId;
+    repoRoot;
+    moved;
+    failed;
+    constructor(sweepId, repoRoot, moved, failed) {
+        this.sweepId = sweepId;
+        this.repoRoot = repoRoot;
+        this.moved = moved;
+        this.failed = failed;
+    }
+}
+exports.OrphanSweepManifest = OrphanSweepManifest;
+// `2026-08-19T14-32-05Z` — the exact shape sweepId() writes, and the only shape reapAged() will delete.
+const SWEEP_ID_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z$/;
+//# sourceMappingURL=orphan-dir-archive.js.map

package/src/orphan-dir-archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-dir-archive.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/orphan-dir-archive.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { OrphanCandidate } from './orphan-dir-scan';\nimport { dotWebpieces } from './state-dir';\nimport { toError } from './to-error';\n\n/** Where every sweep's archive lands, under the repo-wide `.webpieces/` — never under a worktree's own. */\nexport const TRASH_STATE_DIR = 'trash';\n/** The per-sweep manifest, holding what moved and the command that brings each one back. */\nexport const TRASH_MANIFEST_FILE = 'manifest.json';\n/** Sweeps older than this are reaped by the next sweep. Matches RETENTION_DAYS for the aged-tree sweep. */\nexport const TRASH_RETENTION_DAYS = 30;\n\nconst MILLIS_PER_DAY = 24 * 60 * 60 * 1000;\n\n/**\n * Moves orphan directories into `.webpieces/trash/<sweepId>/` and records how to bring each one back.\n *\n * ─── WHY `mv` AND NEVER `rm -rf` ──────────────────────────────────────────────────────────────────────\n * This runs unattended, on other people's machines, against a predicate that is very good but is still a\n * predicate. A `mv` makes the worst possible outcome — a false positive on a directory somebody actually\n * wanted — a thing they undo in one command, instead of a thing they restore from a backup or lose. That\n * single decision is what makes it defensible to run this automatically at all, and it is the same trade\n * `wp-cleanup` already makes when it archives a branch to a tag before deleting the ref.\n *\n * ─── WHY ONE DIRECTORY PER SWEEP, TIMESTAMP-NAMED ─────────────────────────────────────────────────────\n * `<sweepId>` is a UTC timestamp with `:` swapped for `-` (path-safe everywhere, Windows included). That\n * spelling sorts LEXICALLY in chronological order, so `ls` reads oldest-first and `ls -r` newest-first,\n * with no flags to remember and no dates to parse. Grouping by sweep also answers the only question\n * anybody actually asks of this directory — \"what did the run I just did take?\" — which a single flat\n * pile of moved directories cannot answer at all.\n *\n * Each sweep directory reproduces the repo-relative path of what it holds, so the manifest's `recover=`\n * is an ordinary `mv` of one path to another, with no bookkeeping needed to reconstruct the destination.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class OrphanDirArchiver {\n    /**\n     * Move every candidate into a fresh sweep directory. `now` is a parameter so specs pin the sweep id\n     * instead of racing the clock.\n     */\n    archive(repoRoot: string, candidates: readonly OrphanCandidate[], now: Date): OrphanSweepResult {\n        const sweepId = this.sweepId(now);\n        const sweepDir = path.join(this.trashRoot(repoRoot), sweepId);\n        const moved: ArchivedOrphan[] = [];\n        const failed: FailedOrphan[] = [];\n        for (const candidate of candidates) {\n            const destination = path.join(sweepDir, candidate.relativePath);\n            const failure = this.move(candidate.absolutePath, destination);\n            if (failure !== null) {\n                failed.push(new FailedOrphan(candidate.relativePath, failure));\n                continue;\n            }\n            moved.push(new ArchivedOrphan(candidate.relativePath, destination,\n                `mv '${destination}' '${candidate.absolutePath}'`));\n        }\n        const manifestError = this.writeManifest(sweepDir, sweepId, repoRoot, moved, failed);\n        return new OrphanSweepResult(sweepId, sweepDir, moved, failed, manifestError);\n    }\n\n    /**\n     * Delete sweep directories older than TRASH_RETENTION_DAYS, and report how many went. Called by the\n     * sweeper AFTER a successful archive, so trash cannot grow without bound on a machine that has the\n     * flag on. This one really does delete — it is deleting the archive, which is the second copy.\n     */\n    reapAged(repoRoot: string, now: Date): number {\n        const root = this.trashRoot(repoRoot);\n        const cutoff = now.getTime() - TRASH_RETENTION_DAYS * MILLIS_PER_DAY;\n        let reaped = 0;\n        for (const entry of this.listSweeps(root)) {\n            const stamp = this.parseSweepId(entry);\n            if (stamp === null || stamp.getTime() >= cutoff) continue;\n            if (this.removeTree(path.join(root, entry))) reaped += 1;\n        }\n        return reaped;\n    }\n\n    /** `<repo>/.webpieces/trash` — the SHARED state dir, so a worktree's trash is not stranded with it. */\n    trashRoot(repoRoot: string): string {\n        return path.join(dotWebpieces.shared(repoRoot), TRASH_STATE_DIR);\n    }\n\n    /**\n     * `2026-08-19T14-32-05Z`. ISO order with `:` replaced, and milliseconds dropped — a sweep is a\n     * human-scale event and a second is resolution enough to name one.\n     */\n    sweepId(now: Date): string {\n        return now.toISOString().replace(/\\.\\d{3}Z$/, 'Z').replace(/:/g, '-');\n    }\n\n    /** The Date a sweep id names, or null when the entry is not one of ours (a stray file, say). */\n    private parseSweepId(entry: string): Date | null {\n        if (!SWEEP_ID_PATTERN.test(entry)) return null;\n        const iso = `${entry.slice(0, 10)}T${entry.slice(11, 19).replace(/-/g, ':')}Z`;\n        const parsed = new Date(iso);\n        return Number.isNaN(parsed.getTime()) ? null : parsed;\n    }\n\n    private listSweeps(root: string): string[] {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: no trash directory yet is the normal\n        // state on every machine that has never swept, and it is not a condition anybody needs told about\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readdirSync(root);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return [];\n        }\n    }\n\n    /**\n     * `mv` the directory, creating the destination's parent chain first. Returns null on success, or the\n     * failure's message — a directory we cannot move is REPORTED and skipped, never fatal.\n     *\n     * `fs.renameSync` first because it is atomic and instant within a filesystem; a cross-device rename\n     * (EXDEV — a repo whose `.webpieces` sits on a different mount) falls back to a recursive copy plus\n     * delete, which is what `mv` itself does in the same situation.\n     */\n    private move(from: string, to: string): string | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: converts a per-directory move failure\n        // into a reported line, because one unmovable directory may not abandon the rest of the sweep\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.mkdirSync(path.dirname(to), { recursive: true });\n            fs.renameSync(from, to);\n            return null;\n        } catch (err: unknown) {\n            const error = toError(err);\n            return this.moveAcrossDevices(from, to, error);\n        }\n    }\n\n    private moveAcrossDevices(from: string, to: string, cause: Error): string | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the fallback's own failure becomes the\n        // reported message for this directory, the same contract move() has\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!this.isCrossDevice(cause)) return cause.message;\n            fs.cpSync(from, to, { recursive: true });\n            fs.rmSync(from, { recursive: true, force: true });\n            return null;\n        } catch (err: unknown) {\n            const error = toError(err);\n            return error.message;\n        }\n    }\n\n    private isCrossDevice(error: Error): boolean {\n        // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error\n        const code = (error as unknown as Record<string, unknown>)['code'];\n        return code === 'EXDEV';\n    }\n\n    private removeTree(target: string): boolean {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: failing to reap OLD trash is cosmetic\n        // and may never surface as an error on a command whose real work already succeeded\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.rmSync(target, { recursive: true, force: true });\n            return true;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return false;\n        }\n    }\n\n    /**\n     * The sweep's own record, beside what it took. Written even when every move failed, because \"this\n     * sweep tried and could not\" is exactly the state somebody debugging needs to find on disk.\n     *\n     * Returns the failure message, or null on success. It is REPORTED rather than swallowed: the manifest\n     * is the durable copy of every `recover=` command, so losing it silently is the one failure here that\n     * costs somebody the ability to undo what just happened. Still never fatal — the directories are\n     * already safely moved by this point, and the recover lines are still printed to the terminal.\n     */\n    private writeManifest(sweepDir: string, sweepId: string, repoRoot: string,\n        moved: readonly ArchivedOrphan[], failed: readonly FailedOrphan[]): string | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the directories are already safely\n        // moved by this point, and an unwritable manifest may not turn that success into a failure\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.mkdirSync(sweepDir, { recursive: true });\n            fs.writeFileSync(path.join(sweepDir, TRASH_MANIFEST_FILE),\n                `${JSON.stringify(new OrphanSweepManifest(sweepId, repoRoot, moved, failed), null, 2)}\\n`, 'utf8');\n            return null;\n        } catch (err: unknown) {\n            const error = toError(err);\n            return error.message;\n        }\n    }\n}\n\n/** One directory that was moved, and the exact command that undoes it. Data-only. */\nexport class ArchivedOrphan {\n    /** Where it used to live, repo-relative. */\n    relativePath: string;\n    /** Where it lives now, absolute. */\n    archivedAt: string;\n    /** The `mv` that puts it back — printed to the human and stored in the manifest verbatim. */\n    recoverCommand: string;\n\n    constructor(relativePath: string, archivedAt: string, recoverCommand: string) {\n        this.relativePath = relativePath;\n        this.archivedAt = archivedAt;\n        this.recoverCommand = recoverCommand;\n    }\n}\n\n/** One directory the sweep found but could not move, with the reason. Data-only. */\nexport class FailedOrphan {\n    relativePath: string;\n    reason: string;\n\n    constructor(relativePath: string, reason: string) {\n        this.relativePath = relativePath;\n        this.reason = reason;\n    }\n}\n\n/** What one sweep did. Data-only. */\nexport class OrphanSweepResult {\n    sweepId: string;\n    sweepDir: string;\n    moved: readonly ArchivedOrphan[];\n    failed: readonly FailedOrphan[];\n    /**\n     * Why the manifest could not be written, or null when it was. Non-null means the printed `recover=`\n     * lines are the ONLY copy — see writeManifest().\n     */\n    manifestError: string | null;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(sweepId: string, sweepDir: string, moved: readonly ArchivedOrphan[],\n        failed: readonly FailedOrphan[], manifestError: string | null) {\n        this.sweepId = sweepId;\n        this.sweepDir = sweepDir;\n        this.moved = moved;\n        this.failed = failed;\n        this.manifestError = manifestError;\n    }\n}\n\n/** The on-disk shape of `manifest.json`. Data-only. */\nexport class OrphanSweepManifest {\n    sweepId: string;\n    repoRoot: string;\n    moved: readonly ArchivedOrphan[];\n    failed: readonly FailedOrphan[];\n\n    constructor(sweepId: string, repoRoot: string, moved: readonly ArchivedOrphan[],\n        failed: readonly FailedOrphan[]) {\n        this.sweepId = sweepId;\n        this.repoRoot = repoRoot;\n        this.moved = moved;\n        this.failed = failed;\n    }\n}\n\n// `2026-08-19T14-32-05Z` — the exact shape sweepId() writes, and the only shape reapAged() will delete.\nconst SWEEP_ID_PATTERN = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}Z$/;\n"]}

package/src/orphan-dir-scan.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Finds ORPHAN DIRECTORIES — the package directories an `nx g move` leaves behind on every clone, which
+ * git cannot remove and which then accumulate on every developer's machine forever.
+ *
+ * ─── WHY GIT LEAVES THEM ──────────────────────────────────────────────────────────────────────────────
+ * Git tracks files, not directories. When a move deletes every tracked file under `libraries/apis/foo/`,
+ * git removes that directory ONLY if it is then truly empty — and it never is, because the build already
+ * put an IGNORED `dist/` and `node_modules/` inside it. So the corpse stands, on every clone, and there
+ * is no git setting that changes this (`core.pruneIgnoredDirs` does not exist).
+ *
+ * ─── WHY THE PREDICATE IS GIT'S OWN ANSWER AND NOT A HAND-ROLLED WALK ─────────────────────────────────
+ * `git clean -Xdn` collapses a directory to a SINGLE entry exactly when everything beneath it is ignored,
+ * and it does that using the repo's real ignore engine — nested `.gitignore` files, `!` negations and
+ * all. Re-implementing that is how a sweeper ends up disagreeing with git about what is disposable.
+ *
+ * It also hands us the safety property for free, which is the reason this can run unattended: a directory
+ * holding even ONE untracked-but-not-ignored file is NOT reported, so a developer's uncommitted new
+ * package can never be a candidate. We do not check that ourselves; git's own output already encodes it.
+ *
+ * ─── THE ONE DISCRIMINATOR THAT NEEDS NO NAME LIST ────────────────────────────────────────────────────
+ * `clean -Xdn` reports two very different things the same way:
+ *
+ *     libraries/apis/pg-dataaccess-api/       ← a corpse: nothing tracked survives under it
+ *     libraries/apis/live-api/dist/           ← a LIVE project's build output, there on purpose
+ *
+ * They are separated by asking whether the directory ITSELF matches an ignore rule. `dist/` does
+ * (`.gitignore:19:dist/`); `pg-dataaccess-api` does not, which is precisely the statement that this
+ * directory was MEANT to hold tracked files — and none are left. No list of artifact directory names is
+ * needed, and none is maintained, so the rule adapts to whatever any given consumer repo ignores.
+ *
+ * That also yields the opt-out, and it is one a developer would reach for anyway: adding `my-sandbox/`
+ * to `.gitignore` makes the directory ignore-matched, which permanently protects it from this sweep.
+ */
+export declare class OrphanDirScanner {
+    /**
+     * Every orphan directory under `repoRoot`, as repo-RELATIVE paths with no trailing slash. Empty when
+     * the tree is clean, when `repoRoot` is not a git repository, or when git cannot be run at all — a
+     * sweeper is never important enough to fail somebody's checkout over.
+     */
+    scan(repoRoot: string): OrphanCandidate[];
+    /**
+     * The DIRECTORY paths `git clean -Xdn` would remove, relative to `repoRoot` and slash-stripped.
+     *
+     * Only entries ending in `/` are directories; a bare path is a single ignored FILE (`.env`,
+     * `.claude/settings.local.json`) and is none of this sweep's business. `Would skip repository` lines
+     * are git telling us it found a nested repo — a linked worktree — which it refuses to descend into,
+     * and so do we.
+     */
+    private reportedByGitClean;
+    /**
+     * True when git matches an ignore rule against the DIRECTORY ITSELF — i.e. it is a build artifact
+     * somebody declared disposable-but-expected, not a corpse. `check-ignore -q` exits 0 on a match and 1
+     * on no match, so a null answer here (any non-zero exit, including a git we could not run) means
+     * "cannot confirm", and the directory is SPARED. Every uncertainty in this class resolves that way.
+     */
+    private isIgnoredItself;
+    /**
+     * The two structural exclusions, both about where a moved nx PROJECT can possibly live.
+     *
+     * DOT SEGMENTS: `.nx/`, `.idea/`, `.webpieces/` and friends are reported whole by `clean -Xdn` (their
+     * contents are ignored, the directories themselves are not) and would otherwise pass the discriminator
+     * above perfectly. They are tool state, they are supposed to be there, and no nx project is named with
+     * a leading dot. Excluding the whole class by shape beats naming today's four and meeting a fifth.
+     *
+     * DEPTH: a moved project lives at `libraries/x`, `apps/x`, `packages/y/z` — never at the top level.
+     * Requiring depth >= 2 costs nothing real and takes every top-level directory in the repo permanently
+     * out of reach of an automated `mv`.
+     */
+    private isSweepable;
+    /**
+     * `git <args>` in `repoRoot`, or null when git exits non-zero or could not be run at all.
+     *
+     * spawnSync rather than execFileSync because a non-zero exit is ORDINARY here — `check-ignore` says
+     * "not ignored" that way — and a status code is a better answer to that question than an exception.
+     *
+     * An ARGUMENT ARRAY, never a shell string: these paths come from a filesystem scan and may hold
+     * spaces, quotes or `$`, and interpolating them into a shell would be building a command injection
+     * into the one tool whose entire job is moving directories around.
+     */
+    private git;
+}
+/** One directory the sweep may archive. Data-only (per CLAUDE.md — classes, not interfaces, for data). */
+export declare class OrphanCandidate {
+    /** Repo-relative, no trailing slash — e.g. `libraries/apis/pg-dataaccess-api`. */
+    relativePath: string;
+    /** The same directory as an absolute path, which is what any `mv` needs. */
+    absolutePath: string;
+    constructor(relativePath: string, absolutePath: string);
+}

package/src/orphan-dir-scan.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrphanCandidate = exports.OrphanDirScanner = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const child_process_1 = require("child_process");
+const inversify_1 = require("inversify");
+/**
+ * Finds ORPHAN DIRECTORIES — the package directories an `nx g move` leaves behind on every clone, which
+ * git cannot remove and which then accumulate on every developer's machine forever.
+ *
+ * ─── WHY GIT LEAVES THEM ──────────────────────────────────────────────────────────────────────────────
+ * Git tracks files, not directories. When a move deletes every tracked file under `libraries/apis/foo/`,
+ * git removes that directory ONLY if it is then truly empty — and it never is, because the build already
+ * put an IGNORED `dist/` and `node_modules/` inside it. So the corpse stands, on every clone, and there
+ * is no git setting that changes this (`core.pruneIgnoredDirs` does not exist).
+ *
+ * ─── WHY THE PREDICATE IS GIT'S OWN ANSWER AND NOT A HAND-ROLLED WALK ─────────────────────────────────
+ * `git clean -Xdn` collapses a directory to a SINGLE entry exactly when everything beneath it is ignored,
+ * and it does that using the repo's real ignore engine — nested `.gitignore` files, `!` negations and
+ * all. Re-implementing that is how a sweeper ends up disagreeing with git about what is disposable.
+ *
+ * It also hands us the safety property for free, which is the reason this can run unattended: a directory
+ * holding even ONE untracked-but-not-ignored file is NOT reported, so a developer's uncommitted new
+ * package can never be a candidate. We do not check that ourselves; git's own output already encodes it.
+ *
+ * ─── THE ONE DISCRIMINATOR THAT NEEDS NO NAME LIST ────────────────────────────────────────────────────
+ * `clean -Xdn` reports two very different things the same way:
+ *
+ *     libraries/apis/pg-dataaccess-api/       ← a corpse: nothing tracked survives under it
+ *     libraries/apis/live-api/dist/           ← a LIVE project's build output, there on purpose
+ *
+ * They are separated by asking whether the directory ITSELF matches an ignore rule. `dist/` does
+ * (`.gitignore:19:dist/`); `pg-dataaccess-api` does not, which is precisely the statement that this
+ * directory was MEANT to hold tracked files — and none are left. No list of artifact directory names is
+ * needed, and none is maintained, so the rule adapts to whatever any given consumer repo ignores.
+ *
+ * That also yields the opt-out, and it is one a developer would reach for anyway: adding `my-sandbox/`
+ * to `.gitignore` makes the directory ignore-matched, which permanently protects it from this sweep.
+ */
+let OrphanDirScanner = class OrphanDirScanner {
+    /**
+     * Every orphan directory under `repoRoot`, as repo-RELATIVE paths with no trailing slash. Empty when
+     * the tree is clean, when `repoRoot` is not a git repository, or when git cannot be run at all — a
+     * sweeper is never important enough to fail somebody's checkout over.
+     */
+    scan(repoRoot) {
+        const reported = this.reportedByGitClean(repoRoot);
+        const candidates = [];
+        for (const relative of reported) {
+            if (!this.isSweepable(relative))
+                continue;
+            if (this.isIgnoredItself(repoRoot, relative))
+                continue;
+            candidates.push(new OrphanCandidate(relative, path.join(repoRoot, relative)));
+        }
+        return candidates.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    }
+    /**
+     * The DIRECTORY paths `git clean -Xdn` would remove, relative to `repoRoot` and slash-stripped.
+     *
+     * Only entries ending in `/` are directories; a bare path is a single ignored FILE (`.env`,
+     * `.claude/settings.local.json`) and is none of this sweep's business. `Would skip repository` lines
+     * are git telling us it found a nested repo — a linked worktree — which it refuses to descend into,
+     * and so do we.
+     */
+    reportedByGitClean(repoRoot) {
+        const raw = this.git(repoRoot, ['clean', '-Xdn']);
+        if (raw === null)
+            return [];
+        const paths = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith(WOULD_REMOVE))
+                continue;
+            const target = trimmed.slice(WOULD_REMOVE.length).trim();
+            if (!target.endsWith('/'))
+                continue;
+            paths.push(target.slice(0, -1));
+        }
+        return paths;
+    }
+    /**
+     * True when git matches an ignore rule against the DIRECTORY ITSELF — i.e. it is a build artifact
+     * somebody declared disposable-but-expected, not a corpse. `check-ignore -q` exits 0 on a match and 1
+     * on no match, so a null answer here (any non-zero exit, including a git we could not run) means
+     * "cannot confirm", and the directory is SPARED. Every uncertainty in this class resolves that way.
+     */
+    isIgnoredItself(repoRoot, relative) {
+        return this.git(repoRoot, ['check-ignore', '-q', '--', relative]) !== null;
+    }
+    /**
+     * The two structural exclusions, both about where a moved nx PROJECT can possibly live.
+     *
+     * DOT SEGMENTS: `.nx/`, `.idea/`, `.webpieces/` and friends are reported whole by `clean -Xdn` (their
+     * contents are ignored, the directories themselves are not) and would otherwise pass the discriminator
+     * above perfectly. They are tool state, they are supposed to be there, and no nx project is named with
+     * a leading dot. Excluding the whole class by shape beats naming today's four and meeting a fifth.
+     *
+     * DEPTH: a moved project lives at `libraries/x`, `apps/x`, `packages/y/z` — never at the top level.
+     * Requiring depth >= 2 costs nothing real and takes every top-level directory in the repo permanently
+     * out of reach of an automated `mv`.
+     */
+    isSweepable(relative) {
+        const segments = relative.split('/');
+        if (segments.length < MIN_DEPTH)
+            return false;
+        return !segments.some((segment) => segment.startsWith('.'));
+    }
+    /**
+     * `git <args>` in `repoRoot`, or null when git exits non-zero or could not be run at all.
+     *
+     * spawnSync rather than execFileSync because a non-zero exit is ORDINARY here — `check-ignore` says
+     * "not ignored" that way — and a status code is a better answer to that question than an exception.
+     *
+     * An ARGUMENT ARRAY, never a shell string: these paths come from a filesystem scan and may hold
+     * spaces, quotes or `$`, and interpolating them into a shell would be building a command injection
+     * into the one tool whose entire job is moving directories around.
+     */
+    git(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', repoRoot, ...args], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: GIT_OUTPUT_LIMIT,
+        });
+        if (result.error !== undefined || result.status !== 0)
+            return null;
+        return result.stdout;
+    }
+};
+exports.OrphanDirScanner = OrphanDirScanner;
+exports.OrphanDirScanner = OrphanDirScanner = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], OrphanDirScanner);
+/** One directory the sweep may archive. Data-only (per CLAUDE.md — classes, not interfaces, for data). */
+class OrphanCandidate {
+    /** Repo-relative, no trailing slash — e.g. `libraries/apis/pg-dataaccess-api`. */
+    relativePath;
+    /** The same directory as an absolute path, which is what any `mv` needs. */
+    absolutePath;
+    constructor(relativePath, absolutePath) {
+        this.relativePath = relativePath;
+        this.absolutePath = absolutePath;
+    }
+}
+exports.OrphanCandidate = OrphanCandidate;
+const WOULD_REMOVE = 'Would remove ';
+// `libraries/foo` is depth 2. Anything shallower is a top-level directory — see isSweepable().
+const MIN_DEPTH = 2;
+// `clean -Xdn` on a large monorepo prints a few hundred lines; 16MB is a ceiling no real repo approaches.
+const GIT_OUTPUT_LIMIT = 16 * 1024 * 1024;
+//# sourceMappingURL=orphan-dir-scan.js.map