@ikarmic/forge-core 5.0.0 → 5.1.0

package/dist/skills/remote.js

@@ -0,0 +1,131 @@
+/**
+ * Skills from a URL: either one skill file (Markdown with front matter) or an index,
+ * `{ "skills": [{ "url": "a.md" }, ...] }`, whose links may be relative to the index.
+ * Responses are cached on disk so a skill still works offline and a slow host is not asked on every run:
+ * a copy younger than the TTL is used as is; an older one is refreshed, and kept if the refresh fails.
+ * Anything that times out or is not a skill is skipped with one warning. Only http and https are fetched.
+ * The `skillPaths` setting that lists URLs is read from the user's config only.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { parseSkill } from './parser.js';
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_CHARS = 200_000;
+const MAX_INDEX_ENTRIES = 20;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** A host that failed is not asked again for this long, so a dead URL does not add its timeout to every message. */
+const RETRY_AFTER_FAILURE_MS = 5 * 60 * 1000;
+const failures = new Map();
+export const isHttpUrl = (s) => /^https?:\/\//i.test(s);
+function cacheFile(dir, url) {
+    return path.join(dir, `${createHash('sha256').update(url).digest('hex').slice(0, 32)}.json`);
+}
+async function readCache(dir, url) {
+    try {
+        const entry = JSON.parse(await readFile(cacheFile(dir, url), 'utf8'));
+        return typeof entry.text === 'string' && typeof entry.fetchedAt === 'number' ? entry : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text at `url`: a fresh cached copy, else the network, else a stale cached copy; throws if there is none. */
+async function fetchText(url, opts) {
+    const cached = await readCache(opts.cacheDir, url);
+    if (cached && opts.now() - cached.fetchedAt < opts.ttlMs)
+        return cached.text;
+    const failKey = `${opts.cacheDir}|${url}`;
+    const failed = failures.get(failKey);
+    const since = failed ? opts.now() - failed.at : 0;
+    if (failed && since >= 0 && since < RETRY_AFTER_FAILURE_MS) {
+        if (cached)
+            return cached.text;
+        throw new Error(failed.message);
+    }
+    try {
+        const res = await opts.fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = (await res.text()).slice(0, MAX_CHARS);
+        try {
+            await mkdir(opts.cacheDir, { recursive: true });
+            await writeFile(cacheFile(opts.cacheDir, url), JSON.stringify({ url, fetchedAt: opts.now(), text }), 'utf8');
+        }
+        catch {
+            // a cache that cannot be written only costs a fetch next time
+        }
+        failures.delete(failKey);
+        return text;
+    }
+    catch (err) {
+        failures.set(failKey, { at: opts.now(), message: err.message });
+        if (cached)
+            return cached.text;
+        throw err;
+    }
+}
+function fallbackName(url) {
+    const last = new URL(url).pathname.split('/').filter(Boolean).pop() ?? 'remote-skill';
+    return last.replace(/\.md$/i, '') || 'remote-skill';
+}
+function asSkill(url, text) {
+    const head = text.trimStart();
+    if (head.startsWith('<') || !head.startsWith('---'))
+        return undefined;
+    const skill = parseSkill(text, { kind: 'remote', path: url }, fallbackName(url));
+    return skill.description.trim() && skill.body ? skill : undefined;
+}
+export async function loadRemoteSkills(url, options = {}) {
+    const warnings = [];
+    if (!isHttpUrl(url))
+        return { skills: [], warnings: [`${url}: only http and https skill URLs are read; skipped`] };
+    const opts = {
+        fetch: options.fetch ?? fetch,
+        cacheDir: options.cacheDir ?? path.join(homedir(), '.forge', 'skill-cache'),
+        ttlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+        now: options.now ?? Date.now,
+    };
+    const loadOne = async (target) => {
+        try {
+            const skill = asSkill(target, await fetchText(target, opts));
+            if (!skill)
+                warnings.push(`${target}: not a skill (needs front matter with a description); skipped`);
+            return skill;
+        }
+        catch (err) {
+            warnings.push(`${target}: ${err.message}; skipped`);
+            return undefined;
+        }
+    };
+    let text;
+    try {
+        text = await fetchText(url, opts);
+    }
+    catch (err) {
+        return { skills: [], warnings: [`${url}: ${err.message}; skipped`] };
+    }
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        let index;
+        try {
+            index = JSON.parse(text);
+        }
+        catch {
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        }
+        const list = Array.isArray(index) ? index : index?.skills;
+        if (!Array.isArray(list))
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        const targets = list
+            .map((e) => (typeof e === 'string' ? e : e?.url))
+            .filter((u) => typeof u === 'string' && u.length > 0)
+            .slice(0, MAX_INDEX_ENTRIES)
+            .map((u) => new URL(u, url).href);
+        const skills = (await Promise.all(targets.map(loadOne))).filter((s) => s !== undefined);
+        return { skills, warnings };
+    }
+    const skill = asSkill(url, text);
+    return skill ? { skills: [skill], warnings } : { skills: [], warnings: [`${url}: not a skill (needs front matter with a description); skipped`] };
+}

package/dist/skills/types.d.ts

@@ -38,6 +38,16 @@ export type SkillSource = {
 } | {
     kind: 'global';
     path: string;
+}
+/** Ships inside Forge; there is no file, `path` is a label. */
+ | {
+    kind: 'builtin';
+    path: string;
+}
+/** Fetched from a URL listed in `skillPaths`; `path` is the URL. */
+ | {
+    kind: 'remote';
+    path: string;
 };
 /** A parsed skill, ready for activation. */
 export interface Skill {

package/dist/steering/extra-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export declare function buildExtraInstructionsBlock(cwd: string, entries: readonly string[], deps?: {
+    fetch?: typeof fetch;
+}): Promise<string>;

package/dist/steering/extra-instructions.js

@@ -0,0 +1,104 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { pathMatchesGlob } from './glob.js';
+const PER_SOURCE_BYTES = 12_000;
+const TOTAL_BYTES = 48_000;
+const MAX_WALK_FILES = 5_000;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'out', 'build', '.next', 'target']);
+const URL_TIMEOUT_MS = 10_000;
+const isGlob = (s) => /[*?[]/.test(s);
+const isUrl = (s) => /^[a-z][a-z0-9+.-]*:\/\//i.test(s);
+async function walk(root) {
+    const out = [];
+    async function visit(dir, rel, depth) {
+        if (depth > 8 || out.length >= MAX_WALK_FILES)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (out.length >= MAX_WALK_FILES)
+                return;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    await visit(path.join(dir, e.name), r, depth + 1);
+            }
+            else if (e.isFile())
+                out.push(r);
+        }
+    }
+    await visit(root, '', 0);
+    return out;
+}
+const clip = (text) => (text.length > PER_SOURCE_BYTES ? `${text.slice(0, PER_SOURCE_BYTES)}\n…(truncated)` : text);
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export async function buildExtraInstructionsBlock(cwd, entries, deps = {}) {
+    const sources = [];
+    const seen = new Set();
+    const addFile = (label, abs) => {
+        const key = path.resolve(abs);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        sources.push({ label, read: () => readFile(abs, 'utf8') });
+    };
+    let walked;
+    for (const raw of entries) {
+        const entry = raw.trim();
+        if (!entry)
+            continue;
+        if (isUrl(entry)) {
+            if (!/^https?:\/\//i.test(entry) || seen.has(entry))
+                continue;
+            seen.add(entry);
+            sources.push({
+                label: entry,
+                read: async () => {
+                    const res = await (deps.fetch ?? fetch)(entry, { signal: AbortSignal.timeout(URL_TIMEOUT_MS) });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return (await res.text()).slice(0, PER_SOURCE_BYTES * 2);
+                },
+            });
+        }
+        else if (isGlob(entry) && !path.isAbsolute(entry) && !entry.startsWith('~')) {
+            walked ??= await walk(cwd);
+            for (const rel of walked.filter((f) => pathMatchesGlob(entry, f)))
+                addFile(rel, path.join(cwd, rel));
+        }
+        else {
+            const abs = entry.startsWith('~') ? path.join(homedir(), entry.slice(1)) : path.resolve(cwd, entry);
+            addFile(entry, abs);
+        }
+    }
+    const blocks = [];
+    let total = 0;
+    for (const s of sources) {
+        if (total >= TOTAL_BYTES)
+            break;
+        let text;
+        try {
+            text = (await s.read()).trim();
+        }
+        catch {
+            continue;
+        }
+        if (!text)
+            continue;
+        const body = clip(text);
+        total += body.length;
+        blocks.push(`<instructions source="${s.label.replace(/"/g, '')}">\n${body}\n</instructions>`);
+    }
+    return blocks.join('\n\n');
+}

package/dist/steering/folder-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `AGENTS.md` of every folder between the workspace root and the file just read (nearest first), each shown
+ * once per run. The root one is already in the system prompt, so it is never repeated here.
+ */
+export declare function folderInstructionsFor(filePath: string, cwd: string, shown: Set<string>): Promise<Array<{
+    file: string;
+    text: string;
+}> | undefined>;

package/dist/steering/folder-instructions.js

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_BYTES = 8_000;
+/**
+ * The `AGENTS.md` of every folder between the workspace root and the file just read (nearest first), each shown
+ * once per run. The root one is already in the system prompt, so it is never repeated here.
+ */
+export async function folderInstructionsFor(filePath, cwd, shown) {
+    const root = path.resolve(cwd);
+    let dir = path.dirname(path.resolve(filePath));
+    const out = [];
+    while (dir !== root && dir.startsWith(root + path.sep)) {
+        const abs = path.join(dir, 'AGENTS.md');
+        if (!shown.has(abs)) {
+            try {
+                const text = (await readFile(abs, 'utf8')).trim();
+                shown.add(abs);
+                if (text)
+                    out.push({ file: path.relative(root, abs), text: text.length > MAX_BYTES ? `${text.slice(0, MAX_BYTES)}\n…(truncated)` : text });
+            }
+            catch {
+                shown.add(abs);
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return out.length ? out : undefined;
+}

package/dist/steering/select.js

@@ -4,6 +4,7 @@
  */
 import path from 'node:path';
 import { pathMatchesGlob } from './glob.js';
+import { isOutsideRel } from '../tools/shared.js';
 export const START_BUDGET_BYTES = 12_000;
 export const TOOL_DOC_BYTES = 8_000;
 export const MAX_TOOL_INJECTIONS = 3;
@@ -19,7 +20,7 @@ export function stripSteering(text) {
 export function toWorkspaceRelative(cwd, p) {
     const abs = path.resolve(cwd, p);
     const rel = path.relative(cwd, abs);
-    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+    if (!rel || isOutsideRel(rel))
         return null;
     return rel.split(path.sep).join('/');
 }

package/dist/timed-fetch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wraps `fetch` with the two timeouts Kilo calls `timeout` and `chunkTimeout`:
+ * - `timeoutMs`: how long to wait for the response to start (headers). It stops counting once the answer begins,
+ *   so a slow stream is never cut short by it.
+ * - `chunkTimeoutMs`: how long a streamed answer may stay silent. A stalled stream is aborted with a clear error
+ *   instead of hanging forever (a connection can stay open while the provider has stopped sending).
+ */
+export interface FetchTimeouts {
+    timeoutMs?: number;
+    chunkTimeoutMs?: number;
+}
+export declare function withTimeouts(base: typeof fetch, opts: FetchTimeouts): typeof fetch;

package/dist/timed-fetch.js

@@ -0,0 +1,83 @@
+export function withTimeouts(base, opts) {
+    const { timeoutMs, chunkTimeoutMs } = opts;
+    if (!timeoutMs && !chunkTimeoutMs)
+        return base;
+    return (async (input, init) => {
+        const controller = new AbortController();
+        const outer = init?.signal;
+        if (outer?.aborted)
+            controller.abort();
+        else
+            outer?.addEventListener('abort', () => controller.abort(), { once: true });
+        let reason;
+        const host = (() => {
+            try {
+                return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).host;
+            }
+            catch {
+                return 'the provider';
+            }
+        })();
+        const fail = (message) => {
+            reason = new Error(message);
+            controller.abort();
+        };
+        const headerTimer = timeoutMs ? setTimeout(() => fail(`The request to ${host} timed out after ${timeoutMs} ms.`), timeoutMs) : undefined;
+        let res;
+        try {
+            res = await base(input, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            throw reason ?? err;
+        }
+        finally {
+            if (headerTimer)
+                clearTimeout(headerTimer);
+        }
+        if (!chunkTimeoutMs || !res.body)
+            return res;
+        const reader = res.body.getReader();
+        let idle;
+        const arm = (onIdle) => {
+            if (idle)
+                clearTimeout(idle);
+            idle = setTimeout(onIdle, chunkTimeoutMs);
+        };
+        const body = new ReadableStream({
+            start(stream) {
+                arm(() => {
+                    fail(`No data for ${chunkTimeoutMs} ms from ${host}.`);
+                    stream.error(reason);
+                });
+            },
+            async pull(stream) {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (idle)
+                            clearTimeout(idle);
+                        stream.close();
+                        return;
+                    }
+                    arm(() => {
+                        fail(`No data for ${chunkTimeoutMs} ms from ${host}.`);
+                        stream.error(reason);
+                        void reader.cancel().catch(() => undefined);
+                    });
+                    stream.enqueue(value);
+                }
+                catch (err) {
+                    if (idle)
+                        clearTimeout(idle);
+                    stream.error(reason ?? err);
+                }
+            },
+            cancel(why) {
+                if (idle)
+                    clearTimeout(idle);
+                return reader.cancel(why);
+            },
+        });
+        return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+    });
+}

package/dist/tools/apply-patch.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const params: z.ZodObject<{
+    patch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    patch: string;
+}, {
+    patch: string;
+}>;
+export type PatchOp = {
+    kind: 'add';
+    path: string;
+    content: string;
+} | {
+    kind: 'delete';
+    path: string;
+} | {
+    kind: 'update';
+    path: string;
+    hunks: Array<{
+        lines: Array<{
+            tag: ' ' | '-' | '+';
+            text: string;
+        }>;
+    }>;
+};
+/** Parse the patch text into operations. Throws on a malformed patch. */
+export declare function parsePatch(text: string): PatchOp[];
+/** Every path a patch touches, once each; empty when the text is not a valid patch (callers then fall back to the broadest target). */
+export declare function patchedPaths(patch: string): string[];
+export interface PatchPreview {
+    path: string;
+    /** Text before the patch; null when the file does not exist yet. */
+    before: string | null;
+    /** Text after the patch; null when the patch deletes the file. */
+    after: string | null;
+    /** Why this file's change could not be worked out (a hunk that does not match). */
+    error?: string;
+}
+/**
+ * What an `apply_patch` call would leave in each file, worked out in memory so it can be shown before it is approved.
+ * Never writes. Throws only for a patch that cannot be parsed at all.
+ */
+export declare function previewPatch(patch: string, read: (path: string) => Promise<string | null>): Promise<PatchPreview[]>;
+export interface ApplyPatchResult {
+    files: Array<{
+        action: 'add' | 'update' | 'delete';
+        path: string;
+    }>;
+}
+export declare const applyPatchTool: ToolDefinition<z.infer<typeof params>, ApplyPatchResult>;
+export {};

package/dist/tools/apply-patch.js

@@ -0,0 +1,197 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { resolveAndCheckPath } from './shared.js';
+import { decodeText, encodeText } from './text-encoding.js';
+const params = z.object({
+    patch: z
+        .string()
+        .min(1)
+        .describe('The patch. Starts with "*** Begin Patch", ends with "*** End Patch". Between them, per file: "*** Add File: path" followed by lines starting with +; "*** Delete File: path"; or "*** Update File: path" followed by hunks that begin with "@@" and whose lines start with a space (kept), - (removed) or + (added).'),
+});
+/** Parse the patch text into operations. Throws on a malformed patch. */
+export function parsePatch(text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    while (lines.length && lines[0].trim() === '')
+        lines.shift();
+    while (lines.length && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    if (lines[0]?.trim() !== '*** Begin Patch' || lines[lines.length - 1]?.trim() !== '*** End Patch') {
+        throw new Error('A patch must start with "*** Begin Patch" and end with "*** End Patch".');
+    }
+    const body = lines.slice(1, -1);
+    const ops = [];
+    let i = 0;
+    while (i < body.length) {
+        const line = body[i];
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+        const add = /^\*\*\* Add File: (.+)$/.exec(line);
+        const del = /^\*\*\* Delete File: (.+)$/.exec(line);
+        const upd = /^\*\*\* Update File: (.+)$/.exec(line);
+        if (add) {
+            const content = [];
+            i++;
+            while (i < body.length && !body[i].startsWith('*** ')) {
+                const l = body[i];
+                if (!l.startsWith('+'))
+                    throw new Error(`Add File ${add[1]}: every line must start with + (got "${l.slice(0, 40)}").`);
+                content.push(l.slice(1));
+                i++;
+            }
+            ops.push({ kind: 'add', path: add[1].trim(), content: content.length ? `${content.join('\n')}\n` : '' });
+        }
+        else if (del) {
+            ops.push({ kind: 'delete', path: del[1].trim() });
+            i++;
+        }
+        else if (upd) {
+            const hunks = [];
+            i++;
+            while (i < body.length && !body[i].startsWith('*** ')) {
+                if (body[i].startsWith('@@')) {
+                    hunks.push({ lines: [] });
+                    i++;
+                    continue;
+                }
+                const l = body[i];
+                const tag = l[0];
+                if (tag !== ' ' && tag !== '-' && tag !== '+')
+                    throw new Error(`Update File ${upd[1]}: bad hunk line "${l.slice(0, 40)}" (start with space, - or +).`);
+                if (hunks.length === 0)
+                    hunks.push({ lines: [] });
+                hunks[hunks.length - 1].lines.push({ tag, text: l.slice(1) });
+                i++;
+            }
+            if (hunks.length === 0)
+                throw new Error(`Update File ${upd[1]} has no hunks.`);
+            ops.push({ kind: 'update', path: upd[1].trim(), hunks });
+        }
+        else {
+            throw new Error(`Unknown patch directive: "${line.slice(0, 60)}"`);
+        }
+    }
+    if (ops.length === 0)
+        throw new Error('The patch has no operations.');
+    return ops;
+}
+/** Every path a patch touches, once each; empty when the text is not a valid patch (callers then fall back to the broadest target). */
+export function patchedPaths(patch) {
+    try {
+        return [...new Set(parsePatch(patch).map((o) => o.path))];
+    }
+    catch {
+        return [];
+    }
+}
+function indexOfSeq(hay, needle, from, norm) {
+    if (needle.length === 0)
+        return from;
+    outer: for (let s = from; s <= hay.length - needle.length; s++) {
+        for (let k = 0; k < needle.length; k++)
+            if (norm(hay[s + k]) !== norm(needle[k]))
+                continue outer;
+        return s;
+    }
+    return -1;
+}
+/** Apply update hunks to file text, in order, each searching after the previous one. Exact match first, then ignoring trailing whitespace. */
+function applyHunks(file, original, hunks) {
+    const eol = original.includes('\r\n') ? '\r\n' : '\n';
+    const endsWithNewline = original.endsWith('\n');
+    const lines = original.replace(/\r\n/g, '\n').split('\n');
+    if (endsWithNewline)
+        lines.pop();
+    let cursor = 0;
+    for (const [n, hunk] of hunks.entries()) {
+        const oldSeq = hunk.lines.filter((l) => l.tag !== '+').map((l) => l.text);
+        const newSeq = hunk.lines.filter((l) => l.tag !== '-').map((l) => l.text);
+        let at = indexOfSeq(lines, oldSeq, cursor, (s) => s);
+        if (at === -1)
+            at = indexOfSeq(lines, oldSeq, cursor, (s) => s.trimEnd());
+        if (at === -1)
+            throw new Error(`Hunk ${n + 1} of ${file} did not match the file. Re-read it and make the context lines exact.`);
+        lines.splice(at, oldSeq.length, ...newSeq);
+        cursor = at + newSeq.length;
+    }
+    return lines.join(eol) + (endsWithNewline ? eol : '');
+}
+/**
+ * What an `apply_patch` call would leave in each file, worked out in memory so it can be shown before it is approved.
+ * Never writes. Throws only for a patch that cannot be parsed at all.
+ */
+export async function previewPatch(patch, read) {
+    const out = [];
+    for (const op of parsePatch(patch)) {
+        const before = await read(op.path);
+        if (op.kind === 'add')
+            out.push({ path: op.path, before, after: op.content });
+        else if (op.kind === 'delete')
+            out.push({ path: op.path, before, after: null });
+        else if (before === null)
+            out.push({ path: op.path, before, after: null, error: `File not found: ${op.path}` });
+        else {
+            try {
+                out.push({ path: op.path, before, after: applyHunks(op.path, before, op.hunks) });
+            }
+            catch (err) {
+                out.push({ path: op.path, before, after: null, error: err.message });
+            }
+        }
+    }
+    return out;
+}
+export const applyPatchTool = {
+    name: 'apply_patch',
+    description: 'Change several files in one step with a patch: add files, delete files, or update files by hunks of context and changed lines. All or nothing: if one hunk does not match, no file is touched. Prefer edit_file for a single small change.',
+    parameters: params,
+    destructive: false,
+    execute: async (args, ctx) => {
+        const ops = parsePatch(args.patch);
+        // Plan every change in memory first, so a bad hunk leaves the workspace as it was.
+        const writes = new Map();
+        const encodings = new Map();
+        const deletes = new Set();
+        const files = [];
+        for (const op of ops) {
+            const abs = resolveAndCheckPath(op.path, ctx);
+            const rel = op.path.split(String.fromCharCode(92)).join('/');
+            if (op.kind === 'add') {
+                const exists = await readFile(abs, 'utf8').then(() => true, () => false);
+                if ((exists && !deletes.has(abs)) || writes.has(abs))
+                    throw new Error(`Cannot add ${op.path}: it already exists.`);
+                writes.set(abs, op.content);
+                files.push({ action: 'add', path: rel });
+            }
+            else if (op.kind === 'delete') {
+                await readFile(abs, 'utf8').catch(() => {
+                    throw new Error(`Cannot delete ${op.path}: file not found.`);
+                });
+                deletes.add(abs);
+                writes.delete(abs);
+                files.push({ action: 'delete', path: rel });
+            }
+            else {
+                let current = writes.get(abs);
+                if (current === undefined) {
+                    const decoded = await readFile(abs).then(decodeText, () => {
+                        throw new Error(`Cannot update ${op.path}: file not found.`);
+                    });
+                    current = decoded.text;
+                    encodings.set(abs, decoded.encoding);
+                }
+                writes.set(abs, applyHunks(op.path, current, op.hunks));
+                files.push({ action: 'update', path: rel });
+            }
+        }
+        for (const abs of deletes)
+            await rm(abs);
+        for (const [abs, content] of writes) {
+            await mkdir(path.dirname(abs), { recursive: true });
+            await writeFile(abs, encodeText(content, encodings.get(abs) ?? 'utf8'));
+        }
+        return { files };
+    },
+};