harnery 0.35.0 → 0.37.0

package/src/lib/coord-root-id.ts

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { DEFAULT_WEB_PORT } from "./local-file-url.ts";
+
+/** Local-only endpoint used to prove that a dashboard serves the caller's repo. */
+export const COORD_ROOT_ID_PATH = "/api/coord-root";
+
+/**
+ * Opaque identity for a canonical coordination root. The path stays local;
+ * only its digest crosses the dashboard boundary.
+ */
+export function coordRootId(root: string): string {
+  const canonical = realpathSync(root);
+  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function localCoordRootIdUrl(
+  port: number | string = DEFAULT_WEB_PORT,
+  protocol = "http:",
+): string {
+  const portPart = String(port) === "" ? "" : `:${port}`;
+  return `${protocol}//127.0.0.1${portPart}${COORD_ROOT_ID_PATH}`;
+}

package/src/lib/docs-lint.ts

@@ -1,8 +1,10 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
 import { hasYamlStatus } from "./docs-frontmatter.ts";
-import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "./docs-metadata-audit.ts";
-import { sh } from "./exec.ts";
+import {
+  auditDocsMetadataRepository,
+  initDocsMetadataAuditContext,
+} from "./docs-metadata-audit.ts";
 
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. Consumers pass repo metadata
@@ -34,8 +36,13 @@ function isSubmoduleInitialized(name: string): boolean {
   return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
 }
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import {
+  createDocsRepositoryView,
+  type DocsRepositorySource,
+  type DocsRepositoryView,
+} from "./docs-repository-view.ts";
 
 /**
  * Documentation linter. Enforces the docs directory-layout + naming contract.
@@ -58,6 +65,7 @@ export interface Violation {
 export interface LintOpts {
   fast?: boolean;
   repo?: string; // limit to one submodule or "." for parent
+  source?: DocsRepositorySource;
 }
 
 /** Files allowed at a submodule root level. Includes:
@@ -145,15 +153,9 @@ function getTargetRepos(opts: LintOpts): { name: string; path: string; isSubmodu
   return all;
 }
 
-/** List all tracked .md files in the given repo via `git ls-files`.
- * Returns paths relative to the repo root. Automatically skips node_modules,
- * vendor, .venv, dbt_packages, build/ etc. because they're gitignored.
- */
-async function findMarkdownFiles(root: string): Promise<string[]> {
-  const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: root });
-  if (result.exitCode !== 0 || !result.stdout) return [];
-  return result.stdout
-    .split("\n")
+/** Select tracked Markdown from the coherent repository view. */
+function findMarkdownFiles(view: DocsRepositoryView): string[] {
+  return view.trackedPaths
     .filter((f) => f.endsWith(".md"))
     .filter(
       (f) =>
@@ -164,19 +166,9 @@ async function findMarkdownFiles(root: string): Promise<string[]> {
     );
 }
 
-/** Read first N lines of a file for header inspection */
-function readHead(path: string, lines = 20): string {
-  try {
-    const content = readFileSync(path, "utf8");
-    return content.split("\n").slice(0, lines).join("\n");
-  } catch {
-    return "";
-  }
-}
-
 /** Detect whether a file declares itself an intentional monolith */
-function isDeclaredMonolith(path: string): boolean {
-  const head = readHead(path, 10);
+function isDeclaredMonolith(content: string): boolean {
+  const head = content.split("\n").slice(0, 10).join("\n");
   return /INTENTIONAL-MONOLITH/i.test(head);
 }
 
@@ -192,10 +184,14 @@ export function hasStatusHeader(path: string): boolean {
 // --- Individual checks ---
 
 /** Entry tier files exist at the repo root */
-function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean): Violation[] {
+function checkEntryTier(
+  repoName: string,
+  view: DocsRepositoryView,
+  isSubmodule: boolean,
+): Violation[] {
   const violations: Violation[] = [];
   // README.md is required for any repo
-  if (!existsSync(join(repoPath, "README.md"))) {
+  if (!view.has("README.md")) {
     violations.push({
       severity: "error",
       repo: repoName,
@@ -205,7 +201,7 @@ function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean
     });
   }
   // CLAUDE.md required for submodules (primary LLM context)
-  if (isSubmodule && !existsSync(join(repoPath, "CLAUDE.md"))) {
+  if (isSubmodule && !view.has("CLAUDE.md")) {
     violations.push({
       severity: "error",
       repo: repoName,
@@ -218,14 +214,9 @@ function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean
 }
 
 /** No forbidden root-level files */
-function checkRootAllowlist(repoName: string, repoPath: string): Violation[] {
+function checkRootAllowlist(repoName: string, view: DocsRepositoryView): Violation[] {
   const violations: Violation[] = [];
-  let entries: string[];
-  try {
-    entries = readdirSync(repoPath);
-  } catch {
-    return violations;
-  }
+  const entries = view.directFileNames(".");
   for (const entry of entries) {
     if (!entry.endsWith(".md")) continue;
     if (ROOT_FILE_ALLOWLIST.has(entry)) continue;
@@ -257,27 +248,13 @@ function checkRootAllowlist(repoName: string, repoPath: string): Violation[] {
  * a no-op unless the host supplies `docsRootAllowlist`. Parent-repo only:
  * submodule `docs/` roots have their own entry tiers, not this one.
  */
-function checkDocsRootAllowlist(repoName: string, repoPath: string): Violation[] {
+function checkDocsRootAllowlist(repoName: string, view: DocsRepositoryView): Violation[] {
   const violations: Violation[] = [];
   if (DOCS_ROOT_ALLOWLIST.length === 0) return violations; // opt-in
   if (repoName !== "(root)") return violations; // parent repo only
   const allow = new Set(DOCS_ROOT_ALLOWLIST);
-  const docsDir = join(repoPath, "docs");
-  let entries: string[];
-  try {
-    entries = readdirSync(docsDir);
-  } catch {
-    return violations; // no docs/ dir — nothing to check
-  }
+  const entries = view.directFileNames("docs");
   for (const entry of entries) {
-    // Subdirs are the intended home for topic docs; only loose files matter.
-    let isFile: boolean;
-    try {
-      isFile = statSync(join(docsDir, entry)).isFile();
-    } catch {
-      continue;
-    }
-    if (!isFile) continue;
     if (!(entry.endsWith(".md") || entry.endsWith(".json"))) continue;
     if (allow.has(entry)) continue;
     violations.push({
@@ -383,13 +360,14 @@ function checkChangelogNames(repoName: string, _repoPath: string, files: string[
 }
 
 /** Intentional monoliths >30KB need a declaration banner */
-function checkMonolithDeclaration(
+async function checkMonolithDeclaration(
   repoName: string,
-  repoPath: string,
+  view: DocsRepositoryView,
   files: string[],
-): Violation[] {
+): Promise<Violation[]> {
   const violations: Violation[] = [];
   const SIZE_THRESHOLD = 30 * 1024;
+  const candidatePaths: string[] = [];
   for (const rel of files) {
     // Only flag top-level docs/ files, not per-repo entry tier (LLM-BRIEFING
     // files are monoliths by convention, no banner needed).
@@ -399,15 +377,17 @@ function checkMonolithDeclaration(
     if (rel.startsWith("docs/audits/")) continue;
     if (rel.startsWith("docs/issues/")) continue;
     if (rel.startsWith("docs/changelogs/")) continue;
-    const full = join(repoPath, rel);
-    let size: number;
-    try {
-      size = statSync(full).size;
-    } catch {
-      continue;
-    }
+    const size = await view.byteLength(rel);
+    if (size === null) continue;
     if (size < SIZE_THRESHOLD) continue;
-    if (isDeclaredMonolith(full)) continue;
+    candidatePaths.push(rel);
+  }
+  const texts = await view.readTexts(candidatePaths);
+  for (const rel of candidatePaths) {
+    const content = texts.get(rel);
+    if (content === undefined || isDeclaredMonolith(content)) continue;
+    const size = await view.byteLength(rel);
+    if (size === null) continue;
     violations.push({
       severity: "warning",
       repo: repoName,
@@ -426,30 +406,31 @@ export async function runLint(opts: LintOpts): Promise<Violation[]> {
   const repos = getTargetRepos(opts);
 
   for (const { name, path, isSubmodule } of repos) {
-    violations.push(...checkEntryTier(name, path, isSubmodule));
-    violations.push(...checkRootAllowlist(name, path));
-    violations.push(...checkDocsRootAllowlist(name, path));
+    const view = await createDocsRepositoryView(path, opts.source ?? "worktree");
+    violations.push(...checkEntryTier(name, view, isSubmodule));
+    violations.push(...checkRootAllowlist(name, view));
+    violations.push(...checkDocsRootAllowlist(name, view));
 
-    const files = await findMarkdownFiles(path);
+    const files = findMarkdownFiles(view);
     violations.push(...checkNamingConvention(name, path, files));
     violations.push(...checkDatedDirs(name, path, files));
     violations.push(...checkChangelogNames(name, path, files));
 
     if (!opts.fast) {
-      violations.push(...checkMonolithDeclaration(name, path, files));
+      violations.push(...(await checkMonolithDeclaration(name, view, files)));
     }
-  }
 
-  const metadataRows = await runDocsMetadataAudit({ repo: opts.repo });
-  for (const row of metadataRows) {
-    for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
-      violations.push({
-        severity: "error",
-        repo: row.repo,
-        path: row.path,
-        rule: `metadata-v2:${issue.code}`,
-        message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
-      });
+    const metadataRows = await auditDocsMetadataRepository(name, view);
+    for (const row of metadataRows) {
+      for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
+        violations.push({
+          severity: "error",
+          repo: row.repo,
+          path: row.path,
+          rule: `metadata-v2:${issue.code}`,
+          message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
+        });
+      }
     }
   }
 

package/src/lib/docs-metadata-audit.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { parseFrontmatter } from "./docs-frontmatter.ts";
 import { isManagedDocsMetadataFile, managedDocsMetadataType } from "./docs-metadata-managed.ts";
@@ -9,7 +9,11 @@ import {
   isDocsMetadataV2,
   validateDocsMetadataV2,
 } from "./docs-metadata-v2.ts";
-import { sh } from "./exec.ts";
+import {
+  createDocsRepositoryView,
+  type DocsRepositorySource,
+  type DocsRepositoryView,
+} from "./docs-repository-view.ts";
 
 let REPO_ROOT = "";
 let SUBMODULES: readonly string[] = [];
@@ -24,6 +28,7 @@ export function initDocsMetadataAuditContext(opts: {
 
 export interface DocsMetadataAuditOpts {
   repo?: string;
+  source?: DocsRepositorySource;
 }
 
 export type DocsMetadataAuditState = "valid" | "invalid" | "legacy" | "missing";
@@ -40,20 +45,12 @@ function isInitializedRepo(path: string): boolean {
   return existsSync(join(path, ".git"));
 }
 
-async function trackedMarkdownFiles(repoPath: string): Promise<string[]> {
-  const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: repoPath });
-  if (result.exitCode !== 0 || !result.stdout.trim()) return [];
-  return result.stdout
-    .trim()
-    .split("\n")
-    .filter((path) => path.endsWith(".md"));
-}
-
-function auditFile(repoName: string, repoPath: string, path: string): DocsMetadataAuditRow | null {
-  let content: string;
-  try {
-    content = readFileSync(join(repoPath, path), "utf8");
-  } catch {
+function auditFile(
+  repoName: string,
+  path: string,
+  content: string | undefined,
+): DocsMetadataAuditRow | null {
+  if (content === undefined) {
     return {
       repo: repoName,
       path: join(repoName === "(root)" ? "" : repoName, path),
@@ -105,6 +102,17 @@ function auditFile(repoName: string, repoPath: string, path: string): DocsMetada
   };
 }
 
+export async function auditDocsMetadataRepository(
+  repoName: string,
+  view: DocsRepositoryView,
+): Promise<DocsMetadataAuditRow[]> {
+  const files = view.trackedPaths.filter((path) => path.endsWith(".md"));
+  const texts = await view.readTexts(files);
+  return files
+    .map((path) => auditFile(repoName, path, texts.get(path)))
+    .filter((row): row is DocsMetadataAuditRow => row !== null);
+}
+
 export async function runDocsMetadataAudit(
   opts: DocsMetadataAuditOpts,
 ): Promise<DocsMetadataAuditRow[]> {
@@ -120,11 +128,8 @@ export async function runDocsMetadataAudit(
 
   const rows: DocsMetadataAuditRow[] = [];
   for (const target of selected) {
-    const files = await trackedMarkdownFiles(target.path);
-    for (const path of files) {
-      const row = auditFile(target.name, target.path, path);
-      if (row) rows.push(row);
-    }
+    const view = await createDocsRepositoryView(target.path, opts.source ?? "worktree");
+    rows.push(...(await auditDocsMetadataRepository(target.name, view)));
   }
 
   return rows.sort((a, b) => a.path.localeCompare(b.path));

package/src/lib/docs-metadata-sync.ts

@@ -4,6 +4,7 @@ import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
 import { parseFrontmatter } from "./docs-frontmatter.ts";
 import { managedDocsMetadataType } from "./docs-metadata-managed.ts";
 import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.ts";
+import { createDocsRepositoryView } from "./docs-repository-view.ts";
 import { sh } from "./exec.ts";
 
 let REPO_ROOT = "";
@@ -21,6 +22,7 @@ export interface DocsMetadataSyncOpts {
   repo?: string;
   files?: string[];
   check?: boolean;
+  cached?: boolean;
   reviewed?: boolean;
   now?: string;
 }
@@ -49,15 +51,27 @@ function targets(repo?: string): Target[] {
   return selected;
 }
 
-async function changedFiles(target: Target, explicit: string[]): Promise<string[]> {
-  if (explicit.length > 0) return explicit;
-  const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
-    cwd: target.path,
-  });
-  if (result.exitCode !== 0) throw new Error(result.stderr || "git diff failed");
+async function gitMarkdownPaths(target: Target, command: string): Promise<string[]> {
+  const result = await sh(command, { cwd: target.path });
+  if (result.exitCode !== 0) throw new Error(result.stderr || `${command} failed`);
   return result.stdout.split("\n").filter(Boolean);
 }
 
+async function changedFiles(target: Target, explicit: string[], check: boolean): Promise<string[]> {
+  if (explicit.length > 0) return explicit;
+  const staged = await gitMarkdownPaths(
+    target,
+    "git diff --cached --name-only --diff-filter=ACMR -- '*.md'",
+  );
+  if (check) return staged;
+
+  const [unstaged, untracked] = await Promise.all([
+    gitMarkdownPaths(target, "git diff --name-only --diff-filter=ACMR -- '*.md'"),
+    gitMarkdownPaths(target, "git ls-files --others --exclude-standard -- '*.md'"),
+  ]);
+  return [...new Set([...staged, ...unstaged, ...untracked])];
+}
+
 async function headContent(target: Target, path: string): Promise<string | null> {
   const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
   return result.exitCode === 0 ? result.stdout : null;
@@ -107,13 +121,22 @@ function addDays(value: string, days: number): string {
 export async function runDocsMetadataSync(
   opts: DocsMetadataSyncOpts,
 ): Promise<DocsMetadataSyncRow[]> {
+  if (opts.cached && !opts.check) {
+    throw new Error("--cached requires --check because Git index validation is read-only");
+  }
   const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
   const rows: DocsMetadataSyncRow[] = [];
   for (const target of targets(opts.repo)) {
-    for (const path of await changedFiles(target, opts.files ?? [])) {
+    const paths = await changedFiles(target, opts.files ?? [], opts.check ?? false);
+    const cachedView = opts.cached ? await createDocsRepositoryView(target.path, "index") : null;
+    const cachedTexts = cachedView ? await cachedView.readTexts(paths) : null;
+    for (const path of paths) {
       const full = join(target.path, path);
-      if (!existsSync(full)) continue;
-      const currentText = readFileSync(full, "utf8");
+      if (cachedView ? !cachedView.has(path) : !existsSync(full)) continue;
+      const currentText = cachedView ? cachedTexts?.get(path) : readFileSync(full, "utf8");
+      if (currentText === undefined) {
+        throw new Error(`Git index content could not be read for ${path}`);
+      }
       const current = parseFrontmatter(currentText);
       if (!managedDocsMetadataType(path, current.data, current.raw !== null)) continue;
       if (!isDocsMetadataV2(current.data)) {

package/src/lib/docs-repository-view.ts

@@ -0,0 +1,220 @@
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { exec } from "./exec.ts";
+
+export type DocsRepositorySource = "worktree" | "index";
+
+interface IndexEntry {
+  oid: string;
+  stage: number;
+}
+
+/**
+ * One coherent repository view for documentation commands.
+ *
+ * Worktree mode preserves the interactive commands' existing behavior. Index
+ * mode reads both path membership and file bytes through Git, so a pre-commit
+ * hook validates the exact index Git handed to it. During a path-scoped commit,
+ * Git exposes its temporary partial-commit index through GIT_INDEX_FILE; the
+ * view deliberately inherits that environment instead of rediscovering the
+ * shared working tree.
+ */
+export interface DocsRepositoryView {
+  readonly root: string;
+  readonly source: DocsRepositorySource;
+  readonly trackedPaths: readonly string[];
+  has(path: string): boolean;
+  directFileNames(directory: string): string[];
+  readTexts(paths: readonly string[]): Promise<Map<string, string>>;
+  byteLength(path: string): Promise<number | null>;
+}
+
+function normalize(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function trackedPathList(stdout: string): string[] {
+  return stdout.split("\0").map(normalize).filter(Boolean);
+}
+
+async function worktreePaths(root: string): Promise<string[]> {
+  const result = await exec(["git", "ls-files", "--cached", "-z"], { cwd: root, trim: false });
+  if (result.exitCode !== 0) {
+    // Worktree lint historically supports non-repository fixtures and simply
+    // has no tracked-file checks to run there. Index mode remains strict.
+    return [];
+  }
+  return trackedPathList(result.stdout);
+}
+
+async function indexEntries(root: string): Promise<Map<string, IndexEntry>> {
+  const result = await exec(["git", "ls-files", "--cached", "--stage", "-z"], {
+    cwd: root,
+    trim: false,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || "git ls-files --stage failed");
+  }
+
+  const entries = new Map<string, IndexEntry>();
+  for (const record of result.stdout.split("\0").filter(Boolean)) {
+    const tab = record.indexOf("\t");
+    if (tab === -1) throw new Error(`invalid git ls-files --stage record: ${record}`);
+    const [mode, oid, stageText] = record.slice(0, tab).split(" ");
+    const path = normalize(record.slice(tab + 1));
+    const stage = Number.parseInt(stageText ?? "", 10);
+    if (!mode || !oid || !Number.isInteger(stage)) {
+      throw new Error(`invalid git ls-files --stage record for ${path}`);
+    }
+    if (stage !== 0) {
+      throw new Error(`cannot validate an index with unmerged entry: ${path}`);
+    }
+    entries.set(path, { oid, stage });
+  }
+  return entries;
+}
+
+function parseBatch(stdout: Buffer, requested: readonly string[]): Map<string, Buffer> {
+  const blobs = new Map<string, Buffer>();
+  let offset = 0;
+  for (const oid of requested) {
+    const newline = stdout.indexOf(0x0a, offset);
+    if (newline === -1) throw new Error(`git cat-file omitted the header for ${oid}`);
+    const header = stdout.subarray(offset, newline).toString("utf8");
+    offset = newline + 1;
+    const [reportedOid, type, sizeText] = header.split(" ");
+    const size = Number.parseInt(sizeText ?? "", 10);
+    if (reportedOid !== oid || type !== "blob" || !Number.isInteger(size) || size < 0) {
+      throw new Error(`git cat-file returned an invalid blob header for ${oid}: ${header}`);
+    }
+    const end = offset + size;
+    if (end > stdout.length) throw new Error(`git cat-file truncated blob ${oid}`);
+    blobs.set(oid, stdout.subarray(offset, end));
+    offset = end;
+    if (stdout[offset] !== 0x0a) throw new Error(`git cat-file omitted the separator for ${oid}`);
+    offset += 1;
+  }
+  return blobs;
+}
+
+function readIndexBlobs(root: string, oids: readonly string[]): Promise<Map<string, Buffer>> {
+  const unique = [...new Set(oids)];
+  if (unique.length === 0) return Promise.resolve(new Map());
+
+  return new Promise((resolveResult, rejectResult) => {
+    const process = spawn("git", ["cat-file", "--batch"], {
+      cwd: root,
+      env: { ...globalThis.process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    const timer = setTimeout(() => process.kill(), 30_000);
+    process.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+    process.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+    process.on("error", (error) => {
+      clearTimeout(timer);
+      rejectResult(error);
+    });
+    process.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        rejectResult(
+          new Error(Buffer.concat(stderr).toString("utf8").trim() || "git cat-file failed"),
+        );
+        return;
+      }
+      try {
+        resolveResult(parseBatch(Buffer.concat(stdout), unique));
+      } catch (error) {
+        rejectResult(error);
+      }
+    });
+    process.stdin.end(`${unique.join("\n")}\n`);
+  });
+}
+
+function directIndexFiles(paths: readonly string[], directory: string): string[] {
+  const normalizedDirectory = normalize(directory).replace(/\/$/, "");
+  return paths
+    .filter((path) => normalize(dirname(path)) === normalizedDirectory)
+    .map((path) => basename(path));
+}
+
+export async function createDocsRepositoryView(
+  root: string,
+  source: DocsRepositorySource = "worktree",
+): Promise<DocsRepositoryView> {
+  if (source === "worktree") {
+    const trackedPaths = await worktreePaths(root);
+    return {
+      root,
+      source,
+      trackedPaths,
+      has: (path) => existsSync(join(root, path)),
+      directFileNames: (directory) => {
+        try {
+          return readdirSync(join(root, directory)).filter((entry) => {
+            try {
+              return statSync(join(root, directory, entry)).isFile();
+            } catch {
+              return false;
+            }
+          });
+        } catch {
+          return [];
+        }
+      },
+      readTexts: async (paths) => {
+        const texts = new Map<string, string>();
+        for (const path of paths) {
+          try {
+            texts.set(path, readFileSync(join(root, path), "utf8"));
+          } catch {
+            // The caller decides whether a missing tracked path is a finding.
+          }
+        }
+        return texts;
+      },
+      byteLength: async (path) => {
+        try {
+          return statSync(join(root, path)).size;
+        } catch {
+          return null;
+        }
+      },
+    };
+  }
+
+  const entries = await indexEntries(root);
+  const trackedPaths = [...entries.keys()];
+  const textCache = new Map<string, string>();
+  const loadTexts = async (paths: readonly string[]): Promise<Map<string, string>> => {
+    const wanted = [...new Set(paths.map(normalize))].filter((path) => entries.has(path));
+    const missing = wanted.filter((path) => !textCache.has(path));
+    const oids = missing.map((path) => entries.get(path)!.oid);
+    const blobs = await readIndexBlobs(root, oids);
+    for (const path of missing) {
+      const blob = blobs.get(entries.get(path)!.oid);
+      if (blob) textCache.set(path, blob.toString("utf8"));
+    }
+    return new Map(
+      wanted.flatMap((path) => (textCache.has(path) ? [[path, textCache.get(path)!]] : [])),
+    );
+  };
+
+  return {
+    root,
+    source,
+    trackedPaths,
+    has: (path) => entries.has(normalize(path)),
+    directFileNames: (directory) => directIndexFiles(trackedPaths, directory),
+    readTexts: loadTexts,
+    byteLength: async (path) => {
+      const normalized = normalize(path);
+      const text = (await loadTexts([normalized])).get(normalized);
+      return text === undefined ? null : Buffer.byteLength(text, "utf8");
+    },
+  };
+}