@ogygie/core 0.8.0 → 0.10.0

package/src/repo-adapter.ts

@@ -0,0 +1,307 @@
+/**
+ * @intent READ-ONLY access to an Ogygie repo, and the only place the framework
+ * touches a repo's disk (DECISIONS.md D10).
+ *
+ * Two tools already need it — the studio, which projects specs into a local
+ * UI, and the MCP server, which serves them to a design space (spec
+ * ogygie-mcp). Two filesystem adapters would be a lockstep bug waiting to
+ * happen: the traversal guard fixed on one side and not the other. So the
+ * interface and its implementations live here, once.
+ *
+ * Writing is NEVER declared in `RepoAdapter`. A tool that writes COMPOSES —
+ * the studio's `SpecStorage` extends this interface with its `write`. That way
+ * the read-only promise of a consumer is checkable by what it consumes, not by
+ * a comment.
+ *
+ * No dependency, on purpose: the git ref is read straight out of `.git`
+ * (D10 excludes a git library for it), so a project installing the core to
+ * validate its manifest drags nothing along.
+ */
+import { readFile as readFileFromDisk, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { z } from "zod";
+import { throwOgygieError } from "./error.schema.js";
+
+export const RepoFileEntrySchema = z.object({
+  /** Path relative to the LISTED directory, "/" separated, never absolute. */
+  path: z.string(),
+  sizeBytes: z.number().int().nonnegative(),
+});
+export type RepoFileEntry = z.infer<typeof RepoFileEntrySchema>;
+
+/**
+ * What a repo can be asked. Four methods, all reading — the shape a consumer
+ * declares when it promises to touch nothing.
+ */
+export interface RepoAdapter {
+  /** UTF-8 content of one file. Refuses a path escaping the repo. */
+  readFile(relativePath: string): Promise<string>;
+  /**
+   * Files under a directory, RECURSIVELY, sorted by path. An absent directory
+   * lists EMPTY rather than failing: a feature declared in the manifest but
+   * not yet written is a legitimate state the map already explains.
+   */
+  listDirectory(relativePath: string): Promise<RepoFileEntry[]>;
+  exists(relativePath: string): Promise<boolean>;
+  /** HEAD commit SHA, or null when the root is not a git clone. */
+  currentRef(): Promise<string | null>;
+}
+
+/**
+ * Directories a repo reader never descends into. Not a blocklist of "bad"
+ * paths — a reader that returned forty thousand `node_modules` entries would
+ * simply be unusable, and nothing under a dot-directory is repo source. The
+ * traversal guard below is what protects, this only keeps listings useful.
+ */
+const NEVER_LISTED = new Set(["node_modules"]);
+
+function isSkippedDirectory(name: string): boolean {
+  return name.startsWith(".") || NEVER_LISTED.has(name);
+}
+
+function refusePathOutsideRepo(relativePath: string, cause: string): never {
+  return throwOgygieError(
+    {
+      code: "PATH_OUTSIDE_REPO",
+      message: "The requested path resolves outside the repo root.",
+      file: relativePath,
+      cause,
+      suggestedFix:
+        "Address a path INSIDE the repo, written relative to its root and without `..`.",
+    },
+    400,
+  );
+}
+
+/**
+ * Textual guard: absolute paths and `..` never reach the disk.
+ *
+ * The prefix test carries a separator on purpose — `/srv/repo-evil` starts
+ * with `/srv/repo` as a string, and a guard that forgets it lets a sibling
+ * directory through (the form this check had while it lived in the studio).
+ */
+function resolveInsideRoot(rootDir: string, relativePath: string): string {
+  if (isAbsolute(relativePath)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" is an absolute path`);
+  }
+  const root = resolve(rootDir);
+  const absolute = resolve(root, relativePath);
+  if (absolute !== root && !absolute.startsWith(root + sep)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" resolves to "${absolute}", outside "${root}"`);
+  }
+  return absolute;
+}
+
+/**
+ * Second guard, for what the first cannot see: a symlink INSIDE the repo
+ * pointing out of it resolves to a clean relative path and still reads someone
+ * else's file. Only checked when the target exists — when it does not, nothing
+ * is read anyway, and `exists` must be able to answer "no" without an error.
+ */
+async function assertRealPathInsideRoot(
+  rootDir: string,
+  absolute: string,
+  relativePath: string,
+): Promise<void> {
+  let realRoot: string;
+  let realTarget: string;
+  try {
+    realRoot = await realpath(rootDir);
+    realTarget = await realpath(absolute);
+  } catch {
+    return;
+  }
+  if (realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)) {
+    refusePathOutsideRepo(
+      relativePath,
+      `"${relativePath}" is a symbolic link leading to "${realTarget}", outside "${realRoot}"`,
+    );
+  }
+}
+
+async function listFilesRecursively(
+  absoluteDir: string,
+  prefix: string,
+): Promise<RepoFileEntry[]> {
+  let entries;
+  try {
+    entries = await readdir(absoluteDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files: RepoFileEntry[] = [];
+  for (const entry of entries) {
+    const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (isSkippedDirectory(entry.name)) continue;
+      files.push(...(await listFilesRecursively(join(absoluteDir, entry.name), relativePath)));
+    } else if (entry.isFile()) {
+      const stats = await stat(join(absoluteDir, entry.name));
+      files.push({ path: relativePath, sizeBytes: stats.size });
+    }
+  }
+  return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/**
+ * Where git really keeps its state for this root.
+ *
+ * `.git` is a directory in a plain clone and a FILE in a worktree, pointing at
+ * the real git dir; a reader that only knows the first form answers "not a git
+ * clone" for every worktree — silently, since a null ref is a legitimate
+ * answer elsewhere. Branch refs then live in the COMMON dir shared with the
+ * main clone, which `commondir` names.
+ */
+async function resolveGitDirs(rootDir: string): Promise<{ gitDir: string; commonDir: string } | null> {
+  const dotGit = join(rootDir, ".git");
+  let gitDir: string;
+  try {
+    const stats = await stat(dotGit);
+    if (stats.isDirectory()) {
+      gitDir = dotGit;
+    } else {
+      const pointer = (await readFileFromDisk(dotGit, "utf8")).trim();
+      const target = pointer.startsWith("gitdir:") ? pointer.slice("gitdir:".length).trim() : "";
+      if (target === "") return null;
+      gitDir = isAbsolute(target) ? target : resolve(rootDir, target);
+    }
+  } catch {
+    return null;
+  }
+  try {
+    const commonPointer = (await readFileFromDisk(join(gitDir, "commondir"), "utf8")).trim();
+    return { gitDir, commonDir: isAbsolute(commonPointer) ? commonPointer : resolve(gitDir, commonPointer) };
+  } catch {
+    return { gitDir, commonDir: gitDir };
+  }
+}
+
+/** A ref name resolved to its SHA — loose file first, then `packed-refs`. */
+async function readRefSha(
+  dirs: { gitDir: string; commonDir: string },
+  refName: string,
+): Promise<string | null> {
+  for (const base of [dirs.gitDir, dirs.commonDir]) {
+    try {
+      const sha = (await readFileFromDisk(join(base, refName), "utf8")).trim();
+      if (sha !== "") return sha;
+    } catch {
+      // Not stored loose here — try the next location, then packed-refs.
+    }
+  }
+  try {
+    const packed = await readFileFromDisk(join(dirs.commonDir, "packed-refs"), "utf8");
+    for (const line of packed.split("\n")) {
+      if (line.startsWith("#") || line.startsWith("^")) continue;
+      const [sha, name] = line.trim().split(" ");
+      if (name === refName && sha !== undefined && sha !== "") return sha;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * The repo as it sits on this disk, at this instant. Every path is relative to
+ * `rootDir` and guarded twice (textually, then through symlinks).
+ */
+export function createFilesystemRepoAdapter(rootDir: string): RepoAdapter {
+  return {
+    async readFile(relativePath: string): Promise<string> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        return await readFileFromDisk(absolute, "utf8");
+      } catch (thrown) {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file cannot be read from the repo.",
+          file: relativePath,
+          cause: `reading "${absolute}" failed: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+          suggestedFix:
+            "Check the path against what the map declares — the manifest is the only chart of a repo.",
+        });
+      }
+    },
+
+    async listDirectory(relativePath: string): Promise<RepoFileEntry[]> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      return listFilesRecursively(absolute, "");
+    },
+
+    async exists(relativePath: string): Promise<boolean> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        await stat(absolute);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    async currentRef(): Promise<string | null> {
+      const dirs = await resolveGitDirs(rootDir);
+      if (dirs === null) return null;
+      let head: string;
+      try {
+        head = (await readFileFromDisk(join(dirs.gitDir, "HEAD"), "utf8")).trim();
+      } catch {
+        return null;
+      }
+      // Detached HEAD holds the SHA itself; otherwise it names a ref.
+      if (!head.startsWith("ref:")) return head === "" ? null : head;
+      return readRefSha(dirs, head.slice("ref:".length).trim());
+    },
+  };
+}
+
+/** Fixture repo for the tests (principle 7: no disk, no network). */
+export interface InMemoryRepoAdapterOptions {
+  /** What `currentRef()` answers — null models a root that is not a clone. */
+  ref?: string | null;
+}
+
+export function createInMemoryRepoAdapter(
+  files: Record<string, string>,
+  options: InMemoryRepoAdapterOptions = {},
+): RepoAdapter {
+  const contents = new Map(Object.entries(files));
+  const ref = options.ref === undefined ? "0".repeat(40) : options.ref;
+  const sizeOf = (content: string): number => Buffer.byteLength(content, "utf8");
+  return {
+    async readFile(relativePath: string): Promise<string> {
+      const content = contents.get(relativePath);
+      if (content === undefined) {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file does not exist in the in-memory repo.",
+          file: relativePath,
+          cause: `no entry for "${relativePath}"`,
+          suggestedFix: "Arrange the file in the fixture passed to createInMemoryRepoAdapter.",
+        });
+      }
+      return content;
+    },
+
+    async listDirectory(relativePath: string): Promise<RepoFileEntry[]> {
+      const prefix = relativePath === "" || relativePath === "." ? "" : `${relativePath.replace(/\/$/, "")}/`;
+      return [...contents.entries()]
+        .filter(([path]) => path.startsWith(prefix))
+        .map(([path, content]) => ({ path: path.slice(prefix.length), sizeBytes: sizeOf(content) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    },
+
+    async exists(relativePath: string): Promise<boolean> {
+      if (contents.has(relativePath)) return true;
+      const prefix = `${relativePath.replace(/\/$/, "")}/`;
+      return [...contents.keys()].some((path) => path.startsWith(prefix));
+    },
+
+    async currentRef(): Promise<string | null> {
+      return ref;
+    },
+  };
+}