@evo-dev/core 0.0.1-alpha.2 → 0.0.1-alpha.4

package/src/team/index.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { appendFile, cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { resolveEvoDevPaths } from "../config/paths.ts";
 import {
   createDefaultSettings,
@@ -12,7 +12,7 @@ import {
   formatScopedKnowledgePromptBlock,
   hasContextInjectionReceipt,
   writeContextInjectionReceipt,
-} from "../knowledge/index.ts";
+} from "../evolution/knowledge/index.ts";
 import { resolveProjectLogKey } from "../runtime-logs/index.ts";
 import { renderTeamRoleStartupPrompt } from "./prompts.ts";
 
@@ -161,7 +161,7 @@ export interface TeamRoleDefinition {
   prompt: string;
   permissions: TeamRolePermissions;
   teamPolicy: TeamRolePolicy;
-  source: "builtin" | "global";
+  source: "builtin" | "global" | "overlay";
 }
 
 export interface ResolvedTeamRole extends TeamRoleDefinition {
@@ -178,6 +178,59 @@ export interface TeamNativeAgentBinding {
   updatedAt: string;
 }
 
+export type TeamOverlaySource = "repo" | "global" | "builtin";
+
+export interface TeamDefinition {
+  version: 1;
+  name: string;
+  description: string;
+  agents: Record<string, string>;
+  body: string;
+}
+
+export interface TeamOverlayResolution {
+  source: TeamOverlaySource;
+  teamPath: string | null;
+  definition: TeamDefinition;
+}
+
+export interface TeamAgentReference {
+  roleId: string;
+  reference: string;
+  sourcePath: string;
+  scope: "repo" | "global";
+}
+
+export interface TeamOverlayAgentSummary {
+  roleId: string;
+  name: string;
+  description: string;
+  sourcePath: string;
+}
+
+export interface TeamAgentDefinition {
+  roleId: string;
+  name: string;
+  description: string;
+  runtime: TeamAgentRuntime | null;
+  model: string | null;
+  thinkingLevel: string | null;
+  writeMode: TeamWriteMode | null;
+  skills: string[];
+  sourcePath: string;
+  markdown: string;
+}
+
+export interface DefaultTeamOverlayFileResult {
+  sourcePath: string;
+  targetPath: string;
+  written: boolean;
+}
+
+export interface EnsureDefaultTeamOverlayResult {
+  files: DefaultTeamOverlayFileResult[];
+}
+
 export interface TeamRoleBindingRecord {
   version: 1;
   roleId: string;
@@ -654,6 +707,22 @@ const BUILT_IN_ROLE_PROMPTS: Record<
       "You are the implementation executor for this EvoDev team run. Keep changes scoped, avoid taking conductor decisions, and report changed files plus verification evidence.",
   },
 };
+const BUILT_IN_TEAM_DEFINITION: TeamDefinition = {
+  version: 1,
+  name: "builtin-minimal-team",
+  description: "Built-in minimal EvoDev team fallback.",
+  agents: {
+    executor: "builtin:executor",
+    reviewer: "builtin:reviewer",
+    tester: "builtin:tester",
+  },
+  body: [
+    "# Built-in Minimal Team",
+    "",
+    "Use role agents only when delegation improves correctness, coverage, safety, or latency.",
+    "Spawn roles on demand and send self-contained assignments through Teams MCP.",
+  ].join("\n"),
+};
 
 export function createTeamRunStore(homeDir?: string): TeamRunStore {
   const paths = resolveTeamRunPaths(homeDir);
@@ -1908,6 +1977,216 @@ export async function listTeamAgents(input: TeamStatusInput = {}): Promise<TeamA
   }));
 }
 
+export async function resolveTeamOverlay(input: {
+  homeDir?: string;
+  repoRoot: string;
+}): Promise<TeamOverlayResolution> {
+  const repoTeamPath = join(input.repoRoot, ".evodev", "team", "team.md");
+  if (await pathExists(repoTeamPath)) {
+    return {
+      source: "repo",
+      teamPath: repoTeamPath,
+      definition: parseTeamDefinitionMarkdown(await readFile(repoTeamPath, "utf8")),
+    };
+  }
+
+  const globalTeamPath = resolveGlobalTeamMarkdownPath(input.homeDir);
+  if (await pathExists(globalTeamPath)) {
+    return {
+      source: "global",
+      teamPath: globalTeamPath,
+      definition: parseTeamDefinitionMarkdown(await readFile(globalTeamPath, "utf8")),
+    };
+  }
+
+  return {
+    source: "builtin",
+    teamPath: null,
+    definition: BUILT_IN_TEAM_DEFINITION,
+  };
+}
+
+export async function ensureDefaultTeamOverlay(input: {
+  homeDir?: string;
+  assetsRootDir: string;
+}): Promise<EnsureDefaultTeamOverlayResult> {
+  const assets = await listDefaultTeamOverlayAssets(input.assetsRootDir);
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const files: DefaultTeamOverlayFileResult[] = [];
+
+  for (const asset of assets) {
+    const targetPath =
+      asset.kind === "team"
+        ? join(paths.rootDir, "team", "team.md")
+        : join(paths.rootDir, "team", "agents", asset.name);
+    const content = await readFile(asset.sourcePath, "utf8");
+    files.push({
+      sourcePath: asset.sourcePath,
+      targetPath,
+      written: await writeTextFileIfMissing(targetPath, content),
+    });
+  }
+
+  return { files };
+}
+
+export function parseTeamDefinitionMarkdown(content: string): TeamDefinition {
+  const markdown = parseMarkdownWithFrontmatter(content);
+  const frontmatter = markdown.frontmatter;
+  const version = frontmatter.version;
+  if (version !== 1) throw new Error("team.md frontmatter version must be 1.");
+  const agents = parseTeamDefinitionAgents(frontmatter.agents);
+
+  return {
+    version: 1,
+    name: optionalString(frontmatter.name) ?? "evodev-team",
+    description: optionalString(frontmatter.description) ?? "EvoDev team overlay.",
+    agents,
+    body: markdown.body.trim(),
+  };
+}
+
+export function resolveTeamAgentReference(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): TeamAgentReference {
+  assertSafeId(input.roleId, "roleId");
+  const reference = input.reference.trim();
+  if (reference.startsWith("global:")) {
+    const name = reference.slice("global:".length);
+    assertSafeId(name, "global agent name");
+    return {
+      roleId: input.roleId,
+      reference,
+      sourcePath: join(resolveEvoDevPaths(input.homeDir).rootDir, "team", "agents", `${name}.md`),
+      scope: "global",
+    };
+  }
+
+  if (reference.includes(":")) {
+    throw new Error(`Unsupported team agent reference for ${input.roleId}: ${reference}`);
+  }
+  if (isAbsolute(reference)) {
+    throw new Error(`Team agent path for ${input.roleId} must be repo-relative.`);
+  }
+  const sourcePath = resolve(input.repoRoot, reference);
+  const relativePath = relative(input.repoRoot, sourcePath);
+  if (
+    relativePath === "" ||
+    relativePath.startsWith("..") ||
+    isAbsolute(relativePath) ||
+    extname(sourcePath) !== ".md"
+  ) {
+    throw new Error(`Team agent path for ${input.roleId} must be a repo-local Markdown file.`);
+  }
+
+  return {
+    roleId: input.roleId,
+    reference,
+    sourcePath,
+    scope: "repo",
+  };
+}
+
+export async function readTeamAgentSummary(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): Promise<TeamOverlayAgentSummary> {
+  const reference = resolveTeamAgentReference(input);
+  const markdown = await readTeamAgentMarkdown(reference);
+  const parsed = parseMarkdownWithFrontmatter(markdown);
+  return {
+    roleId: input.roleId,
+    name: optionalString(parsed.frontmatter.name) ?? defaultRoleName(input.roleId),
+    description:
+      optionalString(parsed.frontmatter.description) ?? `EvoDev ${input.roleId} role agent.`,
+    sourcePath: reference.sourcePath,
+  };
+}
+
+export async function readTeamAgentDefinition(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): Promise<TeamAgentDefinition> {
+  const reference = resolveTeamAgentReference(input);
+  const markdown = await readTeamAgentMarkdown(reference);
+  const parsed = parseMarkdownWithFrontmatter(markdown);
+  const evodev = isRecord(parsed.frontmatter.evodev) ? parsed.frontmatter.evodev : {};
+  return {
+    roleId: input.roleId,
+    name: optionalString(parsed.frontmatter.name) ?? defaultRoleName(input.roleId),
+    description:
+      optionalString(parsed.frontmatter.description) ?? `EvoDev ${input.roleId} role agent.`,
+    runtime: optionalRuntime(evodev.runtime),
+    model: optionalNullableString(parsed.frontmatter.model) ?? null,
+    thinkingLevel:
+      optionalNullableString(evodev.thinking) ??
+      optionalNullableString(evodev.thinkingLevel) ??
+      null,
+    writeMode: optionalWriteMode(evodev.writeMode),
+    skills: parseStringList(evodev.skills),
+    sourcePath: reference.sourcePath,
+    markdown,
+  };
+}
+
+export async function renderMainTeamOverlayContext(input: {
+  homeDir?: string;
+  repoRoot: string;
+  overlay?: TeamOverlayResolution;
+}): Promise<string> {
+  const overlay = input.overlay ?? (await resolveTeamOverlay(input));
+  const summaries = await readTeamOverlayAgentSummaries({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    overlay,
+  });
+  const roleLines =
+    summaries.length === 0
+      ? ["- none declared"]
+      : summaries.map((summary) => `- ${summary.roleId}: ${summary.name} - ${summary.description}`);
+  const source =
+    overlay.teamPath === null
+      ? `${overlay.source} fallback`
+      : `${overlay.source}: ${overlay.teamPath}`;
+
+  return [
+    "EvoDev team overlay:",
+    `Team: ${overlay.definition.name}`,
+    `Description: ${overlay.definition.description}`,
+    `Source: ${source}`,
+    "",
+    "Team strategy:",
+    overlay.definition.body || "(none)",
+    "",
+    "Declared role agents:",
+    ...roleLines,
+    "",
+    "Overlay rules:",
+    "- Declared role agents are spawned only on demand.",
+    "- Delegate by role id; role agent Markdown is loaded only inside the spawned role.",
+  ].join("\n");
+}
+
+export function renderRoleAgentDefinitionContext(input: {
+  definition: TeamAgentDefinition;
+}): string {
+  return [
+    "EvoDev role agent Markdown definition:",
+    `Source path: ${input.definition.sourcePath}`,
+    "Use this Markdown as the role-specific operating definition for this role only.",
+    "<evodev-agent-markdown>",
+    input.definition.markdown.trimEnd(),
+    "</evodev-agent-markdown>",
+  ].join("\n");
+}
+
 export async function resolveTeamRole(input: {
   homeDir?: string;
   repoRoot: string;
@@ -1920,6 +2199,37 @@ export async function resolveTeamRole(input: {
 }): Promise<ResolvedTeamRole> {
   assertSafeId(input.roleId, "roleId");
   const settings = await readSettingsOrDefault(input.homeDir);
+  const overlay = await resolveTeamOverlay({ homeDir: input.homeDir, repoRoot: input.repoRoot });
+  if (overlay.source !== "builtin" && input.roleId !== "main") {
+    const reference = overlay.definition.agents[input.roleId];
+    if (reference === undefined) {
+      throw new Error(
+        `Role ${input.roleId} is not declared in team overlay ${overlay.teamPath ?? overlay.source}.`,
+      );
+    }
+    const agent = await readTeamAgentDefinition({
+      homeDir: input.homeDir,
+      repoRoot: input.repoRoot,
+      roleId: input.roleId,
+      reference,
+    });
+    return {
+      version: 1,
+      roleId: input.roleId,
+      roleName: agent.name,
+      description: agent.description,
+      runtime: agent.runtime ?? settings.teamRuntime.defaultRuntime,
+      model: agent.model ?? settings.teamRuntime.defaultModel,
+      thinkingLevel: agent.thinkingLevel ?? settings.teamRuntime.defaultThinkingLevel,
+      prompt: renderRoleAgentDefinitionContext({ definition: agent }),
+      permissions: parseRolePermissions({ writeMode: agent.writeMode ?? undefined }, false),
+      teamPolicy: parseRolePolicy(undefined, settings.teamRuntime.recordTranscript),
+      source: "overlay",
+      sourcePath: agent.sourcePath,
+      nativeAgent: null,
+    };
+  }
+
   const globalRolePath = join(
     resolveEvoDevPaths(input.homeDir).roleAgentsDir,
     `${input.roleId}.json`,
@@ -1942,12 +2252,24 @@ export async function resolveTeamRole(input: {
     defaultThinkingLevel: settings.teamRuntime.defaultThinkingLevel,
     recordTranscript: settings.teamRuntime.recordTranscript,
   });
+  const prompt =
+    input.roleId === "main"
+      ? appendPromptBlock(
+          parsed.prompt,
+          await renderMainTeamOverlayContext({
+            homeDir: input.homeDir,
+            repoRoot: input.repoRoot,
+            overlay,
+          }),
+        )
+      : parsed.prompt;
 
   return {
     ...parsed,
     runtime: input.overrides?.runtime ?? nativeAgent?.target ?? parsed.runtime,
     model: input.overrides?.model ?? parsed.model,
     thinkingLevel: input.overrides?.thinkingLevel ?? parsed.thinkingLevel,
+    prompt,
     sourcePath,
     nativeAgent,
   };
@@ -2614,6 +2936,239 @@ function createBuiltInRole(roleId: string, runtime: TeamAgentRuntime): unknown {
   };
 }
 
+async function readTeamOverlayAgentSummaries(input: {
+  homeDir?: string;
+  repoRoot: string;
+  overlay: TeamOverlayResolution;
+}): Promise<TeamOverlayAgentSummary[]> {
+  const entries = Object.entries(input.overlay.definition.agents);
+  if (input.overlay.source === "builtin") {
+    return entries.map(([roleId]) => {
+      const builtin = BUILT_IN_ROLE_PROMPTS[roleId];
+      return {
+        roleId,
+        name: builtin?.roleName ?? defaultRoleName(roleId),
+        description: builtin?.description ?? `EvoDev ${roleId} role agent.`,
+        sourcePath: "builtin",
+      };
+    });
+  }
+
+  return Promise.all(
+    entries.map(([roleId, reference]) =>
+      readTeamAgentSummary({
+        homeDir: input.homeDir,
+        repoRoot: input.repoRoot,
+        roleId,
+        reference,
+      }),
+    ),
+  );
+}
+
+async function listDefaultTeamOverlayAssets(
+  assetsRootDir: string,
+): Promise<
+  Array<
+    | { kind: "team"; sourcePath: string; name: "team.md" }
+    | { kind: "agent"; sourcePath: string; name: string }
+  >
+> {
+  const teamPath = join(assetsRootDir, "team", "team.md");
+  const agentsDir = join(assetsRootDir, "team", "agents");
+  await assertReadableFile(teamPath, "Default team asset");
+
+  let entries: Array<{ name: string; isFile(): boolean }>;
+  try {
+    entries = (await readdir(agentsDir, { withFileTypes: true })) as Array<{
+      name: string;
+      isFile(): boolean;
+    }>;
+  } catch (error) {
+    throw new Error(
+      `Cannot read default team agents directory ${agentsDir}: ${describeError(error)}`,
+    );
+  }
+
+  const agentFiles = entries
+    .filter((entry) => entry.isFile() && extname(entry.name) === ".md")
+    .map((entry) => entry.name)
+    .sort();
+  if (agentFiles.length === 0) {
+    throw new Error(`Default team agents directory has no Markdown files: ${agentsDir}`);
+  }
+
+  return [
+    { kind: "team", sourcePath: teamPath, name: "team.md" },
+    ...agentFiles.map((name) => ({
+      kind: "agent" as const,
+      sourcePath: join(agentsDir, name),
+      name,
+    })),
+  ];
+}
+
+async function assertReadableFile(path: string, label: string): Promise<void> {
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) throw new Error("not a file");
+  } catch (error) {
+    throw new Error(`${label} is not readable at ${path}: ${describeError(error)}`);
+  }
+}
+
+async function writeTextFileIfMissing(path: string, content: string): Promise<boolean> {
+  try {
+    await readFile(path, "utf8");
+    return false;
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw new Error(`Cannot inspect ${path}: ${describeError(error)}`);
+    }
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+  return true;
+}
+
+function parseTeamDefinitionAgents(value: unknown): Record<string, string> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error("team.md agents must be a role-id map.");
+  const agents: Record<string, string> = {};
+  for (const [roleId, reference] of Object.entries(value)) {
+    assertSafeId(roleId, "team.md agents roleId");
+    if (typeof reference !== "string" || reference.trim() === "") {
+      throw new Error(`team.md agent reference for ${roleId} must be a non-empty string.`);
+    }
+    agents[roleId] = reference.trim();
+  }
+  return agents;
+}
+
+async function readTeamAgentMarkdown(reference: TeamAgentReference): Promise<string> {
+  if (extname(reference.sourcePath) !== ".md") {
+    throw new Error(`Team agent file for ${reference.roleId} must be Markdown.`);
+  }
+  try {
+    return await readFile(reference.sourcePath, "utf8");
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      throw new Error(`Team agent file not found for ${reference.roleId}: ${reference.sourcePath}`);
+    }
+    throw new Error(
+      `Cannot read team agent file for ${reference.roleId}: ${reference.sourcePath}: ${describeError(
+        error,
+      )}`,
+    );
+  }
+}
+
+function parseMarkdownWithFrontmatter(content: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const text = content.startsWith("\uFEFF") ? content.slice(1) : content;
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return { frontmatter: {}, body: text };
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end < 0) throw new Error("Markdown frontmatter is not closed.");
+  return {
+    frontmatter: parseSimpleYaml(lines.slice(1, end).join("\n")),
+    body: lines.slice(end + 1).join("\n"),
+  };
+}
+
+function parseSimpleYaml(content: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: Array<{ indent: number; value: Record<string, unknown> | unknown[] }> = [
+    { indent: -1, value: root },
+  ];
+  const lines = content.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index] ?? "";
+    if (rawLine.trim() === "" || rawLine.trimStart().startsWith("#")) continue;
+    const indent = rawLine.match(/^ */)?.[0].length ?? 0;
+    const trimmed = rawLine.trim();
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].value;
+
+    if (trimmed.startsWith("- ")) {
+      if (!Array.isArray(parent)) throw new Error("Invalid YAML list item placement.");
+      parent.push(parseYamlScalar(trimmed.slice(2).trim()));
+      continue;
+    }
+
+    const separator = trimmed.indexOf(":");
+    if (separator <= 0) throw new Error(`Invalid YAML line: ${trimmed}`);
+    const key = trimmed.slice(0, separator).trim();
+    const rawValue = trimmed.slice(separator + 1).trim();
+    if (!isRecord(parent)) throw new Error(`Invalid YAML parent for key ${key}.`);
+
+    if (rawValue === "") {
+      const next = findNextYamlContentLine(lines, index + 1);
+      const value: Record<string, unknown> | unknown[] =
+        next !== null && next.indent > indent && next.trimmed.startsWith("- ") ? [] : {};
+      parent[key] = value;
+      stack.push({ indent, value });
+      continue;
+    }
+
+    parent[key] = parseYamlScalar(rawValue);
+  }
+
+  return root;
+}
+
+function findNextYamlContentLine(
+  lines: string[],
+  start: number,
+): { indent: number; trimmed: string } | null {
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    return {
+      indent: line.match(/^ */)?.[0].length ?? 0,
+      trimmed: line.trim(),
+    };
+  }
+  return null;
+}
+
+function parseYamlScalar(value: string): unknown {
+  if (value === "") return "";
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null" || value === "~") return null;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    if (inner === "") return [];
+    return inner.split(",").map((item) => parseYamlScalar(item.trim()));
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  return value;
+}
+
+function appendPromptBlock(prompt: string, block: string): string {
+  if (block.trim() === "") return prompt;
+  return `${prompt.trimEnd()}\n\n${block.trim()}`;
+}
+
+function resolveGlobalTeamMarkdownPath(homeDir?: string): string {
+  return join(resolveEvoDevPaths(homeDir).rootDir, "team", "team.md");
+}
+
 function parseRolePermissions(value: unknown, main: boolean): TeamRolePermissions {
   const input = isRecord(value) ? value : {};
   return {
@@ -2742,6 +3297,12 @@ function parseRuntime(value: unknown, fallback: TeamAgentRuntime): TeamAgentRunt
   throw new Error("Role runtime must be codex or claude.");
 }
 
+function optionalRuntime(value: unknown): TeamAgentRuntime | null {
+  if (value === undefined || value === null) return null;
+  if (value === "codex" || value === "claude") return value;
+  throw new Error("Role evodev.runtime must be codex or claude.");
+}
+
 function parseWriteMode(value: unknown, fallback: TeamWriteMode): TeamWriteMode {
   if (value === undefined || value === null) return fallback;
   if (["read-only", "repo-write", "worktree-write", "disabled"].includes(String(value))) {
@@ -2750,6 +3311,18 @@ function parseWriteMode(value: unknown, fallback: TeamWriteMode): TeamWriteMode
   throw new Error("Role writeMode is invalid.");
 }
 
+function optionalWriteMode(value: unknown): TeamWriteMode | null {
+  if (value === undefined || value === null) return null;
+  return parseWriteMode(value, "repo-write");
+}
+
+function parseStringList(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+  if (typeof value === "string" && value.trim() !== "") return [value.trim()];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.trim() !== "");
+}
+
 export function isActiveTeamAgentStatus(status: TeamAgentStatus): boolean {
   return (
     status === "starting" ||

package/src/utils/errors.ts

@@ -0,0 +1,13 @@
+export function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") ||
+      error.message.includes("ENOENT"))
+  );
+}
+
+export function isFileExistsError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST"
+  );
+}

package/src/utils/fs.ts

@@ -0,0 +1,40 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isNotFoundError } from "./errors.ts";
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNotFoundError(error)) return false;
+    throw error;
+  }
+}
+
+export async function readJsonFile<T>(path: string, parse: (value: unknown) => T): Promise<T> {
+  return parse(JSON.parse(await readFile(path, "utf8")) as unknown);
+}
+
+export async function readJsonFiles<T>(dir: string, parse: (value: unknown) => T): Promise<T[]> {
+  if (!(await pathExists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const values: T[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    values.push(await readJsonFile(join(dir, entry.name), parse));
+  }
+  return values;
+}
+
+export async function writeJsonFile(
+  path: string,
+  value: unknown,
+  options: { overwrite?: boolean } = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    flag: options.overwrite === false ? "wx" : "w",
+  });
+}