@danypops/lector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Popsuevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @danypops/lector
+
+The capability core and daemon half of [Lector](../../README.md) -- domain,
+ports, adapters, and the CLI/systemd service. See the repo root README for
+the overall architecture and how `packages/pi-lector` fits in.
+
+## Storage and service
+
+```text
+$XDG_DATA_HOME/lector/lector.db       # content-addressed cache (SQLite, when enabled)
+$XDG_RUNTIME_DIR/lector/{port,token}  # private daemon discovery
+```
+
+```bash
+lector service install   # write a systemd user unit, enable, and start it
+lector service status
+lector service restart
+```
+
+The installed service runs `lector serve --dynamic-workspaces`: a long-lived
+background daemon doesn't know upfront which project(s) will use it, so it starts
+with zero pre-registered workspaces and relies entirely on `workspace.registerPath`
+at runtime — the same explicit-registration path a host adapter uses to attach
+whatever directory it's running in.
+
+## CLI
+
+```bash
+lector workspace register <dir>
+lector workspace read <workspace-id> <path>
+lector workspace edit <workspace-id> <path> --content <text> (--create | --expected-hash <hash>)
+lector workspace symbols <workspace-id> <query>
+lector workspace populate-symbol-graph <workspace-id> --max-files <n> --max-symbols-per-file <n> --background --wait-ms 500
+lector job status <job-id>
+lector workspace cache-status <workspace-id> --max-files <n> --max-symbols-per-file <n>
+```
+
+Background jobs are process-lifetime and bounded. A daemon restart or retention
+expiry makes an old id unavailable; `job status` reports that explicitly. A running
+scan returns its job id and an actionable still-loading state instead of blocking
+the caller.
+
+`exactEdit` requires either `--create` (the entry must not already exist) or
+`--expected-hash <hash>` (the entry must currently match that hash) — a write never
+silently overwrites content it didn't know about.
+
+## Symbol backends
+
+Two independent `SymbolIndexPort` implementations, exercised against a shared
+conformance fixture so they're proven to agree (or documented where they don't),
+not assumed to:
+
+- **`typescript-language-server`** (default) — a warm, real `tsserver` process per
+  workspace, most accurate when it has a loaded project.
+- **tree-sitter** (via `web-tree-sitter`, WASM — no native toolchain required) — no
+  subprocess, always current, results cached per file under a content-addressed key.
+

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@danypops/lector",
+	"version": "0.1.0",
+	"description": "Platform-neutral filesystem & code-intelligence capability: core, service, and driven adapters",
+	"license": "MIT",
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"bin": {
+		"lector": "src/cli.ts"
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"cli": "bun src/cli.ts",
+		"serve": "bun src/cli.ts serve",
+		"bench:cold-start": "bun benchmarks/language-server-cold-start.ts"
+	},
+	"dependencies": {
+		"@danypops/daemon-kit": "^0.3.2",
+		"bash-language-server": "^5.6.0",
+		"graphology": "^0.26.0",
+		"lru-cache": "^11.5.2",
+		"pyright": "^1.1.411",
+		"simple-git": "^3.36.0",
+		"tree-sitter-wasms": "^0.1.13",
+		"typescript": "^5.9.3",
+		"typescript-language-server": "^5.3.0",
+		"web-tree-sitter": "0.20.8",
+		"yaml-language-server": "^1.24.0"
+	},
+	"devDependencies": {
+		"bun-types": "latest"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DanyPops/lector.git",
+		"directory": "packages/lector"
+	},
+	"homepage": "https://github.com/DanyPops/lector#readme",
+	"bugs": {
+		"url": "https://github.com/DanyPops/lector/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": ["src", "README.md", "LICENSE"]
+}

package/src/adapters/directory-size.ts

@@ -0,0 +1,19 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Real on-disk size in bytes via `du -sb`, not a hand-rolled recursive stat sum -- `du` already
+ * handles hard links and sparse files correctly, a walker built from scratch would not.
+ * Linux-only (GNU coreutils `-b`), matching this codebase's existing /proc-based RSS measurement.
+ */
+export async function measureDirectorySizeBytes(path: string): Promise<number> {
+	const { stdout } = await execFileAsync("du", ["-sb", path]);
+	const [sizeText] = stdout.split("\t");
+	const size = Number.parseInt(sizeText ?? "", 10);
+	if (!Number.isFinite(size)) {
+		throw new Error(`du produced unparseable output for ${path}: ${JSON.stringify(stdout)}`);
+	}
+	return size;
+}

package/src/adapters/find-source-files.ts

@@ -0,0 +1,35 @@
+import { type Dirent, readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+
+/** Shared with RipgrepTextSearch -- one skip-list, not two independently-maintained ones. */
+export const SKIP_DIRECTORY_NAMES = new Set(["node_modules", ".git", "dist", "build", "out", "coverage"]);
+
+/** Bounded (entry-count-limited, skips node_modules/.git/build output and hidden dirs) recursive source-file scan. */
+export function findSourceFiles(rootPath: string, isSourceExtension: (extension: string) => boolean, maxFiles: number): string[] {
+	const files: string[] = [];
+	let scanned = 0;
+
+	const visit = (relativeDir: string): void => {
+		if (scanned >= maxFiles) return;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(join(rootPath, relativeDir), { withFileTypes: true, encoding: "utf-8" });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (scanned >= maxFiles) return;
+			const relativePath = relativeDir ? join(relativeDir, entry.name) : entry.name;
+			if (entry.isDirectory()) {
+				if (SKIP_DIRECTORY_NAMES.has(entry.name) || entry.name.startsWith(".")) continue;
+				visit(relativePath);
+			} else if (entry.isFile() && isSourceExtension(extname(entry.name))) {
+				scanned++;
+				files.push(relativePath);
+			}
+		}
+	};
+
+	visit("");
+	return files;
+}

package/src/adapters/git-repo-fetcher.ts

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LRUCache } from "lru-cache";
+import simpleGit from "simple-git";
+import { assertSafeRepoReference } from "../domain/assert-safe-repo-reference.ts";
+import { RepoFetchFailed, type RepoFetchResult } from "../domain/repo-fetch-result.ts";
+import type { RepoReference } from "../domain/repo-reference.ts";
+import type { RepoFetcherPort } from "../ports/repo-fetcher-port.ts";
+import { measureDirectorySizeBytes } from "./directory-size.ts";
+
+interface RepoCacheEntry {
+	readonly path: string;
+	readonly resolvedRef: string;
+	readonly fetchedAt: number;
+}
+
+const INDEX_FILENAME = "index.json";
+const DEFAULT_MAX_CACHE_BYTES = 5 * 1024 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 500;
+
+function cacheKey(reference: RepoReference): string {
+	return `${reference.host}/${reference.owner}/${reference.repo}/${reference.ref ?? "HEAD"}`;
+}
+
+export interface GitRepoFetcherOptions {
+	/** Disk budget in bytes across every cached clone. Least-recently-fetched clones are deleted once exceeded. */
+	readonly maxCacheBytes?: number;
+	readonly maxEntries?: number;
+	/** Maps a reference to what git should clone from. Defaults to `https://<host>/<owner>/<repo>.git`. Overridable so tests can point at a real local bare-repo fixture instead of the network. */
+	readonly resolveCloneUrl?: (reference: RepoReference) => string;
+}
+
+function defaultCloneUrl(reference: RepoReference): string {
+	return `https://${reference.host}/${reference.owner}/${reference.repo}.git`;
+}
+
+/**
+ * RepoFetcherPort backed by a real `git clone --depth 1`, content-addressed by
+ * (host, owner, repo, ref) under `reposDir`. Disk usage is bounded by an LRU cache keyed the same
+ * way; evicting an entry deletes its directory, so the cache and the filesystem never disagree
+ * about what's actually on disk. Calls are serialized through an in-process queue -- this daemon
+ * is the sole writer of reposDir, so a promise chain is sufficient; no cross-process file lock
+ * is needed.
+ */
+export class GitRepoFetcher implements RepoFetcherPort {
+	private readonly reposDir: string;
+	private readonly indexPath: string;
+	private readonly resolveCloneUrl: (reference: RepoReference) => string;
+	private readonly cache: LRUCache<string, RepoCacheEntry>;
+	private queue: Promise<unknown> = Promise.resolve();
+
+	constructor(reposDir: string, options: GitRepoFetcherOptions = {}) {
+		this.reposDir = reposDir;
+		this.indexPath = join(reposDir, INDEX_FILENAME);
+		this.resolveCloneUrl = options.resolveCloneUrl ?? defaultCloneUrl;
+		this.cache = new LRUCache<string, RepoCacheEntry>({
+			maxSize: options.maxCacheBytes ?? DEFAULT_MAX_CACHE_BYTES,
+			// A single clone larger than the whole budget must still be stored (evicting everything
+			// else) rather than silently rejected -- lru-cache's own default couples this to maxSize.
+			maxEntrySize: Number.MAX_SAFE_INTEGER,
+			max: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+			dispose: (entry) => {
+				rmSync(entry.path, { recursive: true, force: true });
+			},
+		});
+		this.loadIndex();
+	}
+
+	async fetch(reference: RepoReference): Promise<RepoFetchResult> {
+		assertSafeRepoReference(reference);
+		const task = this.queue.then(() => this.fetchLocked(reference));
+		this.queue = task.then(
+			() => undefined,
+			() => undefined,
+		);
+		return task;
+	}
+
+	private async fetchLocked(reference: RepoReference): Promise<RepoFetchResult> {
+		const key = cacheKey(reference);
+		const cached = this.cache.get(key);
+		if (cached) {
+			return { path: cached.path, fromCache: true, resolvedRef: cached.resolvedRef, refFallbackOccurred: false };
+		}
+
+		const targetDir = join(this.reposDir, reference.host, reference.owner, reference.repo, reference.ref ?? "HEAD");
+		await rm(targetDir, { recursive: true, force: true });
+		const tmpDir = `${targetDir}.tmp-${process.pid}-${Date.now()}`;
+		await rm(tmpDir, { recursive: true, force: true });
+
+		const url = this.resolveCloneUrl(reference);
+		let resolvedRef = reference.ref ?? "HEAD";
+		let refFallbackOccurred = false;
+		try {
+			await this.clone(url, reference.ref, tmpDir);
+		} catch (firstError) {
+			if (reference.ref === null) {
+				throw new RepoFetchFailed(reference.host, reference.owner, reference.repo, reference.ref, firstError);
+			}
+			await rm(tmpDir, { recursive: true, force: true });
+			try {
+				await this.clone(url, null, tmpDir);
+				refFallbackOccurred = true;
+				resolvedRef = "HEAD";
+			} catch (secondError) {
+				throw new RepoFetchFailed(reference.host, reference.owner, reference.repo, reference.ref, secondError);
+			}
+		}
+
+		await rm(join(tmpDir, ".git"), { recursive: true, force: true });
+		await mkdir(dirname(targetDir), { recursive: true });
+		await rename(tmpDir, targetDir);
+
+		const sizeBytes = await measureDirectorySizeBytes(targetDir);
+		const entry: RepoCacheEntry = { path: targetDir, resolvedRef, fetchedAt: Date.now() };
+		this.cache.set(key, entry, { size: sizeBytes });
+		this.persistIndex();
+
+		return { path: targetDir, fromCache: false, resolvedRef, refFallbackOccurred };
+	}
+
+	private async clone(url: string, ref: string | null, targetDir: string): Promise<void> {
+		const options = ref ? ["--depth", "1", "--branch", ref] : ["--depth", "1"];
+		await simpleGit().clone(url, targetDir, options);
+	}
+
+	private loadIndex(): void {
+		if (!existsSync(this.indexPath)) return;
+		try {
+			const dumped = JSON.parse(readFileSync(this.indexPath, "utf8")) as Parameters<typeof this.cache.load>[0];
+			this.cache.load(dumped);
+		} catch {
+			// Corrupt or unreadable index -- start fresh, do not throw. Directories left over from a
+			// prior run are cleaned up lazily the next time their key is fetched again (fetchLocked
+			// always rm's targetDir before cloning into it).
+		}
+	}
+
+	private persistIndex(): void {
+		mkdirSync(this.reposDir, { recursive: true });
+		const temp = `${this.indexPath}.${process.pid}.tmp`;
+		writeFileSync(temp, JSON.stringify(this.cache.dump()), "utf8");
+		renameSync(temp, this.indexPath);
+	}
+}

package/src/adapters/in-memory-content-cache.ts

@@ -0,0 +1,19 @@
+import type { ContentHash } from "../domain/content-hash.ts";
+import type { ContentCacheEntry, ContentCachePort, ContentSymbol } from "../ports/content-cache-port.ts";
+
+/** In-process ContentCachePort -- no persistence, cleared on process exit. The default when no durable cache is configured. */
+export class InMemoryContentCache implements ContentCachePort {
+	private readonly entries = new Map<ContentHash, ContentCacheEntry>();
+
+	async get(hash: ContentHash): Promise<ContentCacheEntry | undefined> {
+		return this.entries.get(hash);
+	}
+
+	async putRawContent(hash: ContentHash, content: string): Promise<void> {
+		this.entries.set(hash, { ...this.entries.get(hash), rawContent: content });
+	}
+
+	async putSymbols(hash: ContentHash, symbols: readonly ContentSymbol[]): Promise<void> {
+		this.entries.set(hash, { ...this.entries.get(hash), symbols });
+	}
+}

package/src/adapters/in-memory-search-cache.ts

@@ -0,0 +1,32 @@
+import { LRUCache } from "lru-cache";
+import { deriveSearchCacheKey, type SearchCacheKey } from "../domain/search-cache-key.ts";
+import type { TextSearchResult } from "../domain/text-search-result.ts";
+import type { SearchCachePort } from "../ports/search-cache-port.ts";
+
+const DEFAULT_MAX_ENTRIES = 200;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+export interface InMemorySearchCacheOptions {
+	readonly maxEntries?: number;
+	readonly ttlMs?: number;
+}
+
+/** SearchCachePort backed by lru-cache -- count- and TTL-bounded, not a hand-rolled Map+timestamp cache. */
+export class InMemorySearchCache implements SearchCachePort {
+	private readonly cache: LRUCache<string, TextSearchResult>;
+
+	constructor(options: InMemorySearchCacheOptions = {}) {
+		this.cache = new LRUCache<string, TextSearchResult>({
+			max: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+			ttl: options.ttlMs ?? DEFAULT_TTL_MS,
+		});
+	}
+
+	async get(key: SearchCacheKey): Promise<TextSearchResult | undefined> {
+		return this.cache.get(deriveSearchCacheKey(key));
+	}
+
+	async set(key: SearchCacheKey, result: TextSearchResult): Promise<void> {
+		this.cache.set(deriveSearchCacheKey(key), result);
+	}
+}

package/src/adapters/in-memory-symbol-graph.ts

@@ -0,0 +1,80 @@
+import Graph from "graphology";
+import type { SymbolGraphGeneration } from "../domain/symbol-graph-generation.ts";
+import type { SymbolNodeId } from "../domain/symbol-node-id.ts";
+import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
+
+/**
+ * In-memory SymbolGraphPort for tests and small/ephemeral workspaces,
+ * backed by graphology for node/edge storage (multi-edge and self-loop
+ * support). reachableFrom is a small explicit bounded-depth BFS on top of
+ * it, since graphology's own traversal helpers don't take a hop limit.
+ */
+export class InMemorySymbolGraph implements SymbolGraphPort {
+	private readonly graph = new Graph({ type: "directed", multi: true, allowSelfLoops: true });
+	private readonly nodes = new Map<SymbolNodeId, SymbolNode>();
+	private generation: SymbolGraphGeneration | undefined;
+
+	async addNode(node: SymbolNode): Promise<void> {
+		this.nodes.set(node.id, node);
+		if (!this.graph.hasNode(node.id)) this.graph.addNode(node.id);
+	}
+
+	async getNode(id: SymbolNodeId): Promise<SymbolNode | undefined> {
+		return this.nodes.get(id);
+	}
+
+	async addEdge(from: SymbolNodeId, to: SymbolNodeId, kind: SymbolEdgeKind): Promise<void> {
+		if (!this.graph.hasNode(from)) this.graph.addNode(from);
+		if (!this.graph.hasNode(to)) this.graph.addNode(to);
+		const edgeKey = `${from}->${to}:${kind}`;
+		if (!this.graph.hasEdge(edgeKey)) this.graph.addEdgeWithKey(edgeKey, from, to, { kind });
+	}
+
+	async edgesFrom(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]> {
+		if (!this.graph.hasNode(id)) return [];
+		return this.graph
+			.outEdges(id)
+			.filter((edgeKey) => !kind || this.graph.getEdgeAttribute(edgeKey, "kind") === kind)
+			.map((edgeKey) => this.graph.target(edgeKey));
+	}
+
+	async edgesTo(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]> {
+		if (!this.graph.hasNode(id)) return [];
+		return this.graph
+			.inEdges(id)
+			.filter((edgeKey) => !kind || this.graph.getEdgeAttribute(edgeKey, "kind") === kind)
+			.map((edgeKey) => this.graph.source(edgeKey));
+	}
+
+	async reachableFrom(id: SymbolNodeId, options: { maxDepth: number; kind?: SymbolEdgeKind }): Promise<readonly SymbolNodeId[]> {
+		if (options.maxDepth < 1 || !this.graph.hasNode(id)) return [];
+		const reached = new Set<SymbolNodeId>();
+		let frontier = new Set<SymbolNodeId>([id]);
+		for (let depth = 0; depth < options.maxDepth && frontier.size > 0; depth++) {
+			const next = new Set<SymbolNodeId>();
+			for (const current of frontier) {
+				for (const neighborId of await this.edgesFrom(current, options.kind)) {
+					if (neighborId === id || reached.has(neighborId)) continue;
+					reached.add(neighborId);
+					next.add(neighborId);
+				}
+			}
+			frontier = next;
+		}
+		return Array.from(reached);
+	}
+
+	async getGeneration(): Promise<SymbolGraphGeneration | undefined> {
+		return this.generation;
+	}
+
+	async setGeneration(generation: SymbolGraphGeneration): Promise<void> {
+		this.generation = generation;
+	}
+
+	async close(): Promise<void> {
+		this.graph.clear();
+		this.nodes.clear();
+		this.generation = undefined;
+	}
+}

package/src/adapters/in-memory-workspace.ts

@@ -0,0 +1,28 @@
+import { type ContentHash, contentHashOf } from "../domain/content-hash.ts";
+import { StaleExpectedHash } from "../domain/exact-edit.ts";
+import type { WorkspaceEntry, WorkspacePort } from "../ports/workspace-port.ts";
+
+/**
+ * InMemoryWorkspace — a WorkspacePort backed by a plain Map, for the walking
+ * skeleton and for shared conformance fixtures. Holds no file descriptors,
+ * watches nothing, and is discarded with the process; a local-filesystem
+ * adapter implements the same port for real workspaces.
+ */
+export class InMemoryWorkspace implements WorkspacePort {
+	private readonly entries = new Map<string, string>();
+
+	async readEntry(path: string): Promise<WorkspaceEntry> {
+		const content = this.entries.get(path);
+		return content === undefined ? { exists: false } : { exists: true, content };
+	}
+
+	async writeEntry(path: string, expectedHash: ContentHash | null, content: string): Promise<{ previousHash: ContentHash | null; newHash: ContentHash }> {
+		const existing = this.entries.get(path);
+		const previousHash = existing === undefined ? null : contentHashOf(existing);
+		if (previousHash !== expectedHash) {
+			throw new StaleExpectedHash(path, expectedHash, previousHash);
+		}
+		this.entries.set(path, content);
+		return { previousHash, newHash: contentHashOf(content) };
+	}
+}

package/src/adapters/local-filesystem-workspace.ts

@@ -0,0 +1,96 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { type ContentHash, contentHashOf } from "../domain/content-hash.ts";
+import { StaleExpectedHash } from "../domain/exact-edit.ts";
+import type { WorkspaceEntry, WorkspacePort } from "../ports/workspace-port.ts";
+
+const DEFAULT_NEW_FILE_MODE = 0o644;
+const PERMISSION_BITS_MASK = 0o777;
+
+/** Raised when a path would resolve outside the workspace's own root directory. */
+export class PathEscapesWorkspaceRoot extends Error {
+	constructor(
+		readonly path: string,
+		readonly root: string,
+	) {
+		super(`path "${path}" escapes workspace root "${root}"`);
+		this.name = "PathEscapesWorkspaceRoot";
+	}
+}
+
+function isEnoent(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT";
+}
+
+/**
+ * LocalFilesystemWorkspace -- a WorkspacePort backed by real files under one
+ * root directory, with expected-hash-guarded atomic writes.
+ *
+ * Writes go through a same-directory temp file, chmod'd to the target's
+ * existing mode before the rename (temp files default to a more
+ * restrictive mode, which a naive rename would otherwise leave in place).
+ */
+export class LocalFilesystemWorkspace implements WorkspacePort {
+	private readonly root: string;
+
+	constructor(root: string) {
+		this.root = resolve(root);
+	}
+
+	private resolvePath(path: string): string {
+		const absolute = resolve(this.root, path);
+		// node:path's relative(), not string-prefix concatenation: `this.root + sep` breaks for
+		// the filesystem root itself ("/" + "/" = "//", which no real absolute path starts
+		// with -- root="/" is a real, legitimate case: a path with no enclosing project root
+		// falls back to it, per pi-lector's workspaceForPath, and every such read was rejected
+		// as "escaping" a root it did not actually escape at all).
+		const relativeToRoot = relative(this.root, absolute);
+		if (relativeToRoot === ".." || relativeToRoot.startsWith(".." + sep) || isAbsolute(relativeToRoot)) {
+			throw new PathEscapesWorkspaceRoot(path, this.root);
+		}
+		return absolute;
+	}
+
+	async readEntry(path: string): Promise<WorkspaceEntry> {
+		const absolute = this.resolvePath(path);
+		try {
+			const content = await readFile(absolute, "utf-8");
+			return { exists: true, content };
+		} catch (error) {
+			if (isEnoent(error)) return { exists: false };
+			throw error;
+		}
+	}
+
+	async writeEntry(path: string, expectedHash: ContentHash | null, content: string): Promise<{ previousHash: ContentHash | null; newHash: ContentHash }> {
+		const absolute = this.resolvePath(path);
+
+		let previousHash: ContentHash | null = null;
+		let previousMode: number | undefined;
+		try {
+			const [existingContent, stats] = await Promise.all([readFile(absolute, "utf-8"), stat(absolute)]);
+			previousHash = contentHashOf(existingContent);
+			previousMode = stats.mode & PERMISSION_BITS_MASK;
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
+
+		if (previousHash !== expectedHash) {
+			throw new StaleExpectedHash(path, expectedHash, previousHash);
+		}
+
+		await mkdir(dirname(absolute), { recursive: true });
+		const tempPath = join(dirname(absolute), `.lector-${randomBytes(8).toString("hex")}.tmp`);
+		try {
+			await writeFile(tempPath, content, "utf-8");
+			await chmod(tempPath, previousMode ?? DEFAULT_NEW_FILE_MODE);
+			await rename(tempPath, absolute);
+		} catch (error) {
+			await rm(tempPath, { force: true });
+			throw error;
+		}
+
+		return { previousHash, newHash: contentHashOf(content) };
+	}
+}

package/src/adapters/local-git.ts

@@ -0,0 +1,73 @@
+import simpleGit from "simple-git";
+import { assertSafeGitArgument } from "../domain/assert-safe-git-argument.ts";
+import type { GitDiffResult } from "../domain/git-diff-result.ts";
+import type { GitLogEntry } from "../domain/git-log-entry.ts";
+import type { GitStatusSummary } from "../domain/git-status.ts";
+import type { GitPort } from "../ports/git-port.ts";
+
+/**
+ * GitPort backed by simple-git rather than a hand-rolled execFile wrapper --
+ * its status/log parsers handle real cases (staged-vs-unstaged distinction,
+ * branch ahead/behind) a first-pass implementation missed, and its
+ * `blockUnsafeOperationsPlugin` (deny-by-category: `-c` config overrides,
+ * `--upload-pack`, `--exec`, etc.) is registered unconditionally by
+ * `simpleGit()` itself -- on by default, not something this adapter has to
+ * opt into. assertSafeGitArgument on `ref` is deliberate defense in depth
+ * on top of that, not a replacement for it.
+ */
+export class LocalGit implements GitPort {
+	private readonly git: ReturnType<typeof simpleGit>;
+
+	constructor(cwd: string) {
+		this.git = simpleGit(cwd);
+	}
+
+	async isGitRepository(): Promise<boolean> {
+		try {
+			return await this.git.checkIsRepo();
+		} catch {
+			return false;
+		}
+	}
+
+	async status(): Promise<GitStatusSummary> {
+		const result = await this.git.status();
+		return {
+			files: result.files.map((file) =>
+				file.from
+					? { path: file.path, renamedFrom: file.from, indexStatus: file.index, workingDirStatus: file.working_dir }
+					: { path: file.path, indexStatus: file.index, workingDirStatus: file.working_dir },
+			),
+			ahead: result.ahead,
+			behind: result.behind,
+			current: result.current,
+			tracking: result.tracking,
+		};
+	}
+
+	async log(maxCount: number): Promise<readonly GitLogEntry[]> {
+		const result = await this.git.log({ maxCount });
+		return result.all.map((entry) => ({
+			sha: entry.hash,
+			authorName: entry.author_name,
+			authorEmail: entry.author_email,
+			authoredAt: entry.date,
+			message: entry.message,
+		}));
+	}
+
+	async diff(ref: string | undefined, maxBytes: number): Promise<GitDiffResult> {
+		const args: string[] = [];
+		if (ref !== undefined) {
+			assertSafeGitArgument(ref);
+			args.push(ref);
+		}
+		// Marks the end of options: even a validated ref can never be reinterpreted as a flag by
+		// git itself past this point -- defense in depth beyond assertSafeGitArgument and simple-git's
+		// own blockUnsafeOperationsPlugin.
+		args.push("--");
+		const raw = await this.git.diff(args);
+		const truncated = raw.length > maxBytes;
+		return { diff: truncated ? raw.slice(0, maxBytes) : raw, truncated };
+	}
+}