@hicaru/pi-rlm 0.2.1 → 0.3.0

package/src/context/namespace.ts

@@ -0,0 +1,180 @@
+/**
+ * Source-id / path-prefix derivation for add_context sources.
+ *
+ * Lifted from the old library-context module with `lib/` → `ctx/`. Fingerprinted source ids
+ * keep two sources that share a basename from colliding.
+ */
+
+import { createHash } from "node:crypto";
+import { basename, isAbsolute, resolve } from "node:path";
+import { estimateTokens } from "../text/tokens.ts";
+import { LEGACY_UNKNOWN_PREFIX, type ContextFile } from "./types.ts";
+
+export interface ContextNamespace {
+  readonly sourceId: string;
+  readonly pathPrefix: string;
+}
+
+/** https://host/… or git@host:… — option-injection safe (never starts with "-"). */
+export const GIT_URL = /^(https:\/\/|git@)[\w.-]+[:/]\S+$/;
+
+/** Short, stable discriminator so two sources never share a namespace. */
+function sourceFingerprint(canonical: string): string {
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+}
+
+/**
+ * Sanitize a path/url basename into a stable, filesystem-safe source id.
+ * `resolvedPath` (absolute path) or the git URL is fingerprinted into the id so
+ * distinct sources sharing a basename get distinct namespaces
+ * (`ctx/utils-3f9a1c02/` vs `ctx/utils-a1b2c3d4/`).
+ */
+export function contextSourceId(source: string, resolvedPath?: string): string {
+  const trimmed = source.trim();
+  const isGit = GIT_URL.test(trimmed);
+  let raw: string;
+  if (isGit) {
+    const m = trimmed.match(/(?:\/|:)([\w.-]+?)(?:\.git)?\/?\s*$/);
+    raw = m?.[1] ?? "repo";
+  } else {
+    raw = basename(resolvedPath ?? trimmed);
+  }
+  const cleaned = raw
+    .replace(/\.git$/i, "")
+    .replace(/[^\w.-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+  const canonical = isGit ? trimmed : (resolvedPath ?? trimmed);
+  return `${cleaned.length > 0 ? cleaned : "ctx"}-${sourceFingerprint(canonical)}`;
+}
+
+export function pathPrefixFor(sourceId: string): string {
+  return `ctx/${sourceId}/`;
+}
+
+/**
+ * Derive the namespace for a source string without packing (host-side idempotency).
+ * Returns both sourceId and pathPrefix so callers never un-parse the prefix.
+ */
+export function contextNamespace(source: string, cwd: string): ContextNamespace {
+  const trimmed = source.trim();
+  const sourceId = GIT_URL.test(trimmed)
+    ? contextSourceId(trimmed)
+    : contextSourceId(trimmed, isAbsolute(trimmed) ? trimmed : resolve(cwd, trimmed));
+  return Object.freeze({ sourceId, pathPrefix: pathPrefixFor(sourceId) });
+}
+
+/** Derive the path prefix for a source string without packing. */
+export function contextPathPrefix(source: string, cwd: string): string {
+  return contextNamespace(source, cwd).pathPrefix;
+}
+
+/**
+ * Apply a path prefix. Empty prefix is identity — the cwd source stays un-prefixed so
+ * search() hits remain real paths that edit/write can act on.
+ */
+export function applyPathPrefix(relPath: string, pathPrefix: string): string {
+  const cleaned = relPath.replace(/^\/+/, "");
+  if (pathPrefix === "") return cleaned;
+  if (cleaned.startsWith(pathPrefix)) return cleaned;
+  return `${pathPrefix}${cleaned}`;
+}
+
+/** Namespaced files plus summed content chars (one pass). */
+export function namespaceContextFilesWithChars(
+  payload: unknown,
+  sourceId: string,
+): { readonly files: readonly ContextFile[]; readonly chars: number } {
+  const prefix = pathPrefixFor(sourceId);
+  if (typeof payload === "string") {
+    return Object.freeze({
+      files: Object.freeze([
+        Object.freeze({
+          path: `${prefix}content`,
+          content: payload,
+          tokens: Math.max(1, estimateTokens(payload.length)),
+        }),
+      ]),
+      chars: payload.length,
+    });
+  }
+  if (!Array.isArray(payload)) return Object.freeze({ files: Object.freeze([]), chars: 0 });
+  const out = new Array<ContextFile>(payload.length);
+  let n = 0;
+  let chars = 0;
+  for (const item of payload) {
+    if (item === null || typeof item !== "object") continue;
+    const rec = item as Record<string, unknown>;
+    const content = typeof rec.content === "string" ? rec.content : String(rec.content ?? "");
+    let path = typeof rec.path === "string" ? rec.path : "unknown";
+    path = applyPathPrefix(path, prefix);
+    const tokens = typeof rec.tokens === "number" && Number.isFinite(rec.tokens)
+      ? Math.max(0, Math.floor(rec.tokens))
+      : Math.max(1, estimateTokens(content.length));
+    out[n++] = Object.freeze({ path, content, tokens });
+    chars += content.length;
+  }
+  out.length = n;
+  return Object.freeze({ files: Object.freeze(out), chars });
+}
+
+/** Namespace file entries under `ctx/<sourceId>/…` (single shared implementation). */
+export function namespaceContextFiles(
+  payload: unknown,
+  sourceId: string,
+): readonly ContextFile[] {
+  return namespaceContextFilesWithChars(payload, sourceId).files;
+}
+
+/** The one `ctx/<id>/` matcher. Never re-declare this regex; use the helpers below. */
+const CTX_PREFIX_RE = /^(ctx\/[^/]+\/)/;
+
+/** Narrow an unknown context entry to a ContextFile. Type guard, never a cast. */
+export function isContextFile(entry: unknown): entry is ContextFile {
+  if (entry === null || typeof entry !== "object") return false;
+  return "path" in entry && typeof entry.path === "string"
+    && "content" in entry && typeof entry.content === "string";
+}
+
+/** `path` of a context entry, or undefined when the entry is not file-shaped. */
+export function contextEntryPath(entry: unknown): string | undefined {
+  return isContextFile(entry) ? entry.path : undefined;
+}
+
+/** The `ctx/<id>/` prefix owning this path, or undefined. Skips the legacy catch-all. */
+function ctxPrefixOf(path: string): string | undefined {
+  const prefix = CTX_PREFIX_RE.exec(path)?.[1];
+  // `ctx/unknown/` is the legacy catch-all: never treat it as an identity.
+  return prefix === undefined || prefix === LEGACY_UNKNOWN_PREFIX ? undefined : prefix;
+}
+
+/** First `ctx/<id>/` prefix found in the payload, or undefined. Skips `ctx/unknown/`. */
+export function payloadPrefix(payload: readonly unknown[]): string | undefined {
+  for (let i = 0; i < payload.length; i++) {
+    const path = contextEntryPath(payload[i]);
+    if (path === undefined) continue;
+    const prefix = ctxPrefixOf(path);
+    if (prefix !== undefined) return prefix;
+  }
+  return undefined;
+}
+
+/**
+ * Every distinct `ctx/<id>/` prefix present in a context payload.
+ *
+ * The loaded-prefix set in bridge/add-context.ts is a CACHE of this — derived state, never
+ * independent state, so it may only be cleared by re-deriving it from the live payload.
+ * Empty-prefix (cwd) sources are intentionally invisible here — the host `loaded` set holds
+ * `""` as its sentinel for those.
+ */
+export function contextPrefixesIn(context: unknown): readonly string[] {
+  if (!Array.isArray(context)) return Object.freeze([]);
+  const seen = new Set<string>();
+  for (let i = 0; i < context.length; i++) {
+    const path = contextEntryPath(context[i]);
+    if (path === undefined) continue;
+    const prefix = ctxPrefixOf(path);
+    if (prefix !== undefined) seen.add(prefix);
+  }
+  return Object.freeze(Array.from(seen));
+}

package/src/context/resolve.ts

@@ -0,0 +1,122 @@
+/**
+ * One router: source string → SourceResult.
+ * git URL → source-git · dir → source-dir · file → document? source-doc : source-text.
+ */
+
+import { basename, isAbsolute, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import type { Result } from "../util/errors.ts";
+import { documentExtFromPath, getAnydoc } from "./anydoc.ts";
+import { GIT_URL, contextSourceId, pathPrefixFor } from "./namespace.ts";
+import { documentToContextFile } from "./source-doc.ts";
+import { sourceDir } from "./source-dir.ts";
+import { sourceGit } from "./source-git.ts";
+import { textToContextFile } from "./source-text.ts";
+import { checkPathSafety, isSensitivePath } from "./walk.ts";
+import {
+  MAX_CONTEXT_FILE_BYTES,
+  type ResolveOpts,
+  type SourceResult,
+} from "./types.ts";
+
+function emptySkipped(): SourceResult["skipped"] {
+  return Object.freeze([]);
+}
+
+function singleFileResult(
+  file: SourceResult["payload"][number],
+  sourceId: string,
+  pathPrefix: string,
+  documents: number,
+  converted: number,
+  skipped: SourceResult["skipped"] = emptySkipped(),
+): SourceResult {
+  return Object.freeze({
+    payload: Object.freeze([file]),
+    files: 1,
+    chars: file.content.length,
+    sourceId,
+    pathPrefix,
+    documents,
+    converted,
+    skipped,
+  });
+}
+
+/**
+ * Resolve a source string (local path or git URL) into a sandbox-ready SourceResult.
+ * `pathPrefix: ""` marks the primary/cwd source (un-prefixed paths).
+ */
+export async function resolveSource(
+  source: string,
+  opts: ResolveOpts,
+): Promise<Result<SourceResult, string>> {
+  const trimmed = source.trim();
+  if (trimmed === "") return { ok: false, error: "add_context: empty source" };
+  if (GIT_URL.test(trimmed)) return await sourceGit(trimmed, opts);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    return { ok: false, error: `unsupported URL scheme (only https:// and git@ are allowed): ${trimmed}` };
+  }
+  const path = isAbsolute(trimmed) ? trimmed : resolve(opts.cwd, trimmed);
+  let s: Awaited<ReturnType<typeof stat>>;
+  try {
+    s = await stat(path);
+  } catch {
+    return { ok: false, error: `add_context: path not found: ${path}` };
+  }
+  const sourceId = contextSourceId(trimmed, path);
+  const pathPrefix = opts.pathPrefix !== undefined ? opts.pathPrefix : pathPrefixFor(sourceId);
+
+  if (s.isDirectory()) {
+    return { ok: true, value: await sourceDir(path, trimmed, { ...opts, pathPrefix }) };
+  }
+
+  // Single-file secret refuse — never pack a .env / key into context for a sub-LLM.
+  const rel = basename(path);
+  if (isSensitivePath(rel) || isSensitivePath(trimmed.replace(/^\.\//, ""))) {
+    return { ok: false, error: `add_context: refused sensitive path: ${path}` };
+  }
+
+  // Symlink safety for single-file: refuse escape of cwd / resolved sensitive targets.
+  const safety = await checkPathSafety(path, opts.cwd);
+  if (!safety.ok) {
+    return {
+      ok: false,
+      error: `add_context: refused ${safety.reason} path: ${path}`,
+    };
+  }
+
+  // Single file — preserve oversize wording (phase-context asserts on limit + llm_query_chunked).
+  if (s.size > MAX_CONTEXT_FILE_BYTES) {
+    return {
+      ok: false,
+      error: `add_context: ${path} is ${s.size.toLocaleString()} bytes `
+        + `(limit ${MAX_CONTEXT_FILE_BYTES.toLocaleString()}) — `
+        + "open() it in the REPL and delegate with llm_query_chunked instead",
+    };
+  }
+
+  const anydoc = await getAnydoc();
+  // formatFromPath is extension-based; one call on the path is enough.
+  const format = anydoc?.formatFromPath(path) ?? documentExtFromPath(path);
+  if (format !== null) {
+    const doc = await documentToContextFile(safety.realAbs, rel, pathPrefix, anydoc);
+    if (!doc.ok) {
+      return { ok: false, error: `add_context: could not convert ${path} (${doc.skipped.reason})` };
+    }
+    return {
+      ok: true,
+      value: singleFileResult(
+        doc.value, sourceId, pathPrefix,
+        1, // documents
+        doc.converted ? 1 : 0,
+      ),
+    };
+  }
+
+  const text = await textToContextFile(safety.realAbs, rel, pathPrefix, MAX_CONTEXT_FILE_BYTES);
+  if (!text.ok) {
+    return { ok: false, error: `add_context: could not read ${path} (${text.skipped.reason})` };
+  }
+  return { ok: true, value: singleFileResult(text.value, sourceId, pathPrefix, 0, 0) };
+}

package/src/context/source-dir.ts

@@ -0,0 +1,166 @@
+/**
+ * Directory pack: walk + per-file routing (bounded pool).
+ *
+ * Routing order is load-bearing:
+ *   sensitive (link name)?  → skipped: "sensitive"
+ *   checkPathSafety (lstat/realpath; escape / resolved-sensitive)
+ *   format != null          → documentToContextFile() ← MUST come before isBinary
+ *   else                    → textToContextFile()
+ *
+ * A .docx IS binary. Reversed, every document in the tree would be dropped as an asset —
+ * precisely the bug this change exists to fix.
+ */
+
+import { join } from "node:path";
+import { documentExtFromPath, getAnydoc, type AnydocHandle } from "./anydoc.ts";
+import { Semaphore } from "../util/concurrency.ts";
+import { documentToContextFile } from "./source-doc.ts";
+import { textToContextFile } from "./source-text.ts";
+import { checkPathSafety, enumerateFiles, isSensitivePath } from "./walk.ts";
+import {
+  MAX_SKIPPED_REPORTED,
+  type ContextFile,
+  type ResolveOpts,
+  type SkippedFile,
+  type SourceResult,
+} from "./types.ts";
+import { applyPathPrefix, contextSourceId, pathPrefixFor } from "./namespace.ts";
+
+/** Conversions are libuv-threadpool bound (default pool 4); 8 keeps the pool busy without thrash. */
+const CONVERT_CONCURRENCY = 8;
+
+export interface PackDirResult {
+  readonly files: readonly ContextFile[];
+  readonly chars: number;
+  readonly documents: number;
+  readonly converted: number;
+  readonly skipped: readonly SkippedFile[];
+}
+
+/**
+ * Walk `dir` and produce ContextFiles. Resolves the anydoc handle once per source
+ * (not per file) and threads it into the per-file router.
+ */
+export async function packDirectory(
+  dir: string,
+  pathPrefix: string,
+  signal?: AbortSignal,
+  anydoc?: AnydocHandle | null,
+): Promise<PackDirResult> {
+  const paths = await enumerateFiles(dir, signal);
+  if (paths.length === 0) {
+    return Object.freeze({
+      files: Object.freeze([]),
+      chars: 0,
+      documents: 0,
+      converted: 0,
+      skipped: Object.freeze([]),
+    });
+  }
+
+  // One handle check per source, not per file.
+  const handle = anydoc !== undefined ? anydoc : await getAnydoc();
+  const gate = new Semaphore(CONVERT_CONCURRENCY);
+  // Pre-allocated slots; compacted in one pass with a single length trim — house style.
+  const slots = new Array<ContextFile | undefined>(paths.length);
+  const drops = new Array<SkippedFile | undefined>(paths.length);
+  const didConvert = new Array<boolean>(paths.length); // true = fresh anydoc conversion
+  const isDoc = new Array<boolean>(paths.length); // true = document-type entry in payload
+
+  await Promise.all(paths.map((rel, i) => gate.run(async () => {
+    if (signal?.aborted) {
+      drops[i] = Object.freeze({ path: applyPathPrefix(rel, pathPrefix), reason: "aborted" });
+      return;
+    }
+    // Sensitive deny-list on the enumerated name — second net under .gitignore.
+    if (isSensitivePath(rel)) {
+      drops[i] = Object.freeze({ path: applyPathPrefix(rel, pathPrefix), reason: "sensitive" });
+      return;
+    }
+    const abs = join(dir, rel);
+    // Symlink safety: realpath, refuse escape of pack root, re-check sensitive on target.
+    const safety = await checkPathSafety(abs, dir);
+    if (!safety.ok) {
+      drops[i] = Object.freeze({ path: applyPathPrefix(rel, pathPrefix), reason: safety.reason });
+      return;
+    }
+    const readAbs = safety.realAbs;
+    // Document router FIRST — a .docx is binary and would be dropped by the text path.
+    // When anydoc is absent, still detect by extension so documents skip as "no-converter".
+    const format = handle?.formatFromPath(rel) ?? documentExtFromPath(rel);
+    if (format !== null) {
+      const doc = await documentToContextFile(readAbs, rel, pathPrefix, handle);
+      if (doc.ok) {
+        slots[i] = doc.value;
+        didConvert[i] = doc.converted;
+        isDoc[i] = true;
+      } else {
+        drops[i] = doc.skipped;
+      }
+      return;
+    }
+    const text = await textToContextFile(readAbs, rel, pathPrefix);
+    if (text.ok) {
+      slots[i] = text.value;
+      didConvert[i] = false;
+      isDoc[i] = false;
+    } else {
+      drops[i] = text.skipped;
+    }
+  })));
+
+  const files = new Array<ContextFile>(paths.length);
+  const skipped = new Array<SkippedFile>(paths.length);
+  let nFiles = 0;
+  let nSkip = 0;
+  let chars = 0;
+  let converted = 0;
+  let documents = 0;
+  for (let i = 0; i < paths.length; i++) {
+    const f = slots[i];
+    if (f !== undefined) {
+      files[nFiles++] = f;
+      chars += f.content.length;
+      if (didConvert[i]) converted += 1;
+      if (isDoc[i]) documents += 1;
+      continue;
+    }
+    const d = drops[i];
+    // Filter unreadable from the model-facing skip list (ENOENT on deleted-tracked paths).
+    // Cap so an asset-heavy repo cannot flood the wire / reply frame.
+    if (d !== undefined && d.reason !== "unreadable" && nSkip < MAX_SKIPPED_REPORTED) {
+      skipped[nSkip++] = d;
+    }
+  }
+  files.length = nFiles;
+  skipped.length = nSkip;
+  return Object.freeze({
+    files: Object.freeze(files),
+    chars,
+    documents,
+    converted,
+    skipped: Object.freeze(skipped),
+  });
+}
+
+/** Pack a directory into a SourceResult with derived (or explicit) namespace. */
+export async function sourceDir(
+  dir: string,
+  source: string,
+  opts: ResolveOpts,
+): Promise<SourceResult> {
+  const sourceId = contextSourceId(source, dir);
+  // Explicit pathPrefix (including "") wins; otherwise derive ctx/<id>/.
+  const pathPrefix = opts.pathPrefix !== undefined ? opts.pathPrefix : pathPrefixFor(sourceId);
+  const packed = await packDirectory(dir, pathPrefix, opts.signal);
+  return Object.freeze({
+    payload: packed.files,
+    files: packed.files.length,
+    chars: packed.chars,
+    sourceId,
+    pathPrefix,
+    documents: packed.documents,
+    converted: packed.converted,
+    skipped: packed.skipped,
+  });
+}

package/src/context/source-doc.ts

@@ -0,0 +1,71 @@
+/**
+ * Document container → anydoc → Markdown → ContextFile, with on-disk MD cache.
+ *
+ * Stamp is captured BEFORE conversion so mid-edit races cannot freeze a stale body forever.
+ * Document size is capped at MAX_DOCUMENT_BYTES (walk and single-file paths share this).
+ */
+
+import type { AnydocHandle } from "./anydoc.ts";
+import { captureStamp, readMdCache, writeMdCache } from "./md-cache.ts";
+import { makeContextFile } from "./merge.ts";
+import { applyPathPrefix } from "./namespace.ts";
+import {
+  MAX_DOCUMENT_BYTES,
+  type ContextFile,
+  type SkipReason,
+  type SkippedFile,
+} from "./types.ts";
+
+export type DocFileResult =
+  | { readonly ok: true; readonly value: ContextFile; /** true only for a real anydoc conversion */ readonly converted: boolean }
+  | { readonly ok: false; readonly skipped: SkippedFile };
+
+function skipReasonFromError(err: unknown): SkipReason {
+  if (err !== null && typeof err === "object" && "code" in err) {
+    const code: unknown = err.code;
+    // Preserve anydoc ConvertErrorCode values rather than collapsing to "convert-failed".
+    if (code === "unsupported" || code === "malformed" || code === "encrypted"
+      || code === "resourceLimit" || code === "missingPart" || code === "io") {
+      return code;
+    }
+  }
+  return "convert-failed";
+}
+
+/**
+ * Convert a document file to a ContextFile via anydoc.
+ * Cache hits do not increment `converted`. Failures degrade to skipped, never throw.
+ */
+export async function documentToContextFile(
+  absPath: string,
+  relPath: string,
+  pathPrefix: string,
+  anydoc: AnydocHandle | null,
+): Promise<DocFileResult> {
+  const path = applyPathPrefix(relPath, pathPrefix);
+  if (anydoc === null) {
+    return { ok: false, skipped: Object.freeze({ path, reason: "no-converter" }) };
+  }
+
+  const stamp = await captureStamp(absPath);
+  if (stamp === undefined) {
+    return { ok: false, skipped: Object.freeze({ path, reason: "unreadable" }) };
+  }
+  if (stamp.size > MAX_DOCUMENT_BYTES) {
+    return { ok: false, skipped: Object.freeze({ path, reason: "oversized" }) };
+  }
+
+  try {
+    const cached = await readMdCache(absPath);
+    if (cached !== undefined) {
+      // Cache hit — document is in context, but no conversion was performed.
+      return { ok: true, value: makeContextFile(path, cached), converted: false };
+    }
+    const markdown = await anydoc.toMarkdown(absPath);
+    // Pass the PRE-conversion stamp — never re-stat after convert (stale-forever bug).
+    await writeMdCache(absPath, markdown, stamp);
+    return { ok: true, value: makeContextFile(path, markdown), converted: true };
+  } catch (err: unknown) {
+    return { ok: false, skipped: Object.freeze({ path, reason: skipReasonFromError(err) }) };
+  }
+}

package/src/context/source-git.ts

@@ -0,0 +1,51 @@
+/**
+ * Shallow-clone a git URL, then pack with source-dir.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { errorMessage, type Result } from "../util/errors.ts";
+import { contextSourceId, pathPrefixFor } from "./namespace.ts";
+import { packDirectory } from "./source-dir.ts";
+import type { ResolveOpts, SourceResult } from "./types.ts";
+
+const execFileP = promisify(execFile);
+
+/** Shallow-clone `url` into a temp dir, pack, then remove the clone. */
+export async function sourceGit(
+  url: string,
+  opts: ResolveOpts,
+): Promise<Result<SourceResult, string>> {
+  const dir = await mkdtemp(join(tmpdir(), "rlm-ctx-"));
+  const sourceId = contextSourceId(url);
+  const pathPrefix = opts.pathPrefix !== undefined ? opts.pathPrefix : pathPrefixFor(sourceId);
+  try {
+    await execFileP("git", ["clone", "--depth", "1", "--", url, dir], {
+      signal: opts.signal,
+      timeout: 120_000,
+      // Never stall on a credential helper for a private URL — fail fast instead.
+      env: Object.freeze({ ...process.env, GIT_TERMINAL_PROMPT: "0" }),
+    });
+    const packed = await packDirectory(dir, pathPrefix, opts.signal);
+    return {
+      ok: true,
+      value: Object.freeze({
+        payload: packed.files,
+        files: packed.files.length,
+        chars: packed.chars,
+        sourceId,
+        pathPrefix,
+        documents: packed.documents,
+        converted: packed.converted,
+        skipped: packed.skipped,
+      }),
+    };
+  } catch (err: unknown) {
+    return { ok: false, error: `git clone failed for ${url} — ${errorMessage(err)}` };
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/context/source-text.ts

@@ -0,0 +1,45 @@
+/**
+ * Plain (non-document) file → ContextFile.
+ * The isBinary probe lives HERE — documents are routed earlier by formatFromPath.
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { makeContextFile } from "./merge.ts";
+import { applyPathPrefix } from "./namespace.ts";
+import { isBinary } from "./walk.ts";
+import { MAX_WALK_FILE_BYTES, type ContextFile, type SkippedFile } from "./types.ts";
+
+export type TextFileResult =
+  | { readonly ok: true; readonly value: ContextFile }
+  | { readonly ok: false; readonly skipped: SkippedFile };
+
+/**
+ * Read a plain-text file into a ContextFile.
+ * Skips binaries (NUL probe), oversize files, and unreadable paths.
+ */
+export async function textToContextFile(
+  absPath: string,
+  relPath: string,
+  pathPrefix: string,
+  maxBytes: number = MAX_WALK_FILE_BYTES,
+): Promise<TextFileResult> {
+  const path = applyPathPrefix(relPath, pathPrefix);
+  try {
+    const s = await stat(absPath);
+    if (!s.isFile()) {
+      return { ok: false, skipped: Object.freeze({ path, reason: "unreadable" }) };
+    }
+    if (s.size > maxBytes) {
+      return { ok: false, skipped: Object.freeze({ path, reason: "oversized" }) };
+    }
+    // Binary probe AFTER the document router has already claimed known containers —
+    // a .docx IS binary; routing order in source-dir is load-bearing.
+    if (await isBinary(absPath)) {
+      return { ok: false, skipped: Object.freeze({ path, reason: "binary" }) };
+    }
+    const content = await readFile(absPath, "utf-8");
+    return { ok: true, value: makeContextFile(path, content) };
+  } catch {
+    return { ok: false, skipped: Object.freeze({ path, reason: "unreadable" }) };
+  }
+}