@dpeek/codeless 0.1.0 → 0.1.2

package/src/attempt.ts

@@ -0,0 +1,104 @@
+export type Attempt = {
+  id: string;
+  stream: string;
+  change: string;
+  role: "implementer";
+  kind: "initial" | "rework";
+  startedAt: string;
+  endedAt: string;
+  selection?: { provider: string; model: string; thinking: string };
+  outcome: string;
+  text?: string;
+  usage?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  cost?: { amount: number; currency: string; source: string };
+  toolCalls: number;
+  errorCount: number;
+  incomplete: boolean;
+};
+
+export function validAttempt(value: unknown, stream: string, change: string): value is Attempt {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const attempt = value as Record<string, unknown>;
+  const allowed = new Set([
+    "id",
+    "stream",
+    "change",
+    "role",
+    "kind",
+    "startedAt",
+    "endedAt",
+    "selection",
+    "outcome",
+    "text",
+    "usage",
+    "cost",
+    "toolCalls",
+    "errorCount",
+    "incomplete",
+  ]);
+  const strings = ["id", "stream", "change", "role", "kind", "startedAt", "endedAt", "outcome"];
+  if (
+    !Object.keys(attempt).every((key) => allowed.has(key)) ||
+    !strings.every((key) => typeof attempt[key] === "string" && attempt[key].length > 0) ||
+    !Number.isFinite(Date.parse(attempt["startedAt"] as string)) ||
+    !Number.isFinite(Date.parse(attempt["endedAt"] as string)) ||
+    attempt["stream"] !== stream ||
+    attempt["change"] !== change ||
+    attempt["role"] !== "implementer" ||
+    !["initial", "rework"].includes(attempt["kind"] as string) ||
+    !Number.isSafeInteger(attempt["toolCalls"]) ||
+    (attempt["toolCalls"] as number) < 0 ||
+    !Number.isSafeInteger(attempt["errorCount"]) ||
+    (attempt["errorCount"] as number) < 0 ||
+    typeof attempt["incomplete"] !== "boolean"
+  )
+    return false;
+  const selection = attempt["selection"];
+  if (
+    selection !== undefined &&
+    (typeof selection !== "object" ||
+      selection === null ||
+      ["provider", "model", "thinking"].some(
+        (key) =>
+          typeof (selection as Record<string, unknown>)[key] !== "string" ||
+          !(selection as Record<string, unknown>)[key],
+      ))
+  )
+    return false;
+  const usage = attempt["usage"];
+  if (
+    usage !== undefined &&
+    (typeof usage !== "object" ||
+      usage === null ||
+      ["input", "output", "cacheRead", "cacheWrite"].some(
+        (key) =>
+          !Number.isSafeInteger((usage as Record<string, unknown>)[key]) ||
+          ((usage as Record<string, unknown>)[key] as number) < 0,
+      ))
+  )
+    return false;
+  if (
+    attempt["incomplete"] === false &&
+    (selection === undefined ||
+      usage === undefined ||
+      attempt["outcome"] === "unknown" ||
+      typeof attempt["text"] !== "string" ||
+      attempt["text"].length === 0)
+  )
+    return false;
+  const cost = attempt["cost"];
+  if (
+    cost !== undefined &&
+    (usage === undefined ||
+      typeof cost !== "object" ||
+      cost === null ||
+      !Number.isFinite((cost as Record<string, unknown>)["amount"]) ||
+      ((cost as Record<string, unknown>)["amount"] as number) < 0 ||
+      typeof (cost as Record<string, unknown>)["currency"] !== "string" ||
+      !(cost as Record<string, unknown>)["currency"] ||
+      typeof (cost as Record<string, unknown>)["source"] !== "string" ||
+      !(cost as Record<string, unknown>)["source"])
+  )
+    return false;
+  return attempt["text"] === undefined || typeof attempt["text"] === "string";
+}

package/src/cli.ts

@@ -8,6 +8,7 @@ import {
   readdirSync,
   realpathSync,
   rmdirSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -15,16 +16,20 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
-import { metricReport, recordDispatch, recordLanding } from "./metrics.ts";
+import { metricReport, recordAttempt, recordDispatch, recordLanding } from "./metrics.ts";
+import { type Attempt, validAttempt } from "./attempt.ts";
 import { roleSelectionArguments, roleSelectionSummary, validateRoleSelection } from "./pi.ts";
 import { readProject } from "./project.ts";
 
 const usage = `Usage:
+  codeless init
   codeless create <slug>
   codeless open <slug>
   codeless planner <slug>
   codeless approve <planner-session>
   codeless dispatch <numbered-change-file>
+  codeless rework <numbered-change-file> <feedback>
+  codeless finish <numbered-change-file>
   codeless land <slug>
   codeless next <numbered-change-file> <landed-commit>
   codeless metrics`;
@@ -36,9 +41,14 @@ export async function runCodeless(args: string[]): Promise<void> {
     return;
   }
   const repository = canonicalPath(run("git", ["rev-parse", "--show-toplevel"]).trim());
-  const { integrationBranch } = readProject(repository);
+  const project = readProject(repository);
+  const { integrationBranch } = project;
   run("git", ["check-ref-format", "--branch", integrationBranch], repository);
   const plannerExtension = resolve(import.meta.dir, "../extension/planner.js");
+  const implementerReportingExtension = resolve(
+    import.meta.dir,
+    "../extension/implementer-reporting.js",
+  );
   const configuredWorkspace = Bun.spawnSync(
     ["git", "config", "--local", "--get", "codeless.workspaceRoot"],
     { cwd: repository },
@@ -123,28 +133,146 @@ export async function runCodeless(args: string[]): Promise<void> {
       .join("-");
   }
 
-  function integrationWorktree(): string {
-    const entries = run("git", ["worktree", "list", "--porcelain", "-z"], repository).split("\0\0");
-    for (const entry of entries) {
-      const fields = entry.split("\0");
-      if (fields.includes(`branch refs/heads/${integrationBranch}`)) {
+  type Worktree = { path: string; branch?: string };
+
+  function registeredWorktrees(): Worktree[] {
+    return run("git", ["worktree", "list", "--porcelain", "-z"], repository)
+      .split("\0\0")
+      .filter(Boolean)
+      .map((entry) => {
+        const fields = entry.split("\0");
         const path = fields.find((field) => field.startsWith("worktree "))?.slice(9);
-        if (path !== undefined) return path;
-      }
-    }
-    throw new Error(`${integrationBranch} needs a dedicated integration worktree`);
+        if (path === undefined) throw new Error("Git did not report a worktree path");
+        const branch = fields.find((field) => field.startsWith("branch "))?.slice(7);
+        return { path: canonicalPath(path), ...(branch === undefined ? {} : { branch }) };
+      });
+  }
+
+  function integrationWorktree(): string {
+    const matches = registeredWorktrees().filter(
+      (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
+    );
+    if (matches.length !== 1)
+      throw new Error(`${integrationBranch} needs exactly one dedicated integration worktree`);
+    return matches[0]!.path;
   }
 
   function primaryWorktree(): string {
-    const entry = run("git", ["worktree", "list", "--porcelain", "-z"], repository).split(
-      "\0\0",
-    )[0];
-    const path = entry
-      ?.split("\0")
-      .find((field) => field.startsWith("worktree "))
-      ?.slice(9);
+    const path = registeredWorktrees()[0]?.path;
     if (path === undefined) throw new Error("Git did not report a primary worktree");
-    return canonicalPath(path);
+    return path;
+  }
+
+  function init(): void {
+    run("git", ["show-ref", "--verify", `refs/heads/${integrationBranch}`], repository);
+    const primary = primaryWorktree();
+    const target = canonicalPath(join(workspaceRoot, "worktree", integrationBranch));
+    const matchingBranch = registeredWorktrees().filter(
+      (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
+    );
+    const targetExists = existsSync(target);
+
+    let workspaceParent = workspaceRoot;
+    while (!existsSync(workspaceParent)) workspaceParent = dirname(workspaceParent);
+    if (!statSync(workspaceParent).isDirectory()) {
+      throw new Error(`Workspace parent is not a directory: ${workspaceParent}`);
+    }
+    const worktreeRoot = join(workspaceRoot, "worktree");
+    const stateDirectories: [string, string][] = [
+      ["Workspace", workspaceRoot],
+      ["Workspace stream path", join(workspaceRoot, "stream")],
+      ["Workspace worktree path", worktreeRoot],
+      ["Workspace metrics path", join(workspaceRoot, "metrics")],
+    ];
+    for (const [label, path] of stateDirectories) {
+      if (existsSync(path) && !statSync(path).isDirectory()) {
+        throw new Error(`${label} is not a directory: ${path}`);
+      }
+    }
+    const defaultWorkspace = workspaceRoot === canonicalPath(join(primary, ".codeless", "state"));
+    const ignoreFile = join(primary, ".gitignore");
+    let stateIgnored = false;
+    if (defaultWorkspace) {
+      if (existsSync(ignoreFile) && !statSync(ignoreFile).isFile()) {
+        throw new Error(`Repository ignore file is not a file: ${ignoreFile}`);
+      }
+
+      function ignoredByRepository(path: string): boolean {
+        const effective = Bun.spawnSync(["git", "check-ignore", "-q", "--no-index", path], {
+          cwd: primary,
+          env: process.env,
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "pipe",
+        });
+        if (effective.exitCode === 1) return false;
+        if (effective.exitCode !== 0) {
+          throw new Error(
+            effective.stderr.toString().trim() || "Could not inspect repository ignores",
+          );
+        }
+        const source = run("git", ["check-ignore", "-v", "--no-index", path], primary).split(
+          ":",
+          1,
+        )[0];
+        return source === ".gitignore" || source === ignoreFile;
+      }
+
+      const protectedPaths = [
+        ".codeless/config.json",
+        ...["change", "implement", "review", "commit"].map((name) =>
+          join(project.prompts, `${name}.md`),
+        ),
+      ];
+      if (protectedPaths.some((path) => ignoredByRepository(path))) {
+        throw new Error(
+          `Repository ignore rule conflicts with Codeless configuration or prompts; narrow ${ignoreFile} to /.codeless/state/`,
+        );
+      }
+      stateIgnored = ignoredByRepository(join(".codeless", "state", ".codeless-init-probe"));
+    }
+
+    if (matchingBranch.length > 1) {
+      throw new Error(`Git reports ${integrationBranch} checked out in multiple worktrees`);
+    }
+    if (matchingBranch.length === 1 && matchingBranch[0]!.path !== target) {
+      throw new Error(
+        `${integrationBranch} is checked out at ${matchingBranch[0]!.path}, expected ${target}`,
+      );
+    }
+    if (matchingBranch.length === 1 && (!targetExists || !statSync(target).isDirectory())) {
+      throw new Error(
+        `Git registers ${integrationBranch} at invalid integration worktree ${target}`,
+      );
+    }
+    if (
+      matchingBranch.length === 1 &&
+      run("git", ["branch", "--show-current"], target).trim() !== integrationBranch
+    ) {
+      throw new Error(`Integration worktree is not on ${integrationBranch}: ${target}`);
+    }
+    if (matchingBranch.length === 0 && targetExists) {
+      throw new Error(`Integration worktree target is occupied: ${target}`);
+    }
+
+    if (defaultWorkspace && !stateIgnored) {
+      const currentIgnore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
+      appendFileSync(
+        ignoreFile,
+        `${currentIgnore.length > 0 && !currentIgnore.endsWith("\n") ? "\n" : ""}/.codeless/state/\n`,
+      );
+    }
+    mkdirSync(join(workspaceRoot, "stream"), { recursive: true });
+    mkdirSync(worktreeRoot, { recursive: true });
+    mkdirSync(join(workspaceRoot, "metrics"), { recursive: true });
+    if (matchingBranch.length === 0) {
+      run("git", ["worktree", "add", target, integrationBranch], repository);
+    }
+
+    console.log(`Integration branch: ${integrationBranch}`);
+    console.log(`Primary checkout: ${primary}`);
+    console.log(`Workspace: ${workspaceRoot}`);
+    console.log(`Integration worktree: ${target}`);
   }
 
   function requireDirection(slug: string, worktree: string): string {
@@ -260,9 +388,9 @@ export async function runCodeless(args: string[]): Promise<void> {
         return Number(rect["x"]) >= rightEdge && candidateTop < bottom && candidateBottom > top;
       })
       .sort((left, right) => Number(left["rect"]["x"]) - Number(right["rect"]["x"]));
-    return candidates.length === 0
-      ? undefined
-      : string(candidates[0]!.pane["pane_id"], "right-hand pane id");
+    if (candidates.length === 0) return undefined;
+    if (candidates.length > 1) throw new Error("Planner layout has an ambiguous right-hand pane");
+    return string(candidates[0]!.pane["pane_id"], "right-hand pane id");
   }
 
   function requirePaneShell(pane: string, worktree: string): void {
@@ -313,6 +441,51 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
   }
 
+  function incompleteAttempt(
+    id: string,
+    slug: string,
+    number: string,
+    selection: { provider: string; model: string; thinking: string } | undefined,
+    kind: "initial" | "rework",
+  ): Attempt {
+    const timestamp = new Date().toISOString();
+    return {
+      id,
+      stream: slug,
+      change: number,
+      role: "implementer",
+      kind,
+      startedAt: timestamp,
+      endedAt: timestamp,
+      ...(selection === undefined ? {} : { selection }),
+      outcome: "unknown",
+      toolCalls: 0,
+      errorCount: 0,
+      incomplete: true,
+    };
+  }
+
+  function collectedAttempt(value: unknown, fallback: Attempt): Attempt {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return fallback;
+    const attempt = value as Partial<Attempt>;
+    if (
+      attempt.id !== fallback.id ||
+      attempt.stream !== fallback.stream ||
+      attempt.change !== fallback.change ||
+      attempt.role !== "implementer" ||
+      attempt.kind !== fallback.kind ||
+      typeof attempt.startedAt !== "string" ||
+      typeof attempt.endedAt !== "string" ||
+      typeof attempt.outcome !== "string" ||
+      typeof attempt.toolCalls !== "number" ||
+      typeof attempt.errorCount !== "number" ||
+      attempt.incomplete !== false ||
+      !validAttempt(attempt, fallback.stream, fallback.change)
+    )
+      return fallback;
+    return attempt;
+  }
+
   function latestChangeNumber(slug: string): string {
     const change = readdirSync(join(workspaceRoot, "stream", slug, "changes"))
       .filter((file) => /^\d{3}\.md$/.test(file))
@@ -538,9 +711,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     requireClean(worktree, branch);
     const prompts = promptDirectory(worktree);
     const selection = readProject(worktree).implementer;
+    const attemptId = crypto.randomUUID();
+    const reportPath = join(workspaceRoot, "metrics", slug, `.attempt-${attemptId}.json`);
+    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, selection, "initial");
     observe("dispatch metrics", () => recordDispatch(workspaceRoot, slug, number));
     await validateRoleSelection("implementer", selection, worktree);
-    console.log(roleSelectionSummary("implementer", selection));
 
     const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
     const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
@@ -592,6 +767,13 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
     requirePaneShell(implementerPane, worktree);
 
+    const collection = JSON.stringify({
+      id: attemptId,
+      stream: slug,
+      change: number,
+      kind: "initial",
+      path: reportPath,
+    });
     const started = herdr([
       "agent",
       "start",
@@ -602,6 +784,10 @@ export async function runCodeless(args: string[]): Promise<void> {
       implementerPane,
       "--",
       "--no-session",
+      "--extension",
+      implementerReportingExtension,
+      "--codeless-attempt",
+      collection,
       "--name",
       `${slug}-impl`,
       ...roleSelectionArguments(selection),
@@ -618,7 +804,7 @@ export async function runCodeless(args: string[]): Promise<void> {
       throw new Error(`${implementerName} started in ${startedCwd}, expected ${worktree}`);
     }
 
-    const completed = run("herdr", [
+    run("herdr", [
       "agent",
       "prompt",
       implementerName,
@@ -627,7 +813,121 @@ export async function runCodeless(args: string[]): Promise<void> {
       "--timeout",
       "3600000",
     ]);
-    console.log(completed.trim());
+    let attempt = fallbackAttempt;
+    try {
+      attempt = collectedAttempt(JSON.parse(readFileSync(reportPath, "utf8")), fallbackAttempt);
+      if (attempt === fallbackAttempt) throw new Error("report did not match its dispatch attempt");
+    } catch (error) {
+      console.error(
+        `codeless: warning: could not collect implementer attempt: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      if (existsSync(reportPath)) unlinkSync(reportPath);
+    }
+    observe("implementer attempt", () => recordAttempt(workspaceRoot, slug, number, attempt));
+    console.log(JSON.stringify(attempt));
+  }
+
+  function activeImplementer(changeArgument: string): {
+    change: string;
+    slug: string;
+    number: string;
+    worktree: string;
+    implementerName: string;
+    pane: string;
+  } {
+    if (process.env["HERDR_ENV"] !== "1")
+      throw new Error("Implementer control must run from a Herdr-managed planner");
+    const { change, slug, number, worktree, branch } = requireChange(changeArgument);
+    if (canonicalPath(process.cwd()) !== worktree)
+      throw new Error(`Implementer control cwd is ${process.cwd()}, expected ${worktree}`);
+    if (run("git", ["branch", "--show-current"], worktree).trim() !== branch)
+      throw new Error(`${worktree} is not on ${branch}`);
+    const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
+    const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
+    if (
+      !plannerProcesses.some(
+        (process) => canonicalPath(string(process["cwd"], "planner cwd")) === worktree,
+      )
+    )
+      throw new Error(`Planner pane ${plannerPane} is not running in ${worktree}`);
+    const layout = object(
+      result(herdr(["pane", "layout", "--pane", plannerPane]))["layout"],
+      "result.layout",
+    );
+    const pane = rightPane(layout, plannerPane);
+    if (pane === undefined) throw new Error("Planner has no right-hand implementer pane");
+    const implementerName = `${slug.replaceAll("-", "_")}_impl`;
+    const agent = object(result(herdr(["agent", "get", pane]))["agent"], "result.agent");
+    if (string(agent["name"], "result.agent.name") !== implementerName)
+      throw new Error(`Right-hand pane ${pane} is not implementer ${implementerName}`);
+    if (!["idle", "done"].includes(string(agent["agent_status"], "result.agent.agent_status")))
+      throw new Error(`Implementer ${implementerName} is not settled`);
+    const agentCwd = string(agent["foreground_cwd"] ?? agent["cwd"], "result.agent.foreground_cwd");
+    if (canonicalPath(agentCwd) !== worktree)
+      throw new Error(`Implementer ${implementerName} is in ${agentCwd}, expected ${worktree}`);
+    const processes = foregroundProcesses(paneProcessInfo(pane));
+    if (
+      !processes.some(
+        (process) => canonicalPath(string(process["cwd"], "implementer cwd")) === worktree,
+      )
+    )
+      throw new Error(`Implementer pane ${pane} is not running in ${worktree}`);
+    return { change, slug, number, worktree, implementerName, pane };
+  }
+
+  async function rework(changeArgument: string, feedback: string): Promise<void> {
+    if (feedback.trim().length === 0 || feedback.trim().length > 2_000)
+      throw new Error("Rework feedback must be concise non-empty text");
+    const { slug, number, implementerName } = activeImplementer(changeArgument);
+    const attemptId = crypto.randomUUID();
+    const reportPath = join(workspaceRoot, "metrics", slug, `.attempt-${attemptId}.json`);
+    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, undefined, "rework");
+    const collection = JSON.stringify({
+      id: attemptId,
+      stream: slug,
+      change: number,
+      kind: "rework",
+      path: reportPath,
+      feedback: feedback.trim(),
+    });
+    run("herdr", [
+      "agent",
+      "prompt",
+      implementerName,
+      `/codeless-rework ${collection}`,
+      "--wait",
+      "--timeout",
+      "3600000",
+    ]);
+    let attempt = fallbackAttempt;
+    try {
+      attempt = collectedAttempt(JSON.parse(readFileSync(reportPath, "utf8")), fallbackAttempt);
+      if (attempt === fallbackAttempt) throw new Error("report did not match its rework attempt");
+    } catch (error) {
+      console.error(
+        `codeless: warning: could not collect implementer attempt: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      if (existsSync(reportPath)) unlinkSync(reportPath);
+    }
+    observe("implementer attempt", () => recordAttempt(workspaceRoot, slug, number, attempt));
+    console.log(JSON.stringify(attempt));
+  }
+
+  function finish(changeArgument: string): void {
+    const { slug, number, worktree, implementerName, pane } = activeImplementer(changeArgument);
+    run("herdr", [
+      "agent",
+      "prompt",
+      implementerName,
+      `/codeless-finish ${JSON.stringify({ stream: slug, change: number })}`,
+      "--wait",
+      "--timeout",
+      "30000",
+    ]);
+    requirePaneShell(pane, worktree);
+    console.log(JSON.stringify({ pane, worktree }));
   }
 
   async function launchPlanner(slug: string): Promise<void> {
@@ -785,6 +1085,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
   }
 
+  if (action === "init") {
+    if (target !== undefined || details.length > 0) throw new Error(usage);
+    init();
+    return;
+  }
   if (action === "metrics") {
     if (target !== undefined || details.length > 0) throw new Error(usage);
     for (const line of metricReport(workspaceRoot)) console.log(line);
@@ -800,6 +1105,16 @@ export async function runCodeless(args: string[]): Promise<void> {
     await dispatch(target);
     return;
   }
+  if (action === "rework") {
+    if (target === undefined || details.length !== 1) throw new Error(usage);
+    await rework(target, details[0]!);
+    return;
+  }
+  if (action === "finish") {
+    if (target === undefined || details.length > 0) throw new Error(usage);
+    finish(target);
+    return;
+  }
   if (action === "next") {
     if (target === undefined || details.length !== 1) throw new Error(usage);
     await nextChange(target, details[0]!);