@gitpagedocs/tools 1.1.44

package/src/crypto/node-crypto-service.ts

@@ -0,0 +1,87 @@
+import {
+  createHash,
+  pbkdf2Sync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  timingSafeEqual,
+} from "node:crypto";
+import type { CryptoService, EncryptedPayload, KeyDerivationParams } from "../ports/crypto";
+import { SecurityError } from "../errors/app-error";
+
+const KEY_LENGTH = 32; // AES-256
+const IV_LENGTH = 12; // GCM nonce
+const DEFAULT_ITERATIONS = 210_000; // OWASP PBKDF2-SHA256 guidance
+const DIGEST = "sha256";
+
+/** Node.js implementation of the CryptoService port (CLI + MCP). */
+export class NodeCryptoService implements CryptoService {
+  constructor(private readonly iterations: number = DEFAULT_ITERATIONS) {}
+
+  async sha256(input: string): Promise<string> {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+  }
+
+  async deriveKey(password: string, params: KeyDerivationParams): Promise<Uint8Array> {
+    const salt = Buffer.from(params.salt, "base64");
+    return new Uint8Array(pbkdf2Sync(password, salt, params.iterations, KEY_LENGTH, DIGEST));
+  }
+
+  async encrypt(plaintext: string, password: string): Promise<EncryptedPayload> {
+    const kdf: KeyDerivationParams = {
+      salt: randomBytes(16).toString("base64"),
+      iterations: this.iterations,
+    };
+    const key = await this.deriveKey(password, kdf);
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    this.wipe(key);
+    return {
+      ciphertext: encrypted.toString("base64"),
+      iv: iv.toString("base64"),
+      authTag: authTag.toString("base64"),
+      kdf,
+    };
+  }
+
+  async decrypt(payload: EncryptedPayload, password: string): Promise<string> {
+    if (!payload.authTag) {
+      throw new SecurityError("Missing authentication tag for AES-256-GCM payload.");
+    }
+    const key = await this.deriveKey(password, payload.kdf);
+    try {
+      const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(payload.iv, "base64"));
+      decipher.setAuthTag(Buffer.from(payload.authTag, "base64"));
+      const decrypted = Buffer.concat([
+        decipher.update(Buffer.from(payload.ciphertext, "base64")),
+        decipher.final(),
+      ]);
+      return decrypted.toString("utf8");
+    } catch (cause) {
+      // Wrong password or tampered ciphertext both surface here.
+      throw new SecurityError("Failed to decrypt payload (wrong password or corrupted data).", { cause });
+    } finally {
+      this.wipe(key);
+    }
+  }
+
+  mask(secret: string): string {
+    if (!secret) return "";
+    if (secret.length <= 8) return "…";
+    return `${secret.slice(0, 3)}…${secret.slice(-4)}`;
+  }
+
+  wipe(buffer: Uint8Array): void {
+    buffer.fill(0);
+  }
+}
+
+/** Constant-time comparison of two hex digests. */
+export function safeHexEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a, "hex");
+  const bufB = Buffer.from(b, "hex");
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}

package/src/crypto/web-crypto-service.ts

@@ -0,0 +1,102 @@
+import type { CryptoService, EncryptedPayload, KeyDerivationParams } from "../ports/crypto";
+import { SecurityError } from "../errors/app-error";
+
+const KEY_BITS = 256;
+const IV_LENGTH = 12;
+const DEFAULT_ITERATIONS = 210_000;
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 1) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+
+function fromBase64(b64: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+// Web Crypto args must be ArrayBuffer-backed (BufferSource) under DOM lib; the
+// cast keeps this file valid under both the Node-typed and DOM-typed programs.
+function enc(text: string): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(text) as Uint8Array<ArrayBuffer>;
+}
+
+/**
+ * Web Crypto (SubtleCrypto) implementation of CryptoService for the browser.
+ * Also runs under Node 22 (globalThis.crypto). AES-GCM keeps the auth tag inside
+ * the ciphertext, so a payload encrypted here is decrypted here.
+ */
+export class WebCryptoService implements CryptoService {
+  constructor(private readonly iterations: number = DEFAULT_ITERATIONS) {}
+
+  // Return type is inferred (SubtleCrypto) to avoid pulling DOM lib type names
+  // into this Node-typed package.
+  private get subtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle) throw new SecurityError("Web Crypto API is unavailable in this runtime.");
+    return c.subtle;
+  }
+
+  async sha256(input: string): Promise<string> {
+    const digest = await this.subtle.digest("SHA-256", enc(input));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+
+  async deriveKey(password: string, params: KeyDerivationParams): Promise<Uint8Array> {
+    const bits = await this.deriveBits(password, params);
+    return new Uint8Array(bits);
+  }
+
+  private async deriveBits(password: string, params: KeyDerivationParams): Promise<ArrayBuffer> {
+    const baseKey = await this.subtle.importKey("raw", enc(password), "PBKDF2", false, ["deriveBits"]);
+    return this.subtle.deriveBits(
+      { name: "PBKDF2", salt: fromBase64(params.salt), iterations: params.iterations, hash: "SHA-256" },
+      baseKey,
+      KEY_BITS,
+    );
+  }
+
+  // Returns an AES-GCM CryptoKey (type inferred to avoid DOM lib names).
+  private async aesKey(password: string, params: KeyDerivationParams) {
+    const bits = await this.deriveBits(password, params);
+    return this.subtle.importKey("raw", bits, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+  }
+
+  async encrypt(plaintext: string, password: string): Promise<EncryptedPayload> {
+    const kdf: KeyDerivationParams = {
+      salt: toBase64(globalThis.crypto.getRandomValues(new Uint8Array(16))),
+      iterations: this.iterations,
+    };
+    const iv: Uint8Array<ArrayBuffer> = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+    const key = await this.aesKey(password, kdf);
+    const encrypted = await this.subtle.encrypt({ name: "AES-GCM", iv }, key, enc(plaintext));
+    return { ciphertext: toBase64(new Uint8Array(encrypted)), iv: toBase64(iv), kdf };
+  }
+
+  async decrypt(payload: EncryptedPayload, password: string): Promise<string> {
+    const key = await this.aesKey(password, payload.kdf);
+    try {
+      const decrypted = await this.subtle.decrypt(
+        { name: "AES-GCM", iv: fromBase64(payload.iv) },
+        key,
+        fromBase64(payload.ciphertext),
+      );
+      return new TextDecoder().decode(decrypted);
+    } catch (cause) {
+      throw new SecurityError("Failed to decrypt payload (wrong password or corrupted data).", { cause });
+    }
+  }
+
+  mask(secret: string): string {
+    if (!secret) return "";
+    if (secret.length <= 8) return "…";
+    return `${secret.slice(0, 3)}…${secret.slice(-4)}`;
+  }
+
+  wipe(buffer: Uint8Array): void {
+    buffer.fill(0);
+  }
+}

package/src/crypto/web.ts

@@ -0,0 +1,2 @@
+// Browser-safe crypto entry: Web Crypto only (no node:crypto).
+export { WebCryptoService } from "./web-crypto-service";

package/src/documentation/doc-generator.ts

@@ -0,0 +1,74 @@
+import type { AIProvider, GenerateRequest, ProviderConfig } from "../ports/ai";
+
+/** Documentation artifact kinds the generator can produce. */
+export type DocKind =
+  | "readme"
+  | "changelog"
+  | "release-notes"
+  | "api"
+  | "architecture"
+  | "database"
+  | "documentation"
+  | "update"
+  | "analyze-repository"
+  | "analyze-project"
+  | "analyze-source"
+  | "validate";
+
+const BASE_SYSTEM =
+  "You are a senior staff engineer and technical writer. Produce precise, " +
+  "well-structured GitHub-flavored Markdown. Be accurate to the provided source; " +
+  "never invent APIs, files, or behavior that is not present in the input.";
+
+const KIND_SYSTEM: Record<DocKind, string> = {
+  readme: "Generate a complete README.md: title, summary, features, install, usage, configuration, and license.",
+  changelog: "Produce a Keep a Changelog style CHANGELOG entry grouping changes under Added/Changed/Fixed/Removed.",
+  "release-notes": "Write concise, user-facing release notes highlighting notable changes and breaking changes.",
+  api: "Generate API reference documentation for the exported functions, classes, and types in the input.",
+  architecture: "Describe the architecture: layers, modules, data flow, and key design decisions. Use diagrams in text form where helpful.",
+  database: "Document the data model: entities, fields, relationships, and constraints inferred from the input.",
+  documentation: "Generate clear developer documentation for the provided code.",
+  update: "Update the existing documentation to reflect the provided source changes, preserving correct content.",
+  "analyze-repository": "Analyze the repository structure and summarize purpose, stack, modules, and notable patterns.",
+  "analyze-project": "Analyze the project and summarize architecture, dependencies, and areas of risk or improvement.",
+  "analyze-source": "Analyze the provided source code: responsibilities, complexity, issues, and suggestions.",
+  validate: "Review the documentation for accuracy, completeness, broken references, and gaps. Return a findings list.",
+};
+
+export interface GenerateDocInput {
+  readonly kind: DocKind;
+  /** Source/context material (file listing, code, existing docs, …). */
+  readonly context: string;
+  /** Optional extra user instructions. */
+  readonly instructions?: string;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Generates documentation by composing a kind-specific prompt and delegating to
+ * any AIProvider. The single place documentation prompts live, shared by the
+ * CLI, MCP and frontend.
+ */
+export class DocumentationService {
+  constructor(
+    private readonly provider: AIProvider,
+    private readonly config: ProviderConfig,
+  ) {}
+
+  buildRequest(input: GenerateDocInput): GenerateRequest {
+    const system = `${BASE_SYSTEM}\n${KIND_SYSTEM[input.kind]}`;
+    const userParts = [input.instructions, "--- INPUT ---", input.context].filter(Boolean);
+    return {
+      system,
+      messages: [{ role: "user", content: userParts.join("\n\n") }],
+      temperature: 0.2,
+      maxTokens: 4000,
+      signal: input.signal,
+    };
+  }
+
+  async generate(input: GenerateDocInput): Promise<string> {
+    const response = await this.provider.generate(this.buildRequest(input), this.config);
+    return response.text;
+  }
+}

package/src/documentation/doc-updater.ts

@@ -0,0 +1,47 @@
+import type { FileService } from "../filesystem/file-service";
+import { patchManagedRegion } from "./marker-patcher";
+
+export interface ManagedUpdate {
+  /** Target file relative to the project root. */
+  readonly path: string;
+  /** Generated content for the managed region (markers added automatically). */
+  readonly generated: string;
+}
+
+export interface UpdateResult {
+  readonly path: string;
+  /** True if an existing managed region was replaced (vs appended). */
+  readonly replaced: boolean;
+  /** True if the file content actually changed (idempotent re-runs are false). */
+  readonly changed: boolean;
+}
+
+/**
+ * Updates only the managed region of documentation files, preserving manual
+ * content. Idempotent: re-running with identical generated content leaves files
+ * untouched (`changed: false`). Built on patchManagedRegion + FileService.
+ */
+export class DocUpdater {
+  constructor(private readonly files: FileService) {}
+
+  async updateManagedFile(path: string, generated: string): Promise<UpdateResult> {
+    let existing = "";
+    try {
+      existing = await this.files.read(path, 2_000_000);
+    } catch {
+      existing = "";
+    }
+    const { content, replaced } = patchManagedRegion(existing, generated);
+    const changed = content !== existing;
+    if (changed) await this.files.write(path, content);
+    return { path, replaced, changed };
+  }
+
+  async updateManagedFiles(updates: ManagedUpdate[]): Promise<UpdateResult[]> {
+    const results: UpdateResult[] = [];
+    for (const update of updates) {
+      results.push(await this.updateManagedFile(update.path, update.generated));
+    }
+    return results;
+  }
+}

package/src/documentation/index.ts

@@ -0,0 +1,18 @@
+export { DocumentationService } from "./doc-generator";
+export type { DocKind, GenerateDocInput } from "./doc-generator";
+export {
+  patchManagedRegion,
+  START_MARKER,
+  END_MARKER,
+} from "./marker-patcher";
+export type { PatchResult } from "./marker-patcher";
+export { DocUpdater } from "./doc-updater";
+export type { ManagedUpdate, UpdateResult } from "./doc-updater";
+export {
+  providersSection,
+  cliCommandsSection,
+  devWorkflowSection,
+  securityNoteSection,
+  CLI_COMMANDS,
+} from "./sections";
+export type { CommandDoc } from "./sections";

package/src/documentation/marker-patcher.ts

@@ -0,0 +1,33 @@
+/**
+ * Idempotent marker-based content patcher. Only the region between the markers
+ * is rewritten; manual content outside is preserved. Used by update flows and
+ * the Phase 9 documentation automation.
+ */
+export const START_MARKER = "<!-- gitpagedocs:start -->";
+export const END_MARKER = "<!-- gitpagedocs:end -->";
+
+export interface PatchResult {
+  readonly content: string;
+  /** True when an existing managed region was replaced (vs appended). */
+  readonly replaced: boolean;
+}
+
+/**
+ * Replace the managed region in `existing` with `generated`. If no markers are
+ * present, the managed block is appended. Re-running with the same generated
+ * content yields identical output (idempotent).
+ */
+export function patchManagedRegion(existing: string, generated: string): PatchResult {
+  const block = `${START_MARKER}\n${generated.trim()}\n${END_MARKER}`;
+  const startIdx = existing.indexOf(START_MARKER);
+  const endIdx = existing.indexOf(END_MARKER);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + END_MARKER.length);
+    return { content: `${before}${block}${after}`, replaced: true };
+  }
+
+  const separator = existing.trim() ? `${existing.replace(/\s+$/, "")}\n\n` : "";
+  return { content: `${separator}${block}\n`, replaced: false };
+}

package/src/documentation/sections.ts

@@ -0,0 +1,82 @@
+import { PROVIDER_CATALOG, ALL_PROVIDER_IDS } from "../ai/catalog";
+
+/**
+ * Deterministic documentation section generators. Pure functions over the
+ * static catalog/command data, so the managed regions they produce are stable
+ * across runs (idempotent) and require no AI call.
+ */
+
+/** Markdown table of supported AI providers and their default models. */
+export function providersSection(): string {
+  const header = "| Provider | ID | Default model | Capabilities |\n| --- | --- | --- | --- |";
+  const rows = ALL_PROVIDER_IDS.map((id) => {
+    const spec = PROVIDER_CATALOG[id];
+    const caps = [
+      spec.capabilities.streaming ? "stream" : null,
+      spec.capabilities.vision ? "vision" : null,
+      spec.capabilities.audio ? "audio" : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    return `| ${spec.label} | \`${id}\` | \`${spec.defaultModel}\` | ${caps || "text"} |`;
+  });
+  return [`### Supported AI providers (${ALL_PROVIDER_IDS.length})`, "", header, ...rows].join("\n");
+}
+
+export interface CommandDoc {
+  readonly name: string;
+  readonly summary: string;
+}
+
+/** Markdown list of CLI commands. */
+export function cliCommandsSection(commands: readonly CommandDoc[]): string {
+  const items = commands.map((c) => `- \`gitpagedocs ${c.name}\` — ${c.summary}`);
+  return ["### CLI commands", "", ...items].join("\n");
+}
+
+/** Markdown block documenting the monorepo dev workflow (deterministic). */
+export function devWorkflowSection(): string {
+  const cmds = [
+    ["pnpm install", "install workspace dependencies"],
+    ["pnpm run typecheck", "type-check frontend + tools + mcp"],
+    ["pnpm run lint", "lint the project"],
+    ["pnpm run test:unit", "run the Vitest unit/integration suite"],
+    ["pnpm run test:cov", "unit tests with coverage"],
+    ["pnpm run test:e2e", "Playwright frontend E2E"],
+    ["pnpm run smoke:all", "CLI/contract/tools/mcp regression wall"],
+    ["pnpm run build", "build the static site"],
+  ];
+  return [
+    "### Development",
+    "",
+    "This is a pnpm + turbo monorepo: `frontend/` (Next.js viewer), `cli/` (the published `gitpagedocs` npm package), `tools/` (`@gitpagedocs/tools` shared core), and `mcp/` (`@gitpagedocs/mcp` server).",
+    "",
+    ...cmds.map(([c, d]) => `- \`${c}\` — ${d}`),
+  ].join("\n");
+}
+
+/** Markdown block summarizing how API keys are handled (deterministic). */
+export function securityNoteSection(): string {
+  return [
+    "### API key handling",
+    "",
+    "- API keys are stored **encrypted at rest** (AES-256-GCM) behind a local password — never in plaintext.",
+    "- The password gates sensitive operations and is held only in memory for the session.",
+    "- Keys are **never logged** (the logger redacts secrets) and are sent only to the AI provider you select.",
+    "- To report a vulnerability, open a security advisory or issue on the repository.",
+  ].join("\n");
+}
+
+/** The canonical command list for the documentation (legacy + new verbs). */
+export const CLI_COMMANDS: readonly CommandDoc[] = [
+  { name: "init", summary: "scaffold gitpagedocs config files" },
+  { name: "config", summary: "show the resolved gitpagedocs config" },
+  { name: "provider [id]", summary: "list AI providers or show one" },
+  { name: "models [provider]", summary: "list catalog models" },
+  { name: "document[:repo|:file|:folder]", summary: "generate documentation with AI" },
+  { name: "deploy | pages", summary: "configure GitHub Pages via Actions and push" },
+  { name: "doctor", summary: "diagnose the environment" },
+  { name: "mcp start", summary: "start the MCP server over stdio" },
+  { name: "version", summary: "print the CLI version" },
+  { name: "update", summary: "show how to update the CLI" },
+];

package/src/errors/app-error.ts

@@ -0,0 +1,84 @@
+/**
+ * Error taxonomy for @gitpagedocs/tools.
+ *
+ * Every domain error extends AppError so consumers can branch on a stable
+ * machine-readable `code` and surface `details` without leaking secrets.
+ */
+export type ErrorCode =
+  | "APP_ERROR"
+  | "VALIDATION_ERROR"
+  | "PROVIDER_ERROR"
+  | "CONFIGURATION_ERROR"
+  | "DOCUMENTATION_ERROR"
+  | "REPOSITORY_ERROR"
+  | "SECURITY_ERROR"
+  | "CACHE_ERROR";
+
+export interface AppErrorOptions {
+  /** Machine-readable, stable across versions. */
+  readonly code?: ErrorCode;
+  /** Underlying error, preserved for diagnostics. */
+  readonly cause?: unknown;
+  /** Structured, secret-free context. */
+  readonly details?: Record<string, unknown>;
+}
+
+export class AppError extends Error {
+  readonly code: ErrorCode;
+  readonly details?: Record<string, unknown>;
+
+  constructor(message: string, options: AppErrorOptions = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = new.target.name;
+    this.code = options.code ?? "APP_ERROR";
+    this.details = options.details;
+    // Preserve prototype chain when targeting ES with downleveled classes.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "VALIDATION_ERROR" });
+  }
+}
+
+export class ProviderError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "PROVIDER_ERROR" });
+  }
+}
+
+export class ConfigurationError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "CONFIGURATION_ERROR" });
+  }
+}
+
+export class DocumentationError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "DOCUMENTATION_ERROR" });
+  }
+}
+
+export class RepositoryError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "REPOSITORY_ERROR" });
+  }
+}
+
+export class SecurityError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "SECURITY_ERROR" });
+  }
+}
+
+export class CacheError extends AppError {
+  constructor(message: string, options: Omit<AppErrorOptions, "code"> = {}) {
+    super(message, { ...options, code: "CACHE_ERROR" });
+  }
+}
+
+export function isAppError(value: unknown): value is AppError {
+  return value instanceof AppError;
+}

package/src/errors/index.ts

@@ -0,0 +1 @@
+export * from "./app-error";

package/src/filesystem/file-service.ts

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { RepositoryError, ValidationError } from "../errors/app-error";
+
+const DEFAULT_IGNORE = new Set([
+  "node_modules", ".git", ".next", "out", "dist", "prebuilt", ".turbo", "coverage",
+]);
+
+export interface ListOptions {
+  recursive?: boolean;
+  maxEntries?: number;
+}
+
+export interface SearchOptions {
+  /** Restrict to files whose path includes this substring (e.g. ".ts"). */
+  extension?: string;
+  maxResults?: number;
+  maxFileBytes?: number;
+}
+
+export interface SearchMatch {
+  readonly file: string;
+  readonly line: number;
+  readonly text: string;
+}
+
+const TEXT_EXT = /\.(md|markdown|mdx|txt|json|ya?ml|ts|tsx|js|jsx|mjs|cjs|css|scss|html?|svg|toml|env)$/i;
+
+/**
+ * Root-bounded filesystem service. All paths are resolved relative to `root`
+ * and may not escape it — the single safe FS surface for the CLI and MCP.
+ */
+export class FileService {
+  constructor(private readonly root: string) {}
+
+  private resolveInside(relativePath: string): string {
+    const abs = path.resolve(this.root, relativePath);
+    const rel = path.relative(this.root, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+      throw new ValidationError(`Path escapes the project root: ${relativePath}`);
+    }
+    return abs;
+  }
+
+  private toRel(abs: string): string {
+    return path.relative(this.root, abs).split(path.sep).join("/");
+  }
+
+  async list(relativeDir = ".", options: ListOptions = {}): Promise<string[]> {
+    const { recursive = false, maxEntries = 2000 } = options;
+    const start = this.resolveInside(relativeDir);
+    const out: string[] = [];
+
+    const walk = async (dir: string): Promise<void> => {
+      if (out.length >= maxEntries) return;
+      let entries: import("node:fs").Dirent[];
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch (cause) {
+        throw new RepositoryError(`Cannot read directory: ${this.toRel(dir)}`, { cause });
+      }
+      for (const entry of entries) {
+        if (DEFAULT_IGNORE.has(entry.name)) continue;
+        if (out.length >= maxEntries) break;
+        const abs = path.join(dir, entry.name);
+        out.push(this.toRel(abs) + (entry.isDirectory() ? "/" : ""));
+        if (recursive && entry.isDirectory()) await walk(abs);
+      }
+    };
+
+    await walk(start);
+    return out.sort();
+  }
+
+  async read(relativePath: string, maxBytes = 512_000): Promise<string> {
+    const abs = this.resolveInside(relativePath);
+    const info = await stat(abs).catch((cause) => {
+      throw new RepositoryError(`File not found: ${relativePath}`, { cause });
+    });
+    if (info.size > maxBytes) {
+      throw new ValidationError(`File too large (${info.size} bytes > ${maxBytes}): ${relativePath}`);
+    }
+    return readFile(abs, "utf8");
+  }
+
+  async write(relativePath: string, content: string): Promise<string> {
+    const abs = this.resolveInside(relativePath);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, content, "utf8");
+    return this.toRel(abs);
+  }
+
+  async search(query: string, options: SearchOptions = {}): Promise<SearchMatch[]> {
+    if (!query.trim()) throw new ValidationError("Search query must not be empty.");
+    const { extension, maxResults = 200, maxFileBytes = 512_000 } = options;
+    const files = await this.list(".", { recursive: true, maxEntries: 5000 });
+    const matches: SearchMatch[] = [];
+    const needle = query.toLowerCase();
+
+    for (const file of files) {
+      if (file.endsWith("/")) continue;
+      if (extension && !file.endsWith(extension)) continue;
+      if (!extension && !TEXT_EXT.test(file)) continue;
+      if (matches.length >= maxResults) break;
+      let content: string;
+      try {
+        content = await this.read(file, maxFileBytes);
+      } catch {
+        continue;
+      }
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i].toLowerCase().includes(needle)) {
+          matches.push({ file, line: i + 1, text: lines[i].trim().slice(0, 240) });
+          if (matches.length >= maxResults) break;
+        }
+      }
+    }
+    return matches;
+  }
+}

package/src/filesystem/index.ts

@@ -0,0 +1,2 @@
+export { FileService } from "./file-service";
+export type { ListOptions, SearchOptions, SearchMatch } from "./file-service";