commandmate 0.11.4 → 0.12.1

package/dist/server/src/lib/skills/uninstall-apply.js

@@ -0,0 +1,495 @@
+"use strict";
+/**
+ * Deleting exactly the files CommandMate wrote, and nothing else (Issue #1236)
+ *
+ * The delete half of the plan/apply pair, and the only module in the codebase
+ * that removes Skill payload from a repository. #1235's install could rely on a
+ * single atomic rename for its safety argument; deletion has no such primitive,
+ * so the argument here is built from four rules instead:
+ *
+ * - **Zero-delete on ambiguity.** The whole install root is re-assessed before
+ *   the first `unlink`. One modified, unknown, missing or irregular path and the
+ *   operation stops having deleted nothing. There is no partial uninstall —
+ *   "removed seven of eight files" is a corrupted Skill reported as a success.
+ * - **The destination is derived, never received.** The install root comes from
+ *   the server-resolved worktree path plus a Skill ID re-checked against
+ *   {@link SKILL_ID_PATTERN}, using #1233's resolver — the same derivation
+ *   install uses, because a delete that resolved its target differently from the
+ *   write that created it would eventually resolve it somewhere else entirely.
+ * - **Nothing is followed.** Every path component from the install root down is
+ *   `lstat`ed immediately before the file it leads to is unlinked, so a symlink
+ *   swapped in after the scan is refused rather than traversed. `unlink` itself
+ *   never follows its final component, so the directory chain is the exposure.
+ * - **Directories go only when empty.** `rmdir(2)` is used, never a recursive
+ *   remove, and only on directories the receipt's own file list implies. An
+ *   empty directory the user made is not ours to collect.
+ *
+ * The receipt is deleted **last**. Until it is gone the directory still explains
+ * itself: a crash mid-delete leaves a worktree that #1234 reconciliation — and a
+ * human reading `.commandmate-receipt.json` — can still make sense of.
+ *
+ * @module lib/skills/uninstall-apply
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillUninstallError = exports.SKILL_UNINSTALL_ERROR_STATUS = exports.SkillUninstallErrorCode = void 0;
+exports.isSkillUninstallError = isSkillUninstallError;
+exports.resolveSkillUninstallTarget = resolveSkillUninstallTarget;
+exports.resolveSkillUninstallTargetFor = resolveSkillUninstallTargetFor;
+exports.assertSkillUninstallAncestors = assertSkillUninstallAncestors;
+exports.removeReceiptOwnedFile = removeReceiptOwnedFile;
+exports.applySkillUninstall = applySkillUninstall;
+exports.hasRemovedSkillPayload = hasRemovedSkillPayload;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("../../lib/skills/constants");
+const integrity_1 = require("../../lib/skills/integrity");
+const install_plan_1 = require("../../lib/skills/install-plan");
+const preview_diff_1 = require("../../lib/skills/preview-diff");
+const uninstall_plan_1 = require("../../lib/skills/uninstall-plan");
+// =============================================================================
+// Errors
+// =============================================================================
+/** Client-safe reasons an uninstall refused to delete or could not finish. */
+exports.SkillUninstallErrorCode = {
+    /** The install root could not be derived safely from the worktree and Skill ID. */
+    TARGET_UNSAFE: 'SKILL_UNINSTALL_TARGET_UNSAFE',
+    /** An ancestor of the install root is a symlink or is not a directory. */
+    ANCESTOR_UNSAFE: 'SKILL_UNINSTALL_ANCESTOR_UNSAFE',
+    /** There is nothing to uninstall at the target. */
+    NOT_INSTALLED: 'SKILL_UNINSTALL_NOT_INSTALLED',
+    /** At least one path is not provably managed and unchanged. Nothing was deleted. */
+    BLOCKED: 'SKILL_UNINSTALL_BLOCKED',
+    /** The install root changed between the plan and this apply. Nothing was deleted. */
+    DRIFT: 'SKILL_UNINSTALL_DRIFT',
+    /** A file changed between the re-assessment and its own delete. */
+    FILE_CHANGED: 'SKILL_UNINSTALL_FILE_CHANGED',
+    /** A path or one of its ancestors is not what it was when it was scanned. */
+    PATH_UNSAFE: 'SKILL_UNINSTALL_PATH_UNSAFE',
+    /** The delete syscall itself failed. */
+    DELETE_FAILED: 'SKILL_UNINSTALL_DELETE_FAILED',
+};
+/** HTTP status each reason maps to, so every caller answers alike. */
+exports.SKILL_UNINSTALL_ERROR_STATUS = {
+    [exports.SkillUninstallErrorCode.TARGET_UNSAFE]: 400,
+    [exports.SkillUninstallErrorCode.ANCESTOR_UNSAFE]: 409,
+    [exports.SkillUninstallErrorCode.NOT_INSTALLED]: 404,
+    [exports.SkillUninstallErrorCode.BLOCKED]: 409,
+    [exports.SkillUninstallErrorCode.DRIFT]: 409,
+    [exports.SkillUninstallErrorCode.FILE_CHANGED]: 409,
+    [exports.SkillUninstallErrorCode.PATH_UNSAFE]: 409,
+    [exports.SkillUninstallErrorCode.DELETE_FAILED]: 500,
+};
+/** An uninstall rejection. The message is built from the code — never from a path. */
+class SkillUninstallError extends Error {
+    code;
+    detail;
+    blockers;
+    constructor(code, detail, 
+    /** Repository-relative paths that blocked the operation, for UX-07. */
+    blockers = []) {
+        super(`Skill uninstall rejected: ${code}`);
+        this.code = code;
+        this.detail = detail;
+        this.blockers = blockers;
+        this.name = 'SkillUninstallError';
+    }
+    get status() {
+        return exports.SKILL_UNINSTALL_ERROR_STATUS[this.code];
+    }
+}
+exports.SkillUninstallError = SkillUninstallError;
+function isSkillUninstallError(value) {
+    return value instanceof SkillUninstallError;
+}
+function fail(code, detail, blockers = []) {
+    throw new SkillUninstallError(code, detail, blockers);
+}
+// =============================================================================
+// Path safety
+// =============================================================================
+/**
+ * Absolute install root for a validated Skill ID inside a server-resolved worktree.
+ *
+ * Delegates to #1233's resolver — the same one {@link resolveSkillInstallTarget}
+ * uses — and re-checks the ID grammar here as well, because `path.join`
+ * normalizes `..` away and a containment check alone would accept an ID that
+ * walked out of the Skills directory.
+ */
+function resolveSkillUninstallTarget(worktreePath, skillId) {
+    return resolveSkillUninstallTargetFor(worktreePath, constants_1.SKILL_INSTALL_ROOT_PREFIX, skillId);
+}
+/** Absolute install root for a Skill ID under one root prefix (#1460). */
+function resolveSkillUninstallTargetFor(worktreePath, rootPrefix, skillId) {
+    if (!constants_1.SKILL_ID_PATTERN.test(skillId) || skillId.length > constants_1.SKILL_ID_MAX_LENGTH) {
+        fail(exports.SkillUninstallErrorCode.TARGET_UNSAFE, { reason: 'skill-id' });
+    }
+    try {
+        return (0, preview_diff_1.resolveSkillInstallRootFor)(worktreePath, rootPrefix, skillId);
+    }
+    catch {
+        return fail(exports.SkillUninstallErrorCode.TARGET_UNSAFE, { reason: 'install-root' });
+    }
+}
+/**
+ * Prove no ancestor of the install root was swapped for a link.
+ *
+ * `lstat` at every level from the worktree down. `realpath` alone would silently
+ * *follow* a swapped ancestor and delete under whatever it pointed at, which is
+ * precisely the failure this whole module exists to make unrepresentable.
+ */
+function assertSkillUninstallAncestors(worktreeRealPath, worktreePath, rootPrefix = constants_1.SKILL_INSTALL_ROOT_PREFIX) {
+    let resolved;
+    try {
+        resolved = (0, fs_1.realpathSync)(worktreePath);
+    }
+    catch {
+        return fail(exports.SkillUninstallErrorCode.ANCESTOR_UNSAFE, { reason: 'worktree-unresolvable' });
+    }
+    if (resolved !== worktreeRealPath) {
+        fail(exports.SkillUninstallErrorCode.ANCESTOR_UNSAFE, { reason: 'worktree-identity' });
+    }
+    let walked = worktreeRealPath;
+    for (const segment of rootPrefix.split('/')) {
+        walked = path_1.default.join(walked, segment);
+        let stats;
+        try {
+            stats = (0, fs_1.lstatSync)(walked);
+        }
+        catch {
+            // Absent is fine: there is then nothing under it to delete.
+            return;
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            fail(exports.SkillUninstallErrorCode.ANCESTOR_UNSAFE, { reason: 'not-a-directory' });
+        }
+    }
+}
+/**
+ * Reject a receipt-recorded path that is not a plain relative path.
+ *
+ * The receipt is a file inside a repository, so it is data the user could have
+ * edited even though CommandMate wrote it. Its `files` entries name what gets
+ * unlinked, and are therefore validated here rather than trusted.
+ */
+function assertSafeRelativePath(relativePath) {
+    if (relativePath.length === 0 ||
+        relativePath.includes('\0') ||
+        relativePath.includes('\\') ||
+        path_1.default.posix.isAbsolute(relativePath) ||
+        path_1.default.win32.isAbsolute(relativePath)) {
+        fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'grammar' });
+    }
+    for (const segment of relativePath.split('/')) {
+        if (segment === '' || segment === '.' || segment === '..') {
+            fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'segment' });
+        }
+    }
+}
+/**
+ * `lstat` every directory from the install root down to the file's parent.
+ *
+ * Run immediately before each `unlink`, not once per operation: the exclusive
+ * lock keeps CommandMate out, but nothing stops the user's own tooling from
+ * replacing a directory with a link while the deletes are running.
+ */
+function assertDirectoryChainIsReal(installRootAbs, relativePath) {
+    let walked = installRootAbs;
+    const segments = relativePath.split('/').slice(0, -1);
+    for (let index = 0; index <= segments.length; index += 1) {
+        if (index > 0)
+            walked = path_1.default.join(walked, segments[index - 1]);
+        let stats;
+        try {
+            stats = (0, fs_1.lstatSync)(walked);
+        }
+        catch {
+            return fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'ancestor-missing' });
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'ancestor-not-a-directory' });
+        }
+    }
+}
+/**
+ * Delete one receipt-owned file, having just proved it is still that file.
+ *
+ * The digest is re-read here even though the assessment already checked it, for
+ * the same reason install re-reads what it wrote: the assessment is evidence
+ * about a moment that has passed, and the only claim worth making about a delete
+ * is one established immediately before the syscall.
+ *
+ * @internal Exported for the guard tests; callers use {@link applySkillUninstall}.
+ * @throws SkillUninstallError — the file was not deleted in every case.
+ */
+function removeReceiptOwnedFile(installRootAbs, relativePath, expected) {
+    assertSafeRelativePath(relativePath);
+    assertDirectoryChainIsReal(installRootAbs, relativePath);
+    const absolute = path_1.default.join(installRootAbs, relativePath);
+    if (path_1.default.relative(installRootAbs, absolute) !== relativePath.split('/').join(path_1.default.sep)) {
+        fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'containment' });
+    }
+    let stats;
+    try {
+        stats = (0, fs_1.lstatSync)(absolute);
+    }
+    catch {
+        return fail(exports.SkillUninstallErrorCode.FILE_CHANGED, { reason: 'vanished' });
+    }
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'not-a-regular-file' });
+    }
+    // A hard link means the same inode is reachable from somewhere we did not
+    // scan, so the receipt cannot claim sole ownership of this content.
+    if (stats.nlink !== 1) {
+        fail(exports.SkillUninstallErrorCode.PATH_UNSAFE, { reason: 'hard-linked' });
+    }
+    if (((stats.mode & 0o111) !== 0) !== expected.executable) {
+        fail(exports.SkillUninstallErrorCode.FILE_CHANGED, { reason: 'mode' });
+    }
+    let bytes;
+    try {
+        bytes = (0, fs_1.readFileSync)(absolute);
+    }
+    catch {
+        return fail(exports.SkillUninstallErrorCode.FILE_CHANGED, { reason: 'unreadable' });
+    }
+    if (!(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)(bytes), expected.sha256)) {
+        fail(exports.SkillUninstallErrorCode.FILE_CHANGED, { reason: 'digest' });
+    }
+    try {
+        (0, fs_1.unlinkSync)(absolute);
+    }
+    catch {
+        return fail(exports.SkillUninstallErrorCode.DELETE_FAILED, { reason: 'unlink' });
+    }
+    return bytes.byteLength;
+}
+/**
+ * Remove a directory only if it is empty.
+ *
+ * `rmdir(2)` refuses a non-empty directory, so the emptiness check and the
+ * removal are one indivisible step rather than a scan followed by a delete that
+ * could act on a directory something was written into meanwhile.
+ *
+ * @returns whether the directory was removed
+ */
+function removeIfEmpty(directoryAbs) {
+    let stats;
+    try {
+        stats = (0, fs_1.lstatSync)(directoryAbs);
+    }
+    catch {
+        return false;
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory())
+        return false;
+    try {
+        (0, fs_1.rmdirSync)(directoryAbs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Directories the receipt's file list implies, deepest first.
+ *
+ * Derived from the receipt rather than from a directory walk on purpose: an
+ * empty directory the user created inside the install root is not something the
+ * install put there, and collecting it would be a deletion nobody asked for.
+ */
+function directoriesImpliedByReceipt(relativePaths) {
+    const directories = new Set();
+    for (const relative of relativePaths) {
+        const segments = relative.split('/').slice(0, -1);
+        let walked = '';
+        for (const segment of segments) {
+            walked = walked === '' ? segment : `${walked}/${segment}`;
+            directories.add(walked);
+        }
+    }
+    return [...directories].sort((a, b) => b.split('/').length - a.split('/').length || (a < b ? 1 : -1));
+}
+/**
+ * Verify and delete one Skill install.
+ *
+ * Everything before {@link SkillUninstallApplyInput.onCommitPoint} is a read:
+ * on any rejection the worktree is byte-for-byte what it was. After it, files
+ * are gone and a failure is reported as *committed, reconciling* — the receipt
+ * survives until last precisely so that state remains explainable.
+ *
+ * @throws SkillUninstallError
+ */
+function applySkillUninstall(input) {
+    // The primary root anchors the plan: its receipt names every root, and its
+    // tree hash and receipt digest are what the plan bound the token to.
+    const primaryAbs = resolveSkillUninstallTarget(input.worktreePath, input.skillId);
+    assertSkillUninstallAncestors(input.worktreeRealPath, input.worktreePath);
+    const primary = (0, uninstall_plan_1.assessSkillUninstall)(primaryAbs, input.skillId, {
+        existing: (0, preview_diff_1.readExistingSkillTree)(primaryAbs),
+    });
+    if (!primary.present) {
+        fail(exports.SkillUninstallErrorCode.NOT_INSTALLED, undefined, primary.blockers);
+    }
+    if (!primary.removable || primary.receipt === null) {
+        fail(exports.SkillUninstallErrorCode.BLOCKED, undefined, primary.blockers);
+    }
+    if (primary.currentTreeHash !== input.expectedTreeHash) {
+        fail(exports.SkillUninstallErrorCode.DRIFT, { reason: 'tree-hash' });
+    }
+    const receipt = primary.receipt;
+    const receiptDigest = primary.receiptDigest;
+    if (receiptDigest === null || !(0, integrity_1.digestMatches)(receiptDigest, input.expectedReceiptDigest)) {
+        fail(exports.SkillUninstallErrorCode.DRIFT, { reason: 'receipt-digest' });
+    }
+    // Resolve and assess every recorded root before deleting anything (#1460). An
+    // absent root is already gone and skipped; any present root that is not
+    // provably managed-and-unchanged blocks the whole operation, so "zero-delete
+    // on ambiguity" holds across roots, not just within one.
+    const installRoots = (0, install_plan_1.receiptInstallRoots)(receipt);
+    const planned = [];
+    for (const rootRel of installRoots) {
+        const rootPrefix = rootRel.slice(0, Math.max(0, rootRel.length - input.skillId.length - 1));
+        const abs = rootPrefix === constants_1.SKILL_INSTALL_ROOT_PREFIX
+            ? primaryAbs
+            : resolveSkillUninstallTargetFor(input.worktreePath, rootPrefix, input.skillId);
+        assertSkillUninstallAncestors(input.worktreeRealPath, input.worktreePath, rootPrefix);
+        const assessment = rootPrefix === constants_1.SKILL_INSTALL_ROOT_PREFIX
+            ? primary
+            : (0, uninstall_plan_1.assessSkillUninstall)(abs, input.skillId, {
+                existing: (0, preview_diff_1.readExistingSkillTree)(abs),
+                rootPrefix,
+            });
+        // A recorded root already removed is not an error: convergence may have
+        // deleted it, or a legacy single-root receipt never wrote it.
+        if (!assessment.present)
+            continue;
+        if (!assessment.removable || assessment.receipt === null) {
+            fail(exports.SkillUninstallErrorCode.BLOCKED, undefined, assessment.blockers);
+        }
+        // Every root holds the byte-identical payload, so each must match the same
+        // tree hash and receipt digest the plan bound; anything else is drift.
+        if (assessment.currentTreeHash !== input.expectedTreeHash) {
+            fail(exports.SkillUninstallErrorCode.DRIFT, { reason: 'tree-hash' });
+        }
+        if (assessment.receiptDigest === null ||
+            !(0, integrity_1.digestMatches)(assessment.receiptDigest, input.expectedReceiptDigest)) {
+            fail(exports.SkillUninstallErrorCode.DRIFT, { reason: 'receipt-digest' });
+        }
+        planned.push({ abs, assessment });
+    }
+    input.onCommitPoint?.();
+    const removedFiles = [];
+    const removedDirectories = [];
+    const retained = [];
+    let allFullyRemoved = true;
+    let primaryReceiptRemoved = false;
+    for (const { abs, assessment } of planned) {
+        const removed = deleteSkillInstallRoot(abs, assessment, receiptDigest);
+        removedFiles.push(...removed.removedFiles);
+        removedDirectories.push(...removed.removedDirectories);
+        retained.push(...removed.retained);
+        if (!removed.fullyRemoved)
+            allFullyRemoved = false;
+        if (abs === primaryAbs)
+            primaryReceiptRemoved = removed.receiptRemoved;
+    }
+    return {
+        installRoot: primary.installRoot,
+        installRoots,
+        version: receipt.version,
+        removedFiles,
+        removedDirectories,
+        retained,
+        receiptRemoved: primaryReceiptRemoved,
+        fullyRemoved: allFullyRemoved,
+    };
+}
+/** Delete every managed file in one root, receipt last. All checks already passed. */
+function deleteSkillInstallRoot(installRootAbs, assessment, receiptDigest) {
+    const payload = assessment.entries.filter((entry) => entry.disposition === 'remove' && !entry.generated);
+    const removedFiles = [];
+    for (const entry of payload) {
+        const size = removeReceiptOwnedFile(installRootAbs, entry.relativePath, {
+            sha256: entry.recordedSha256,
+            executable: entry.executable,
+        });
+        removedFiles.push({ path: entry.path, sha256: entry.recordedSha256, size });
+    }
+    const removedDirectories = [];
+    for (const relative of directoriesImpliedByReceipt(payload.map((entry) => entry.relativePath))) {
+        if (removeIfEmpty(path_1.default.join(installRootAbs, relative))) {
+            removedDirectories.push(`${assessment.installRoot}/${relative}`);
+        }
+    }
+    // Last, so that up to this point the directory still says what it is.
+    const receiptEntry = assessment.entries.find((entry) => entry.generated);
+    if (receiptEntry) {
+        const size = removeReceiptOwnedFile(installRootAbs, install_plan_1.SKILL_RECEIPT_FILENAME, {
+            sha256: receiptDigest,
+            executable: false,
+        });
+        removedFiles.push({
+            path: `${assessment.installRoot}/${install_plan_1.SKILL_RECEIPT_FILENAME}`,
+            sha256: receiptDigest,
+            size,
+        });
+    }
+    const fullyRemoved = removeIfEmpty(installRootAbs);
+    const retained = fullyRemoved ? [] : listRetainedPaths(installRootAbs, assessment.installRoot);
+    return {
+        removedFiles,
+        removedDirectories,
+        retained,
+        receiptRemoved: receiptEntry !== undefined,
+        fullyRemoved,
+    };
+}
+/**
+ * Name what is still inside the install root.
+ *
+ * Only reached when the root would not collect, which after a fail-closed
+ * assessment means something appeared during the delete. The user is told the
+ * paths rather than that "uninstall partially failed" (UX-07).
+ */
+function listRetainedPaths(installRootAbs, installRoot) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(installRootAbs);
+    }
+    catch {
+        return [];
+    }
+    return entries.map((name) => ({
+        path: `${installRoot}/${name}`,
+        reason: 'SKILL_UNINSTALL_UNMANAGED_FILE',
+        messageKey: 'skills.uninstall.reason.unmanagedFile',
+    }));
+}
+/**
+ * Whether the payload a committed uninstall removed is really gone.
+ *
+ * The uninstall counterpart of `hasCommittedSkillPayload`: #1234's reconciler
+ * asks whether the filesystem side of an operation landed, and for a delete
+ * that means the receipt no longer names this install.
+ */
+function hasRemovedSkillPayload(worktreePath, skillId, receiptDigest) {
+    let installRootAbs;
+    try {
+        installRootAbs = resolveSkillUninstallTarget(worktreePath, skillId);
+    }
+    catch {
+        return true;
+    }
+    let bytes;
+    try {
+        bytes = (0, fs_1.readFileSync)(path_1.default.join(installRootAbs, install_plan_1.SKILL_RECEIPT_FILENAME));
+    }
+    catch {
+        return true;
+    }
+    return receiptDigest !== null && !(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)(bytes), receiptDigest);
+}