promptdock 1.2.1 → 1.2.2

package/dist/installer.js

@@ -1,20 +1,32 @@
 // The two-phase install engine (shared by `install` and `update`):
-//   POST install → download to a SIBLING temp dir → verify EVERY sha256 →
-//   re-validate EVERY path (E8/audit row 10 — the server is untrusted) →
-//   atomic move into place (same-parent rename; staged replace on update) →
-//   write the receipt → best-effort /install/complete.
-// All-or-nothing: any failure discards the temp dir and leaves the target
-// exactly as it was ("integrity check failed — nothing installed").
+//   POST install → refuse on local changes the manifest reveals → download into a
+//   temporary folder ABOVE the skills folder → verify EVERY sha256 → re-validate EVERY
+//   path (E8/audit row 10 — the server is untrusted) → check local changes AGAIN →
+//   carry the member's own files into the new copy → write the receipt into it → swap
+//   (same-filesystem renames, the old copy kept until the new one verifies) → best-effort
+//   /install/complete.
+// All-or-nothing: any failure before the swap discards the temporary folder and leaves
+// the target exactly as it was ("Nothing was installed" / "Nothing was changed").
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { CliError, EXIT, mapFsError, networkError } from "./errors.js";
+import { CliError, EXIT, mapFsError } from "./errors.js";
 import { SERVER_PATH_MAX, terminalLine } from "./terminal-text.js";
 import { CLI_DOS_MAX_SKILL_FILES as MAX_SKILL_FILES, CLI_DOS_MAX_SKILL_FILE_BYTES as MAX_SKILL_FILE_BYTES, CLI_DOS_MAX_SKILL_TOTAL_BYTES as MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
 import { sha256Hex, sha256Matches } from "./integrity.js";
+import { carryEntry, conflictChanges, isCarried, localChangesRefusal, mergeChanges, pathKeyFor, probeCaseInsensitive, receiptSideChanges, specialChanges, unlistedEntries, } from "./local-changes.js";
 import { validateSkillPaths } from "./paths.js";
-import { writeReceipt, RECEIPT_SCHEMA } from "./receipts.js";
+import { RECEIPT_NAME, readReceipt, writeReceipt, RECEIPT_SCHEMA } from "./receipts.js";
 const INTEGRITY_ABORT = "integrity check failed — nothing installed";
+/** An install's temporary folders, by kind. The number in the name is the operation's start. */
+export const STAGING_PREFIX = ".promptdock-staging-";
+export const OLD_PREFIX = ".promptdock-old-";
+/** A previous copy kept because the new one did not verify: never removed automatically. */
+export const KEPT_PREFIX = ".promptdock-kept-";
+/** `.promptdock-<kind>-<start ms>-<random>`: the age a later command reads (ENG-A4). */
+export function tempName(kind, startedAt) {
+    return `.promptdock-${kind}-${Math.floor(startedAt)}-${randomBytes(6).toString("hex")}`;
+}
 /** Narrow the untrusted install response; throws INTEGRITY on a bad shape. */
 export function checkInstallResponse(resp) {
     const bad = () => new CliError(`${INTEGRITY_ABORT} (malformed server response)`, EXIT.INTEGRITY, {
@@ -124,22 +136,65 @@ export function assertSafeManifest(manifest) {
     }
 }
 /**
- * Download every manifest file into `<parent>/.promptdock-staging-*` (SIBLING of
- * the target so the final rename never crosses filesystems), verifying sha256 +
- * byte length against the manifest. Throws (and discards the temp dir) on ANY
- * mismatch — the sha in the manifest is the transport-integrity anchor.
+ * Where an install's temporary folders live (DX-A2, I5): the folder ABOVE the skills
+ * folder, so a killed install never leaves a folder holding a SKILL.md where the agent
+ * scans for skills. Falls back to the skills folder itself when the folder above is
+ * missing, not writable, or on another filesystem (the swap must stay a rename, and a
+ * rename across filesystems fails with EXDEV). The skills folder must exist.
  */
-export async function downloadAndStage(ctx, api, resp, targetDir) {
-    assertSafeManifest(resp.manifest);
-    const urlByPath = new Map(resp.files.map((f) => [f.path, f.url]));
+export function tempRootFor(targetDir) {
     const parent = dirname(targetDir);
+    const grand = dirname(parent);
+    if (grand === parent)
+        return parent;
     try {
-        mkdirSync(parent, { recursive: true });
+        accessSync(grand, fsConstants.W_OK);
+        if (statSync(grand).dev !== statSync(parent).dev)
+            return parent;
+        return grand;
     }
-    catch (err) {
-        throw mapFsError(err, parent);
+    catch {
+        return parent;
     }
-    const tempDir = join(parent, `.promptdock-staging-${randomBytes(6).toString("hex")}`);
+}
+/** Can this process really create a folder in `dir`? (A mode-bit check can pass and lie.) */
+function canCreateIn(dir) {
+    const probe = join(dir, `.promptdock-probe-${randomBytes(4).toString("hex")}`);
+    try {
+        mkdirSync(probe);
+    }
+    catch {
+        return false;
+    }
+    rmSync(probe, { recursive: true, force: true });
+    return true;
+}
+const DROPPED = (path, i, n) => `The connection dropped while downloading ${terminalLine(path, SERVER_PATH_MAX)} (${i} of ${n}). Nothing was installed. Run the same command again.`;
+const LINKS_EXPIRED = "The download links expired before the files finished downloading. Nothing was installed. Run the same command again.";
+const CHANGED_WHILE_INSTALLING = "This skill changed while it was installing. Nothing was installed. Run the same command again.";
+/** A re-signed response must describe the same files, or it is not a refresh (I9). */
+function sameManifest(a, b) {
+    if (a.skill.version_id !== b.skill.version_id || a.manifest.length !== b.manifest.length)
+        return false;
+    const key = (e) => `${e.path}\u0000${e.sha256.toLowerCase()}`;
+    const want = new Set(a.manifest.map(key));
+    return b.manifest.every((e) => want.has(key(e)));
+}
+/**
+ * Download every manifest file into `tempDir` (which must not exist yet), verifying
+ * sha256 + byte length against the manifest. Throws (and removes `tempDir`) on ANY
+ * mismatch — the sha in the manifest is the transport-integrity anchor.
+ *
+ * I6: a dropped connection is exit 6 (`download`), never an "unexpected error".
+ * I9: signed URLs expire after a few minutes while files download one at a time, so a
+ * 400 or 403 from a signed URL re-signs ONCE through `resign` (the install endpoint:
+ * `record_skill_install` is idempotent per member and skill, so no second install is
+ * recorded) and retries; a second expiry is the plain "links expired" refusal.
+ */
+export async function downloadAndStage(ctx, resp0, tempDir, opts = {}) {
+    let resp = resp0;
+    assertSafeManifest(resp.manifest);
+    let urlByPath = new Map(resp.files.map((f) => [f.path, f.url]));
     const files = [];
     /**
      * Bytes actually RECEIVED, not bytes the server said it would send.
@@ -153,42 +208,84 @@ export async function downloadAndStage(ctx, api, resp, targetDir) {
      * The manifest check is a fast pre-flight; THIS is the enforcement.
      */
     let received = 0;
+    let resigned = false;
+    const n = resp.manifest.length;
     try {
-        mkdirSync(tempDir, { recursive: true });
-        for (const entry of resp.manifest) {
-            const url = urlByPath.get(entry.path);
-            if (!url) {
-                throw new CliError(`${INTEGRITY_ABORT} (no download URL for "${entry.path}")`, EXIT.INTEGRITY, {
-                    footer: "integrity",
-                });
-            }
-            let res;
-            try {
-                res = await ctx.fetch(url);
-            }
-            catch {
-                throw networkError(api.baseUrl, ctx.env);
-            }
-            if (!res.ok) {
-                // A lapsed signed URL is a free re-request (audit row 13) — say so.
-                throw new CliError(`download failed for "${entry.path}" (HTTP ${res.status}) — re-run the install (the download link may have expired; retrying is free)`, EXIT.NETWORK, { footer: "download" });
-            }
-            // ⚠️ CHECK BEFORE BUFFERING, then check again after.
-            //
-            // The fuse exists so a compromised server cannot fill your disk, and
-            // `await res.arrayBuffer()` reads the ENTIRE body into memory first — so a check
-            // that only runs afterwards has already let the download happen. A hostile server
-            // could stream gigabytes and the guard would fire, too late, on a machine that had
-            // already paid for it.
-            //
-            // So: refuse on a declared `content-length` over the fuse without reading a byte,
-            // and refuse again on the real length (content-length is server-supplied and may
-            // be absent or lie, which is exactly why the second check stays).
-            const declared = Number(res.headers.get("content-length"));
-            if (Number.isFinite(declared) && declared > MAX_SKILL_FILE_BYTES) {
-                throw new CliError(`${INTEGRITY_ABORT} ("${entry.path}" declares ${declared} bytes, over the limit)`, EXIT.INTEGRITY, { footer: "integrity" });
+        try {
+            mkdirSync(tempDir);
+        }
+        catch (err) {
+            throw mapFsError(err, tempDir);
+        }
+        for (let i = 0; i < resp.manifest.length; i++) {
+            const entry = resp.manifest[i];
+            let buf = null;
+            while (buf === null) {
+                const url = urlByPath.get(entry.path);
+                if (!url) {
+                    throw new CliError(`${INTEGRITY_ABORT} (no download URL for "${entry.path}")`, EXIT.INTEGRITY, {
+                        footer: "integrity",
+                    });
+                }
+                let res;
+                try {
+                    res = await ctx.fetch(url);
+                }
+                catch {
+                    throw new CliError(DROPPED(entry.path, i + 1, n), EXIT.NETWORK, { footer: "download" });
+                }
+                if ((res.status === 400 || res.status === 403) && opts.resign) {
+                    await res.body?.cancel().catch(() => { });
+                    if (resigned)
+                        throw new CliError(LINKS_EXPIRED, EXIT.NETWORK, { footer: "download" });
+                    resigned = true;
+                    let fresh;
+                    try {
+                        fresh = checkInstallResponse(await opts.resign());
+                    }
+                    catch (err) {
+                        if (err instanceof CliError && err.code === "version_conflict") {
+                            throw new CliError(CHANGED_WHILE_INSTALLING, err.exitCode, { footer: "version_conflict" });
+                        }
+                        throw err;
+                    }
+                    if (!sameManifest(resp, fresh)) {
+                        throw new CliError(CHANGED_WHILE_INSTALLING, EXIT.DENIED, { footer: "version_conflict" });
+                    }
+                    resp = fresh;
+                    urlByPath = new Map(resp.files.map((f) => [f.path, f.url]));
+                    continue;
+                }
+                if (!res.ok) {
+                    // A lapsed signed URL is a free re-request (audit row 13) — say so.
+                    throw new CliError(`download failed for "${entry.path}" (HTTP ${res.status}) — re-run the install (the download link may have expired; retrying is free)`, EXIT.NETWORK, { footer: "download" });
+                }
+                // ⚠️ CHECK BEFORE BUFFERING, then check again after.
+                //
+                // The fuse exists so a compromised server cannot fill your disk, and
+                // `await res.arrayBuffer()` reads the ENTIRE body into memory first — so a check
+                // that only runs afterwards has already let the download happen. A hostile server
+                // could stream gigabytes and the guard would fire, too late, on a machine that had
+                // already paid for it.
+                //
+                // So: refuse on a declared `content-length` over the fuse without reading a byte,
+                // and refuse again on the real length (content-length is server-supplied and may
+                // be absent or lie, which is exactly why the second check stays).
+                const declared = Number(res.headers.get("content-length"));
+                if (Number.isFinite(declared) && declared > MAX_SKILL_FILE_BYTES) {
+                    throw new CliError(`${INTEGRITY_ABORT} ("${entry.path}" declares ${declared} bytes, over the limit)`, EXIT.INTEGRITY, { footer: "integrity" });
+                }
+                try {
+                    buf = await readBounded(res, MAX_SKILL_FILE_BYTES, entry.path);
+                }
+                catch (err) {
+                    // I6: a body that stops mid-stream rejects with a bare TypeError ("terminated"),
+                    // which used to surface as "unexpected error" and exit 1.
+                    if (err instanceof CliError)
+                        throw err;
+                    throw new CliError(DROPPED(entry.path, i + 1, n), EXIT.NETWORK, { footer: "download" });
+                }
             }
-            const buf = await readBounded(res, MAX_SKILL_FILE_BYTES, entry.path);
             received += buf.byteLength;
             if (received > MAX_SKILL_TOTAL_BYTES) {
                 throw new CliError(`${INTEGRITY_ABORT} (the package sent more than the ${MAX_SKILL_TOTAL_BYTES}-byte install limit)`, EXIT.INTEGRITY, { footer: "integrity" });
@@ -208,7 +305,7 @@ export async function downloadAndStage(ctx, api, resp, targetDir) {
             }
             files.push({ path: entry.path, sha256: sha256Hex(buf) });
         }
-        return { tempDir, files };
+        return { tempDir, files, resp };
     }
     catch (err) {
         rmSync(tempDir, { recursive: true, force: true });
@@ -216,79 +313,240 @@ export async function downloadAndStage(ctx, api, resp, targetDir) {
     }
 }
 /**
- * Atomic-ish commit: fresh target → one rename; existing target → staged
- * replace (target → .promptdock-old-*, temp → target, drop old; on failure the
- * old dir is restored). Same-parent renames only.
+ * The full phase 2: refuse on manifest conflicts → download → verify → check again →
+ * carry → receipt into the new copy → swap → verify → drop the old copy → best-effort
+ * complete. `refString` is the canonical handle/slug.
  */
-export function commitStaged(tempDir, targetDir) {
+export async function performInstall(ctx, api, opts) {
+    // ENG-A4: one start time for both temporary folders, taken before the receipt is
+    // written, so the receipt is never older than the folders' names.
+    const startedAt = ctx.now();
+    const { targetDir, existing, force } = opts;
     const parent = dirname(targetDir);
+    try {
+        mkdirSync(parent, { recursive: true });
+    }
+    catch (err) {
+        throw mapFsError(err, parent);
+    }
+    // The folder above can pass a mode-bit check and still refuse a write (a sandbox, SIP);
+    // then the skills folder it is, as DX-A2 allows.
+    let root = tempRootFor(targetDir);
+    if (root !== parent && !canCreateIn(root))
+        root = parent;
+    const key = pathKeyFor(probeCaseInsensitive(root, ctx.platform));
+    const prior = existing.kind === "update" ? existing.receipt : null;
+    const carries = existing.kind === "update" || existing.kind === "unmanaged";
+    const shipped = opts.resp.manifest.map((e) => e.path);
+    const refuse = (changes) => localChangesRefusal({
+        verb: opts.verb,
+        title: opts.title,
+        from: prior ? String(prior.version) : null,
+        to: String(opts.resp.skill.version),
+        dir: targetDir,
+        changes,
+    });
+    /** what blocks right now: the receipt's view, then collisions with what ships */
+    const scan = () => {
+        const unlisted = unlistedEntries(targetDir, prior, key);
+        const conflicts = conflictChanges(unlisted, shipped, key);
+        const receiptSide = prior ? receiptSideChanges(targetDir, prior, unlisted) : specialChanges(unlisted);
+        return { unlisted, conflicts, blocking: mergeChanges(receiptSide, conflicts) };
+    };
+    // ── refuse before any download on what the manifest reveals (DX-A1's order) ─────────
+    if (carries && !force && existsSync(targetDir)) {
+        const { blocking } = scan();
+        if (blocking.length > 0)
+            throw refuse(blocking);
+    }
+    opts.onDownload?.(opts.resp);
+    // ── the temporary folder, removed by Ctrl-C until the swap (I5) ─────────────────────
+    const tempDir = join(root, tempName("staging", startedAt));
+    const releaseTrap = ctx.trap?.(() => rmSync(tempDir, { recursive: true, force: true })) ?? (() => { });
+    let staged;
+    try {
+        staged = await downloadAndStage(ctx, opts.resp, tempDir, { resign: opts.resign });
+    }
+    catch (err) {
+        releaseTrap();
+        throw err;
+    }
+    const resp = staged.resp;
+    let oldDir;
+    const kept = [];
+    const replaced = [];
+    const removed = [];
+    let receipt;
+    try {
+        // ── check again, right before the swap (ENG-A36) ──────────────────────────────────
+        if (carries && existsSync(targetDir)) {
+            const { unlisted, conflicts, blocking } = scan();
+            if (blocking.length > 0 && !force)
+                throw refuse(blocking);
+            const ships = new Set(shipped.map(key));
+            for (const c of blocking) {
+                replaced.push({
+                    path: c.path,
+                    reason: c.reason,
+                    shipped: c.reason === "path_conflict" || ships.has(key(c.path)),
+                });
+            }
+            // ── carry the member's own files into the new copy (ENG-A6) ─────────────────────
+            for (const e of unlisted) {
+                if (!isCarried(e, conflicts, key))
+                    continue;
+                try {
+                    carryEntry(targetDir, staged.tempDir, e);
+                }
+                catch (err) {
+                    throw mapFsError(err, join(targetDir, e.path));
+                }
+                if (e.kind === "file" || e.kind === "link")
+                    kept.push(e.path);
+            }
+        }
+        else if (existing.kind === "foreign" && existsSync(targetDir)) {
+            for (const e of unlistedEntries(targetDir, null, key)) {
+                if (e.kind !== "dir")
+                    removed.push(e.path);
+            }
+        }
+        // ── the receipt goes in BEFORE the swap (I5) ──────────────────────────────────────
+        receipt = {
+            schema: RECEIPT_SCHEMA,
+            cli_version: ctx.version,
+            skill_id: resp.skill.id,
+            ref: opts.refString,
+            version_id: resp.skill.version_id,
+            version: resp.skill.version,
+            installed_at: new Date(Math.max(ctx.now(), startedAt)).toISOString(),
+            target: opts.targetId,
+            files: staged.files,
+        };
+        try {
+            writeReceipt(staged.tempDir, receipt, prior ?? undefined);
+        }
+        catch (err) {
+            throw mapFsError(err, join(staged.tempDir, RECEIPT_NAME));
+        }
+        oldDir = commitStaged(staged.tempDir, targetDir, root, startedAt);
+    }
+    catch (err) {
+        rmSync(staged.tempDir, { recursive: true, force: true });
+        releaseTrap();
+        throw err;
+    }
+    releaseTrap();
+    const warnings = [];
+    if (oldDir) {
+        const problem = verifyInstalled(targetDir, resp.manifest, kept);
+        if (problem) {
+            // ⚠️ Never leave this copy under the `old` name: the leftover sweep deletes an old
+            // copy whose target holds a newer receipt, which this target does.
+            const keptDir = join(root, tempName("kept", startedAt));
+            try {
+                renameSync(oldDir, keptDir);
+                rmSync(`${oldDir}.json`, { force: true });
+                warnings.push(`Kept the previous copy at ${keptDir} because ${problem}. Check ${targetDir}, then delete the previous copy.`);
+            }
+            catch {
+                warnings.push(`Kept the previous copy at ${oldDir} because ${problem}. Check ${targetDir}, then delete the previous copy.`);
+            }
+        }
+        else {
+            try {
+                rmSync(oldDir, { recursive: true, force: true });
+                rmSync(`${oldDir}.json`, { force: true });
+            }
+            catch (err) {
+                warnings.push(`Couldn't remove the previous copy at ${oldDir} (${err.message}); the next promptdock command removes it.`);
+            }
+        }
+    }
+    // E5 phase 2 — best-effort: the files are on disk either way; the server's
+    // grace sweep expires an uncompleted ticket, and a retryable complete is
+    // idempotent. Never fail a finished install over this call.
+    try {
+        await api.request("POST", `/api/v1/cli/skills/${resp.skill.id}/install/complete`);
+    }
+    catch {
+        /* best-effort */
+    }
+    return { receipt, kept, replaced, removed, warnings };
+}
+/**
+ * The swap. A fresh target is one rename. An existing target goes aside as
+ * `.promptdock-old-*` under `root`, beside a sidecar naming the target so a later
+ * command can put it back after a crash (ENG-A4); the staged copy is renamed in, and
+ * the old copy is returned for the caller to verify against and then delete (ENG-A36).
+ * A failed second rename renames the old copy back: the machine must never end up with
+ * NOTHING.
+ */
+export function commitStaged(tempDir, targetDir, root, startedAt) {
     if (!existsSync(targetDir)) {
         try {
             renameSync(tempDir, targetDir);
         }
         catch (err) {
-            rmSync(tempDir, { recursive: true, force: true });
             throw mapFsError(err, targetDir);
         }
-        return;
+        return null;
+    }
+    const oldDir = join(root, tempName("old", startedAt));
+    try {
+        writeFileSync(`${oldDir}.json`, JSON.stringify({ target: targetDir }) + "\n");
+    }
+    catch (err) {
+        throw mapFsError(err, `${oldDir}.json`);
     }
-    const oldDir = join(parent, `.promptdock-old-${randomBytes(6).toString("hex")}`);
     try {
         renameSync(targetDir, oldDir);
     }
     catch (err) {
-        rmSync(tempDir, { recursive: true, force: true });
+        rmSync(`${oldDir}.json`, { force: true });
         throw mapFsError(err, targetDir);
     }
     try {
         renameSync(tempDir, targetDir);
     }
     catch (err) {
-        // Roll the old contents back — the machine must never end up with NOTHING.
         try {
             renameSync(oldDir, targetDir);
+            rmSync(`${oldDir}.json`, { force: true });
         }
         catch {
-            /* the old dir stays on disk for manual recovery */
+            /* the old copy and its sidecar stay for the next command to restore */
         }
-        rmSync(tempDir, { recursive: true, force: true });
         throw mapFsError(err, targetDir);
     }
-    rmSync(oldDir, { recursive: true, force: true });
+    return oldDir;
 }
 /**
- * The full phase-2: download → verify → commit → receipt → best-effort complete.
- * `refString` is the canonical handle/slug; `prior` carries a matching update's
- * receipt so unknown fields survive the rewrite (DX F16).
+ * After the swap: does the new copy hold its receipt, every shipped file with the right
+ * bytes, and every member file that was carried? Returns why not, or null. Only then is
+ * the old copy deleted (ENG-A36), so a defect in the carry can never cost a member a
+ * file.
  */
-export async function performInstall(ctx, api, opts) {
-    const staged = await downloadAndStage(ctx, api, opts.resp, opts.targetDir);
-    commitStaged(staged.tempDir, opts.targetDir);
-    const receipt = {
-        schema: RECEIPT_SCHEMA,
-        cli_version: ctx.version,
-        skill_id: opts.resp.skill.id,
-        ref: opts.refString,
-        version_id: opts.resp.skill.version_id,
-        version: opts.resp.skill.version,
-        installed_at: new Date(ctx.now()).toISOString(),
-        target: opts.targetId,
-        files: staged.files,
-    };
-    try {
-        writeReceipt(opts.targetDir, receipt, opts.prior);
-    }
-    catch (err) {
-        throw mapFsError(err, join(opts.targetDir, ".promptdock.json"));
-    }
-    // E5 phase 2 — best-effort: the files are on disk either way; the server's
-    // grace sweep expires an uncompleted ticket, and a retryable complete is
-    // idempotent. Never fail a finished install over this call.
-    try {
-        await api.request("POST", `/api/v1/cli/skills/${opts.resp.skill.id}/install/complete`);
+function verifyInstalled(targetDir, manifest, kept) {
+    if (readReceipt(targetDir).kind !== "ok")
+        return "the new copy has no readable receipt";
+    for (const e of manifest) {
+        try {
+            if (!sha256Matches(readFileSync(join(targetDir, e.path)), e.sha256)) {
+                return `${e.path} did not verify after the swap`;
+            }
+        }
+        catch {
+            return `${e.path} is missing after the swap`;
+        }
     }
-    catch {
-        /* best-effort */
+    for (const p of kept) {
+        try {
+            lstatSync(join(targetDir, p));
+        }
+        catch {
+            return `your file ${p} did not carry over`;
+        }
     }
-    return receipt;
+    return null;
 }

package/dist/integrity.d.ts

@@ -2,3 +2,16 @@
 export declare function sha256Hex(data: Uint8Array | Buffer): string;
 /** Constant-shape compare (case-forgiving hex; empty expected = never matches). */
 export declare function sha256Matches(data: Uint8Array | Buffer, expectedHex: string): boolean;
+/**
+ * Does `buf` hold the bytes a receipt recorded, line endings aside? (I8, 1.2.2)
+ *
+ * A skill folder checked out with git's `autocrlf` gets CRLF endings, and a byte-exact
+ * hash then calls every text file edited, which refuses every update and uninstall for a
+ * change nobody made. So a mismatch is retried with the content normalized to LF and to
+ * CRLF. A match after normalization means the file differs ONLY in line endings, which
+ * no update or uninstall can destroy anything by replacing.
+ *
+ * A NUL byte means binary, and binary never gets the retry: rewriting `\r\n` inside a
+ * binary file is not a line-ending difference.
+ */
+export declare function matchesReceiptHash(buf: Buffer, sha256: string): boolean;

package/dist/integrity.js

@@ -9,3 +9,30 @@ export function sha256Matches(data, expectedHex) {
         return false;
     return sha256Hex(data) === expectedHex.toLowerCase();
 }
+/**
+ * Does `buf` hold the bytes a receipt recorded, line endings aside? (I8, 1.2.2)
+ *
+ * A skill folder checked out with git's `autocrlf` gets CRLF endings, and a byte-exact
+ * hash then calls every text file edited, which refuses every update and uninstall for a
+ * change nobody made. So a mismatch is retried with the content normalized to LF and to
+ * CRLF. A match after normalization means the file differs ONLY in line endings, which
+ * no update or uninstall can destroy anything by replacing.
+ *
+ * A NUL byte means binary, and binary never gets the retry: rewriting `\r\n` inside a
+ * binary file is not a line-ending difference.
+ */
+export function matchesReceiptHash(buf, sha256) {
+    const want = sha256.toLowerCase();
+    if (sha256Hex(buf) === want)
+        return true;
+    if (buf.includes(0))
+        return false;
+    const text = buf.toString("latin1");
+    if (!text.includes("\n"))
+        return false;
+    const lf = text.replace(/\r\n/g, "\n");
+    if (sha256Hex(Buffer.from(lf, "latin1")) === want)
+        return true;
+    const crlf = lf.replace(/\n/g, "\r\n");
+    return sha256Hex(Buffer.from(crlf, "latin1")) === want;
+}

package/dist/leftovers.d.ts

@@ -0,0 +1,32 @@
+import type { CliContext } from "./context.js";
+/** A staging folder younger than this may belong to an install still running. */
+export declare const STAGING_MAX_AGE_MS: number;
+export type LeftoverNote = {
+    kind: "removed";
+    path: string;
+} | {
+    kind: "restored";
+    path: string;
+} | {
+    kind: "undated";
+    path: string;
+} | {
+    kind: "unclaimed";
+    path: string;
+};
+/** Both folders an install's temporary folders for `targetDir` can be in. */
+export declare function tempRootsFor(targetDir: string): string[];
+/** The temporary-folder roots for every skills folder a lifecycle command can see. */
+export declare function sweepRoots(opts: {
+    cwd: string;
+    home: string;
+    scope: "local" | "global" | "both";
+    targetId?: string;
+    dir?: string;
+}): string[];
+/** Sweep `roots` (deduplicated). Never throws: a leftover must not block the command. */
+export declare function sweepLeftovers(roots: string[], now: number): LeftoverNote[];
+/** The line each note prints on stderr (stdout stays the command's own, `--json` or not). */
+export declare function leftoverLine(note: LeftoverNote): string;
+/** Sweep and report: what every skill-touching command runs before it reads a receipt. */
+export declare function sweepAndReport(ctx: CliContext, roots: string[]): void;