holo-codex 0.1.0

package/plugins/autonomous-pr-loop/core/git.ts

@@ -0,0 +1,213 @@
+import { execFileSync } from "node:child_process";
+import type { AgentLoopStorage } from "./types.js";
+import { AgentLoopError } from "./errors.js";
+import { redactRemote } from "./command.js";
+
+/** Result of a git side-effect that may safely no-op on resume. */
+export interface GitLifecycleResult {
+  skipped: boolean;
+  message: string;
+  branch?: string;
+}
+
+/** Return the current checked-out branch name. */
+export function getCurrentBranch(repoRoot: string): string {
+  return git(repoRoot, ["branch", "--show-current"]);
+}
+
+/** Return true when the worktree has no staged or unstaged changes. */
+export function isWorktreeClean(repoRoot: string): boolean {
+  return git(repoRoot, ["status", "--short"]).length === 0;
+}
+
+/** Return the configured origin remote URL. */
+export function getOriginRemote(repoRoot: string): string {
+  return git(repoRoot, ["remote", "get-url", "origin"]);
+}
+
+/** Ensure origin points at GitHub, or raise the unsupported remote gate. */
+export function assertGitHubRemote(repoRoot: string): void {
+  const remote = getOriginRemote(repoRoot);
+  if (!remote.includes("github.com")) {
+    throw new AgentLoopError("unsupported_remote", "origin remote is not a GitHub remote.", {
+      details: { remote: redactRemote(remote) },
+      exitCode: 2
+    });
+  }
+}
+
+/** Synchronize the base branch using only checkout plus ff-only pull. */
+export function syncBaseBranch(repoRoot: string, baseBranch: string): GitLifecycleResult {
+  assertGitHubRemote(repoRoot);
+  if (!isWorktreeClean(repoRoot)) {
+    throw new AgentLoopError("dirty_unowned_worktree", "Worktree must be clean before syncing base branch.", {
+      details: { baseBranch },
+      exitCode: 2
+    });
+  }
+  git(repoRoot, ["checkout", baseBranch]);
+  git(repoRoot, ["pull", "--ff-only", "origin", baseBranch]);
+  return { skipped: false, message: `Synced ${baseBranch}.`, branch: baseBranch };
+}
+
+/** Create or restore a lifecycle branch without silently overwriting unrelated branches. */
+export function createBranch(
+  repoRoot: string,
+  branchName: string,
+  options: { storage?: AgentLoopStorage; runId?: string } = {}
+): GitLifecycleResult {
+  const linked = options.runId && options.storage ? options.storage.getPrLink(options.runId) : undefined;
+  if (branchExists(repoRoot, branchName)) {
+    if (linked?.branch === branchName) {
+      git(repoRoot, ["checkout", branchName]);
+      recordDecision(options, "branch_reused", `Reused branch ${branchName}.`, { branchName });
+      return { skipped: true, message: `Reused current run branch ${branchName}.`, branch: branchName };
+    }
+    const suffixed = nextAvailableBranch(repoRoot, branchName);
+    git(repoRoot, ["checkout", "-b", suffixed]);
+    recordDecision(options, "branch_renamed", `Created suffixed branch ${suffixed}.`, {
+      requested: branchName,
+      actual: suffixed
+    });
+    return { skipped: false, message: `Created ${suffixed}.`, branch: suffixed };
+  }
+  git(repoRoot, ["checkout", "-b", branchName]);
+  return { skipped: false, message: `Created ${branchName}.`, branch: branchName };
+}
+
+/** Stage a constrained list of paths. */
+export function stagePaths(repoRoot: string, paths: string[]): GitLifecycleResult {
+  if (paths.length === 0) {
+    return { skipped: true, message: "No paths to stage." };
+  }
+  git(repoRoot, ["add", "--", ...paths]);
+  return { skipped: false, message: `Staged ${paths.length} paths.` };
+}
+
+/** Commit staged changes when there is an actual staged diff. */
+export function commit(repoRoot: string, message: string): GitLifecycleResult {
+  if (!hasStagedDiff(repoRoot)) {
+    return { skipped: true, message: "No staged diff to commit." };
+  }
+  git(repoRoot, ["commit", "-m", message]);
+  return { skipped: false, message };
+}
+
+/** Push a branch unless the local and remote refs already match. */
+export function pushBranch(repoRoot: string, branchName: string): GitLifecycleResult {
+  const local = git(repoRoot, ["rev-parse", branchName]);
+  const remote = tryGit(repoRoot, ["rev-parse", `origin/${branchName}`]);
+  if (remote && remote === local) {
+    return { skipped: true, message: `origin/${branchName} already matches local.`, branch: branchName };
+  }
+  git(repoRoot, ["push", "-u", "origin", branchName]);
+  return { skipped: false, message: `Pushed ${branchName}.`, branch: branchName };
+}
+
+/** Return changed files relative to an optional base ref. */
+export function getChangedFiles(repoRoot: string, baseRef?: string): string[] {
+  if (baseRef) {
+    return git(repoRoot, ["diff", "--name-only", baseRef]).split("\n").filter(Boolean);
+  }
+  return git(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"])
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => parsePorcelainPath(line))
+    .filter((path, index, paths) => path.length > 0 && paths.indexOf(path) === index);
+}
+
+/** Execute a safe git command without shell interpretation. */
+export function git(repoRoot: string, args: string[]): string {
+  rejectUnsafeGit(args);
+  return execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+
+function tryGit(repoRoot: string, args: string[]): string | undefined {
+  try {
+    return git(repoRoot, args);
+  } catch {
+    return undefined;
+  }
+}
+
+function branchExists(repoRoot: string, branchName: string): boolean {
+  return (
+    Boolean(tryGit(repoRoot, ["rev-parse", "--verify", branchName])) ||
+    Boolean(tryGit(repoRoot, ["ls-remote", "--heads", "origin", branchName]))
+  );
+}
+
+function nextAvailableBranch(repoRoot: string, branchName: string): string {
+  for (let index = 2; index < 100; index += 1) {
+    const candidate = `${branchName}-${index}`;
+    if (!branchExists(repoRoot, candidate)) {
+      return candidate;
+    }
+  }
+  throw new AgentLoopError("policy_violation", "Could not find an available branch suffix.", {
+    details: { branchName },
+    exitCode: 2
+  });
+}
+
+function hasStagedDiff(repoRoot: string): boolean {
+  try {
+    git(repoRoot, ["diff", "--cached", "--quiet"]);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function parsePorcelainPath(line: string): string {
+  const renamed = line.slice(3).split(" -> ");
+  return (renamed.at(-1) ?? "").trim().replace(/^"|"$/g, "");
+}
+
+function recordDecision(
+  options: { storage?: AgentLoopStorage; runId?: string },
+  kind: string,
+  message: string,
+  details: unknown
+): void {
+  if (options.storage && options.runId) {
+    options.storage.appendDecision({ runId: options.runId, kind, message, details });
+  }
+}
+
+function rejectUnsafeGit(args: string[]): void {
+  const command = stripGitGlobalOptions(args);
+  if (command[0] === "reset" && command.includes("--hard")) {
+    throw new AgentLoopError("policy_violation", "git reset --hard is not allowed.", { exitCode: 2 });
+  }
+  if (command[0] === "clean") {
+    throw new AgentLoopError("policy_violation", "git clean is not allowed.", { exitCode: 2 });
+  }
+  if (command[0] === "rebase") {
+    throw new AgentLoopError("policy_violation", "git rebase is not allowed.", { exitCode: 2 });
+  }
+  if (command[0] === "push" && command.some((arg) => arg === "-f" || arg.startsWith("--force"))) {
+    throw new AgentLoopError("policy_violation", "force push is not allowed.", { exitCode: 2 });
+  }
+}
+
+function stripGitGlobalOptions(args: string[]): string[] {
+  const result = [...args];
+  while (result.length > 0) {
+    const first = result[0];
+    if (first === "-C" || first === "--git-dir" || first === "--work-tree") {
+      result.splice(0, 2);
+      continue;
+    }
+    if (first?.startsWith("--git-dir=") || first?.startsWith("--work-tree=")) {
+      result.shift();
+      continue;
+    }
+    break;
+  }
+  return result;
+}

package/plugins/autonomous-pr-loop/core/github.ts

@@ -0,0 +1,269 @@
+import { execFileSync } from "node:child_process";
+import type { AgentLoopConfig } from "./types.js";
+import { AgentLoopError } from "./errors.js";
+
+export interface GitHubPullRequest {
+  number: number;
+  url: string;
+  title?: string;
+  body?: string;
+  headRefName: string;
+  baseRefName: string;
+  state: string;
+  isDraft: boolean;
+  mergedAt?: string | null;
+  reviewDecision?: string;
+  statusCheckRollup?: unknown[];
+}
+
+export interface GitHubCommandOptions {
+  repoRoot: string;
+  config: AgentLoopConfig;
+  signal?: AbortSignal;
+}
+
+const REVIEW_THREADS_QUERY = `
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100) {
+        nodes {
+          isResolved
+          isOutdated
+          comments(first: 100) {
+            nodes {
+              id
+              url
+              body
+              path
+              line
+              diffHunk
+              author {
+                login
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+
+/** Verify the current gh CLI session can access GitHub. */
+export function checkGhAuth(repoRoot: string): void {
+  runGh(repoRoot, ["auth", "status"]);
+}
+
+/** List pull requests for a head branch. */
+export async function listPullRequestsByHead(options: GitHubCommandOptions, branch: string): Promise<GitHubPullRequest[]> {
+  const stdout = await runGhJson(options, [
+    "pr",
+    "list",
+    "--head",
+    branch,
+    "--json",
+    "number,url,title,body,headRefName,baseRefName,state,isDraft,mergedAt"
+  ]);
+  return parseJson(stdout, "Could not parse gh pr list output.") as GitHubPullRequest[];
+}
+
+/** List recent pull requests for the configured repository. */
+export function listPullRequests(options: GitHubCommandOptions): GitHubPullRequest[] {
+  const stdout = runGh(options.repoRoot, [
+    "pr",
+    "list",
+    "--state",
+    "all",
+    "--limit",
+    "100",
+    "--json",
+    "number,url,title,body,headRefName,baseRefName,state,isDraft,mergedAt"
+  ]);
+  return parseJson(stdout, "Could not parse gh pr list output.") as GitHubPullRequest[];
+}
+
+/** List open pull requests for the configured repository. */
+export function listOpenPullRequests(options: GitHubCommandOptions): GitHubPullRequest[] {
+  const stdout = runGh(options.repoRoot, [
+    "pr",
+    "list",
+    "--state",
+    "open",
+    "--json",
+    "number,url,title,body,headRefName,baseRefName,state,isDraft,mergedAt"
+  ]);
+  return parseJson(stdout, "Could not parse gh pr list output.") as GitHubPullRequest[];
+}
+
+/** Read a pull request by number with fields needed by PR C. */
+export async function viewPullRequest(options: GitHubCommandOptions, prNumber: number): Promise<GitHubPullRequest> {
+  const stdout = await runGhJson(options, [
+    "pr",
+    "view",
+    String(prNumber),
+    "--json",
+    "number,url,headRefName,baseRefName,state,isDraft,mergedAt,reviewDecision,statusCheckRollup"
+  ]);
+  return parseJson(stdout, "Could not parse gh pr view output.") as GitHubPullRequest;
+}
+
+/** Fetch PR reviewThreads through GitHub GraphQL for comment-level state. */
+export async function fetchReviewThreads(options: GitHubCommandOptions, prNumber: number): Promise<unknown> {
+  const [owner, name] = options.config.repoId.split("/");
+  if (!owner || !name) {
+    throw new AgentLoopError("invalid_config", "Config repoId must be owner/repo.");
+  }
+  const stdout = await runGhJson(options, [
+    "api",
+    "graphql",
+    "-f",
+    `query=${REVIEW_THREADS_QUERY}`,
+    "-F",
+    `owner=${owner}`,
+    "-F",
+    `name=${name}`,
+    "-F",
+    `number=${prNumber}`
+  ]);
+  return parseJson(stdout, "Could not parse gh GraphQL output.");
+}
+
+/** Create a draft pull request and return the new URL. */
+export function createDraftPullRequest(options: GitHubCommandOptions, input: {
+  title: string;
+  body: string;
+  head: string;
+  base: string;
+}): string {
+  return runGh(options.repoRoot, [
+    "pr",
+    "create",
+    "--draft",
+    "--title",
+    input.title,
+    "--body",
+    input.body,
+    "--head",
+    input.head,
+    "--base",
+    input.base
+  ]);
+}
+
+/** Add a PR comment. */
+export function commentOnPullRequest(repoRoot: string, prNumber: number, body: string): void {
+  runGh(repoRoot, ["pr", "comment", String(prNumber), "--body", body]);
+}
+
+/** Mark a draft PR ready for review. */
+export function markPullRequestReady(repoRoot: string, prNumber: number): void {
+  runGh(repoRoot, ["pr", "ready", String(prNumber)]);
+}
+
+/** Merge a PR only when the caller has already passed all PR C guards. */
+export function mergePullRequest(repoRoot: string, prNumber: number): void {
+  runGh(repoRoot, ["pr", "merge", String(prNumber), "--merge"]);
+}
+
+/** Run a gh read command with transient retry handling. */
+export async function runGhJson(
+  options: GitHubCommandOptions,
+  args: string[],
+  signal = options.signal
+): Promise<string> {
+  let lastError: unknown;
+  const attempts = options.config.githubRetryMaxAttempts;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return runGh(options.repoRoot, args);
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof AgentLoopError) || error.code !== "github_transient_failure") {
+        throw error;
+      }
+      if (attempt < attempts) {
+        await sleep(options.config.githubRetryBaseDelayMs * 2 ** (attempt - 1), signal);
+      }
+    }
+  }
+  if (lastError instanceof AgentLoopError) {
+    throw lastError;
+  }
+  throw new AgentLoopError("github_transient_failure", "GitHub command failed after retries.", {
+    details: { args },
+    exitCode: 2
+  });
+}
+
+/** Run gh without shell interpretation and normalize common failure classes. */
+export function runGh(repoRoot: string, args: string[]): string {
+  try {
+    return execFileSync("gh", args, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  } catch (error) {
+    throw classifyGhError(error, args);
+  }
+}
+
+function classifyGhError(error: unknown, args: string[]): AgentLoopError {
+  const detail = error as { stderr?: string; stdout?: string; message?: string; status?: number };
+  const text = `${detail.stderr ?? ""}\n${detail.stdout ?? ""}\n${detail.message ?? ""}`.toLowerCase();
+  const details = { args, status: detail.status, stderr: detail.stderr };
+  if (text.includes("not logged") || text.includes("authentication") || text.includes("http 401")) {
+    return new AgentLoopError("needs_secret_or_login", "GitHub CLI authentication is required.", {
+      details,
+      exitCode: 2
+    });
+  }
+  if (isResourceLookup(args) && (text.includes("not found") || text.includes("could not resolve"))) {
+    return new AgentLoopError("github_resource_not_found", "GitHub resource was not found.", {
+      details: { ...details, classification: "not_found" }
+    });
+  }
+  if (
+    text.includes("rate limit") ||
+    text.includes("secondary rate") ||
+    text.includes("network") ||
+    text.includes("timed out") ||
+    text.includes("http 5")
+  ) {
+    return new AgentLoopError("github_transient_failure", "GitHub transient failure.", {
+      details,
+      exitCode: 2
+    });
+  }
+  return new AgentLoopError("storage_error", "GitHub CLI command failed.", { details });
+}
+
+function parseJson(value: string, message: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new AgentLoopError("storage_error", message, {
+      details: { cause: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+
+function isResourceLookup(args: string[]): boolean {
+  return args[0] === "pr" || (args[0] === "api" && args[1] === "graphql");
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const cleanup = (): void => signal?.removeEventListener("abort", abort);
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const abort = (): void => {
+      clearTimeout(timer);
+      cleanup();
+      reject(new AgentLoopError("github_transient_failure", "GitHub retry was aborted.", { exitCode: 2 }));
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}

package/plugins/autonomous-pr-loop/core/gitnexus.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import { writeArtifact } from "./artifacts.js";
+import { AgentLoopError } from "./errors.js";
+import type { AgentLoopConfig, AgentLoopStorage } from "./types.js";
+
+export interface GitNexusResult {
+  ok: boolean;
+  skipped: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+/** Run `gitnexus status` as a best-effort repository health check. */
+export function gitnexusStatus(repoRoot: string, config: AgentLoopConfig): GitNexusResult {
+  return runGitNexus(repoRoot, ["status"], config.gitnexusRequired);
+}
+
+/** Run `gitnexus analyze` as a best-effort repository index refresh. */
+export function gitnexusAnalyze(repoRoot: string, config: AgentLoopConfig): GitNexusResult {
+  return runGitNexus(repoRoot, ["analyze"], config.gitnexusRequired);
+}
+
+/** Guard commit/push with `gitnexus detect_changes` when required by config. */
+export function gitnexusDetectChanges(
+  repoRoot: string,
+  config: AgentLoopConfig,
+  storage: AgentLoopStorage,
+  runId: string
+): GitNexusResult {
+  const result = runGitNexus(repoRoot, ["detect_changes"], config.gitnexusRequired);
+  if (!result.ok && config.gitnexusRequired) {
+    throw new AgentLoopError("gitnexus_check_failed", "GitNexus detect_changes did not pass.", {
+      details: { stdout: result.stdout, stderr: result.stderr },
+      exitCode: 2
+    });
+  }
+  if (!config.gitnexusRequired) {
+    const artifact = writeArtifact(
+      repoRoot,
+      storage,
+      runId,
+      "log",
+      "gitnexus-alternative-scope-check.txt",
+      `stdout:\n${result.stdout}\n\nstderr:\n${result.stderr}\n`
+    );
+    storage.appendDecision({
+      runId,
+      kind: "gitnexus_not_required",
+      message: "GitNexus detect_changes was not required; stored alternative scope evidence.",
+      details: { artifactId: artifact.id, ok: result.ok }
+    });
+  }
+  return result;
+}
+
+/** Placeholder impact query for PR C callers and later PRs. */
+export function gitnexusImpact(repoRoot: string, config: AgentLoopConfig): GitNexusResult {
+  return runGitNexus(repoRoot, ["impact"], config.gitnexusRequired);
+}
+
+function runGitNexus(repoRoot: string, args: string[], required: boolean): GitNexusResult {
+  try {
+    const stdout = execFileSync("npx", ["gitnexus", ...args], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return { ok: true, skipped: false, stdout: stdout.trim(), stderr: "" };
+  } catch (error) {
+    const typed = error as { stderr?: string; stdout?: string; message?: string; status?: number };
+    const result = {
+      ok: false,
+      skipped: false,
+      stdout: typed.stdout ?? "",
+      stderr: typed.stderr ?? typed.message ?? ""
+    };
+    if (required && isToolUnavailable(typed)) {
+      throw new AgentLoopError("required_tool_unavailable", "GitNexus is required but unavailable.", {
+        details: { args, stderr: result.stderr, status: typed.status },
+        exitCode: 2
+      });
+    }
+    return result;
+  }
+}
+
+function isToolUnavailable(error: { stderr?: string; message?: string; status?: number }): boolean {
+  const text = `${error.stderr ?? ""}\n${error.message ?? ""}`.toLowerCase();
+  return error.status === 127 || text.includes("not found") || text.includes("could not determine executable");
+}

package/plugins/autonomous-pr-loop/core/happy.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+
+export interface HappyCapability {
+  installed: boolean;
+  versionText?: string;
+  supportsNotify: boolean;
+}
+
+/** Detect local Happy notify support without starting sessions or remote bridges. */
+export function detectHappy(): HappyCapability {
+  const help = runHappyHelp(["--help"]);
+  if (!help.ok) {
+    return { installed: false, supportsNotify: false };
+  }
+  const notify = runHappyHelp(["notify", "--help"]);
+  const versionText = firstLine(help.output);
+  return {
+    installed: true,
+    ...(versionText ? { versionText } : {}),
+    supportsNotify: notify.ok
+  };
+}
+
+function runHappyHelp(args: string[]): { ok: boolean; output: string } {
+  try {
+    return {
+      ok: true,
+      output: execFileSync("happy", args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 2_000
+      }).trim()
+    };
+  } catch {
+    return { ok: false, output: "" };
+  }
+}
+
+function firstLine(value: string): string | undefined {
+  const line = value.split(/\r?\n/).find((item) => item.trim().length > 0)?.trim();
+  return line ? line.slice(0, 200) : undefined;
+}