@oscharko-dev/keiko-workspace 0.2.0

package/dist/discovery.js

@@ -0,0 +1,199 @@
+// Recursive, bounded, deterministic file discovery and a single boundary-checked read path.
+// Security invariants (ADR-0005 D2/D3):
+//   - every directory descent and every read goes through resolveWithinWorkspace first;
+//   - always-on DENY patterns are applied before the optional .gitignore subset;
+//   - a symlink whose realpath escapes the root is skipped (never followed);
+//   - recursion is capped by maxDepth and total results by maxFiles.
+import { relative } from "node:path";
+import { nodeWorkspaceFs, } from "./fs.js";
+import { compileIgnore, isDenied, isIgnored } from "./ignore.js";
+import { resolveWithinWorkspace } from "./paths.js";
+import { containedRealPathInfo } from "./realpath.js";
+import { FileTooLargeError, PathDeniedError, WorkspaceReadError } from "./errors.js";
+import { redact } from "@oscharko-dev/keiko-security";
+import { DEFAULT_READ_OPTIONS, } from "./types.js";
+function toRelative(root, absolutePath) {
+    return relative(root, absolutePath).split("\\").join("/");
+}
+function toRealRelative(fs, root, absolutePath) {
+    try {
+        return toRelative(fs.realPath(root), absolutePath);
+    }
+    catch {
+        return toRelative(root, absolutePath);
+    }
+}
+// A benign-named workspace root that is a SYMLINK into a denied location (e.g. "~/docs" -> "~/.aws")
+// is invisible to the root-relative deny checks: they only see paths BELOW the root, never the denied
+// segment that resolving the root itself introduces. Flag it — but ONLY when the symlink ADDS the
+// denial (the real root is denied while the lexical root is not). A non-symlinked root, a benign
+// platform link (macOS "/tmp" -> "/private/tmp"), and a root that merely sits under a denied-named
+// ANCESTOR the user did not symlink into (e.g. the product's own ".claude" worktree) all keep working,
+// preserving the existing relative-only semantics for every non-attack path.
+function realRootIsDeniedViaSymlink(realRoot, lexicalRoot) {
+    return isDenied(realRoot) && !isDenied(lexicalRoot);
+}
+// Returns false when the entry must be skipped for any security or noise reason, recording
+// which tier rejected it for the discovery stats.
+function isAllowed(walk, relPath, isDir) {
+    if (isDenied(relPath)) {
+        walk.denied += 1;
+        return false;
+    }
+    if (walk.applyGitignore && isIgnored(walk.matcher, relPath, isDir)) {
+        walk.ignored += 1;
+        return false;
+    }
+    return true;
+}
+function childRelative(root, absoluteDir, name) {
+    const dirRel = toRelative(root, absoluteDir);
+    return dirRel === "" ? name : `${dirRel}/${name}`;
+}
+function readDirSafe(walk, absoluteDir) {
+    try {
+        return walk.fs.readDir(absoluteDir);
+    }
+    catch {
+        return [];
+    }
+}
+function statSize(walk, absolutePath) {
+    try {
+        return walk.fs.stat(absolutePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function handleEntry(walk, absoluteDir, entry, depth) {
+    const childAbs = resolveWithinWorkspace(walk.root, childRelative(walk.root, absoluteDir, entry.name));
+    const relPath = toRelative(walk.root, childAbs);
+    if (!isAllowed(walk, relPath, entry.isDirectory)) {
+        return;
+    }
+    // Symlinks are skipped unconditionally (for safety/simplicity). A non-symlink entry that
+    // reports neither isFile nor isDirectory is likewise treated as non-traversable noise.
+    // Only genuine files and directories are walked.
+    if (entry.isSymbolicLink) {
+        return;
+    }
+    if (entry.isDirectory) {
+        descend(walk, childAbs, depth + 1);
+        return;
+    }
+    if (entry.isFile) {
+        walk.out.push({ relativePath: relPath, sizeBytes: statSize(walk, childAbs) });
+    }
+}
+function descend(walk, absoluteDir, depth) {
+    if (depth > walk.opts.maxDepth || walk.out.length >= walk.opts.maxFiles) {
+        return;
+    }
+    const entries = [...readDirSafe(walk, absoluteDir)].sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        if (walk.out.length >= walk.opts.maxFiles) {
+            return;
+        }
+        handleEntry(walk, absoluteDir, entry, depth);
+    }
+}
+function runWalk(workspace, opts, fs) {
+    const walk = {
+        fs,
+        root: workspace.root,
+        matcher: compileIgnore(workspace.ignoreLines),
+        opts,
+        applyGitignore: opts.applyGitignore,
+        out: [],
+        denied: 0,
+        ignored: 0,
+    };
+    // Refuse to walk a benign-named root that resolves into a denied location via a symlink: discovery
+    // does not realpath-contain the ROOT, so it would otherwise list a symlinked credential dir's files.
+    // Treated as denied (no throw — discovery filters rather than raises), consistent with per-entry deny.
+    let realRoot;
+    try {
+        realRoot = fs.realPath(workspace.root);
+    }
+    catch {
+        realRoot = workspace.root;
+    }
+    if (realRootIsDeniedViaSymlink(realRoot, workspace.root)) {
+        walk.denied += 1;
+        return walk;
+    }
+    descend(walk, resolveWithinWorkspace(workspace.root, "."), 0);
+    return walk;
+}
+export function discoverFiles(workspace, opts, fs = nodeWorkspaceFs) {
+    return runWalk(workspace, opts, fs).out;
+}
+export function discoverWithStats(workspace, opts, fs = nodeWorkspaceFs) {
+    const walk = runWalk(workspace, opts, fs);
+    return {
+        files: walk.out,
+        stats: { discovered: walk.out.length, denied: walk.denied, ignored: walk.ignored },
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : "unknown error";
+}
+function statFile(fs, absolutePath, relPath) {
+    try {
+        return fs.stat(absolutePath);
+    }
+    catch (error) {
+        throw new WorkspaceReadError(`cannot stat file: ${relPath} (${describe(error)})`, relPath);
+    }
+}
+function assertNoHardLinkAlias(stats, relPath) {
+    if (stats.hardLinkCount !== undefined && stats.hardLinkCount > 1) {
+        throw new PathDeniedError(`refusing to read a hard-linked workspace alias: ${relPath}`, relPath);
+    }
+}
+function readContent(fs, absolutePath, relPath, opts) {
+    let raw;
+    try {
+        raw = fs.readFileUtf8(absolutePath);
+    }
+    catch (error) {
+        throw new WorkspaceReadError(`cannot read file: ${relPath} (${describe(error)})`, relPath);
+    }
+    const rawBytes = Buffer.byteLength(raw, "utf8");
+    const truncated = rawBytes > opts.maxBytes;
+    const text = truncated
+        ? Buffer.from(raw, "utf8").subarray(0, opts.maxBytes).toString("utf8")
+        : raw;
+    return { relativePath: relPath, sizeBytes: rawBytes, text: redact(text), truncated };
+}
+// The single read path. Order: boundary -> deny -> realpath containment -> size cap -> read -> redact.
+// Realpath containment is shared with the write/cwd paths via assertContainedRealPath: when the
+// path does not exist, it validates the nearest existing parent and returns absolutePath, so a
+// missing in-root file still surfaces as a WorkspaceReadError (not a false PathEscapeError).
+export function readWorkspaceFile(workspace, relPath, opts = DEFAULT_READ_OPTIONS, fs = nodeWorkspaceFs) {
+    const absolutePath = resolveWithinWorkspace(workspace.root, relPath);
+    const normalizedRel = toRelative(workspace.root, absolutePath);
+    if (isDenied(normalizedRel)) {
+        throw new PathDeniedError(`refusing to read a denied path: ${normalizedRel}`, normalizedRel);
+    }
+    const contained = containedRealPathInfo(fs, workspace.root, absolutePath);
+    // Deny a benign-named root symlink that resolves into a protected location (e.g. "~/docs" ->
+    // "~/.aws"): the deny checks here only see the path relative to the realpath'd root, so a denied
+    // segment in the ROOT itself is invisible to them and the file would read through. Only the symlink
+    // case is added — see realRootIsDeniedViaSymlink — so existing non-symlink reads are unchanged.
+    if (realRootIsDeniedViaSymlink(contained.realBase, workspace.root)) {
+        throw new PathDeniedError(`refusing to read a denied path: ${normalizedRel}`, normalizedRel);
+    }
+    const resolvedPath = contained.path;
+    const resolvedRel = toRealRelative(fs, workspace.root, resolvedPath);
+    if (isDenied(resolvedRel)) {
+        throw new PathDeniedError(`refusing to read a denied path: ${normalizedRel}`, normalizedRel);
+    }
+    const stats = statFile(fs, resolvedPath, normalizedRel);
+    assertNoHardLinkAlias(stats, normalizedRel);
+    if (stats.size > opts.maxBytes) {
+        throw new FileTooLargeError(`file exceeds the read cap: ${normalizedRel}`, normalizedRel, stats.size, opts.maxBytes);
+    }
+    return readContent(fs, resolvedPath, normalizedRel, opts);
+}

package/dist/document-extraction.d.ts

@@ -0,0 +1,44 @@
+import type { WorkspaceFs } from "./fs.js";
+export declare const MAX_EXTRACTED_BYTES = 65536;
+export declare const MAX_TOTAL_EXTRACTED_BYTES = 262144;
+export declare const SUPPORTED_MIME_PREFIXES: readonly string[];
+export declare const SUPPORTED_MIME_LITERALS: ReadonlySet<string>;
+export type DocumentExtractionFailure = {
+    readonly kind: "binary-file";
+    readonly mimeHint?: string | undefined;
+} | {
+    readonly kind: "unsupported-type";
+    readonly mimeHint?: string | undefined;
+} | {
+    readonly kind: "denied-path";
+} | {
+    readonly kind: "not-found";
+} | {
+    readonly kind: "unreadable";
+} | {
+    readonly kind: "empty";
+};
+export interface ExtractedDocumentContext {
+    readonly id: string;
+    readonly displayName: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+    readonly extractedBytes: number;
+    readonly truncated: boolean;
+    readonly truncationMarker: string | undefined;
+    readonly text: string;
+}
+export interface DocumentExtractionBudget {
+    readonly perDocBytes: number;
+    readonly totalBudgetUsedBytes: number;
+    readonly totalBudgetBytes: number;
+}
+export type DocumentExtractionResult = {
+    readonly ok: true;
+    readonly context: ExtractedDocumentContext;
+} | {
+    readonly ok: false;
+    readonly failure: DocumentExtractionFailure;
+};
+export declare function extractDocumentContext(fs: WorkspaceFs, workspaceRoot: string, relativePath: string, budget: DocumentExtractionBudget): Promise<DocumentExtractionResult>;
+//# sourceMappingURL=document-extraction.d.ts.map

package/dist/document-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extraction.d.ts","sourceRoot":"","sources":["../src/document-extraction.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAK3C,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAc,CAAC;AAEpE,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAOtD,CAAC;AA8CH,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAwSxE,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,WAAW,EACf,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAMnC"}

package/dist/document-extraction.js

@@ -0,0 +1,372 @@
+// Issue #148 — Safe document context extraction for conversation inputs (Epic #142).
+//
+// This module turns a workspace-relative file path into a bounded, redacted text excerpt that
+// the BFF and the model gateway can safely concatenate into a prompt. The extractor is text-only
+// by deliberate design: PDF, Word, and other binary document parsing is OUT OF SCOPE for this
+// issue because it would require a new parser dependency, a much larger trust surface (CVE-risk
+// in parsing libraries), and an OCR strategy that #148 does not own.
+//
+// Byte-budget rationale (matches the per-payload aggregate budget on the server side):
+//   - Per-document cap of 64 KiB (MAX_EXTRACTED_BYTES) is large enough to carry a typical
+//     README/spec/JSON config in full and small enough that 4 attached files at the per-payload
+//     aggregate cap of 256 KiB (MAX_TOTAL_EXTRACTED_BYTES) still fits inside the gateway's
+//     128 K-character body cap (MAX_BODY_BYTES) with room for the user draft and JSON framing.
+//   - Truncation is REPORTED to the caller (`truncated: true` + human-readable marker) so the
+//     UI can render a badge and the prompt composer can append a fixed marker after the text.
+//
+// Path-safe error contract (AC #2):
+//   - The failure tagged-union carries a `kind` ONLY. No `path` field; no message field that
+//     embeds the resolved or relative path. This keeps absolute filesystem paths off the wire
+//     for both reportable failures and unreportable ones (binary/empty/etc.).
+//   - All four boundary errors (denied-path / not-found / unreadable / binary-file) are derived
+//     from the existing workspace primitives (`resolveWithinWorkspace`,
+//     `assertContainedRealPath`, `looksBinary`) so this module owns no new path-validation logic.
+import { basename, extname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { redact } from "@oscharko-dev/keiko-security";
+import { looksBinary } from "./binaryDetect.js";
+import { PathEscapeError, PathDeniedError } from "./errors.js";
+import { resolveWithinWorkspace } from "./paths.js";
+import { assertContainedRealPath } from "./realpath.js";
+import { isDenied } from "./ignore.js";
+export const MAX_EXTRACTED_BYTES = 65_536; // per-document budget (64 KiB)
+export const MAX_TOTAL_EXTRACTED_BYTES = 262_144; // per-payload aggregate budget (256 KiB)
+export const SUPPORTED_MIME_PREFIXES = ["text/"];
+export const SUPPORTED_MIME_LITERALS = new Set([
+    "application/json",
+    "application/x-yaml",
+    "application/yaml",
+    "application/xml",
+    "application/javascript",
+    "application/typescript",
+]);
+// File-extension → MIME map. Only text-like / structured-text formats are recognised. Anything
+// outside this map falls into `unsupported-type` (e.g. `.exe`, `.pdf`, `.docx`, `.png`).
+const EXTENSION_MIME = new Map([
+    [".md", "text/markdown"],
+    [".markdown", "text/markdown"],
+    [".txt", "text/plain"],
+    [".log", "text/plain"],
+    [".json", "application/json"],
+    [".yaml", "application/yaml"],
+    [".yml", "application/yaml"],
+    [".xml", "application/xml"],
+    [".html", "text/html"],
+    [".htm", "text/html"],
+    [".css", "text/css"],
+    [".js", "application/javascript"],
+    [".jsx", "application/javascript"],
+    [".mjs", "application/javascript"],
+    [".cjs", "application/javascript"],
+    [".ts", "application/typescript"],
+    [".tsx", "application/typescript"],
+    [".py", "text/x-python"],
+    [".rb", "text/x-ruby"],
+    [".go", "text/x-go"],
+    [".rs", "text/x-rust"],
+    [".java", "text/x-java"],
+    [".kt", "text/x-kotlin"],
+    [".cpp", "text/x-c++src"],
+    [".cc", "text/x-c++src"],
+    [".cxx", "text/x-c++src"],
+    [".c", "text/x-csrc"],
+    [".h", "text/x-chdr"],
+    [".hpp", "text/x-c++hdr"],
+    [".sh", "text/x-shellscript"],
+    [".bash", "text/x-shellscript"],
+    [".zsh", "text/x-shellscript"],
+    [".toml", "application/toml"],
+    [".ini", "text/plain"],
+    [".csv", "text/csv"],
+    [".tsv", "text/tab-separated-values"],
+    [".sql", "application/sql"],
+]);
+const BINARY_PROBE_BYTES = 512;
+function classifyByExtension(relativePath) {
+    const ext = extname(relativePath).toLowerCase();
+    if (ext.length === 0) {
+        return undefined;
+    }
+    return EXTENSION_MIME.get(ext);
+}
+function isSupportedMime(mimeType) {
+    if (SUPPORTED_MIME_PREFIXES.some((prefix) => mimeType.startsWith(prefix))) {
+        return true;
+    }
+    return SUPPORTED_MIME_LITERALS.has(mimeType);
+}
+function denied() {
+    return { ok: false, failure: { kind: "denied-path" } };
+}
+function notFound() {
+    return { ok: false, failure: { kind: "not-found" } };
+}
+function unreadable() {
+    return { ok: false, failure: { kind: "unreadable" } };
+}
+function empty() {
+    return { ok: false, failure: { kind: "empty" } };
+}
+function binary(mimeHint) {
+    if (mimeHint === undefined) {
+        return { ok: false, failure: { kind: "binary-file" } };
+    }
+    return { ok: false, failure: { kind: "binary-file", mimeHint } };
+}
+function unsupported(mimeHint) {
+    if (mimeHint === undefined) {
+        return { ok: false, failure: { kind: "unsupported-type" } };
+    }
+    return { ok: false, failure: { kind: "unsupported-type", mimeHint } };
+}
+function isStepOk(value) {
+    return "step" in value;
+}
+function resolveSafePath(fs, workspaceRoot, relativePath) {
+    let absolutePath;
+    try {
+        absolutePath = resolveWithinWorkspace(workspaceRoot, relativePath);
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            return denied();
+        }
+        throw error;
+    }
+    const normalizedRel = absolutePath.slice(workspaceRoot.length).replace(/^[/\\]/, "");
+    if (isDenied(normalizedRel)) {
+        return denied();
+    }
+    let resolved;
+    try {
+        resolved = assertContainedRealPath(fs, workspaceRoot, absolutePath, normalizedRel);
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError || error instanceof PathDeniedError) {
+            return denied();
+        }
+        throw error;
+    }
+    return { step: "ok", resolved };
+}
+function statFile(fs, resolvedPath) {
+    try {
+        const stats = fs.stat(resolvedPath);
+        return { step: "ok", size: stats.size, isFile: stats.isFile };
+    }
+    catch {
+        if (!fs.exists(resolvedPath)) {
+            return notFound();
+        }
+        return unreadable();
+    }
+}
+function effectivePerDocBudget(budget) {
+    const remainingTotal = Math.max(0, budget.totalBudgetBytes - budget.totalBudgetUsedBytes);
+    return Math.min(budget.perDocBytes, remainingTotal);
+}
+async function probeBinary(fs, resolvedPath, size) {
+    if (fs.readFileBytes === undefined) {
+        // Synchronous read fallback for FS adapters without the byte-level port. We only need a
+        // small slice for the binary probe; reading utf-8-as-string and re-encoding is acceptable
+        // here because EVERY adapter ships readFileUtf8 (it's a required port member).
+        let utf8;
+        try {
+            utf8 = fs.readFileUtf8(resolvedPath);
+        }
+        catch {
+            return unreadable();
+        }
+        const encoded = new TextEncoder().encode(utf8);
+        return {
+            step: "ok",
+            bytes: encoded.subarray(0, Math.min(BINARY_PROBE_BYTES, encoded.length)),
+        };
+    }
+    try {
+        const bytes = await fs.readFileBytes(resolvedPath, Math.min(BINARY_PROBE_BYTES, size));
+        return { step: "ok", bytes };
+    }
+    catch {
+        return unreadable();
+    }
+}
+async function readBudgetedBytes(fs, resolvedPath, cap) {
+    if (cap === 0) {
+        return { step: "ok", bytes: new Uint8Array(0) };
+    }
+    if (fs.readFileBytes !== undefined) {
+        try {
+            const bytes = await fs.readFileBytes(resolvedPath, cap);
+            return { step: "ok", bytes };
+        }
+        catch {
+            return unreadable();
+        }
+    }
+    let utf8;
+    try {
+        utf8 = fs.readFileUtf8(resolvedPath);
+    }
+    catch {
+        return unreadable();
+    }
+    const encoded = new TextEncoder().encode(utf8);
+    return { step: "ok", bytes: encoded.subarray(0, Math.min(cap, encoded.length)) };
+}
+function buildTruncationMarker(extractedBytes, originalBytes) {
+    return `[…truncated to first ${String(extractedBytes)} of ${String(originalBytes)} bytes]`;
+}
+// Returns the expected byte-length of the UTF-8 sequence starting with `lead`, or 0 when
+// the byte is not a valid UTF-8 leading byte.
+function utf8LeadByteSeqLen(lead) {
+    if ((lead & 0x80) === 0x00)
+        return 1; // ASCII
+    if ((lead & 0xe0) === 0xc0)
+        return 2;
+    if ((lead & 0xf0) === 0xe0)
+        return 3;
+    if ((lead & 0xf8) === 0xf0)
+        return 4;
+    return 0; // continuation byte or invalid — not a lead byte
+}
+// Returns the length of the valid UTF-8 prefix of `bytes`, backing off any incomplete
+// multibyte sequence at the tail. A full file that is valid UTF-8 will have its entire
+// length returned unchanged; a capped slice that was cut mid-codepoint will have at most
+// 3 bytes trimmed (the maximum tail of an incomplete 4-byte sequence).
+//
+// Algorithm: scan backward from the end for the first byte that is NOT a UTF-8 continuation
+// byte (0x80–0xBF). That byte is the start of the last (possibly incomplete) sequence.
+// If the sequence is incomplete, exclude it; otherwise keep the full slice.
+function validUtf8PrefixLength(bytes) {
+    const len = bytes.length;
+    if (len === 0)
+        return 0;
+    // Walk back over continuation bytes (0x80–0xBF), up to 3.
+    let i = len - 1;
+    const limit = Math.max(len - 4, -1);
+    while (i > limit && ((bytes[i] ?? 0) & 0xc0) === 0x80) {
+        i -= 1;
+    }
+    const seqLen = utf8LeadByteSeqLen(bytes[i] ?? 0);
+    if (seqLen === 0)
+        return i; // not a lead byte — exclude it
+    // If the sequence started at i extends past the slice end, exclude it.
+    return i + seqLen <= len ? len : i;
+}
+function decodeUtf8(bytes) {
+    // fatal: true makes the decoder throw on invalid UTF-8 byte sequences. This is the
+    // second binary-classification gate after the NUL-byte probe — a file that survives the
+    // probe but is still not valid UTF-8 is treated as binary, not silently decoded with
+    // replacement characters.
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        return { step: "ok", text: decoder.decode(bytes) };
+    }
+    catch {
+        return binary();
+    }
+}
+function trimTrailingWhitespace(value) {
+    return value.replace(/\s+$/u, "");
+}
+async function classifyFileMime(fs, file, relativePath) {
+    const probe = await probeBinary(fs, file.resolvedPath, file.size);
+    if (!isStepOk(probe)) {
+        return probe;
+    }
+    if (looksBinary(probe.bytes)) {
+        return binary(classifyByExtension(relativePath));
+    }
+    const mimeType = classifyByExtension(relativePath);
+    if (mimeType === undefined || !isSupportedMime(mimeType)) {
+        return unsupported(mimeType);
+    }
+    return { step: "ok", mimeType };
+}
+async function readAndCap(fs, file, budget) {
+    const cap = effectivePerDocBudget(budget);
+    const read = await readBudgetedBytes(fs, file.resolvedPath, cap);
+    if (!isStepOk(read)) {
+        return read;
+    }
+    // When the byte slice was capped below the file size a multibyte codepoint may straddle
+    // the boundary. Back the slice to the last complete UTF-8 codepoint so the fatal decoder
+    // does not mistake a clean text file for binary. A file that is genuinely NOT at a
+    // codepoint boundary due to truncation will have at most 3 bytes trimmed.
+    const isCapped = read.bytes.length < file.size;
+    const bytes = isCapped ? read.bytes.subarray(0, validUtf8PrefixLength(read.bytes)) : read.bytes;
+    const decoded = decodeUtf8(bytes);
+    if (!isStepOk(decoded)) {
+        return decoded;
+    }
+    const text = trimTrailingWhitespace(decoded.text);
+    // Report the number of bytes actually read from disk (before the codepoint trim) so the
+    // truncation marker quotes an honest byte count rather than the post-trim length.
+    const extractedBytes = read.bytes.length;
+    const truncated = extractedBytes < file.size;
+    return { step: "ok", value: { text, extractedBytes, truncated } };
+}
+function buildContext(relativePath, mimeType, file, capped) {
+    const marker = capped.truncated
+        ? buildTruncationMarker(capped.extractedBytes, file.size)
+        : undefined;
+    return {
+        id: randomUUID(),
+        displayName: basename(relativePath),
+        mimeType,
+        sizeBytes: file.size,
+        extractedBytes: capped.extractedBytes,
+        truncated: capped.truncated,
+        truncationMarker: marker,
+        text: redact(capped.text),
+    };
+}
+// Public entry: extracts text from a workspace-relative path. All error paths produce a path-
+// safe DocumentExtractionFailure tagged-union (no path strings in the failure object).
+export async function extractDocumentContext(fs, workspaceRoot, relativePath, budget) {
+    const safe = resolveSafePath(fs, workspaceRoot, relativePath);
+    if (isStepOk(safe)) {
+        return extractFromResolvedPath(fs, relativePath, safe.resolved, budget);
+    }
+    return safe;
+}
+async function extractFromResolvedPath(fs, relativePath, resolvedPath, budget) {
+    const stat = statFile(fs, resolvedPath);
+    if (!isStepOk(stat)) {
+        return stat;
+    }
+    if (!stat.isFile) {
+        return notFound();
+    }
+    if (stat.size === 0) {
+        return empty();
+    }
+    const file = { resolvedPath, size: stat.size };
+    const mimeResult = await classifyFileMime(fs, file, relativePath);
+    if (!isStepOk(mimeResult)) {
+        return mimeResult;
+    }
+    const capped = await readAndCap(fs, file, budget);
+    if (!isStepOk(capped)) {
+        return capped;
+    }
+    if (capped.value.extractedBytes === 0) {
+        // Budget exhausted at entry: surface as a truncated zero-byte excerpt so the caller can
+        // still render a chip + truncation badge. AC #3 — UI shows the doc contributed nothing.
+        return {
+            ok: true,
+            context: {
+                id: randomUUID(),
+                displayName: basename(relativePath),
+                mimeType: mimeResult.mimeType,
+                sizeBytes: file.size,
+                extractedBytes: 0,
+                truncated: true,
+                truncationMarker: buildTruncationMarker(0, file.size),
+                text: "",
+            },
+        };
+    }
+    return { ok: true, context: buildContext(relativePath, mimeResult.mimeType, file, capped.value) };
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export { WORKSPACE_CODES, WorkspaceError, PathEscapeError, PathDeniedError, WorkspaceNotFoundError, FileTooLargeError, WorkspaceReadError, RepoSearchInvalidQueryError, RepoSearchInvalidRangeError, RepoSearchUnsupportedFileError, } from "@oscharko-dev/keiko-security/errors/workspace";
+export type { WorkspaceCode } from "@oscharko-dev/keiko-security/errors/workspace";
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC"}

package/dist/errors.js

@@ -0,0 +1,4 @@
+// Re-export shim: the workspace error taxonomy now lives in @oscharko-dev/keiko-security
+// (issue #159, ADR-0019). All existing import sites (`from "./errors.js"`) keep resolving
+// unchanged via this barrel.
+export { WORKSPACE_CODES, WorkspaceError, PathEscapeError, PathDeniedError, WorkspaceNotFoundError, FileTooLargeError, WorkspaceReadError, RepoSearchInvalidQueryError, RepoSearchInvalidRangeError, RepoSearchUnsupportedFileError, } from "@oscharko-dev/keiko-security/errors/workspace";

package/dist/fs.d.ts

@@ -0,0 +1,25 @@
+export interface WorkspaceStat {
+    readonly size: number;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+    readonly hardLinkCount?: number | undefined;
+    readonly mtimeMs?: number | undefined;
+}
+export interface WorkspaceDirEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    readonly isSymbolicLink: boolean;
+}
+export interface WorkspaceFs {
+    readonly readFileUtf8: (absolutePath: string) => string;
+    readonly stat: (absolutePath: string) => WorkspaceStat;
+    readonly readDir: (absolutePath: string) => readonly WorkspaceDirEntry[];
+    readonly realPath: (absolutePath: string) => string;
+    readonly exists: (absolutePath: string) => boolean;
+    readonly readFileBytes?: (absolutePath: string, maxBytes: number) => Promise<Uint8Array>;
+    readonly readFileRange?: (absolutePath: string, startByte: number, length: number) => Promise<Uint8Array>;
+}
+export declare const nodeWorkspaceFs: WorkspaceFs;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,aAAa,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,iBAAiB,EAAE,CAAC;IACzE,QAAQ,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;IAInD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAGzF,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1B;AAMD,eAAO,MAAM,eAAe,EAAE,WA6D7B,CAAC"}