@bjoernrochel/sevro 0.1.0-rc.1

package/src/fixture-cleanup.ts

@@ -0,0 +1,38 @@
+import { chmod, lstat, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+function permissionFailure(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "EACCES" || code === "EPERM";
+}
+
+async function restoreDirectoryAccess(path: string): Promise<void> {
+  const entry = await lstat(path);
+  if (!entry.isDirectory()) return;
+  await chmod(path, (entry.mode & 0o7777) | 0o700);
+  for (const child of await readdir(path, { withFileTypes: true }))
+    if (child.isDirectory())
+      await restoreDirectoryAccess(join(path, child.name));
+}
+
+/** Clear a completed fixture while preserving its reserved root for active peers. */
+export async function clearFixtureContents(workspace: string): Promise<void> {
+  const root = await lstat(workspace);
+  if (!root.isDirectory())
+    throw new Error("fixture workspace is not a directory");
+  if ((root.mode & 0o700) !== 0o700)
+    await chmod(workspace, (root.mode & 0o7777) | 0o700);
+  const names = await readdir(workspace);
+  await Promise.all(
+    names.map(async (name) => {
+      const path = join(workspace, name);
+      try {
+        await rm(path, { recursive: true, force: true });
+      } catch (error) {
+        if (!permissionFailure(error)) throw error;
+        await restoreDirectoryAccess(path);
+        await rm(path, { recursive: true, force: true });
+      }
+    }),
+  );
+}

package/src/fixture-setup.ts

@@ -0,0 +1,163 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+
+const MAX_COMMAND_BYTES = 64 * 1024;
+const MAX_ENV_BYTES = 16 * 1024;
+const TIMEOUT_MS = 120_000;
+const RESERVED_ENV = new Set([
+  "PATH",
+  "HOME",
+  "TMPDIR",
+  "GIT_CONFIG_GLOBAL",
+  "GIT_CONFIG_NOSYSTEM",
+  "GIT_TERMINAL_PROMPT",
+]);
+
+export interface FixtureSetupDeclaration {
+  command: string[];
+  environment?: Record<string, string>;
+}
+
+export interface FixtureSetup extends FixtureSetupDeclaration {
+  environment: Record<string, string>;
+}
+
+/** Validate a trusted extension's bounded fixture setup command. */
+export function prepareFixtureSetup(value: unknown): FixtureSetup | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid fixture setup");
+  const input = value as Record<string, unknown>;
+  if (
+    Object.keys(input).some((key) => key !== "command" && key !== "environment")
+  )
+    throw new Error("unsupported fixture setup field");
+  const command = input.command;
+  if (
+    !Array.isArray(command) ||
+    !command.length ||
+    command.length > 16 ||
+    command.some(
+      (arg) => typeof arg !== "string" || !arg.length || arg.includes("\0"),
+    ) ||
+    !isAbsolute(command[0]) ||
+    Buffer.byteLength(command.join("\0"), "utf8") > MAX_COMMAND_BYTES
+  )
+    throw new Error("invalid fixture setup command");
+  const environment = input.environment ?? {};
+  if (
+    !environment ||
+    typeof environment !== "object" ||
+    Array.isArray(environment)
+  )
+    throw new Error("invalid fixture setup environment");
+  const entries = Object.entries(environment);
+  if (
+    entries.length > 32 ||
+    entries.some(
+      ([name, value]) =>
+        !/^[A-Z][A-Z0-9_]*$/.test(name) ||
+        RESERVED_ENV.has(name) ||
+        typeof value !== "string" ||
+        value.includes("\0") ||
+        /\{\{(?!sevro\.(?:project|workspace)\}\})/.test(value),
+    ) ||
+    Buffer.byteLength(JSON.stringify(environment), "utf8") > MAX_ENV_BYTES
+  )
+    throw new Error("invalid fixture setup environment");
+  return { command, environment: environment as Record<string, string> };
+}
+
+function stopProcess(proc: Bun.Subprocess): void {
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-proc.pid, "SIGKILL");
+      return;
+    } catch {
+      // The process group may already be gone.
+    }
+  }
+  try {
+    proc.kill("SIGKILL");
+  } catch {
+    // The process already exited.
+  }
+}
+
+/** Run setup after fixture history and before evaluator artifacts are mounted. */
+export async function runFixtureSetup(
+  setup: FixtureSetup,
+  options: {
+    workspace: string;
+    projectRoot: string;
+    fixtureBinDir?: string;
+    signal?: AbortSignal;
+  },
+): Promise<void> {
+  if (options.signal?.aborted) throw new Error("fixture setup cancelled");
+  const home = await mkdtemp(join(tmpdir(), "sevro-setup-"));
+  let proc: Bun.Subprocess | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cancel: (() => void) | undefined;
+  try {
+    const environment = Object.fromEntries(
+      Object.entries(setup.environment).map(([name, value]) => [
+        name,
+        value
+          .replaceAll("{{sevro.project}}", options.projectRoot)
+          .replaceAll("{{sevro.workspace}}", options.workspace),
+      ]),
+    );
+    proc = Bun.spawn(setup.command, {
+      cwd: options.workspace,
+      env: {
+        PATH: options.fixtureBinDir
+          ? `${options.fixtureBinDir}${delimiter}${process.env.PATH ?? "/usr/bin:/bin"}`
+          : (process.env.PATH ?? "/usr/bin:/bin"),
+        HOME: home,
+        TMPDIR: home,
+        LANG: process.env.LANG ?? "C",
+        GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null",
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_AUTHOR_NAME: "Sevro Fixture",
+        GIT_AUTHOR_EMAIL: "fixture@sevro.invalid",
+        GIT_COMMITTER_NAME: "Sevro Fixture",
+        GIT_COMMITTER_EMAIL: "fixture@sevro.invalid",
+        GIT_AUTHOR_DATE: "2000-01-01T00:00:00+00:00",
+        GIT_COMMITTER_DATE: "2000-01-01T00:00:00+00:00",
+        ...environment,
+      },
+      detached: process.platform !== "win32",
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const running = proc;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new Error("fixture setup timed out")),
+        TIMEOUT_MS,
+      );
+    });
+    const aborted = new Promise<never>((_resolve, reject) => {
+      if (!options.signal) return;
+      cancel = () => reject(new Error("fixture setup cancelled"));
+      if (options.signal.aborted) cancel();
+      else options.signal.addEventListener("abort", cancel, { once: true });
+    });
+    const code = await Promise.race([running.exited, timeout, aborted]);
+    if (code !== 0) throw new Error(`fixture setup failed (${code})`);
+  } catch (error) {
+    if (proc) {
+      stopProcess(proc);
+      await proc.exited;
+    }
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (cancel) options.signal?.removeEventListener("abort", cancel);
+    await rm(home, { recursive: true, force: true });
+  }
+}

package/src/generated-fixture.ts

@@ -0,0 +1,220 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { canonicalJson } from "./identity";
+import { prepareFixtureBin } from "./fixture-bin";
+import { prepareGitHooks } from "./git-hooks";
+import { fixtureParts } from "./preparation";
+
+const MAX_COMMITS = 128;
+const MAX_FILES = 1024;
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_GIT_OUTPUT = 64 * 1024;
+
+export interface GeneratedFixture {
+  kind: "generated";
+  commits: { message: string; files: Record<string, string> }[];
+  files?: Record<string, string>;
+  staged?: string[];
+  commitFiles?: boolean;
+  hooks?: Record<string, string>;
+  bin?: Record<string, string>;
+}
+
+function validFiles(value: unknown): value is Record<string, string> {
+  return (
+    Boolean(value && typeof value === "object" && !Array.isArray(value)) &&
+    Object.values(value as object).every((item) => typeof item === "string")
+  );
+}
+
+function validPath(path: string): void {
+  const parts = fixtureParts(path);
+  if (parts.some((part) => part.toLowerCase() === ".git"))
+    throw new Error("generated fixture cannot write repository metadata");
+}
+
+/** Freeze a bounded declarative history before any host or fixture work. */
+export function prepareGeneratedFixture(value: unknown): GeneratedFixture {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid generated fixture");
+  const fixture = value as Record<string, unknown>;
+  if (
+    fixture.kind !== "generated" ||
+    Object.keys(fixture).some(
+      (key) =>
+        ![
+          "kind",
+          "commits",
+          "files",
+          "staged",
+          "commitFiles",
+          "hooks",
+          "bin",
+        ].includes(key),
+    ) ||
+    !Array.isArray(fixture.commits) ||
+    fixture.commits.length > MAX_COMMITS ||
+    (fixture.files !== undefined && !validFiles(fixture.files)) ||
+    (fixture.staged !== undefined &&
+      (!Array.isArray(fixture.staged) ||
+        !fixture.staged.every((item: unknown) => typeof item === "string"))) ||
+    (fixture.commitFiles !== undefined &&
+      typeof fixture.commitFiles !== "boolean")
+  )
+    throw new Error("invalid generated fixture");
+  prepareGitHooks(fixture.hooks);
+  prepareFixtureBin(fixture.bin);
+  let bytes = 0;
+  let files = 0;
+  const paths: string[] = [];
+  for (const commit of fixture.commits) {
+    if (
+      !commit ||
+      typeof commit !== "object" ||
+      Array.isArray(commit) ||
+      Object.keys(commit).some((key) => key !== "message" && key !== "files") ||
+      typeof commit.message !== "string" ||
+      !commit.message.trim() ||
+      Buffer.byteLength(commit.message, "utf8") > 4096 ||
+      !validFiles(commit.files) ||
+      Object.keys(commit.files).length === 0
+    )
+      throw new Error("invalid generated fixture commit");
+    bytes += Buffer.byteLength(commit.message, "utf8");
+    for (const [path, content] of Object.entries(
+      commit.files as Record<string, string>,
+    )) {
+      validPath(path);
+      paths.push(path);
+      files++;
+      bytes +=
+        Buffer.byteLength(path, "utf8") + Buffer.byteLength(content, "utf8");
+    }
+  }
+  const overlay = (fixture.files ?? {}) as Record<string, string>;
+  for (const [path, content] of Object.entries(overlay)) {
+    validPath(path);
+    paths.push(path);
+    files++;
+    bytes +=
+      Buffer.byteLength(path, "utf8") + Buffer.byteLength(content, "utf8");
+  }
+  bytes += ((fixture.staged ?? []) as string[]).reduce(
+    (size, path) => size + Buffer.byteLength(path, "utf8"),
+    0,
+  );
+  if (files > MAX_FILES || bytes > MAX_BYTES)
+    throw new Error("generated fixture exceeds the size limit");
+  const unique = [...new Set(paths)];
+  const normalized = unique.map((path) => path.toLowerCase());
+  for (let index = 0; index < normalized.length; index++) {
+    for (let other = 0; other < index; other++) {
+      if (
+        normalized[index] === normalized[other] ||
+        normalized[index]!.startsWith(`${normalized[other]}/`) ||
+        normalized[other]!.startsWith(`${normalized[index]}/`)
+      )
+        throw new Error("generated fixture paths collide");
+    }
+  }
+  const staged = (fixture.staged ?? []) as string[];
+  if (
+    new Set(staged.map((path) => path.toLowerCase())).size !== staged.length ||
+    staged.some((path) => !Object.hasOwn(overlay, path)) ||
+    (fixture.commitFiles === true && Object.keys(overlay).length === 0)
+  )
+    throw new Error("invalid generated fixture staging");
+  return JSON.parse(canonicalJson(fixture)) as GeneratedFixture;
+}
+
+async function git(workspace: string, args: string[]): Promise<void> {
+  async function bounded(stream: ReadableStream<Uint8Array>): Promise<void> {
+    let size = 0;
+    for await (const chunk of stream) {
+      size += chunk.byteLength;
+      if (size > MAX_GIT_OUTPUT)
+        throw new Error("generated fixture Git output is too large");
+    }
+  }
+  const proc = Bun.spawn(
+    [
+      "git",
+      "-c",
+      `core.hooksPath=${process.platform === "win32" ? "NUL" : "/dev/null"}`,
+      ...args,
+    ],
+    {
+      cwd: workspace,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        ...(process.env.SystemRoot
+          ? { SystemRoot: process.env.SystemRoot }
+          : {}),
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null",
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_AUTHOR_NAME: "Sevro Fixture",
+        GIT_AUTHOR_EMAIL: "fixture@sevro.invalid",
+        GIT_COMMITTER_NAME: "Sevro Fixture",
+        GIT_COMMITTER_EMAIL: "fixture@sevro.invalid",
+        GIT_AUTHOR_DATE: "2000-01-01T00:00:00+00:00",
+        GIT_COMMITTER_DATE: "2000-01-01T00:00:00+00:00",
+      },
+    },
+  );
+  try {
+    const [, , code] = await Promise.all([
+      bounded(proc.stdout),
+      bounded(proc.stderr),
+      proc.exited,
+    ]);
+    if (code !== 0) throw new Error();
+  } catch {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // The process may have exited before the failure was observed.
+    }
+    await proc.exited;
+    throw new Error("generated fixture Git operation failed");
+  }
+}
+
+async function writeFiles(
+  workspace: string,
+  files: Record<string, string>,
+): Promise<void> {
+  for (const [path, content] of Object.entries(files)) {
+    const target = join(workspace, ...fixtureParts(path));
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(target, content, { flag: "w", mode: 0o600 });
+  }
+}
+
+/** Build a deterministic local Git history, then apply working-tree state. */
+export async function materializeGeneratedFixture(
+  fixture: GeneratedFixture,
+  workspace: string,
+): Promise<void> {
+  await git(workspace, ["init", "--quiet", "--initial-branch=main"]);
+  for (const commit of fixture.commits) {
+    await writeFiles(workspace, commit.files);
+    await git(workspace, ["add", "--", ...Object.keys(commit.files)]);
+    await git(workspace, ["commit", "--quiet", "-m", commit.message]);
+  }
+  const overlay = fixture.files ?? {};
+  await writeFiles(workspace, overlay);
+  if (fixture.commitFiles) {
+    await git(workspace, ["add", "--", ...Object.keys(overlay)]);
+    await git(workspace, [
+      "commit",
+      "--quiet",
+      "-m",
+      "Add evaluation scaffolding",
+    ]);
+  }
+  if (fixture.staged?.length)
+    await git(workspace, ["add", "--", ...fixture.staged]);
+}

package/src/git-hooks.ts

@@ -0,0 +1,63 @@
+import { chmod, lstat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const MAX_HOOKS = 32;
+const MAX_HOOK_BYTES = 1024 * 1024;
+
+/** Bound hook declarations and keep every name inside Git's hooks directory. */
+export function prepareGitHooks(value: unknown): Record<string, string> | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid fixture hooks");
+  const hooks = value as Record<string, unknown>;
+  const entries = Object.entries(hooks);
+  if (
+    entries.length > MAX_HOOKS ||
+    entries.some(
+      ([name, content]) =>
+        !/^[a-z][a-z0-9-]*$/.test(name) ||
+        name.length > 64 ||
+        typeof content !== "string" ||
+        !content ||
+        content.includes("\0"),
+    ) ||
+    entries.reduce(
+      (size, [name, content]) =>
+        size +
+        Buffer.byteLength(name, "utf8") +
+        Buffer.byteLength(content as string, "utf8"),
+      0,
+    ) > MAX_HOOK_BYTES
+  )
+    throw new Error("invalid fixture hooks");
+  return hooks as Record<string, string>;
+}
+
+/** Install executable hooks only after fixture commits and overlays are ready. */
+export async function installGitHooks(
+  hooks: Record<string, string> | undefined,
+  workspace: string,
+): Promise<void> {
+  if (!hooks) return;
+  const directory = join(workspace, ".git", "hooks");
+  const root = await lstat(directory);
+  if (!root.isDirectory() || root.isSymbolicLink())
+    throw new Error("fixture Git hooks directory is invalid");
+  for (const [name, content] of Object.entries(hooks)) {
+    const target = join(directory, name);
+    try {
+      const existing = await lstat(target);
+      if (!existing.isFile() || existing.isSymbolicLink())
+        throw new Error("fixture Git hook target is invalid");
+    } catch (error) {
+      if (!(
+        error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT"
+      ))
+        throw error;
+    }
+    await writeFile(target, content, { mode: 0o755 });
+    await chmod(target, 0o755);
+  }
+}

package/src/graders/git-head.ts

@@ -0,0 +1,176 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+
+const MAX_OUTPUT_BYTES = 128;
+const TIMEOUT_MS = 10_000;
+const REVISION = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+export interface GitHeadCheckDeclaration {
+  id: string;
+  grader: "sevro.git-head";
+  configuration: Record<string, unknown>;
+}
+
+export interface PreparedGitHeadCheck {
+  id: string;
+  kind: "changed" | "unchanged" | "base-ancestor";
+}
+
+export function prepareGitHeadChecks(
+  declarations: GitHeadCheckDeclaration[],
+): PreparedGitHeadCheck[] {
+  return declarations.map(({ id, configuration }) => {
+    if (
+      !id ||
+      !configuration ||
+      typeof configuration !== "object" ||
+      Object.keys(configuration).some((key) => key !== "kind") ||
+      (configuration.kind !== "changed" &&
+        configuration.kind !== "unchanged" &&
+        configuration.kind !== "base-ancestor")
+    )
+      throw new Error("invalid Git HEAD check declaration");
+    return { id, kind: configuration.kind };
+  });
+}
+
+async function boundedOutput(
+  stream: ReadableStream<Uint8Array>,
+): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_OUTPUT_BYTES)
+      throw new Error("Git HEAD output is oversized");
+    chunks.push(value);
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(
+    Buffer.concat(chunks),
+  );
+}
+
+function stopProcess(proc: Bun.Subprocess): void {
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-proc.pid, "SIGKILL");
+      return;
+    } catch {
+      // The process group may already have exited.
+    }
+  }
+  try {
+    proc.kill("SIGKILL");
+  } catch {
+    // The process already exited.
+  }
+}
+
+async function git(
+  workspace: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<{ code: number; output: string }> {
+  if (signal?.aborted) throw new Error("Git HEAD check cancelled");
+  const gitDirectory = await lstat(join(workspace, ".git"));
+  if (!gitDirectory.isDirectory() || gitDirectory.isSymbolicLink())
+    throw new Error("Git fixture metadata is not a directory");
+  const proc = Bun.spawn(["git", ...args], {
+    cwd: workspace,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    detached: process.platform !== "win32",
+    env: {
+      PATH: process.env.PATH ?? "/usr/bin:/bin",
+      ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+      GIT_CONFIG_NOSYSTEM: "1",
+      GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null",
+      GIT_NO_REPLACE_OBJECTS: "1",
+      GIT_TERMINAL_PROMPT: "0",
+    },
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cancel: (() => void) | undefined;
+  try {
+    const complete = Promise.all([
+      boundedOutput(proc.stdout),
+      proc.exited,
+    ]).then(([output, code]) => ({ output: output.trim(), code }));
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new Error("Git HEAD check timed out")),
+        TIMEOUT_MS,
+      );
+    });
+    const aborted = new Promise<never>((_resolve, reject) => {
+      if (!signal) return;
+      cancel = () => reject(new Error("Git HEAD check cancelled"));
+      signal.addEventListener("abort", cancel, { once: true });
+      if (signal.aborted) cancel();
+    });
+    return await Promise.race([complete, timeout, aborted]);
+  } catch (error) {
+    stopProcess(proc);
+    await proc.exited;
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (cancel) signal?.removeEventListener("abort", cancel);
+  }
+}
+
+export async function gitHeadRevision(
+  workspace: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await git(
+    workspace,
+    ["rev-parse", "--verify", "HEAD^{commit}"],
+    signal,
+  );
+  if (result.code !== 0 || !REVISION.test(result.output))
+    throw new Error("Git HEAD revision is unavailable");
+  return result.output;
+}
+
+export async function gitHeadState(
+  workspace: string,
+  baseRevision: string,
+  signal?: AbortSignal,
+): Promise<{ currentRevision: string; baseAncestor: boolean }> {
+  if (!REVISION.test(baseRevision)) throw new Error("invalid base revision");
+  const currentRevision = await gitHeadRevision(workspace, signal);
+  const ancestry = await git(
+    workspace,
+    ["merge-base", "--is-ancestor", baseRevision, currentRevision],
+    signal,
+  );
+  if (ancestry.code !== 0 && ancestry.code !== 1)
+    throw new Error("Git HEAD ancestry is unavailable");
+  return { currentRevision, baseAncestor: ancestry.code === 0 };
+}
+
+export function assessGitHeadCheck(
+  check: PreparedGitHeadCheck,
+  baseRevision: string,
+  state: { currentRevision: string; baseAncestor: boolean },
+): { passed: boolean; detail: string } {
+  if (check.kind === "unchanged")
+    return {
+      passed: state.currentRevision === baseRevision,
+      detail: "candidate created or switched to a different commit",
+    };
+  if (check.kind === "changed")
+    return {
+      passed: state.currentRevision !== baseRevision,
+      detail: "candidate did not create the expected commit",
+    };
+  return {
+    passed: state.baseAncestor,
+    detail: "candidate replaced or diverged from the fixture history",
+  };
+}