commandmate 0.11.4 → 0.12.1

package/dist/server/src/lib/skills/preview-diff.js

@@ -0,0 +1,627 @@
+"use strict";
+/**
+ * Virtual install diff between a verified Skill package and a live worktree (Issue #1233)
+ *
+ * Answers one question before anything is written: if this exact package landed
+ * in `.agents/skills/<skill-id>` right now, which files would appear, which
+ * would change, and which already-present file would be overwritten.
+ *
+ * Three properties the rest of the install flow depends on:
+ * - Nothing here writes. Every path is derived from a server-resolved worktree
+ *   path plus a validated Skill ID; no caller-supplied path reaches the disk.
+ * - A state that could mislead is named rather than smoothed over: a detached or
+ *   unborn HEAD, a binary or truncated body, a CRLF payload and a git-ignored
+ *   destination each get an explicit field, because silently rendering them as
+ *   an ordinary diff is how a user approves something they did not see.
+ * - An existing file is never classified as a clean overwrite. It is either
+ *   provably the same managed content (`unchanged`/`modify`) or it is a
+ *   conflict, and conflicts make the plan non-installable.
+ *
+ * @module lib/skills/preview-diff
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillPreviewWarning = exports.SkillDiffReason = exports.SKILL_TREE_SCAN_MAX_DEPTH = exports.SKILL_TREE_SCAN_MAX_ENTRIES = exports.SKILL_DIFF_CONTEXT_LINES = exports.SKILL_DIFF_MAX_LINES = exports.SKILL_DIFF_MAX_TOTAL_BYTES = exports.SKILL_DIFF_MAX_FILE_BYTES = void 0;
+exports.skillInstallRootFor = skillInstallRootFor;
+exports.skillInstallRoot = skillInstallRoot;
+exports.resolveSkillInstallRootFor = resolveSkillInstallRootFor;
+exports.resolveSkillInstallRoot = resolveSkillInstallRoot;
+exports.resolveSkillInstallRoots = resolveSkillInstallRoots;
+exports.isBinaryContent = isBinaryContent;
+exports.detectLineEnding = detectLineEnding;
+exports.computeSkillTreeHash = computeSkillTreeHash;
+exports.readExistingSkillTree = readExistingSkillTree;
+exports.readSkillGitTargetState = readSkillGitTargetState;
+exports.findGitIgnoredPaths = findGitIgnoredPaths;
+exports.buildUnifiedDiff = buildUnifiedDiff;
+exports.buildSkillPreviewDiff = buildSkillPreviewDiff;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const git_exec_1 = require("../../lib/git/git-exec");
+const constants_1 = require("../../lib/skills/constants");
+const integrity_1 = require("../../lib/skills/integrity");
+const operation_store_1 = require("../../lib/skills/operation-store");
+// =============================================================================
+// Limits
+// =============================================================================
+/** Maximum bytes of diff text kept for a single file. */
+exports.SKILL_DIFF_MAX_FILE_BYTES = 64 * 1024;
+/** Maximum bytes of diff text kept across a whole plan. */
+exports.SKILL_DIFF_MAX_TOTAL_BYTES = 512 * 1024;
+/** Maximum diff lines emitted for a single file. */
+exports.SKILL_DIFF_MAX_LINES = 400;
+/** Context lines around the changed region of a modified file. */
+exports.SKILL_DIFF_CONTEXT_LINES = 3;
+/** Maximum entries walked when scanning the existing target directory. */
+exports.SKILL_TREE_SCAN_MAX_ENTRIES = 2000;
+/** Maximum directory depth walked under the target root. */
+exports.SKILL_TREE_SCAN_MAX_DEPTH = 16;
+/** Bytes inspected when deciding whether content is binary. */
+const BINARY_SNIFF_BYTES = 8000;
+/** Why an entry was classified the way it was. Stable machine codes. */
+exports.SkillDiffReason = {
+    /** Path does not exist in the worktree. */
+    NEW_FILE: 'SKILL_DIFF_NEW_FILE',
+    /** Present, recorded by the install receipt, and byte-identical to the package. */
+    CONTENT_IDENTICAL: 'SKILL_DIFF_CONTENT_IDENTICAL',
+    /** Present, matches what the receipt recorded, and the package supersedes it. */
+    MANAGED_UPDATE: 'SKILL_DIFF_MANAGED_UPDATE',
+    /** Present and recorded, but its bytes no longer match the receipt. */
+    LOCAL_MODIFICATION: 'SKILL_DIFF_LOCAL_MODIFICATION',
+    /** Present under the install root with no receipt recording it. */
+    UNMANAGED_SKILL: 'SKILL_DIFF_UNMANAGED_SKILL',
+    /** Recorded by the receipt but absent from the package being installed. */
+    RECEIPT_ORPHAN: 'SKILL_DIFF_RECEIPT_ORPHAN',
+    /** Present as a symlink, a directory or another non-regular entry. */
+    NOT_A_REGULAR_FILE: 'SKILL_DIFF_NOT_A_REGULAR_FILE',
+};
+/** Plan-level conditions a user must be told about before approving. */
+exports.SkillPreviewWarning = {
+    /** HEAD is not on a branch; the install would land on a detached checkout. */
+    DETACHED_HEAD: 'SKILL_PREVIEW_DETACHED_HEAD',
+    /** The repository has no commit yet, so there is no HEAD to pin the plan to. */
+    UNBORN_HEAD: 'SKILL_PREVIEW_UNBORN_HEAD',
+    /** HEAD could not be resolved at all. */
+    HEAD_UNRESOLVED: 'SKILL_PREVIEW_HEAD_UNRESOLVED',
+    /** The worktree has uncommitted changes. */
+    WORKING_TREE_DIRTY: 'SKILL_PREVIEW_WORKING_TREE_DIRTY',
+    /** At least one destination path is ignored or excluded by git. */
+    PATH_GIT_IGNORED: 'SKILL_PREVIEW_PATH_GIT_IGNORED',
+    /** At least one diff body was cut short. */
+    DIFF_TRUNCATED: 'SKILL_PREVIEW_DIFF_TRUNCATED',
+    /** At least one file has no textual diff because its content is binary. */
+    BINARY_CONTENT: 'SKILL_PREVIEW_BINARY_CONTENT',
+    /** At least one payload file uses CRLF or mixed terminators. */
+    LINE_ENDING_CRLF: 'SKILL_PREVIEW_LINE_ENDING_CRLF',
+    /** The existing target directory could not be scanned completely. */
+    TREE_SCAN_TRUNCATED: 'SKILL_PREVIEW_TREE_SCAN_TRUNCATED',
+};
+// =============================================================================
+// Paths
+// =============================================================================
+/** Repository-relative install root for a validated Skill ID under one root prefix (#1460). */
+function skillInstallRootFor(rootPrefix, skillId) {
+    return `${rootPrefix}/${skillId}`;
+}
+/** Repository-relative install root under the primary `.agents/skills` prefix. */
+function skillInstallRoot(skillId) {
+    return skillInstallRootFor(constants_1.SKILL_INSTALL_ROOT_PREFIX, skillId);
+}
+/**
+ * Absolute install root for a Skill ID under one root prefix (#1460).
+ *
+ * The ID is re-checked against the slug grammar rather than only comparing the
+ * joined result: `path.join` normalizes `..` away, so `<prefix>/../x` and the
+ * sibling `x` compare equal and a containment check alone would accept an ID
+ * that walked out of the Skills directory. Rejecting the grammar first makes
+ * traversal unrepresentable; the containment check then covers the rest. The
+ * containment check is applied per root prefix, so the `.claude/skills` root
+ * gets exactly the escape rejection the `.agents/skills` root always had.
+ */
+function resolveSkillInstallRootFor(worktreePath, rootPrefix, skillId) {
+    if (!constants_1.SKILL_ID_PATTERN.test(skillId) || skillId.length > constants_1.SKILL_ID_MAX_LENGTH) {
+        throw new Error('Skill ID is not a valid install root segment');
+    }
+    const root = path_1.default.resolve(worktreePath);
+    const target = path_1.default.resolve(root, rootPrefix, skillId);
+    const relative = path_1.default.relative(root, target);
+    if (relative !== path_1.default.join(rootPrefix, skillId) ||
+        relative.startsWith('..') ||
+        path_1.default.isAbsolute(relative)) {
+        throw new Error('Skill install root escapes the worktree');
+    }
+    return target;
+}
+/** Absolute install root under the primary `.agents/skills` prefix. */
+function resolveSkillInstallRoot(worktreePath, skillId) {
+    return resolveSkillInstallRootFor(worktreePath, constants_1.SKILL_INSTALL_ROOT_PREFIX, skillId);
+}
+/**
+ * Resolve every root a Skill would be placed into, primary first (#1460).
+ *
+ * Each root is containment-checked independently, so a malformed prefix or ID is
+ * rejected before any of them is used. The default is the full product set
+ * ({@link SKILL_INSTALL_ROOT_PREFIXES}); callers migrating from the single-root
+ * API pass a narrower set.
+ */
+function resolveSkillInstallRoots(worktreePath, skillId, rootPrefixes = constants_1.SKILL_INSTALL_ROOT_PREFIXES) {
+    return rootPrefixes.map((prefix) => ({
+        prefix,
+        rel: skillInstallRootFor(prefix, skillId),
+        abs: resolveSkillInstallRootFor(worktreePath, prefix, skillId),
+    }));
+}
+// =============================================================================
+// Content classification
+// =============================================================================
+/** Content is treated as binary when a NUL byte appears near the start. */
+function isBinaryContent(bytes) {
+    const limit = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+    for (let i = 0; i < limit; i += 1) {
+        if (bytes[i] === 0)
+            return true;
+    }
+    return false;
+}
+/** Terminator style of a payload, so a CRLF file is not silently normalized. */
+function detectLineEnding(bytes) {
+    let crlf = 0;
+    let lf = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+        if (bytes[i] !== 0x0a)
+            continue;
+        if (i > 0 && bytes[i - 1] === 0x0d)
+            crlf += 1;
+        else
+            lf += 1;
+    }
+    if (crlf > 0 && lf > 0)
+        return 'mixed';
+    if (crlf > 0)
+        return 'crlf';
+    if (lf > 0)
+        return 'lf';
+    return 'none';
+}
+/**
+ * Split into lines without normalizing terminators.
+ *
+ * A trailing `\r` is kept on the line, so a CRLF file diffs as CRLF rather than
+ * appearing identical to its LF twin.
+ */
+function splitLines(bytes) {
+    const text = Buffer.from(bytes).toString('utf-8');
+    if (text.length === 0)
+        return [];
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * Order-independent digest of a file set.
+ *
+ * Apply re-computes this over the live directory and refuses when it differs,
+ * so the mode bit is part of the input: a payload that gained an execute bit
+ * between plan and apply is drift, not a detail.
+ */
+function computeSkillTreeHash(files) {
+    const canonical = [...files]
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .map((file) => `${file.path}\x00${file.sha256}\x00${file.executable ? '1' : '0'}`)
+        .join('\n');
+    return (0, crypto_1.createHash)('sha256').update(`skill-tree-v1\n${canonical}`).digest('hex');
+}
+// =============================================================================
+// Existing tree
+// =============================================================================
+function isExecutableMode(mode) {
+    return (mode & 0o111) !== 0;
+}
+/**
+ * List the install root as it is right now.
+ *
+ * `lstat` rather than `stat` throughout: a symlink under the install root is
+ * reported as an irregular path instead of being followed, so a planted link
+ * cannot make the preview describe a file outside the worktree.
+ */
+function readExistingSkillTree(installRootAbs) {
+    let rootStats;
+    try {
+        rootStats = (0, fs_1.lstatSync)(installRootAbs);
+    }
+    catch {
+        return { present: false, files: [], irregularPaths: [], truncated: false };
+    }
+    if (!rootStats.isDirectory()) {
+        return { present: true, files: [], irregularPaths: [''], truncated: false };
+    }
+    const files = [];
+    const irregularPaths = [];
+    let truncated = false;
+    let scanned = 0;
+    const walk = (dirAbs, relPrefix, depth) => {
+        if (truncated)
+            return;
+        if (depth > exports.SKILL_TREE_SCAN_MAX_DEPTH) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(dirAbs, { withFileTypes: true });
+        }
+        catch {
+            truncated = true;
+            return;
+        }
+        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            if (truncated)
+                return;
+            scanned += 1;
+            if (scanned > exports.SKILL_TREE_SCAN_MAX_ENTRIES) {
+                truncated = true;
+                return;
+            }
+            const relative = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+            const absolute = path_1.default.join(dirAbs, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolute, relative, depth + 1);
+                continue;
+            }
+            if (!entry.isFile()) {
+                irregularPaths.push(relative);
+                continue;
+            }
+            let stats;
+            try {
+                stats = (0, fs_1.lstatSync)(absolute);
+            }
+            catch {
+                irregularPaths.push(relative);
+                continue;
+            }
+            if (!stats.isFile() || stats.size > constants_1.SKILL_FILE_MAX_SIZE) {
+                irregularPaths.push(relative);
+                continue;
+            }
+            let bytes;
+            try {
+                bytes = (0, fs_1.readFileSync)(absolute);
+            }
+            catch {
+                irregularPaths.push(relative);
+                continue;
+            }
+            files.push({
+                path: relative,
+                sha256: (0, integrity_1.computeSha256Hex)(bytes),
+                size: bytes.byteLength,
+                executable: isExecutableMode(stats.mode),
+                bytes,
+            });
+        }
+    };
+    walk(installRootAbs, '', 0);
+    return { present: true, files, irregularPaths, truncated };
+}
+// =============================================================================
+// Git state
+// =============================================================================
+/**
+ * Resolve branch, HEAD and dirtiness of a server-resolved worktree.
+ *
+ * The two failure modes are deliberately distinguished rather than collapsed
+ * into "no branch": a detached HEAD has a commit to pin the plan to, an unborn
+ * HEAD has none, and apply must be able to tell those apart.
+ */
+async function readSkillGitTargetState(worktreePath) {
+    const [branch, headCommit, status] = await Promise.all([
+        (0, git_exec_1.execGitCommand)(['symbolic-ref', '--quiet', '--short', 'HEAD'], worktreePath),
+        (0, git_exec_1.execGitCommand)(['rev-parse', 'HEAD'], worktreePath),
+        (0, git_exec_1.execGitCommand)(['status', '--porcelain'], worktreePath),
+    ]);
+    const commit = headCommit && /^[0-9a-f]{40}$/.test(headCommit) ? headCommit : null;
+    let headState;
+    if (branch && commit)
+        headState = 'attached';
+    else if (!branch && commit)
+        headState = 'detached';
+    else if (branch && !commit)
+        headState = 'unborn';
+    else
+        headState = 'unknown';
+    return {
+        headState,
+        branch: branch && branch.length > 0 ? branch : null,
+        headCommit: commit,
+        dirty: status !== null && status.length > 0,
+    };
+}
+/**
+ * Which destination paths git would ignore.
+ *
+ * `check-ignore` exits 1 when nothing matched, which `execFile` surfaces as a
+ * rejection, so the non-zero exit is read for stdout rather than treated as a
+ * failure. Paths already in the index are not reported, which is the answer we
+ * want: a tracked file stays visible to git regardless of ignore rules.
+ */
+async function findGitIgnoredPaths(worktreePath, relativePaths) {
+    if (relativePaths.length === 0)
+        return new Set();
+    try {
+        const { stdout } = await (0, git_exec_1.execFileAsync)('git', ['check-ignore', '-z', '--', ...relativePaths], { cwd: worktreePath, timeout: 3000 });
+        return parseNulSeparated(stdout);
+    }
+    catch (error) {
+        const stdout = error.stdout;
+        return typeof stdout === 'string' ? parseNulSeparated(stdout) : new Set();
+    }
+}
+function parseNulSeparated(stdout) {
+    return new Set(stdout.split('\0').filter((value) => value.length > 0));
+}
+function emptyBody() {
+    return { text: null, truncated: false, additions: 0, deletions: 0 };
+}
+/**
+ * Build a single-hunk unified diff.
+ *
+ * The changed region is found by trimming the common prefix and suffix rather
+ * than by running an LCS: the result is a correct, honest diff at linear cost,
+ * and a preview does not gain anything from splitting one edit into several
+ * hunks it would render adjacently anyway.
+ */
+function buildUnifiedDiff(before, after, budget) {
+    if (before === null && after === null)
+        return emptyBody();
+    const beforeLines = before ? splitLines(before) : [];
+    const afterLines = after ? splitLines(after) : [];
+    let prefix = 0;
+    const maxPrefix = Math.min(beforeLines.length, afterLines.length);
+    while (prefix < maxPrefix && beforeLines[prefix] === afterLines[prefix])
+        prefix += 1;
+    let suffix = 0;
+    while (suffix < maxPrefix - prefix &&
+        beforeLines[beforeLines.length - 1 - suffix] === afterLines[afterLines.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const removed = beforeLines.slice(prefix, beforeLines.length - suffix);
+    const added = afterLines.slice(prefix, afterLines.length - suffix);
+    if (removed.length === 0 && added.length === 0)
+        return emptyBody();
+    const contextStart = Math.max(0, prefix - exports.SKILL_DIFF_CONTEXT_LINES);
+    const leadingContext = beforeLines.slice(contextStart, prefix);
+    const trailingContext = beforeLines.slice(beforeLines.length - suffix, Math.min(beforeLines.length, beforeLines.length - suffix + exports.SKILL_DIFF_CONTEXT_LINES));
+    const beforeCount = leadingContext.length + removed.length + trailingContext.length;
+    const afterCount = leadingContext.length + added.length + trailingContext.length;
+    const beforeStart = beforeCount === 0 ? 0 : contextStart + 1;
+    const afterStart = afterCount === 0 ? 0 : contextStart + 1;
+    const lines = [`@@ -${beforeStart},${beforeCount} +${afterStart},${afterCount} @@`];
+    let truncated = false;
+    let bytes = lines[0].length + 1;
+    const push = (prefixChar, value) => {
+        if (lines.length >= exports.SKILL_DIFF_MAX_LINES + 1)
+            return false;
+        const line = `${prefixChar}${value}`;
+        const cost = line.length + 1;
+        if (bytes + cost > exports.SKILL_DIFF_MAX_FILE_BYTES || cost > budget.remainingBytes - bytes) {
+            return false;
+        }
+        lines.push(line);
+        bytes += cost;
+        return true;
+    };
+    for (const value of leadingContext) {
+        if (!push(' ', value)) {
+            truncated = true;
+            break;
+        }
+    }
+    if (!truncated) {
+        for (const value of removed) {
+            if (!push('-', value)) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    if (!truncated) {
+        for (const value of added) {
+            if (!push('+', value)) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    if (!truncated) {
+        for (const value of trailingContext) {
+            if (!push(' ', value)) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    if (truncated)
+        lines.push('… diff truncated');
+    const text = lines.join('\n');
+    budget.remainingBytes = Math.max(0, budget.remainingBytes - text.length);
+    return { text, truncated, additions: added.length, deletions: removed.length };
+}
+function classify(planned, existing, recorded) {
+    if (!existing) {
+        return planned
+            ? { change: 'add', reason: exports.SkillDiffReason.NEW_FILE }
+            : { change: 'unchanged', reason: exports.SkillDiffReason.RECEIPT_ORPHAN };
+    }
+    if (!recorded) {
+        return { change: 'unmanaged', reason: exports.SkillDiffReason.UNMANAGED_SKILL };
+    }
+    if (existing.sha256 !== recorded.sha256 || existing.executable !== recorded.executable) {
+        return { change: 'conflict', reason: exports.SkillDiffReason.LOCAL_MODIFICATION };
+    }
+    if (!planned) {
+        return { change: 'unmanaged', reason: exports.SkillDiffReason.RECEIPT_ORPHAN };
+    }
+    if (planned.sha256 === existing.sha256 && planned.executable === existing.executable) {
+        return { change: 'unchanged', reason: exports.SkillDiffReason.CONTENT_IDENTICAL };
+    }
+    return { change: 'modify', reason: exports.SkillDiffReason.MANAGED_UPDATE };
+}
+/**
+ * Assemble the virtual diff.
+ *
+ * Every planned write appears, including the generated receipt, and every file
+ * already under the install root appears even when the package does not mention
+ * it — an existing Skill the user installed by hand must be visible as
+ * something the install would collide with, not omitted because the package is
+ * unaware of it.
+ */
+function buildSkillPreviewDiff(input) {
+    const installRoot = skillInstallRootFor(input.installRootPrefix ?? constants_1.SKILL_INSTALL_ROOT_PREFIX, input.skillId);
+    const plannedByPath = new Map(input.plannedFiles.map((file) => [file.relativePath, file]));
+    const existingByPath = new Map(input.existing.files.map((file) => [file.path, file]));
+    const allPaths = [
+        ...new Set([
+            ...plannedByPath.keys(),
+            ...existingByPath.keys(),
+            ...(input.receiptFiles ? [...input.receiptFiles.keys()] : []),
+        ]),
+    ]
+        .filter((relative) => !(0, operation_store_1.isSkillInstallStagingPath)(`${installRoot}/${relative}`))
+        .sort();
+    const budget = { remainingBytes: exports.SKILL_DIFF_MAX_TOTAL_BYTES };
+    const entries = [];
+    const stats = {
+        added: 0,
+        modified: 0,
+        unchanged: 0,
+        conflicted: 0,
+        unmanaged: 0,
+        binaryFiles: 0,
+        truncatedFiles: 0,
+        diffBytes: 0,
+    };
+    let anyCrlf = false;
+    for (const relative of allPaths) {
+        const planned = plannedByPath.get(relative) ?? null;
+        const existing = existingByPath.get(relative) ?? null;
+        const recorded = input.receiptFiles?.get(relative) ?? null;
+        const { change, reason } = classify(planned, existing, recorded);
+        const repoPath = `${installRoot}/${relative}`;
+        const source = planned?.bytes ?? existing?.bytes ?? null;
+        const binary = (planned ? isBinaryContent(planned.bytes) : false) ||
+            (existing ? isBinaryContent(existing.bytes) : false);
+        const lineEnding = source ? detectLineEnding(source) : 'none';
+        if (planned && (lineEnding === 'crlf' || lineEnding === 'mixed'))
+            anyCrlf = true;
+        const body = binary || change === 'unchanged'
+            ? emptyBody()
+            : buildUnifiedDiff(existing?.bytes ?? null, planned?.bytes ?? null, budget);
+        entries.push({
+            path: repoPath,
+            change,
+            reason,
+            generated: planned?.generated ?? false,
+            sha256: planned?.sha256 ?? null,
+            size: planned?.size ?? null,
+            executable: planned?.executable ?? existing?.executable ?? false,
+            currentSha256: existing?.sha256 ?? null,
+            currentSize: existing?.size ?? null,
+            binary,
+            lineEnding,
+            gitIgnored: input.gitIgnoredPaths.has(repoPath),
+            diff: body.text,
+            diffTruncated: body.truncated,
+            additions: body.additions,
+            deletions: body.deletions,
+        });
+        if (change === 'add')
+            stats.added += 1;
+        else if (change === 'modify')
+            stats.modified += 1;
+        else if (change === 'unchanged')
+            stats.unchanged += 1;
+        else if (change === 'conflict')
+            stats.conflicted += 1;
+        else
+            stats.unmanaged += 1;
+        if (binary)
+            stats.binaryFiles += 1;
+        if (body.truncated)
+            stats.truncatedFiles += 1;
+        stats.diffBytes += body.text?.length ?? 0;
+    }
+    for (const irregular of input.existing.irregularPaths) {
+        const repoPath = irregular ? `${installRoot}/${irregular}` : installRoot;
+        entries.push({
+            path: repoPath,
+            change: 'conflict',
+            reason: exports.SkillDiffReason.NOT_A_REGULAR_FILE,
+            generated: false,
+            sha256: null,
+            size: null,
+            executable: false,
+            currentSha256: null,
+            currentSize: null,
+            binary: false,
+            lineEnding: 'none',
+            gitIgnored: input.gitIgnoredPaths.has(repoPath),
+            diff: null,
+            diffTruncated: false,
+            additions: 0,
+            deletions: 0,
+        });
+        stats.conflicted += 1;
+    }
+    const warnings = collectWarnings(input, entries, stats, anyCrlf);
+    // The planned tree keeps every file the install would not remove, so the hash
+    // describes the directory apply must produce — not just the package.
+    const plannedTree = input.plannedFiles.map((file) => ({
+        path: file.relativePath,
+        sha256: file.sha256,
+        executable: file.executable,
+    }));
+    for (const existing of input.existing.files) {
+        if (!plannedByPath.has(existing.path)) {
+            plannedTree.push({
+                path: existing.path,
+                sha256: existing.sha256,
+                executable: existing.executable,
+            });
+        }
+    }
+    return {
+        installRoot,
+        entries: entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+        stats,
+        warnings,
+        currentTreeHash: computeSkillTreeHash(input.existing.files),
+        plannedTreeHash: computeSkillTreeHash(plannedTree),
+    };
+}
+function collectWarnings(input, entries, stats, anyCrlf) {
+    const warnings = [];
+    if (input.git.headState === 'detached')
+        warnings.push(exports.SkillPreviewWarning.DETACHED_HEAD);
+    if (input.git.headState === 'unborn')
+        warnings.push(exports.SkillPreviewWarning.UNBORN_HEAD);
+    if (input.git.headState === 'unknown')
+        warnings.push(exports.SkillPreviewWarning.HEAD_UNRESOLVED);
+    if (input.git.dirty)
+        warnings.push(exports.SkillPreviewWarning.WORKING_TREE_DIRTY);
+    if (entries.some((entry) => entry.gitIgnored))
+        warnings.push(exports.SkillPreviewWarning.PATH_GIT_IGNORED);
+    if (stats.truncatedFiles > 0)
+        warnings.push(exports.SkillPreviewWarning.DIFF_TRUNCATED);
+    if (stats.binaryFiles > 0)
+        warnings.push(exports.SkillPreviewWarning.BINARY_CONTENT);
+    if (anyCrlf)
+        warnings.push(exports.SkillPreviewWarning.LINE_ENDING_CRLF);
+    if (input.existing.truncated)
+        warnings.push(exports.SkillPreviewWarning.TREE_SCAN_TRUNCATED);
+    return warnings;
+}