@jhlee0619/codexloop 0.1.0

package/scripts/lib/state.mjs

@@ -0,0 +1,378 @@
+// CodexLoop state persistence.
+//
+// State lives project-local under <repo>/.loop/ so it is committable/ignorable
+// by the team and survives machine moves. (Codex plugin's per-session state
+// under $CLAUDE_PLUGIN_DATA is a good fit for transient jobs, but loops are
+// long-running per-project artifacts.)
+//
+// Layout:
+//   <repo>/.loop/state.json              canonical state
+//   <repo>/.loop/iterations/NNNN.json    per-iteration forensic dump
+//   <repo>/.loop/iterations-dryrun/NNNN.json
+//   <repo>/.loop/proposals/NNNN-<id>.json
+//   <repo>/.loop/progress.log            append-only learning log
+//   <repo>/.loop/loop.lock               advisory lock { pid, loopId, acquiredAt }
+//   <repo>/.loop/loop.pid                pid of running worker
+//   <repo>/.loop/loop.log                worker stdout/stderr stream
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import process from "node:process";
+
+import { isProcessAlive } from "./process.mjs";
+
+const STATE_VERSION = 1;
+const STATE_FILENAME = "state.json";
+
+const MIGRATIONS = [
+  // Index 0 would migrate v0 -> v1, etc. Empty for now.
+];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export function resolveLoopDir(repoRoot) {
+  return path.join(repoRoot, ".loop");
+}
+
+export function getLoopPaths(repoRoot) {
+  const root = resolveLoopDir(repoRoot);
+  return {
+    root,
+    state: path.join(root, STATE_FILENAME),
+    iterations: path.join(root, "iterations"),
+    iterationsDryRun: path.join(root, "iterations-dryrun"),
+    proposals: path.join(root, "proposals"),
+    progressLog: path.join(root, "progress.log"),
+    lock: path.join(root, "loop.lock"),
+    pid: path.join(root, "loop.pid"),
+    log: path.join(root, "loop.log"),
+    archive: path.join(root, "archive")
+  };
+}
+
+export function ensureLoopDir(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  fs.mkdirSync(paths.iterations, { recursive: true });
+  fs.mkdirSync(paths.proposals, { recursive: true });
+  return paths;
+}
+
+// CodexLoop's opinionated defaults — independent of ~/.codex/config.toml.
+// These apply when the user starts a loop without passing --model / --effort
+// and when no prior state has set them explicitly.
+export const DEFAULT_MODEL = "gpt-5.4";
+export const DEFAULT_REASONING_EFFORT = "xhigh";
+export const VALID_REASONING_EFFORTS = Object.freeze([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh"
+]);
+
+export function defaultState() {
+  return {
+    version: STATE_VERSION,
+    loopId: null,
+    status: "idle",
+    pid: null,
+    mode: "interactive",
+    model: DEFAULT_MODEL,
+    reasoningEffort: DEFAULT_REASONING_EFFORT,
+    startedAt: null,
+    lastIterationAt: null,
+    completedAt: null,
+    goal: {
+      text: "",
+      acceptanceCriteria: [],
+      seedCommit: null,
+      relevantGlobs: [],
+      testCmd: null,
+      lintCmd: null,
+      typeCmd: null,
+      goalHash: null
+    },
+    budget: {
+      maxIterations: 20,
+      maxElapsedMs: 3_600_000,
+      maxCodexCalls: 200,
+      consumed: {
+        iterations: 0,
+        elapsedMs: 0,
+        codexCalls: 0,
+        startedAtMs: null
+      }
+    },
+    convergence: {
+      epsilon: 0.02,
+      stableWindow: 2,
+      scoreHistory: [],
+      stalledSince: null
+    },
+    iterations: [],
+    accepted: [],
+    rejected: [],
+    openIssues: [],
+    openIssuesInitial: 0,
+    stopReason: null,
+    error: null
+  };
+}
+
+export const MODEL_ALIASES = Object.freeze({
+  spark: "gpt-5.3-codex-spark"
+});
+
+export function normalizeModelName(name) {
+  if (name == null) return null;
+  const trimmed = String(name).trim();
+  if (!trimmed) return null;
+  const lower = trimmed.toLowerCase();
+  return MODEL_ALIASES[lower] ?? trimmed;
+}
+
+export function normalizeReasoningEffort(effort) {
+  if (effort == null) return null;
+  const trimmed = String(effort).trim().toLowerCase();
+  if (!trimmed) return null;
+  if (!VALID_REASONING_EFFORTS.includes(trimmed)) {
+    throw new Error(
+      `Invalid reasoning effort "${effort}". Valid values: ${VALID_REASONING_EFFORTS.join(", ")}`
+    );
+  }
+  return trimmed;
+}
+
+function mergeStateShape(loaded) {
+  const base = defaultState();
+  const merged = {
+    ...base,
+    ...loaded,
+    goal: { ...base.goal, ...(loaded.goal ?? {}) },
+    budget: {
+      ...base.budget,
+      ...(loaded.budget ?? {}),
+      consumed: { ...base.budget.consumed, ...(loaded.budget?.consumed ?? {}) }
+    },
+    convergence: { ...base.convergence, ...(loaded.convergence ?? {}) },
+    iterations: Array.isArray(loaded.iterations) ? loaded.iterations : [],
+    accepted: Array.isArray(loaded.accepted) ? loaded.accepted : [],
+    rejected: Array.isArray(loaded.rejected) ? loaded.rejected : [],
+    openIssues: Array.isArray(loaded.openIssues) ? loaded.openIssues : []
+  };
+  merged.version = STATE_VERSION;
+  return merged;
+}
+
+function applyMigrations(loaded) {
+  let state = loaded;
+  const version = Number.isFinite(state?.version) ? state.version : 0;
+  for (let i = version; i < STATE_VERSION; i += 1) {
+    const migrate = MIGRATIONS[i];
+    if (typeof migrate === "function") {
+      state = migrate(state);
+    }
+  }
+  if (state) {
+    state.version = STATE_VERSION;
+  }
+  return state;
+}
+
+export function loadState(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  if (!fs.existsSync(paths.state)) {
+    return defaultState();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(paths.state, "utf8"));
+  } catch (err) {
+    throw new Error(`Failed to parse ${paths.state}: ${err.message}`);
+  }
+  return mergeStateShape(applyMigrations(parsed));
+}
+
+function atomicWriteFile(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const suffix = `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const tmp = `${filePath}.tmp-${suffix}`;
+  fs.writeFileSync(tmp, contents, "utf8");
+  fs.renameSync(tmp, filePath);
+}
+
+export function saveState(repoRoot, state) {
+  ensureLoopDir(repoRoot);
+  const paths = getLoopPaths(repoRoot);
+  const payload = `${JSON.stringify({ ...state, version: STATE_VERSION }, null, 2)}\n`;
+  atomicWriteFile(paths.state, payload);
+  return state;
+}
+
+export function updateState(repoRoot, mutate) {
+  const state = loadState(repoRoot);
+  mutate(state);
+  return saveState(repoRoot, state);
+}
+
+export function generateLoopId() {
+  const time = Date.now().toString(36);
+  const rand = crypto.randomBytes(3).toString("hex");
+  return `loop-${time}-${rand}`;
+}
+
+export function computeGoalHash(goal) {
+  const canonical = JSON.stringify({
+    text: goal.text ?? "",
+    acceptanceCriteria: goal.acceptanceCriteria ?? [],
+    testCmd: goal.testCmd ?? null,
+    lintCmd: goal.lintCmd ?? null,
+    typeCmd: goal.typeCmd ?? null
+  });
+  return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+
+export function writeIterationFile(repoRoot, iteration, { dryRun = false } = {}) {
+  const paths = getLoopPaths(repoRoot);
+  const dir = dryRun ? paths.iterationsDryRun : paths.iterations;
+  fs.mkdirSync(dir, { recursive: true });
+  const name = `${String(iteration.index).padStart(4, "0")}.json`;
+  const filePath = path.join(dir, name);
+  atomicWriteFile(filePath, `${JSON.stringify(iteration, null, 2)}\n`);
+  return filePath;
+}
+
+export function readIterationFile(repoRoot, index, { dryRun = false } = {}) {
+  const paths = getLoopPaths(repoRoot);
+  const dir = dryRun ? paths.iterationsDryRun : paths.iterations;
+  const name = `${String(index).padStart(4, "0")}.json`;
+  const filePath = path.join(dir, name);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeProposalFile(repoRoot, iterationIndex, proposalId, proposal) {
+  const paths = getLoopPaths(repoRoot);
+  fs.mkdirSync(paths.proposals, { recursive: true });
+  const safeId = String(proposalId).replace(/[^a-zA-Z0-9_-]/g, "_");
+  const name = `${String(iterationIndex).padStart(4, "0")}-${safeId}.json`;
+  const filePath = path.join(paths.proposals, name);
+  atomicWriteFile(filePath, `${JSON.stringify(proposal, null, 2)}\n`);
+  return filePath;
+}
+
+export function appendProgressLog(repoRoot, text) {
+  const paths = getLoopPaths(repoRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  const line = `${nowIso()} ${text}\n`;
+  fs.appendFileSync(paths.progressLog, line, "utf8");
+}
+
+export function readProgressLogTail(repoRoot, { lines = 30 } = {}) {
+  const paths = getLoopPaths(repoRoot);
+  if (!fs.existsSync(paths.progressLog)) {
+    return "";
+  }
+  const contents = fs.readFileSync(paths.progressLog, "utf8");
+  const split = contents.split(/\r?\n/).filter(Boolean);
+  return split.slice(-lines).join("\n");
+}
+
+export class LoopLockError extends Error {
+  constructor(message, info) {
+    super(message);
+    this.name = "LoopLockError";
+    this.info = info;
+  }
+}
+
+export function acquireLock(repoRoot, { pid, loopId }) {
+  ensureLoopDir(repoRoot);
+  const paths = getLoopPaths(repoRoot);
+  if (fs.existsSync(paths.lock)) {
+    let existing = null;
+    try {
+      existing = JSON.parse(fs.readFileSync(paths.lock, "utf8"));
+    } catch {
+      existing = null;
+    }
+    if (existing && Number.isFinite(existing.pid) && isProcessAlive(existing.pid)) {
+      throw new LoopLockError(
+        `Another CodexLoop is already running (pid=${existing.pid}, loopId=${existing.loopId ?? "unknown"}). ` +
+          "Run /cloop:status to inspect or /cloop:stop to cancel it.",
+        existing
+      );
+    }
+  }
+  const payload = { pid, loopId, acquiredAt: nowIso() };
+  atomicWriteFile(paths.lock, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+export function releaseLock(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  if (fs.existsSync(paths.lock)) {
+    try { fs.unlinkSync(paths.lock); } catch {}
+  }
+}
+
+export function readLock(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  if (!fs.existsSync(paths.lock)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(paths.lock, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writePidFile(repoRoot, pid) {
+  const paths = getLoopPaths(repoRoot);
+  ensureLoopDir(repoRoot);
+  atomicWriteFile(paths.pid, `${pid}\n`);
+}
+
+export function removePidFile(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  if (fs.existsSync(paths.pid)) {
+    try { fs.unlinkSync(paths.pid); } catch {}
+  }
+}
+
+export function readPidFile(repoRoot) {
+  const paths = getLoopPaths(repoRoot);
+  if (!fs.existsSync(paths.pid)) return null;
+  try {
+    const pid = Number.parseInt(fs.readFileSync(paths.pid, "utf8").trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export function ensureGitignore(repoRoot) {
+  const gitignorePath = path.join(repoRoot, ".gitignore");
+  const entry = ".loop/";
+  let existing = "";
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, "utf8");
+    const normalized = existing.split(/\r?\n/).map((l) => l.trim());
+    if (normalized.includes(".loop/") || normalized.includes(".loop") || normalized.includes("/.loop/")) {
+      return { added: false, path: gitignorePath };
+    }
+  }
+  const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  fs.writeFileSync(gitignorePath, `${existing}${separator}${entry}\n`, "utf8");
+  return { added: true, path: gitignorePath };
+}
+
+export { STATE_VERSION };

package/scripts/lib/validate.mjs

@@ -0,0 +1,71 @@
+// Validation runner: executes the user-configured test / lint / type
+// commands and reports exit-code-derived pass/fail plus a simple regression
+// flag relative to the previous iteration.
+
+import { runCommand } from "./process.mjs";
+
+function tailLines(text, max = 20) {
+  if (!text) return "";
+  const split = String(text).split(/\r?\n/);
+  return split.slice(-max).join("\n");
+}
+
+function runShell(cmd, { cwd, timeoutMs = 600_000 }) {
+  const startedAt = Date.now();
+  const result = runCommand("sh", ["-c", cmd], { cwd, timeoutMs });
+  return {
+    cmd,
+    status: result.status,
+    signal: result.signal,
+    error: result.error ? result.error.message : null,
+    stdoutTail: tailLines(result.stdout),
+    stderrTail: tailLines(result.stderr),
+    durationMs: Date.now() - startedAt
+  };
+}
+
+// Returns a structured record the iteration layer records verbatim.
+// `previousIteration` is the previous iteration summary from state.iterations
+// (undefined on the first iteration).
+export async function runValidation({ cwd, goal, previousIteration }) {
+  const record = {
+    passed: null,
+    testsPassed: null,
+    passingTests: null,
+    failingTests: null,
+    typeErrors: null,
+    lintErrors: null,
+    regression: false,
+    commands: []
+  };
+
+  const test = goal?.testCmd ? runShell(goal.testCmd, { cwd }) : null;
+  if (test) {
+    record.commands.push({ kind: "test", ...test });
+    record.testsPassed = test.status === 0;
+  }
+
+  const lint = goal?.lintCmd ? runShell(goal.lintCmd, { cwd }) : null;
+  if (lint) {
+    record.commands.push({ kind: "lint", ...lint });
+    record.lintErrors = lint.status === 0 ? 0 : 1;
+  }
+
+  const typeCheck = goal?.typeCmd ? runShell(goal.typeCmd, { cwd }) : null;
+  if (typeCheck) {
+    record.commands.push({ kind: "type", ...typeCheck });
+    record.typeErrors = typeCheck.status === 0 ? 0 : 1;
+  }
+
+  if (record.commands.length === 0) {
+    record.passed = null;
+  } else {
+    record.passed = record.commands.every((c) => c.status === 0);
+  }
+
+  if (previousIteration?.validate?.passed === true && record.passed === false) {
+    record.regression = true;
+  }
+
+  return record;
+}

package/scripts/lib/workspace.mjs

@@ -0,0 +1,49 @@
+// Workspace root resolution.
+//
+// CodexLoop requires a git repository at the target directory so it can use
+// `git stash` / `git apply` / `git reset --hard` to make patch application
+// safely reversible. This module is the single source of truth for finding
+// the repo root and for refusing to start a loop outside of one.
+
+import { spawnSync } from "node:child_process";
+
+function runGit(args, cwd) {
+  return spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+
+export function resolveWorkspaceRoot(cwd = process.cwd()) {
+  const result = runGit(["rev-parse", "--show-toplevel"], cwd);
+  if (result.status === 0 && result.stdout.trim()) {
+    return result.stdout.trim();
+  }
+  return cwd;
+}
+
+export function isInsideGitRepo(cwd = process.cwd()) {
+  const result = runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+  return result.status === 0 && result.stdout.trim() === "true";
+}
+
+export function requireGitRepository(cwd = process.cwd()) {
+  const result = runGit(["rev-parse", "--show-toplevel"], cwd);
+  if (result.status !== 0 || !result.stdout.trim()) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new Error(
+      `CodexLoop requires a git repository. '${cwd}' is not inside one${detail ? ` (${detail})` : ""}. ` +
+        "Run 'git init' and commit a baseline before starting a loop."
+    );
+  }
+  return result.stdout.trim();
+}
+
+export function gitHeadSha(cwd) {
+  const result = runGit(["rev-parse", "HEAD"], cwd);
+  if (result.status !== 0) {
+    return null;
+  }
+  return result.stdout.trim() || null;
+}