@oscharko-dev/keiko 0.1.0-beta.0

package/dist/tools/index.d.ts

@@ -0,0 +1,11 @@
+export type { CommandResult, CommandRule, CommandRunInput, NetworkPolicy, PatchApplyResult, PatchChangeKind, PatchConflict, PatchFileChange, PatchHunk, PatchLimits, PatchRejection, PatchRejectionCode, PatchValidation, SandboxPolicy, ToolHostConfig, ToolHostConfigInput, } from "./types.js";
+export { DEFAULT_COMMAND_RULES, DEFAULT_ENV_ALLOWLIST, DEFAULT_PATCH_LIMITS, DEFAULT_SANDBOX_POLICY, DEFAULT_TOOL_HOST_CONFIG, resolveToolHostConfig, } from "./types.js";
+export { CommandCancelledError, CommandDeniedError, CommandTimeoutError, OutputLimitError, PatchApplyDisabledError, PatchApplyError, PatchValidationError, TOOL_CODES, ToolArgumentError, ToolError, UnknownToolError, type ToolCode, } from "./errors.js";
+export { buildSandboxEnv, collectSensitiveEnvValues, isCommandAllowed, type CommandDecision, } from "./sandbox.js";
+export { nodeWorkspaceWriter, type WorkspaceWriter } from "./writer.js";
+export { nodeSpawnFn, runCommand, type RunCommandDeps, type RunCommandInput, type ExecutableResolver, type ExecutableResolverDeps, type SpawnFn, type SpawnOptions, } from "./exec.js";
+export { applyPatch, renderDryRun, validatePatch, type ApplyDeps, type ValidateDeps, } from "./patch.js";
+export { normalizeUnifiedDiffHunks } from "./patch-normalize.js";
+export { parseUnifiedDiff, type ParsedPatch } from "./patch-parse.js";
+export { TOOL_DEFINITIONS } from "./schemas.js";
+export { WorkspaceToolHost } from "./registry.js";

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+// Public barrel for the safe tool-execution layer (ADR-0006). The tool host is the trust
+// boundary between model output and developer repositories: deny-by-default command allowlist,
+// env-isolated no-shell spawn, and a fail-closed, atomic patch workflow. Explicit named
+// re-exports, `type` keyword for type-only, double quotes, `.js`.
+export { DEFAULT_COMMAND_RULES, DEFAULT_ENV_ALLOWLIST, DEFAULT_PATCH_LIMITS, DEFAULT_SANDBOX_POLICY, DEFAULT_TOOL_HOST_CONFIG, resolveToolHostConfig, } from "./types.js";
+export { CommandCancelledError, CommandDeniedError, CommandTimeoutError, OutputLimitError, PatchApplyDisabledError, PatchApplyError, PatchValidationError, TOOL_CODES, ToolArgumentError, ToolError, UnknownToolError, } from "./errors.js";
+export { buildSandboxEnv, collectSensitiveEnvValues, isCommandAllowed, } from "./sandbox.js";
+export { nodeWorkspaceWriter } from "./writer.js";
+export { nodeSpawnFn, runCommand, } from "./exec.js";
+export { applyPatch, renderDryRun, validatePatch, } from "./patch.js";
+export { normalizeUnifiedDiffHunks } from "./patch-normalize.js";
+export { parseUnifiedDiff } from "./patch-parse.js";
+export { TOOL_DEFINITIONS } from "./schemas.js";
+export { WorkspaceToolHost } from "./registry.js";

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

@@ -0,0 +1,10 @@
+import type { PatchFileChange } from "./types.js";
+export interface HunkConflict {
+    readonly hunkIndex: number;
+    readonly reason: string;
+}
+export interface ApplyOutcome {
+    readonly content: string | null;
+    readonly conflicts: readonly HunkConflict[];
+}
+export declare function computeFileContent(change: PatchFileChange, current: string | undefined): ApplyOutcome;

package/dist/tools/patch-content.js

@@ -0,0 +1,126 @@
+// PURE hunk application against in-memory file content. Given the current file lines and a
+// file's hunks, it verifies the pre-image (context and removed lines must match the current
+// content at the hunk location) and produces the post-image. A mismatch yields a conflict
+// rather than a silent corruption — the apply phase refuses to write when any conflict exists.
+// Splits file content into lines WITHOUT a trailing empty element for a final newline, so line
+// indexing matches unified-diff 1-based line numbers. An empty file is zero lines.
+function toLines(content) {
+    if (content === "") {
+        return [];
+    }
+    const lines = content.split("\n");
+    if (lines.at(-1) === "") {
+        lines.pop();
+    }
+    return lines;
+}
+function joinLines(lines) {
+    return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+// Applies a single hunk starting at `cursor` (0-based index into the original lines). Returns the
+// produced output lines, the count of original lines consumed, and a conflict reason on mismatch.
+function applyHunk(original, hunk, cursor) {
+    const out = [];
+    let pos = cursor;
+    for (const raw of hunk.lines) {
+        const marker = raw.charAt(0);
+        const text = raw.slice(1);
+        if (marker === "+") {
+            out.push(text);
+            continue;
+        }
+        // context (" ") and removal ("-") must both match the current line at pos.
+        if (original[pos] !== text) {
+            return {
+                outLines: [],
+                consumed: 0,
+                conflict: `context mismatch at original line ${String(pos + 1)}`,
+            };
+        }
+        if (marker === " ") {
+            out.push(text);
+        }
+        pos += 1;
+    }
+    return { outLines: out, consumed: pos - cursor, conflict: undefined };
+}
+// Applies all hunks of a modify in order. Hunks are anchored by their stated oldStart (1-based);
+// lines between hunks are copied verbatim. Returns the new content or the collected conflicts.
+function applyModify(original, hunks) {
+    const out = [];
+    const conflicts = [];
+    let cursor = 0;
+    hunks.forEach((hunk, index) => {
+        const anchor = Math.max(hunk.oldStart - 1, 0);
+        if (anchor < cursor) {
+            conflicts.push({ hunkIndex: index, reason: "overlapping or out-of-order hunk" });
+            return;
+        }
+        // Copy verbatim the unchanged lines between the previous cursor and this hunk's anchor.
+        out.push(...original.slice(cursor, Math.min(anchor, original.length)));
+        cursor = anchor;
+        const result = applyHunk(original, hunk, cursor);
+        if (result.conflict !== undefined) {
+            conflicts.push({ hunkIndex: index, reason: result.conflict });
+            return;
+        }
+        out.push(...result.outLines);
+        cursor += result.consumed;
+    });
+    // Copy any remaining original lines after the last applied hunk.
+    out.push(...original.slice(cursor));
+    return conflicts.length > 0
+        ? { content: null, conflicts }
+        : { content: joinLines(out), conflicts: [] };
+}
+// Verifies a delete's pre-image against the current content (C2). A delete hunk lists the lines to
+// remove (`-`) and surrounding context (` `); their concatenation must equal the current file, or
+// the diff is stale/fabricated and we MUST NOT delete a mismatched file. A hunk-free delete (no
+// pre-image to check) is accepted as-is. `+` lines are not expected in a delete and are ignored.
+function verifyDeletePreImage(change, current) {
+    const preImage = [];
+    for (const hunk of change.hunks) {
+        for (const raw of hunk.lines) {
+            const marker = raw.charAt(0);
+            if (marker === " " || marker === "-") {
+                preImage.push(raw.slice(1));
+            }
+        }
+    }
+    if (preImage.length === 0) {
+        return { content: null, conflicts: [] };
+    }
+    const matches = joinLines(preImage) === current || preImage.join("\n") === current;
+    return matches
+        ? { content: null, conflicts: [] }
+        : {
+            content: null,
+            conflicts: [{ hunkIndex: 0, reason: "delete pre-image does not match current content" }],
+        };
+}
+// Computes the post-image for one file change against its current content (undefined = absent).
+export function computeFileContent(change, current) {
+    if (change.kind === "create") {
+        if (current !== undefined) {
+            return {
+                content: null,
+                conflicts: [{ hunkIndex: 0, reason: "create target already exists" }],
+            };
+        }
+        const added = change.hunks.flatMap((h) => h.lines.filter((l) => l.startsWith("+")).map((l) => l.slice(1)));
+        return { content: joinLines(added), conflicts: [] };
+    }
+    if (change.kind === "delete") {
+        if (current === undefined) {
+            return {
+                content: null,
+                conflicts: [{ hunkIndex: 0, reason: "delete target does not exist" }],
+            };
+        }
+        return verifyDeletePreImage(change, current);
+    }
+    if (current === undefined) {
+        return { content: null, conflicts: [{ hunkIndex: 0, reason: "modify target does not exist" }] };
+    }
+    return applyModify(toLines(current), change.hunks);
+}

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

@@ -0,0 +1 @@
+export declare function normalizeUnifiedDiffHunks(diff: string): string;

package/dist/tools/patch-normalize.js

@@ -0,0 +1,80 @@
+// Best-effort normalization for common LLM unified-diff shorthand. This module rewrites hunk headers
+// from the hunk body markers (" ", "+", "-") and repairs blank context lines that models often emit
+// as an empty line instead of a single-space diff line. It does not invent paths; the normal
+// validate/apply path still performs path containment, deny-list checks, and conflict checks.
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@(.*)$/;
+function isBodyLine(line) {
+    const marker = line.charAt(0);
+    return marker === " " || marker === "+" || marker === "-";
+}
+function isFileHeaderPair(lines, index) {
+    return (lines[index]?.startsWith("--- ") === true &&
+        lines[index + 1]?.startsWith("+++ ") === true);
+}
+function hunkEnd(lines, start) {
+    let index = start;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        if (line.startsWith("@@") || isFileHeaderPair(lines, index)) {
+            break;
+        }
+        index += 1;
+    }
+    return index;
+}
+function countOldLines(lines) {
+    return lines.filter((line) => line.startsWith(" ") || line.startsWith("-")).length;
+}
+function countNewLines(lines) {
+    return lines.filter((line) => line.startsWith(" ") || line.startsWith("+")).length;
+}
+function parseStarts(line) {
+    const match = HUNK_HEADER.exec(line);
+    if (match === null) {
+        return line.trim() === "@@" ? { oldStart: 0, newStart: 1, suffix: "" } : undefined;
+    }
+    return {
+        oldStart: Number(match[1]),
+        newStart: Number(match[2]),
+        suffix: match[3] ?? "",
+    };
+}
+function formatRange(start, count) {
+    return `${String(start)},${String(count)}`;
+}
+function normalizeHunkHeader(header, body) {
+    const starts = parseStarts(header);
+    if (starts === undefined) {
+        return header;
+    }
+    const { oldStart, newStart, suffix } = starts;
+    return `@@ -${formatRange(oldStart, countOldLines(body))} +${formatRange(newStart, countNewLines(body))} @@${suffix}`;
+}
+function hasBodyLineBefore(lines, index) {
+    return lines.slice(0, index).some(isBodyLine);
+}
+function hasBodyLineAfter(lines, index) {
+    return lines.slice(index + 1).some(isBodyLine);
+}
+function normalizeBlankContextLines(lines) {
+    return lines.map((line, index) => line === "" && hasBodyLineBefore(lines, index) && hasBodyLineAfter(lines, index) ? " " : line);
+}
+export function normalizeUnifiedDiffHunks(diff) {
+    const lines = diff.split("\n");
+    const out = [];
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        if (!line.startsWith("@@")) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const end = hunkEnd(lines, index + 1);
+        const normalizedLines = normalizeBlankContextLines(lines.slice(index + 1, end));
+        const body = normalizedLines.filter(isBodyLine);
+        out.push(normalizeHunkHeader(line, body), ...normalizedLines);
+        index = end;
+    }
+    return out.join("\n");
+}

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

@@ -0,0 +1,8 @@
+import type { PatchFileChange } from "./types.js";
+export interface ParsedPatch {
+    readonly files: readonly PatchFileChange[];
+}
+export declare class PatchParseError extends Error {
+    constructor(message: string);
+}
+export declare function parseUnifiedDiff(diff: string): ParsedPatch;

package/dist/tools/patch-parse.js

@@ -0,0 +1,201 @@
+// PURE, ReDoS-free unified-diff parser. Supported subset (documented in ADR-0006):
+//   - file headers `--- a/<path>` / `+++ b/<path>`, with `/dev/null` for create/delete;
+//   - hunk headers `@@ -l,s +l,s @@` (the count `,s` defaults to 1 when omitted);
+//   - body lines beginning with " " (context), "+" (add), "-" (remove), and "\" (no-newline).
+// This is NOT git-apply: no rename detection, no binary patches, no fuzzy matching. The parser
+// is linear (a single pass with bounded per-line regexes) so it cannot backtrack catastrophically.
+// Bounded, anchored hunk-header regex. Each numeric group is `\d+` (linear, no nesting).
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+export class PatchParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PatchParseError";
+    }
+}
+function stripPrefix(raw) {
+    if (raw === "/dev/null") {
+        return raw;
+    }
+    // Drop a leading `a/` or `b/` git prefix; otherwise keep the path verbatim.
+    if (raw.startsWith("a/") || raw.startsWith("b/")) {
+        return raw.slice(2);
+    }
+    return raw;
+}
+// The header path may carry a trailing tab + timestamp (`path\t2024-…`); keep only the path.
+function headerPath(line, marker) {
+    const rest = line.slice(marker.length);
+    const tab = rest.indexOf("\t");
+    const raw = tab === -1 ? rest : rest.slice(0, tab);
+    return stripPrefix(raw.trim());
+}
+function classify(oldPath, newPath) {
+    if (oldPath === "/dev/null") {
+        return { kind: "create", path: newPath };
+    }
+    if (newPath === "/dev/null") {
+        return { kind: "delete", path: oldPath };
+    }
+    return { kind: "modify", path: newPath };
+}
+function toHunk(acc) {
+    return {
+        oldStart: acc.oldStart,
+        oldLines: acc.oldLines,
+        newStart: acc.newStart,
+        newLines: acc.newLines,
+        lines: acc.lines,
+    };
+}
+function parseHunkHeader(line) {
+    const match = HUNK_HEADER.exec(line);
+    if (match === null) {
+        throw new PatchParseError("malformed hunk header");
+    }
+    const oldLines = match[2] === undefined ? 1 : Number(match[2]);
+    const newLines = match[4] === undefined ? 1 : Number(match[4]);
+    return {
+        oldStart: Number(match[1]),
+        oldLines,
+        newStart: Number(match[3]),
+        newLines,
+        lines: [],
+        oldRemaining: oldLines,
+        newRemaining: newLines,
+    };
+}
+function newFileAccumulator() {
+    return {
+        oldPath: undefined,
+        newPath: undefined,
+        hunks: [],
+        current: undefined,
+        added: 0,
+        removed: 0,
+    };
+}
+function finishHunk(file) {
+    if (file.current !== undefined) {
+        if (file.current.oldRemaining !== 0 || file.current.newRemaining !== 0) {
+            throw new PatchParseError("hunk body has fewer lines than declared");
+        }
+        file.hunks.push(toHunk(file.current));
+        file.current = undefined;
+    }
+}
+function finishFile(files, file) {
+    finishHunk(file);
+    if (file.oldPath === undefined || file.newPath === undefined) {
+        return;
+    }
+    const { kind, path } = classify(file.oldPath, file.newPath);
+    files.push({
+        path,
+        kind,
+        hunks: file.hunks,
+        addedLines: file.added,
+        removedLines: file.removed,
+    });
+}
+function countBody(file, line) {
+    if (line.startsWith("+")) {
+        file.added += 1;
+    }
+    else if (line.startsWith("-")) {
+        file.removed += 1;
+    }
+}
+function startNewFile(state, oldPath) {
+    if (state.current !== undefined) {
+        finishFile(state.files, state.current);
+    }
+    const file = newFileAccumulator();
+    file.oldPath = oldPath;
+    state.current = file;
+    return file;
+}
+function isHunkBodyLine(line) {
+    const marker = line.charAt(0);
+    return marker === " " || marker === "+" || marker === "-";
+}
+// A hunk is still consuming body lines while either the old or the new line budget is positive.
+function hunkActive(file) {
+    const hunk = file.current;
+    return hunk !== undefined && (hunk.oldRemaining > 0 || hunk.newRemaining > 0);
+}
+// Draws down the hunk's old/new line budget for a body line (context draws both, `-` old, `+` new).
+function assertBudgetAvailable(hunk, line) {
+    const marker = line.charAt(0);
+    const oldNeeded = marker === " " || marker === "-" ? 1 : 0;
+    const newNeeded = marker === " " || marker === "+" ? 1 : 0;
+    if (hunk.oldRemaining < oldNeeded || hunk.newRemaining < newNeeded) {
+        throw new PatchParseError("hunk body has more lines than declared");
+    }
+}
+function consumeBudget(hunk, line) {
+    const marker = line.charAt(0);
+    if (marker === " ") {
+        hunk.oldRemaining -= 1;
+        hunk.newRemaining -= 1;
+    }
+    else if (marker === "-") {
+        hunk.oldRemaining -= 1;
+    }
+    else if (marker === "+") {
+        hunk.newRemaining -= 1;
+    }
+}
+function handleBodyLine(file, line) {
+    if (file.current === undefined) {
+        return; // lines outside a hunk (e.g. `diff --git`, `index …`) are ignored
+    }
+    if (line.startsWith("\\")) {
+        return; // "" marker
+    }
+    // Only genuine body lines (context/add/remove) belong to the hunk. An empty trailing line
+    // (the split artifact of a final newline) or any other token ends the hunk so it is not
+    // mistaken for a zero-length context line that would never match the file content.
+    if (!isHunkBodyLine(line)) {
+        finishHunk(file);
+        return;
+    }
+    assertBudgetAvailable(file.current, line);
+    file.current.lines.push(line);
+    countBody(file, line);
+    consumeBudget(file.current, line);
+}
+function handleLine(state, line) {
+    // While a hunk still has budget, ` `/`+`/`-` lines are BODY even if they render as `--- `/`+++ `
+    // (C6). Only once the hunk is consumed (or absent) can a `--- ` line open a new file.
+    if (state.current !== undefined && hunkActive(state.current) && isHunkBodyLine(line)) {
+        handleBodyLine(state.current, line);
+        return;
+    }
+    if (line.startsWith("--- ")) {
+        startNewFile(state, headerPath(line, "--- "));
+        return;
+    }
+    if (state.current === undefined) {
+        return; // skip preamble before the first file header
+    }
+    if (line.startsWith("+++ ")) {
+        state.current.newPath = headerPath(line, "+++ ");
+        return;
+    }
+    if (line.startsWith("@@")) {
+        finishHunk(state.current);
+        state.current.current = parseHunkHeader(line);
+        return;
+    }
+    handleBodyLine(state.current, line);
+}
+export function parseUnifiedDiff(diff) {
+    const state = { files: [], current: undefined };
+    for (const line of diff.split("\n")) {
+        handleLine(state, line);
+    }
+    if (state.current !== undefined) {
+        finishFile(state.files, state.current);
+    }
+    return { files: state.files };
+}

package/dist/tools/patch.d.ts

@@ -0,0 +1,18 @@
+import { type WorkspaceFs } from "../workspace/fs.js";
+import type { WorkspaceInfo } from "../workspace/types.js";
+import { type WorkspaceWriter } from "./writer.js";
+import { type PatchApplyResult, type PatchLimits, type PatchValidation } from "./types.js";
+export interface ValidateDeps {
+    readonly fs?: WorkspaceFs | undefined;
+    readonly limits?: PatchLimits | undefined;
+}
+export declare function validatePatch(workspace: WorkspaceInfo, diff: string, deps?: ValidateDeps): PatchValidation;
+export declare function renderDryRun(validation: PatchValidation): string;
+export interface ApplyDeps {
+    readonly applyEnabled: boolean;
+    readonly signal: AbortSignal;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly writer?: WorkspaceWriter | undefined;
+    readonly limits?: PatchLimits | undefined;
+}
+export declare function applyPatch(workspace: WorkspaceInfo, diff: string, deps: ApplyDeps): PatchApplyResult;