@qilin-agent/workspace-changes 0.0.0-stage → 3.1.3

package/lib/types/capture.d.ts

@@ -0,0 +1,47 @@
+/** One captured side of a path. */
+export type Capture = 
+/** No file at the path. */
+{
+    kind: 'absent';
+}
+/** A regular file larger than the configured cap; its content is not stored. */
+ | {
+    kind: 'oversized';
+}
+/** A stored copy, named by the SHA-1 of its bytes. */
+ | {
+    kind: 'file';
+    file: string;
+    binary: boolean;
+};
+/**
+ * Store the current content of one path. At most `maxBytes + 1` bytes are
+ * read, so a file that grows past the cap while it is read costs no more
+ * memory than the cap.
+ * @param absolute - canonical absolute path of the file.
+ * @param directory - directory holding content-addressed copies; created when missing.
+ * @param maxBytes - inclusive byte cap on a stored copy.
+ * @returns the capture, or undefined for a path that is neither absent nor a regular file.
+ * @throws when the path cannot be opened or read for a reason other than absence, or the copy cannot be written.
+ */
+export declare function captureFile(absolute: string, directory: string, maxBytes: number): Promise<Capture | undefined>;
+/**
+ * Whether two captures are known to hold the same content. Two absent sides
+ * are the same; two stored copies are the same when their bytes hash alike;
+ * an oversized side is never known to match anything, since its content was
+ * not read.
+ * @param a - one side.
+ * @param b - the other side.
+ * @returns true only when both sides are known to match.
+ */
+export declare function sameCapture(a: Capture, b: Capture): boolean;
+/**
+ * The path a first-party file-tool call is about to mutate: `write`, `edit`,
+ * and the mutating `str_replace_editor` commands. Other tools, reads, and
+ * incomplete arguments yield undefined.
+ * @param name - wire tool name.
+ * @param args - parsed call arguments.
+ * @returns the model-facing path, or undefined.
+ */
+export declare function mutationPath(name: string, args: unknown): string | undefined;
+//# sourceMappingURL=capture.d.ts.map

package/lib/types/capture.js

@@ -0,0 +1,107 @@
+/**
+ * Whole-file captures around file-tool edits: the content of a path before
+ * the turn's first mutation of it and at turn end, stored content-addressed
+ * under the Session's temporary directory so both sides of a comparison
+ * survive later edits without depending on git.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, open, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Bytes git inspects for a NUL byte before treating content as binary. */
+const BINARY_PROBE_BYTES = 8000;
+/** Whether a filesystem error names a missing path. */
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+/**
+ * Store the current content of one path. At most `maxBytes + 1` bytes are
+ * read, so a file that grows past the cap while it is read costs no more
+ * memory than the cap.
+ * @param absolute - canonical absolute path of the file.
+ * @param directory - directory holding content-addressed copies; created when missing.
+ * @param maxBytes - inclusive byte cap on a stored copy.
+ * @returns the capture, or undefined for a path that is neither absent nor a regular file.
+ * @throws when the path cannot be opened or read for a reason other than absence, or the copy cannot be written.
+ */
+export async function captureFile(absolute, directory, maxBytes) {
+    let handle;
+    try {
+        handle = await open(absolute, 'r');
+    }
+    catch (error) {
+        /* v8 ignore next -- an unopenable present file needs permissions the tests cannot revoke on every host. */
+        if (!isMissing(error))
+            throw error;
+        return { kind: 'absent' };
+    }
+    let bytes;
+    try {
+        if (!(await handle.stat()).isFile())
+            return undefined;
+        const probe = Buffer.allocUnsafe(maxBytes + 1);
+        let length = 0;
+        while (length < probe.length) {
+            const { bytesRead } = await handle.read(probe, length, probe.length - length, length);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+        }
+        if (length > maxBytes)
+            return { kind: 'oversized' };
+        bytes = probe.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+    const file = join(directory, createHash('sha1').update(bytes).digest('hex'));
+    await mkdir(directory, { recursive: true });
+    // Identical content across paths and turns shares one copy; `wx` keeps an existing copy as is.
+    await writeFile(file, bytes, { flag: 'wx' }).catch((error) => {
+        /* v8 ignore next -- a copy that cannot be written needs a directory the tests cannot make unwritable on every host. */
+        if (error.code !== 'EEXIST')
+            throw error;
+    });
+    return { kind: 'file', file, binary: bytes.subarray(0, BINARY_PROBE_BYTES).includes(0) };
+}
+/**
+ * Whether two captures are known to hold the same content. Two absent sides
+ * are the same; two stored copies are the same when their bytes hash alike;
+ * an oversized side is never known to match anything, since its content was
+ * not read.
+ * @param a - one side.
+ * @param b - the other side.
+ * @returns true only when both sides are known to match.
+ */
+export function sameCapture(a, b) {
+    if (a.kind === 'absent' || b.kind === 'absent')
+        return a.kind === b.kind;
+    return a.kind === 'file' && b.kind === 'file' && a.file === b.file;
+}
+/** A non-blank string, or undefined. */
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * The path a first-party file-tool call is about to mutate: `write`, `edit`,
+ * and the mutating `str_replace_editor` commands. Other tools, reads, and
+ * incomplete arguments yield undefined.
+ * @param name - wire tool name.
+ * @param args - parsed call arguments.
+ * @returns the model-facing path, or undefined.
+ */
+export function mutationPath(name, args) {
+    if (typeof args !== 'object' || args === null || Array.isArray(args))
+        return undefined;
+    const record = args;
+    switch (name) {
+        case 'write':
+            return typeof record.content === 'string' ? text(record.file_path) : undefined;
+        case 'edit':
+            return typeof record.old_string === 'string' && typeof record.new_string === 'string' ? text(record.file_path) : undefined;
+        case 'str_replace_editor':
+            return record.command === 'create' || record.command === 'str_replace' || record.command === 'insert' ? text(record.path) : undefined;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=capture.js.map

package/lib/types/compare.d.ts

@@ -0,0 +1,19 @@
+import type { WorkspaceDiffHunk } from './types.ts';
+/** Hunks, whether the timeout degraded them, and the changed-line totals they carry. */
+export interface Comparison {
+    hunks: WorkspaceDiffHunk[];
+    coarse: boolean;
+    added: number;
+    deleted: number;
+}
+/**
+ * Compare two texts line by line. A side that is null means the file did not
+ * exist. A comparison exceeding `timeoutMs` yields one hunk that deletes every
+ * old line and adds every new line.
+ * @param before - turn-start text, or null.
+ * @param after - turn-end text, or null.
+ * @param timeoutMs - milliseconds the line comparison may run.
+ * @returns hunks and totals; no hunks when both sides hold the same lines.
+ */
+export declare function compareText(before: string | null, after: string | null, timeoutMs: number): Comparison;
+//# sourceMappingURL=compare.d.ts.map

package/lib/types/compare.js

@@ -0,0 +1,56 @@
+/** Line comparison of two whole-file texts, bounded by a timeout that degrades to whole-file replacement. */
+import { structuredPatch } from 'diff';
+/** Context lines around each change, the unified-diff default. */
+const CONTEXT_LINES = 3;
+/**
+ * A side's text with every line terminated, so the last line compares by
+ * content alone and empty text reads as no lines rather than one empty line.
+ */
+function terminated(text) {
+    return text === '' || text.endsWith('\n') ? text : `${text}\n`;
+}
+/** Content lines of a terminated text; empty text is zero lines. */
+function lines(text) {
+    return text === '' ? [] : text.slice(0, -1).split('\n');
+}
+/**
+ * Compare two texts line by line. A side that is null means the file did not
+ * exist. A comparison exceeding `timeoutMs` yields one hunk that deletes every
+ * old line and adds every new line.
+ * @param before - turn-start text, or null.
+ * @param after - turn-end text, or null.
+ * @param timeoutMs - milliseconds the line comparison may run.
+ * @returns hunks and totals; no hunks when both sides hold the same lines.
+ */
+export function compareText(before, after, timeoutMs) {
+    const oldText = terminated(before ?? '');
+    const newText = terminated(after ?? '');
+    const patch = structuredPatch('', '', oldText, newText, undefined, undefined, { context: CONTEXT_LINES, timeout: timeoutMs });
+    let hunks;
+    let coarse = false;
+    if (patch === undefined) {
+        coarse = true;
+        const oldLines = lines(oldText);
+        const newLines = lines(newText);
+        hunks = [{
+                oldStart: 1, oldLines: oldLines.length,
+                newStart: 1, newLines: newLines.length,
+                lines: [...oldLines.map(line => `-${line}`), ...newLines.map(line => `+${line}`)],
+            }];
+    }
+    else {
+        hunks = patch.hunks.map(({ oldStart, oldLines, newStart, newLines, lines: body }) => ({ oldStart, oldLines, newStart, newLines, lines: body }));
+    }
+    let added = 0;
+    let deleted = 0;
+    for (const hunk of hunks) {
+        for (const line of hunk.lines) {
+            if (line.startsWith('+'))
+                added += 1;
+            else if (line.startsWith('-'))
+                deleted += 1;
+        }
+    }
+    return { hunks, coarse, added, deleted };
+}
+//# sourceMappingURL=compare.js.map

package/lib/types/git.d.ts

@@ -0,0 +1,140 @@
+import type { SubprocessRuntime } from '@qilin-agent/subprocess';
+import { type NumstatEntry } from './numstat.ts';
+/** Settled git command facts; a nonzero exit is a result, not an exception. */
+export interface GitRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when stdout exceeded the output cap and lost its head. */
+    truncated: boolean;
+}
+/** Per-command spawn facts. */
+export interface GitRunOptions {
+    cwd: string;
+    env?: Readonly<Record<string, string>> | undefined;
+    stdin?: string | undefined;
+    /** In-memory stdout cap for this command, replacing the runner's `outputMaxBytes`. */
+    maxBytes?: number | undefined;
+    signal: AbortSignal;
+}
+/** Bounds every git command runs under. */
+export interface GitLimits {
+    /** Milliseconds before a command is terminated. */
+    timeoutMs: number;
+    /** In-memory stdout cap in bytes. */
+    outputMaxBytes: number;
+}
+/** Runs one resolved git executable with scrubbed environment, timeout, and bounded output. */
+export declare class GitRunner {
+    private readonly subprocess;
+    private readonly executable;
+    private readonly limits;
+    constructor(subprocess: SubprocessRuntime, executable: string, limits: GitLimits);
+    /**
+     * Run `git <args>` to completion.
+     * @param args - git arguments; never shell-interpreted.
+     * @param options - working directory, extra environment, stdin data, and cancellation.
+     * @returns exit facts and collected output.
+     * @throws when the command times out, is aborted, or cannot spawn.
+     */
+    run(args: readonly string[], options: GitRunOptions): Promise<GitRunResult>;
+}
+/** The repository enclosing a Session working directory and the private directory its snapshots write to. */
+export interface GitWorkspace {
+    /** Repository top-level directory, the root every diff path is relative to. */
+    root: string;
+    /** Absolute git directory holding the repository's index. */
+    gitDir: string;
+    /** Private directory holding the snapshot object store and each snapshot's scratch index. */
+    scratch: string;
+    /** Environment that routes object writes to the private store and object reads through the repository's store. */
+    env: Readonly<Record<string, string>>;
+    /** Work-tree paths a snapshot must skip: the private directory when a temporary root lies inside the work tree. */
+    excludes: readonly string[];
+}
+/**
+ * Locate the repository enclosing a working directory and prepare the private
+ * directory its snapshots write to. The repository's own object store is
+ * attached read-only as an alternate, so snapshots read committed content from
+ * it and write nothing into it. A private directory that lies inside the work
+ * tree, as a temporary root under the workspace does, is excluded from every
+ * snapshot. A directory outside any repository yields null; any other git
+ * failure throws.
+ * @param git - command runner.
+ * @param cwd - absolute Session working directory.
+ * @param scratch - yields the private directory for snapshot objects and scratch indexes; called only for a located repository.
+ * @param signal - cancellation.
+ * @returns the repository, or null when the directory is not inside one.
+ */
+export declare function locateGitWorkspace(git: GitRunner, cwd: string, scratch: () => Promise<string>, signal: AbortSignal): Promise<GitWorkspace | null>;
+/**
+ * Write the complete work tree, including untracked and modified files but
+ * not ignored ones, as a tree object through a private index seeded from the
+ * repository's index. New blobs and the tree land in the private object store;
+ * the repository's index, object store, work tree, and refs stay unchanged,
+ * and an in-progress merge keeps its unmerged entries.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param signal - cancellation.
+ * @returns the tree object id.
+ */
+export declare function snapshotTree(git: GitRunner, workspace: GitWorkspace, signal: AbortSignal): Promise<string>;
+/** A blob one snapshot tree holds at a path. */
+export interface TreeBlob {
+    oid: string;
+    /** Object size in bytes. */
+    size: number;
+}
+/**
+ * The blob a snapshot tree holds at one path.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param tree - snapshot tree id.
+ * @param path - slash-separated path relative to the repository root.
+ * @param signal - cancellation.
+ * @returns the blob, or null when the tree holds nothing at the path or holds a gitlink or tree there.
+ */
+export declare function treeBlob(git: GitRunner, workspace: GitWorkspace, tree: string, path: string, signal: AbortSignal): Promise<TreeBlob | null>;
+/**
+ * The text of one blob whose size {@link treeBlob} reported within the cap.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param oid - blob id.
+ * @param maxBytes - inclusive byte cap the caller checked the blob's size against.
+ * @param signal - cancellation.
+ * @returns the blob decoded as UTF-8.
+ */
+export declare function blobText(git: GitRunner, workspace: GitWorkspace, oid: string, maxBytes: number, signal: AbortSignal): Promise<string>;
+/**
+ * Per-file line counts between two snapshot trees, with renames detected.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param before - turn-start tree id.
+ * @param after - turn-end tree id.
+ * @param signal - cancellation.
+ * @returns changed files relative to the repository root.
+ * @throws when git fails or the output exceeded the cap.
+ */
+export declare function diffTrees(git: GitRunner, workspace: GitWorkspace, before: string, after: string, signal: AbortSignal): Promise<NumstatEntry[]>;
+/**
+ * Work-tree directories the index records as gitlinks: nested repositories and
+ * submodules, whose contents snapshots never descend into and `check-ignore`
+ * refuses to classify.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param signal - cancellation.
+ * @returns slash-separated gitlink paths relative to the repository root.
+ */
+export declare function gitlinkPaths(git: GitRunner, workspace: GitWorkspace, signal: AbortSignal): Promise<Set<string>>;
+/**
+ * The subset of work-tree paths that the repository ignores. Tracked files
+ * are never reported, so a tracked file matching an ignore pattern still
+ * counts as covered by snapshots.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param paths - slash-separated paths relative to the repository root.
+ * @param signal - cancellation.
+ * @returns the ignored members of `paths`.
+ */
+export declare function ignoredPaths(git: GitRunner, workspace: GitWorkspace, paths: readonly string[], signal: AbortSignal): Promise<Set<string>>;
+//# sourceMappingURL=git.d.ts.map

package/lib/types/git.js

@@ -0,0 +1,224 @@
+/** Git working-tree snapshots, tree diffs, and ignore checks through the subprocess capability. */
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { parseNumstat } from "./numstat.js";
+import { canonicalPath, isInside, toPosix } from "./paths.js";
+/** Milliseconds a git child gets to exit after termination starts; a fixed lifecycle constant. */
+const TERMINATE_GRACE_MS = 2_000;
+/** Retained stderr tail for diagnostics. */
+const STDERR_TAIL_BYTES = 16 * 1024;
+/** Runs one resolved git executable with scrubbed environment, timeout, and bounded output. */
+export class GitRunner {
+    subprocess;
+    executable;
+    limits;
+    constructor(subprocess, executable, limits) {
+        this.subprocess = subprocess;
+        this.executable = executable;
+        this.limits = limits;
+    }
+    /**
+     * Run `git <args>` to completion.
+     * @param args - git arguments; never shell-interpreted.
+     * @param options - working directory, extra environment, stdin data, and cancellation.
+     * @returns exit facts and collected output.
+     * @throws when the command times out, is aborted, or cannot spawn.
+     */
+    async run(args, options) {
+        const timeout = AbortSignal.timeout(this.limits.timeoutMs);
+        const signal = AbortSignal.any([options.signal, timeout]);
+        const handle = this.subprocess.spawn({
+            argv: [this.executable, ...args],
+            cwd: options.cwd,
+            stdio: {
+                stdin: options.stdin === undefined ? 'ignore' : { data: options.stdin },
+                stdout: { maxBytes: options.maxBytes ?? this.limits.outputMaxBytes },
+                stderr: { maxBytes: STDERR_TAIL_BYTES },
+            },
+            graceMs: TERMINATE_GRACE_MS,
+            signal,
+            // The subprocess credential scrub removes ambient GIT_CONFIG_KEY_n entries.
+            env: { GIT_CONFIG_COUNT: '0', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C', ...options.env },
+        });
+        const outcome = await handle.done;
+        if (signal.aborted) {
+            throw new Error(`git ${args.join(' ')} ${timeout.aborted ? `timed out after ${this.limits.timeoutMs}ms` : 'was aborted'}`);
+        }
+        /* v8 ignore start -- collect-mode stdio always yields both readers. */
+        const stdout = handle.collected.stdout?.readFrom(0) ?? { text: '', lossy: false };
+        const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+        /* v8 ignore stop */
+        return { exitCode: outcome.exitCode, stdout: stdout.text, stderr, truncated: stdout.lossy };
+    }
+}
+/**
+ * Reject a failed command with its stderr.
+ * @param result - settled command facts.
+ * @param what - command description for the error message.
+ * @returns the same result when it exited zero.
+ */
+function ok(result, what) {
+    if (result.exitCode !== 0)
+        throw new Error(`${what} failed: ${result.stderr.trim()}`);
+    return result;
+}
+/** Whether a filesystem error names a missing path. */
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+/**
+ * Locate the repository enclosing a working directory and prepare the private
+ * directory its snapshots write to. The repository's own object store is
+ * attached read-only as an alternate, so snapshots read committed content from
+ * it and write nothing into it. A private directory that lies inside the work
+ * tree, as a temporary root under the workspace does, is excluded from every
+ * snapshot. A directory outside any repository yields null; any other git
+ * failure throws.
+ * @param git - command runner.
+ * @param cwd - absolute Session working directory.
+ * @param scratch - yields the private directory for snapshot objects and scratch indexes; called only for a located repository.
+ * @param signal - cancellation.
+ * @returns the repository, or null when the directory is not inside one.
+ */
+export async function locateGitWorkspace(git, cwd, scratch, signal) {
+    const found = await git.run(['rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-path', 'objects'], { cwd, signal });
+    if (found.exitCode === 128 && /not a git repository/i.test(found.stderr))
+        return null;
+    const lines = ok(found, 'git rev-parse').stdout.split('\n').map(line => resolve(cwd, line));
+    const [root, gitDir, repositoryObjects] = lines;
+    // git reports the canonical root; compare the private directory in the same spelling.
+    const directory = await canonicalPath(await scratch());
+    const objects = join(directory, 'objects');
+    await mkdir(objects, { recursive: true });
+    const excludes = isInside(root, directory) ? [toPosix(relative(root, directory))] : [];
+    const env = { GIT_OBJECT_DIRECTORY: objects, GIT_ALTERNATE_OBJECT_DIRECTORIES: repositoryObjects };
+    return { root, gitDir, scratch: directory, env, excludes };
+}
+/**
+ * Write the complete work tree, including untracked and modified files but
+ * not ignored ones, as a tree object through a private index seeded from the
+ * repository's index. New blobs and the tree land in the private object store;
+ * the repository's index, object store, work tree, and refs stay unchanged,
+ * and an in-progress merge keeps its unmerged entries.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param signal - cancellation.
+ * @returns the tree object id.
+ */
+export async function snapshotTree(git, workspace, signal) {
+    const scratch = await mkdtemp(join(workspace.scratch, 'index-'));
+    try {
+        const index = join(scratch, 'index');
+        // A repository without an index yet (fresh `git init`) starts from scratch.
+        await copyFile(join(workspace.gitDir, 'index'), index).catch((error) => {
+            if (!isMissing(error))
+                throw error;
+        });
+        const env = { ...workspace.env, GIT_INDEX_FILE: index };
+        // `--ignore-errors` skips unreadable files and reports them through exit code 1; the index is still complete.
+        const pathspec = workspace.excludes.length === 0 ? [] : ['--', '.', ...workspace.excludes.map(path => `:(exclude)${path}`)];
+        const added = await git.run(['add', '--all', '--ignore-errors', ...pathspec], { cwd: workspace.root, env, signal });
+        /* v8 ignore next -- git reports a skipped unreadable file only on hosts whose permissions the tests can revoke. */
+        if (added.exitCode !== 1)
+            ok(added, `git add in ${workspace.root}`);
+        return ok(await git.run(['write-tree'], { cwd: workspace.root, env, signal }), 'git write-tree').stdout.trim();
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * The blob a snapshot tree holds at one path.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param tree - snapshot tree id.
+ * @param path - slash-separated path relative to the repository root.
+ * @param signal - cancellation.
+ * @returns the blob, or null when the tree holds nothing at the path or holds a gitlink or tree there.
+ */
+export async function treeBlob(git, workspace, tree, path, signal) {
+    // The path is a pathspec; literal matching keeps `*`, `?`, and `[` in a file name from selecting another entry.
+    const result = ok(await git.run(['ls-tree', '-z', '-l', tree, '--', path], {
+        cwd: workspace.root, env: { ...workspace.env, GIT_LITERAL_PATHSPECS: '1' }, signal,
+    }), 'git ls-tree');
+    const entry = result.stdout.split('\0')[0];
+    const match = /^\d+ (\S+) ([0-9a-f]+) +(\d+)\t/.exec(entry);
+    if (match === null || match[1] !== 'blob')
+        return null;
+    return { oid: match[2], size: Number(match[3]) };
+}
+/**
+ * The text of one blob whose size {@link treeBlob} reported within the cap.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param oid - blob id.
+ * @param maxBytes - inclusive byte cap the caller checked the blob's size against.
+ * @param signal - cancellation.
+ * @returns the blob decoded as UTF-8.
+ */
+export async function blobText(git, workspace, oid, maxBytes, signal) {
+    const result = ok(await git.run(['cat-file', 'blob', oid], { cwd: workspace.root, env: workspace.env, maxBytes, signal }), 'git cat-file');
+    /* v8 ignore next -- callers size the blob with treeBlob first; a blob is immutable, so the cap cannot be exceeded here. */
+    if (result.truncated)
+        throw new Error(`blob ${oid} exceeds ${maxBytes} bytes`);
+    return result.stdout;
+}
+/**
+ * Per-file line counts between two snapshot trees, with renames detected.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param before - turn-start tree id.
+ * @param after - turn-end tree id.
+ * @param signal - cancellation.
+ * @returns changed files relative to the repository root.
+ * @throws when git fails or the output exceeded the cap.
+ */
+export async function diffTrees(git, workspace, before, after, signal) {
+    if (before === after)
+        return [];
+    const result = ok(await git.run(['diff-tree', '-r', '-M', '-z', '--numstat', before, after], {
+        cwd: workspace.root, env: workspace.env, signal,
+    }), 'git diff-tree');
+    if (result.truncated)
+        throw new Error('git diff-tree output exceeded the configured cap');
+    return parseNumstat(result.stdout);
+}
+/**
+ * Work-tree directories the index records as gitlinks: nested repositories and
+ * submodules, whose contents snapshots never descend into and `check-ignore`
+ * refuses to classify.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param signal - cancellation.
+ * @returns slash-separated gitlink paths relative to the repository root.
+ */
+export async function gitlinkPaths(git, workspace, signal) {
+    const result = ok(await git.run(['ls-files', '-z', '--stage'], { cwd: workspace.root, env: workspace.env, signal }), 'git ls-files');
+    const links = new Set();
+    for (const entry of result.stdout.split('\0')) {
+        if (entry.startsWith('160000 '))
+            links.add(entry.slice(entry.indexOf('\t') + 1));
+    }
+    return links;
+}
+/**
+ * The subset of work-tree paths that the repository ignores. Tracked files
+ * are never reported, so a tracked file matching an ignore pattern still
+ * counts as covered by snapshots.
+ * @param git - command runner.
+ * @param workspace - addressed repository.
+ * @param paths - slash-separated paths relative to the repository root.
+ * @param signal - cancellation.
+ * @returns the ignored members of `paths`.
+ */
+export async function ignoredPaths(git, workspace, paths, signal) {
+    if (paths.length === 0)
+        return new Set();
+    const result = await git.run(['check-ignore', '-z', '--stdin'], {
+        cwd: workspace.root, env: workspace.env, stdin: `${paths.join('\0')}\0`, signal,
+    });
+    if (result.exitCode === 1)
+        return new Set();
+    return new Set(ok(result, 'git check-ignore').stdout.split('\0').filter(path => path !== ''));
+}
+//# sourceMappingURL=git.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,34 @@
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+export type { WorkspaceChangedFile, WorkspaceChanges, WorkspaceChangesSummary, WorkspaceDiffHunk, WorkspaceFileDiff, WorkspaceSessionChangedFile, WorkspaceSessionChanges, } from './types.ts';
+/** Stable Loader identity. */
+export declare const name = "workspace-changes";
+/** Services used to run git and observe turns. */
+export declare const inject: string[];
+/** Snapshot, capture, and comparison bounds. Invalid values fail plugin load. */
+export interface Config {
+    /** Milliseconds one git command may run before the turn's record is abandoned. */
+    timeoutMs: number;
+    /** Bytes of git output retained per command; a larger diff listing abandons the record. */
+    outputMaxBytes: number;
+    /** Maximum files carried by one summary; `total` still reports the complete count. */
+    maxFiles: number;
+    /**
+     * Bytes a file may hold to be captured around a file-tool edit or read from a snapshot for its comparison.
+     * A larger file gets no comparison; one captured around a file-tool edit is also listed without counts.
+     */
+    maxFileBytes: number;
+    /** Milliseconds a line comparison may run before it degrades to whole-file replacement. */
+    diffTimeoutMs: number;
+}
+/** Schemastery validation for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * Observe top-level turns of every Session with a working directory, capture
+ * file-tool edits, announce change summaries, and serve them with their
+ * comparisons as `workspaceChanges`.
+ * @param ctx - host context with `subprocess`.
+ * @param config - validated bounds.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map