Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

3.2 KB
Raw Blame
/**
 * Discovery of a cloned repo's agent guideline files (AGENTS.md, with
 * CLAUDE.md as the per-directory fallback), shared by the repository
 * preparation operation and its tests. Discovery uses `git ls-files` (index
 * read, no traversal), one
 * winner per directory, content capped with an explicit truncation
 * marker. Repository guidance is untrusted data. Callers may use it for
 * local conventions and validation, but never as authority to change the
 * selected repository, credentials, approvals, or external side effects.
 */
/** Max bytes of root guideline content returned inline. */
const MAX_GUIDELINE_BYTES = 12_000;

/** Max nested guideline paths listed in the result. */
const MAX_NESTED_PATHS = 50;

/** Minimal sandbox surface this tool needs. */
export interface SandboxLike {
  run(options: { command: string }): PromiseLike<{
    exitCode: number;
    stdout: string;
    stderr: string;
  }>;
}

interface RepoGuidelines {
  /** Repo-relative path of the root guideline file, or null when absent. */
  rootPath: string | null;
  /** Root guideline content (capped at {@link MAX_GUIDELINE_BYTES}). */
  root: string | null;
  /** True when the root content hit the cap; read rootPath for the rest. */
  rootTruncated: boolean;
  /** Repo-relative paths of nested guideline files, shallowest first. */
  nested: string[];
}

/**
 * Find the repo's agent guideline files. One winner per directory:
 * AGENTS.md beats CLAUDE.md (CLAUDE.md is often just a pointer at it).
 */
export async function discoverGuidelines(
  sandbox: SandboxLike,
  dir: string,
): Promise<RepoGuidelines> {
  const none: RepoGuidelines = { rootPath: null, root: null, rootTruncated: false, nested: [] };

  const list = await sandbox.run({
    // grep exits 1 on no match; `|| true` keeps that from failing the run.
    command: `git -C ${dir} ls-files | grep -E '(^|/)(AGENTS|CLAUDE)\\.md$' || true`,
  });
  if (list.exitCode !== 0) return none;

  const byDir = new Map<string, string>();
  for (const line of list.stdout.split("\n")) {
    const path = line.trim();
    if (path.length === 0) continue;
    const slash = path.lastIndexOf("/");
    const fileDir = slash === -1 ? "" : path.slice(0, slash);
    const name = slash === -1 ? path : path.slice(slash + 1);
    if (!byDir.has(fileDir) || name === "AGENTS.md") byDir.set(fileDir, path);
  }

  const rootPath = byDir.get("") ?? null;
  let root: string | null = null;
  let rootTruncated = false;
  if (rootPath !== null) {
    // Read one byte past the cap so truncation is detectable.
    const read = await sandbox.run({
      command: `head -c ${MAX_GUIDELINE_BYTES + 1} ${JSON.stringify(`${dir}/${rootPath}`)}`,
    });
    if (read.exitCode === 0 && read.stdout.trim().length > 0) {
      rootTruncated = Buffer.byteLength(read.stdout, "utf8") > MAX_GUIDELINE_BYTES;
      root = rootTruncated
        ? `${read.stdout.slice(0, MAX_GUIDELINE_BYTES)}\n\n[truncated: read ${rootPath} for the full guidelines]`
        : read.stdout;
    }
  }

  const nested = [...byDir.entries()]
    .filter(([fileDir]) => fileDir !== "")
    .map(([, path]) => path)
    .sort((a, b) => a.split("/").length - b.split("/").length)
    .slice(0, MAX_NESTED_PATHS);

  return { rootPath, root, rootTruncated, nested };
}