@jhlee0619/codexloop 0.1.0 → 0.1.3

package/scripts/lib/modes/artifact.mjs

@@ -0,0 +1,56 @@
+// Artifact-mode adapter — for document/paper/report completion loops.
+// Prefers operation-based proposals over unified diffs. Runs built-in
+// validators keyed by spec.validators plus mode-required implicit
+// validators (file_exists on required_files).
+
+export const name = "artifact";
+
+export function getCommonVars(state) {
+  const spec = state.goal?.spec ?? null;
+  const vars = {};
+  if (spec) {
+    vars.REQUIRED_FILES = Array.isArray(spec.required_files) ? spec.required_files : [];
+    vars.REQUIRED_SECTIONS = Array.isArray(spec.required_sections) ? spec.required_sections : [];
+    vars.PLACEHOLDER_POLICY = spec.placeholder_policy ?? null;
+  }
+  return vars;
+}
+
+export function getImplicitValidators(spec) {
+  const implicit = [];
+  if (Array.isArray(spec?.required_files) && spec.required_files.length > 0) {
+    implicit.push({
+      name: "file_exists",
+      args: { files: spec.required_files }
+    });
+  }
+  if (Array.isArray(spec?.required_sections) && spec.required_sections.length > 0) {
+    implicit.push({
+      name: "headings_present",
+      args: { sections: spec.required_sections }
+    });
+  }
+  return implicit;
+}
+
+export function getQualityWeights() {
+  return {
+    validatorPassRate: 0.35,
+    requiredFilePresence: 0.25,
+    distanceFromGoal: 0.20,
+    winnerConfidence: 0.10,
+    issueReduction: 0.10
+  };
+}
+
+export function getGuards() {
+  return ["requiredFileDeletion", "wholeSectionDeletion"];
+}
+
+export function getPromptSuffix() {
+  return [
+    "Task mode: artifact. Proposals SHOULD prefer `operations[]` over unified diffs for document editing.",
+    "Supported operation kinds: replace_section, insert_after_heading, replace_file, append_to_file.",
+    "Use `patch` (unified diff) only when the target file is code, not a document."
+  ].join("\n");
+}

package/scripts/lib/modes/code.mjs

@@ -0,0 +1,33 @@
+// Code-mode adapter — extracts the existing v0.1.0 hardcoded values as a
+// named adapter so iteration.mjs can dispatch by state.taskMode.
+//
+// This adapter must produce IDENTICAL behavior to v0.1.0 when taskMode === "code".
+
+export const name = "code";
+
+export function getCommonVars(_state) {
+  return {};
+}
+
+export function getImplicitValidators(_spec) {
+  return [];
+}
+
+export function getQualityWeights() {
+  return {
+    testPassRate: 0.30,
+    issueReduction: 0.20,
+    winnerConfidence: 0.15,
+    typeClean: 0.15,
+    lintClean: 0.10,
+    distanceFromGoal: 0.10
+  };
+}
+
+export function getGuards() {
+  return ["testFileDeleted", "testDisabled", "missingTestJustification"];
+}
+
+export function getPromptSuffix() {
+  return "Task mode: code. Proposals MUST use unified diffs in the `patch` field.";
+}

package/scripts/lib/modes/index.mjs

@@ -0,0 +1,30 @@
+// Mode adapter registry. iteration.mjs calls getModeAdapter(state.taskMode)
+// once per iteration to get the per-mode constants (prompt vars, quality
+// weights, validators, guards, prompt suffix).
+//
+// In v0.2 this is a simple lookup table. In v0.5 it grows into a real
+// interface with per-mode prompt file resolution.
+
+import * as code from "./code.mjs";
+import * as artifact from "./artifact.mjs";
+
+const ADAPTERS = {
+  code,
+  artifact,
+  paper: artifact  // v0.5 will ship a dedicated paper adapter; for now alias to artifact
+};
+
+export function getModeAdapter(taskMode) {
+  const key = String(taskMode ?? "code").toLowerCase();
+  const adapter = ADAPTERS[key];
+  if (!adapter) {
+    throw new Error(
+      `Unknown task mode "${taskMode}". Valid modes: ${Object.keys(ADAPTERS).join(", ")}`
+    );
+  }
+  return adapter;
+}
+
+export function getValidModes() {
+  return Object.keys(ADAPTERS);
+}

package/scripts/lib/operations.mjs

@@ -0,0 +1,244 @@
+// Operation-based proposal translator for artifact/paper mode.
+//
+// Codex returns operations[] in the proposal instead of a unified diff.
+// Each operation targets a single file with a specific kind of edit. The
+// runtime applies every operation in order, then stages + commits the
+// result in the same preSha/postSha/rollback framework as the patch path.
+//
+// v0.2 ships four operation kinds:
+//   replace_section      — find Markdown heading, replace its body
+//   insert_after_heading — insert content after a heading line
+//   replace_file         — overwrite entire file
+//   append_to_file       — append to end
+
+import fs from "node:fs";
+import path from "node:path";
+
+export class OperationError extends Error {
+  constructor(message, { op, file, kind } = {}) {
+    super(message);
+    this.name = "OperationError";
+    this.op = op;
+    this.file = file;
+    this.kind = kind;
+  }
+}
+
+const OP_HANDLERS = {
+  replace_section: handleReplaceSection,
+  insert_after_heading: handleInsertAfterHeading,
+  replace_file: handleReplaceFile,
+  append_to_file: handleAppendToFile
+};
+
+export function getSupportedOpKinds() {
+  return Object.keys(OP_HANDLERS);
+}
+
+export function applyOperations({ cwd, operations }) {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    return { applied: false, empty: true, filesTouched: [], opResults: [], error: null };
+  }
+
+  const filesTouched = new Set();
+  const opResults = [];
+
+  for (const op of operations) {
+    const handler = OP_HANDLERS[op.kind];
+    if (!handler) {
+      return {
+        applied: false,
+        empty: false,
+        filesTouched: [...filesTouched],
+        opResults,
+        error: `Unsupported operation kind: ${op.kind}. Supported: ${getSupportedOpKinds().join(", ")}`
+      };
+    }
+    try {
+      const result = handler(cwd, op);
+      opResults.push({ kind: op.kind, file: op.file, ...result });
+      if (result.changed) {
+        filesTouched.add(op.file);
+      }
+    } catch (err) {
+      return {
+        applied: false,
+        empty: false,
+        filesTouched: [...filesTouched],
+        opResults,
+        error: err instanceof OperationError
+          ? `${err.kind}:${err.file}: ${err.message}`
+          : `${op.kind}:${op.file}: ${err.message}`
+      };
+    }
+  }
+
+  return {
+    applied: filesTouched.size > 0,
+    empty: filesTouched.size === 0,
+    filesTouched: [...filesTouched],
+    opResults,
+    error: null
+  };
+}
+
+// ── replace_section ────────────────────────────────────────────────
+// Find the first exact Markdown heading match (case-sensitive, trimmed).
+// Replace from the line AFTER the heading up to (but not including) the
+// next heading of same-or-higher level. If heading is not found, throw.
+function handleReplaceSection(cwd, op) {
+  const { file, heading, content } = op;
+  validateRequired(op, ["file", "heading", "content"]);
+
+  const absPath = path.resolve(cwd, file);
+  if (!fs.existsSync(absPath)) {
+    throw new OperationError(`File not found: ${file}`, { op, file, kind: "replace_section" });
+  }
+
+  const original = fs.readFileSync(absPath, "utf8");
+  const lines = original.split(/\r?\n/);
+
+  const headingTrimmed = heading.trim();
+  const headingLevel = countHeadingLevel(headingTrimmed);
+  if (headingLevel === 0) {
+    throw new OperationError(`"${heading}" is not a valid Markdown heading`, { op, file, kind: "replace_section" });
+  }
+
+  const startIdx = lines.findIndex((l) => l.trim() === headingTrimmed);
+  if (startIdx === -1) {
+    throw new OperationError(`Heading "${heading}" not found in ${file}`, { op, file, kind: "replace_section" });
+  }
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i += 1) {
+    const lvl = countHeadingLevel(lines[i].trim());
+    if (lvl > 0 && lvl <= headingLevel) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  const contentLines = content.endsWith("\n")
+    ? content.slice(0, -1).split("\n")
+    : content.split("\n");
+
+  const result = [
+    ...lines.slice(0, startIdx + 1),
+    ...contentLines,
+    ...lines.slice(endIdx)
+  ];
+
+  const output = result.join("\n");
+  if (output === original) {
+    return { changed: false };
+  }
+  fs.writeFileSync(absPath, output, "utf8");
+  return { changed: true };
+}
+
+// ── insert_after_heading ───────────────────────────────────────────
+function handleInsertAfterHeading(cwd, op) {
+  const { file, heading, content } = op;
+  validateRequired(op, ["file", "heading", "content"]);
+
+  const absPath = path.resolve(cwd, file);
+  if (!fs.existsSync(absPath)) {
+    throw new OperationError(`File not found: ${file}`, { op, file, kind: "insert_after_heading" });
+  }
+
+  const original = fs.readFileSync(absPath, "utf8");
+  const lines = original.split(/\r?\n/);
+
+  const headingTrimmed = heading.trim();
+  const idx = lines.findIndex((l) => l.trim() === headingTrimmed);
+  if (idx === -1) {
+    throw new OperationError(`Heading "${heading}" not found in ${file}`, { op, file, kind: "insert_after_heading" });
+  }
+
+  const contentLines = content.endsWith("\n")
+    ? content.slice(0, -1).split("\n")
+    : content.split("\n");
+
+  const result = [
+    ...lines.slice(0, idx + 1),
+    ...contentLines,
+    ...lines.slice(idx + 1)
+  ];
+
+  const output = result.join("\n");
+  if (output === original) {
+    return { changed: false };
+  }
+  fs.writeFileSync(absPath, output, "utf8");
+  return { changed: true };
+}
+
+// ── replace_file ───────────────────────────────────────────────────
+function handleReplaceFile(cwd, op) {
+  const { file, content } = op;
+  validateRequired(op, ["file", "content"]);
+
+  const absPath = path.resolve(cwd, file);
+  const dirPath = path.dirname(absPath);
+  fs.mkdirSync(dirPath, { recursive: true });
+
+  let original = "";
+  if (fs.existsSync(absPath)) {
+    original = fs.readFileSync(absPath, "utf8");
+  }
+
+  if (content === original) {
+    return { changed: false };
+  }
+  fs.writeFileSync(absPath, content, "utf8");
+  return { changed: true };
+}
+
+// ── append_to_file ─────────────────────────────────────────────────
+function handleAppendToFile(cwd, op) {
+  const { file, content } = op;
+  validateRequired(op, ["file", "content"]);
+
+  if (!content) {
+    return { changed: false };
+  }
+
+  const absPath = path.resolve(cwd, file);
+  const dirPath = path.dirname(absPath);
+  fs.mkdirSync(dirPath, { recursive: true });
+
+  let existing = "";
+  if (fs.existsSync(absPath)) {
+    existing = fs.readFileSync(absPath, "utf8");
+  }
+
+  const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  fs.writeFileSync(absPath, existing + separator + content, "utf8");
+  return { changed: true };
+}
+
+// ── helpers ────────────────────────────────────────────────────────
+
+function countHeadingLevel(line) {
+  const match = /^(#{1,6})\s/.exec(line);
+  return match ? match[1].length : 0;
+}
+
+function validateRequired(op, fields) {
+  for (const field of fields) {
+    if (op[field] == null || (typeof op[field] === "string" && !op[field].trim())) {
+      throw new OperationError(
+        `Operation ${op.kind} requires non-empty "${field}"`,
+        { op, file: op.file, kind: op.kind }
+      );
+    }
+  }
+}
+
+// Synthesize a human-readable summary for logging and progress.log.
+export function summarizeOperations(operations) {
+  if (!Array.isArray(operations) || operations.length === 0) return "(no operations)";
+  return operations
+    .map((op) => `${op.kind} ${op.file}${op.heading ? ` @ "${op.heading}"` : ""}`)
+    .join("; ");
+}

package/scripts/lib/retrieve.mjs

@@ -0,0 +1,132 @@
+// Context bundle collector (= the "retrieve" phase).
+//
+// Runs BEFORE evaluate in every iteration. Collects relevant file contents
+// from the target repo so the Codex prompt has actual document context
+// instead of just a git diff. The bundle is injected into commonVars as
+// {{CONTEXT_BUNDLE}}.
+//
+// Code mode: spec is null → bundle is empty → zero token overhead.
+// Artifact mode: spec.required_files + state.goal.relevantGlobs drive the collection.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const DEFAULT_CAP_BYTES = 64 * 1024;
+
+const DEFAULT_FILES = ["TASK.md", "GOAL.md", "PRD.md", "cloop.task.json", "AGENTS.md"];
+
+export function collectBundle({ state, repoRoot, capBytes = DEFAULT_CAP_BYTES }) {
+  const spec = state?.goal?.spec ?? null;
+  const result = {
+    files: [],
+    totalBytes: 0,
+    truncated: false,
+    fileCount: 0
+  };
+
+  if (!spec && (!state?.goal?.relevantGlobs || state.goal.relevantGlobs.length === 0)) {
+    return result;
+  }
+
+  const candidates = new Set();
+
+  if (Array.isArray(spec?.required_files)) {
+    for (const f of spec.required_files) {
+      candidates.add(f);
+    }
+  }
+
+  if (Array.isArray(spec?.required_sections)) {
+    for (const entry of spec.required_sections) {
+      if (entry.file) candidates.add(entry.file);
+    }
+  }
+
+  for (const defaultFile of DEFAULT_FILES) {
+    const absPath = path.resolve(repoRoot, defaultFile);
+    if (fs.existsSync(absPath)) {
+      candidates.add(defaultFile);
+    }
+  }
+
+  if (Array.isArray(state?.goal?.relevantGlobs)) {
+    for (const glob of state.goal.relevantGlobs) {
+      if (!glob.includes("*") && !glob.includes("?")) {
+        const absPath = path.resolve(repoRoot, glob);
+        if (fs.existsSync(absPath) && fs.statSync(absPath).isFile()) {
+          candidates.add(glob);
+        }
+      }
+    }
+  }
+
+  let usedBytes = 0;
+
+  for (const relPath of candidates) {
+    const absPath = path.resolve(repoRoot, relPath);
+    if (!fs.existsSync(absPath)) continue;
+
+    let stat;
+    try {
+      stat = fs.statSync(absPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile()) continue;
+
+    if (usedBytes + stat.size > capBytes) {
+      result.truncated = true;
+      result.files.push({
+        path: relPath,
+        contentHash: null,
+        content: `(truncated — file ${stat.size} bytes, cap remaining ${capBytes - usedBytes} bytes)`,
+        truncated: true
+      });
+      continue;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(absPath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const contentHash = crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+
+    result.files.push({
+      path: relPath,
+      contentHash,
+      content,
+      truncated: false
+    });
+
+    usedBytes += Buffer.byteLength(content, "utf8");
+  }
+
+  result.totalBytes = usedBytes;
+  result.fileCount = result.files.length;
+  return result;
+}
+
+export function formatBundleForPrompt(bundle) {
+  if (!bundle || bundle.fileCount === 0) {
+    return "(no context bundle — code mode or no required files)";
+  }
+
+  const parts = [];
+  for (const file of bundle.files) {
+    if (file.truncated) {
+      parts.push(`--- ${file.path} ---\n${file.content}`);
+    } else {
+      parts.push(`--- ${file.path} (${file.contentHash}) ---\n${file.content}`);
+    }
+  }
+
+  if (bundle.truncated) {
+    parts.push(`\n(bundle truncated at ${DEFAULT_CAP_BYTES} bytes — some files shown as preview only)`);
+  }
+
+  return parts.join("\n\n");
+}

package/scripts/lib/state.mjs

@@ -22,11 +22,19 @@ import process from "node:process";
 
 import { isProcessAlive } from "./process.mjs";
 
-const STATE_VERSION = 1;
+const STATE_VERSION = 2;
 const STATE_FILENAME = "state.json";
 
 const MIGRATIONS = [
-  // Index 0 would migrate v0 -> v1, etc. Empty for now.
+  // Index 0: placeholder (v0 never existed in the wild).
+  undefined,
+  // Index 1: v1 → v2. Adds taskMode + goal.spec for artifact/paper mode support.
+  function migrateV1toV2(state) {
+    if (!state.taskMode) state.taskMode = "code";
+    if (!state.goal) state.goal = {};
+    if (state.goal.spec === undefined) state.goal.spec = null;
+    return state;
+  }
 ];
 
 function nowIso() {
@@ -82,6 +90,7 @@ export function defaultState() {
     status: "idle",
     pid: null,
     mode: "interactive",
+    taskMode: "code",
     model: DEFAULT_MODEL,
     reasoningEffort: DEFAULT_REASONING_EFFORT,
     startedAt: null,
@@ -95,7 +104,8 @@ export function defaultState() {
       testCmd: null,
       lintCmd: null,
       typeCmd: null,
-      goalHash: null
+      goalHash: null,
+      spec: null
     },
     budget: {
       maxIterations: 20,
@@ -226,14 +236,26 @@ export function generateLoopId() {
   return `loop-${time}-${rand}`;
 }
 
-export function computeGoalHash(goal) {
-  const canonical = JSON.stringify({
+export function computeGoalHash(goal, taskMode) {
+  // BC: when taskMode is "code" and spec is null, the canonical string MUST be
+  // byte-for-byte identical to v0.1.0's format. We achieve this by only
+  // appending v0.2 fields when they differ from code-mode defaults. This
+  // guarantees that a v1 state file loaded by v0.2 code produces the same
+  // goalHash without requiring the migration to rewrite it.
+  const parts = {
     text: goal.text ?? "",
     acceptanceCriteria: goal.acceptanceCriteria ?? [],
     testCmd: goal.testCmd ?? null,
     lintCmd: goal.lintCmd ?? null,
     typeCmd: goal.typeCmd ?? null
-  });
+  };
+  const tm = taskMode ?? "code";
+  const spec = goal.spec ?? null;
+  if (tm !== "code" || spec !== null) {
+    parts.taskMode = tm;
+    parts.spec = spec;
+  }
+  const canonical = JSON.stringify(parts);
   return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
 

package/scripts/lib/task-spec.mjs

@@ -0,0 +1,111 @@
+// Structured task spec loader, validator, and canonicalizer.
+//
+// A task spec can come from:
+//   1. --task-file <path>.json  (explicit flag)
+//   2. cloop.task.json at repo root  (committed declarative spec)
+//   3. Interview-assembled spec at .loop/task-spec.json
+//
+// When the file is plain text (not JSON), it is treated as goal text and
+// spec stays null (legacy code-mode behavior).
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { getValidModes } from "./modes/index.mjs";
+
+const SPEC_VERSION = 1;
+
+export function loadTaskSpec(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(filePath, "utf8").trim();
+  if (!raw) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  return validateAndCanonicalizeSpec(parsed);
+}
+
+export function autoDetectTaskSpec(repoRoot) {
+  const candidate = path.join(repoRoot, "cloop.task.json");
+  if (fs.existsSync(candidate)) {
+    return loadTaskSpec(candidate);
+  }
+  return null;
+}
+
+export function validateAndCanonicalizeSpec(raw) {
+  if (raw == null || typeof raw !== "object") {
+    throw new Error("Task spec must be a JSON object");
+  }
+
+  const spec = {
+    version: raw.version ?? SPEC_VERSION,
+    mode: normalizeMode(raw.mode ?? "artifact"),
+    required_files: Array.isArray(raw.required_files) ? raw.required_files.filter(Boolean) : [],
+    required_sections: Array.isArray(raw.required_sections)
+      ? raw.required_sections.map(canonicalizeSection)
+      : [],
+    placeholder_policy: canonicalizePlaceholderPolicy(raw.placeholder_policy),
+    validators: Array.isArray(raw.validators) ? raw.validators.map(canonicalizeValidator) : []
+  };
+
+  return spec;
+}
+
+function normalizeMode(mode) {
+  const lower = String(mode).trim().toLowerCase();
+  const valid = getValidModes();
+  if (!valid.includes(lower)) {
+    throw new Error(`Invalid task mode "${mode}". Valid: ${valid.join(", ")}`);
+  }
+  return lower;
+}
+
+function canonicalizeSection(entry) {
+  if (typeof entry === "string") {
+    return { file: entry, headings: [] };
+  }
+  return {
+    file: String(entry.file ?? ""),
+    headings: Array.isArray(entry.headings) ? entry.headings.filter(Boolean) : []
+  };
+}
+
+function canonicalizePlaceholderPolicy(policy) {
+  if (policy == null) return null;
+  return {
+    max: typeof policy.max === "number" ? policy.max : 10,
+    disallowed_kinds: Array.isArray(policy.disallowed_kinds) ? policy.disallowed_kinds : []
+  };
+}
+
+function canonicalizeValidator(entry) {
+  if (typeof entry === "string") {
+    return { name: entry, args: {} };
+  }
+  return {
+    name: String(entry.name ?? ""),
+    args: entry.args != null && typeof entry.args === "object" ? entry.args : {}
+  };
+}
+
+export function canonicalizeSpecForHash(spec) {
+  if (spec == null) return null;
+  return JSON.stringify({
+    version: spec.version ?? SPEC_VERSION,
+    mode: spec.mode ?? "code",
+    required_files: spec.required_files ?? [],
+    required_sections: spec.required_sections ?? [],
+    placeholder_policy: spec.placeholder_policy ?? null,
+    validators: spec.validators ?? []
+  });
+}
+
+export { SPEC_VERSION };