cloving 1.1.0 → 1.3.0

package/templates/develop/develop/pull.ts

@@ -0,0 +1,152 @@
+import type { CycleOutcome, PullRequest } from "cloving/workflows";
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+import type { DevelopTask, DevelopReport } from "./report.ts";
+import { queuePartial } from "./queue-partial.ts";
+
+export async function preparePull(cycleId: string): Promise<void> {
+  const result = await protectedEffect({
+    scope: { phase: "pull-request", operation: "github-prepare", round: 1 },
+    capability: "github",
+    method: "prepare",
+    target: cycleId,
+    payload: "{}",
+    units: 1,
+  });
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+}
+
+export async function openPull(request: {
+  readonly input: DevelopTask;
+  readonly round: number;
+}): Promise<PullRequest> {
+  const { input, round } = request;
+  const result = await protectedEffect({
+    scope: { phase: "pull-request", operation: "github-open-pr", round: round },
+    capability: "github",
+    method: "open-pr",
+    target: input.cycleId,
+    payload: JSON.stringify({
+      title: (input.ticket.split("\n")[0] ?? "Develop task")
+        .replace(/^#+\s*/, "")
+        .slice(0, 200),
+      body: "Review the committed changes and repository checks for this task.",
+    }),
+    units: 1,
+  });
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+  const value: unknown = JSON.parse(result.result ?? "null");
+  return pullOf(value, input.cycleId);
+}
+
+function pullFields(
+  value: unknown,
+): value is { number: unknown; url: unknown; commit: unknown } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "number" in value &&
+    "url" in value &&
+    "commit" in value
+  );
+}
+
+function pullOf(value: unknown, target: string): PullRequest {
+  if (!pullFields(value)) throw new Error("invalid-pull-request");
+  const { number, url, commit } = value;
+  if (
+    typeof number !== "number" ||
+    !Number.isSafeInteger(number) ||
+    number < 1 ||
+    typeof url !== "string" ||
+    typeof commit !== "string" ||
+    !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(commit)
+  )
+    throw new Error("invalid-pull-request");
+  return { number, url, commit, target };
+}
+
+export async function finishPull(request: {
+  readonly input: DevelopTask;
+  readonly round: number;
+  readonly report: DevelopReport;
+  readonly pull: PullRequest;
+}): Promise<CycleOutcome> {
+  const { input, round, report, pull } = request;
+  const outcome = {
+    kind: "handoff_requested" as const,
+    cycleId: input.cycleId,
+    promotionId: `pull-request-${String(pull.number)}`,
+    ticketStatus: report.status.kind,
+  };
+  const target = input.issue;
+  if (target === null) return outcome;
+  const result =
+    report.status.kind === "partial"
+      ? await queuePartial({
+          cycleId: input.cycleId,
+          round,
+          issue: target,
+          pullRequest: pull.number,
+          remaining: report.status.remaining,
+        })
+      : await protectedEffect({
+          scope: {
+            phase: "pull-request",
+            operation: "github-close-issue",
+            round: round,
+          },
+          capability: "github",
+          method: "close-issue",
+          target: input.cycleId,
+          payload: JSON.stringify({
+            owner: target.owner,
+            repository: target.repository,
+            number: target.number,
+            pullRequest: pull.number,
+          }),
+          units: 1,
+        });
+  if (result.kind === "completed") return outcome;
+  return {
+    kind: outcome.kind,
+    cycleId: outcome.cycleId,
+    promotionId: outcome.promotionId,
+    ticketStatus: outcome.ticketStatus,
+    issueUpdate: "failed",
+  };
+}
+
+export async function labelTicket(
+  input: DevelopTask,
+  state: { readonly key: "start" | "blocked"; readonly round: number },
+): Promise<void> {
+  const issue = input.issue;
+  if (issue === null) return;
+  const result = await protectedEffect({
+    scope: {
+      phase: "pull-request",
+      operation: "github-label",
+      round: state.round,
+      key: state.key,
+    },
+    capability: "github",
+    method: "label",
+    target: input.cycleId,
+    payload: JSON.stringify({
+      owner: issue.owner,
+      repository: issue.repository,
+      number: issue.number,
+      add:
+        state.key === "start" ? ["cloving: in progress"] : ["cloving: blocked"],
+      remove:
+        state.key === "start"
+          ? ["cloving: ready", "cloving: blocked"]
+          : ["cloving: in progress"],
+    }),
+    units: 1,
+  });
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+}

package/templates/develop/develop/queue-partial.ts

@@ -0,0 +1,39 @@
+import type { ProtectedResult } from "cloving/workflows";
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+
+export interface QueuePartialInput {
+  readonly cycleId: string;
+  readonly round: number;
+  readonly remaining: readonly string[];
+  readonly issue: {
+    readonly owner: string;
+    readonly repository: string;
+    readonly number: number;
+  };
+  readonly pullRequest: number;
+}
+
+export async function queuePartial(
+  input: QueuePartialInput,
+): Promise<ProtectedResult> {
+  if (!Number.isSafeInteger(input.round) || input.round < 1 || input.round > 4)
+    throw new Error("invalid-development-round");
+  return await protectedEffect({
+    scope: {
+      phase: "pull-request",
+      operation: "github-partial-issue",
+      round: input.round,
+    },
+    capability: "github",
+    method: "partial-issue",
+    target: input.cycleId,
+    units: 1,
+    payload: JSON.stringify({
+      owner: input.issue.owner,
+      repository: input.issue.repository,
+      number: input.issue.number,
+      pullRequest: input.pullRequest,
+      remaining: input.remaining,
+    }),
+  });
+}

package/templates/develop/develop/refusal-tests.ts

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import { fakeStepBridge } from "cloving/workflows/testing";
+import { reportOf } from "./report.ts";
+import { openPull } from "./pull.ts";
+import { commit, input, completed } from "./scenarios.ts";
+import type { FlowTest } from "./flow-tests.ts";
+import { develop } from "../develop.ts";
+import { effects } from "./scenarios.ts";
+
+export const refusalTests: FlowTest[] = [];
+
+for (const operation of [
+  "claude run-turn",
+  "github open-pr",
+  "github wait-review",
+  "github merge",
+]) {
+  refusalTests.push({
+    name: `CLV-221 a ${operation} failure survives a blocked label failure`,
+    run: async () => {
+      using bridge = fakeStepBridge({
+        effects: {
+          ...effects(),
+          [operation]: [
+            {
+              kind: "failed",
+              operationId: "development-failed",
+              reason: "development-failed",
+            },
+          ],
+          "github label": [
+            completed({}),
+            {
+              kind: "failed",
+              operationId: "label-failed",
+              reason: "label-failed",
+            },
+          ],
+        },
+      });
+      await assert.rejects(develop(input), (error) => {
+        assert.ok(error instanceof AggregateError);
+        assert.equal(error.message, "development-and-label-failed");
+        assert.deepEqual(error.errors, [
+          new Error("development-failed"),
+          new Error("label-failed"),
+        ]);
+        assert.equal(error.cause, error.errors[1]);
+        return true;
+      });
+      const last = bridge.requests.at(-1);
+      assert.ok(last && last[0] === "effect");
+      assert.equal(last[1].method, "label");
+      assert.equal(last[1].scope.key, "blocked");
+    },
+  });
+}
+
+refusalTests.push({
+  name: "CLV-221 a failed lifecycle label stops before the worker runs",
+  run: async () => {
+    for (const reason of ["label-unavailable", null]) {
+      using bridge = fakeStepBridge({
+        effects: {
+          ...effects(),
+          "github label": [
+            {
+              kind: "failed",
+              operationId: "label-failed",
+              reason,
+            },
+          ],
+        },
+      });
+      await assert.rejects(develop(input), { message: reason ?? "failed" });
+      assert.equal(bridge.requests.length, 2);
+    }
+  },
+});
+
+refusalTests.push({
+  name: "CLV-221 a truncated worker summary preserves structured partial status",
+  run: () => {
+    const status = { kind: "partial", remaining: ["Verify recovery."] };
+    assert.deepEqual(
+      reportOf(
+        completed({ summary: "Report was truncated.", ticketStatus: status }),
+      ),
+      { summary: "Report was truncated.", status, commit: null, clean: false },
+    );
+    assert.throws(() => reportOf({ ...completed({}), result: null }), {
+      message: "invalid-development-report",
+    });
+    assert.throws(
+      () =>
+        reportOf({ kind: "failed", operationId: "turn-failed", reason: null }),
+      { message: "failed" },
+    );
+  },
+});
+
+refusalTests.push({
+  name: "CLV-221 invalid worker reports cannot open a pull request",
+  run: () => {
+    assert.throws(
+      () =>
+        reportOf({
+          kind: "failed",
+          operationId: "failed-operation",
+          reason: "worker-failed",
+        }),
+      {
+        message: "worker-failed",
+      },
+    );
+    for (const value of [null, {}, { summary: 42 }])
+      assert.throws(() => reportOf(completed(value)), {
+        message: "invalid-development-report",
+      });
+  },
+});
+
+refusalTests.push({
+  name: "CLV-221 malformed pull identities cannot reach review or merge",
+  run: async () => {
+    for (const value of [
+      null,
+      {},
+      { number: 7 },
+      { number: 7, url: "pull/7" },
+      { number: "7", url: "pull/7", commit },
+      { number: NaN, url: "pull/7", commit },
+      { number: 0, url: "pull/7", commit },
+      { number: 7, url: null, commit },
+      { number: 7, url: "pull/7", commit: 42 },
+      { number: 7, url: "pull/7", commit: "short" },
+    ]) {
+      using bridge = fakeStepBridge({ turn: completed(value) });
+      await assert.rejects(
+        openPull({
+          input: {
+            cycleId: input.cycleId,
+            repository: input.repository,
+            ticket: "Fix the counter.",
+            issue: null,
+          },
+          round: 1,
+        }),
+        { message: "invalid-pull-request" },
+      );
+      assert.equal(bridge.requests.length, 1);
+    }
+    using bridge = fakeStepBridge({
+      turn: {
+        kind: "failed",
+        operationId: "failed-operation",
+        reason: "open-failed",
+      },
+    });
+    await assert.rejects(
+      openPull({
+        input: {
+          cycleId: input.cycleId,
+          repository: input.repository,
+          ticket: "Fix the counter.",
+          issue: null,
+        },
+        round: 1,
+      }),
+      { message: "open-failed" },
+    );
+    assert.equal(bridge.requests.length, 1);
+  },
+});

package/templates/develop/develop/report.ts

@@ -0,0 +1,156 @@
+import {
+  ticketStatus,
+  type CycleOutcome,
+  type ProtectedResult,
+  type TicketStatus,
+} from "cloving/workflows";
+import { developTurn } from "./turn.ts";
+
+export interface DevelopInput {
+  readonly cycleId: string;
+  readonly repository: string;
+  readonly input:
+    | {
+        readonly ticket: { readonly id: string; readonly text: string };
+      }
+    | { readonly prompt: string };
+}
+
+export function ticketInput(input: DevelopInput): DevelopTask {
+  if (!("ticket" in input.input)) throw new Error("ticket-input-required");
+  return {
+    cycleId: input.cycleId,
+    repository: input.repository,
+    ticket: input.input.ticket.text,
+    issue: ticketIssue(input.input.ticket.text),
+  };
+}
+
+export function promptInput(input: DevelopInput): DevelopTask {
+  if (!("prompt" in input.input)) throw new Error("prompt-input-required");
+  return {
+    cycleId: input.cycleId,
+    repository: input.repository,
+    ticket: input.input.prompt,
+    issue: null,
+  };
+}
+
+export interface DevelopTask {
+  readonly cycleId: string;
+  readonly repository: string;
+  readonly ticket: string;
+  readonly issue: {
+    readonly owner: string;
+    readonly repository: string;
+    readonly number: number;
+  } | null;
+}
+
+function ticketIssue(ticket: string) {
+  const match = /^GitHub issue: ([\w.-]+)\/([\w.-]+)#(\d+)/m.exec(ticket);
+  if (match === null) return null;
+  return {
+    owner: match[1] ?? "",
+    repository: match[2] ?? "",
+    number: Number(match[3]),
+  };
+}
+
+export interface DevelopReport {
+  readonly summary: string;
+  readonly status: TicketStatus;
+  readonly commit: string | null;
+  readonly clean: boolean;
+}
+
+export interface DevelopState {
+  readonly input: DevelopTask;
+  readonly round: number;
+  readonly feedback: DevelopFeedback | null;
+}
+
+export async function developReport(
+  state: DevelopState,
+): Promise<DevelopReport> {
+  const { input, round, feedback } = state;
+  return reportOf(
+    await developTurn({
+      cycleId: input.cycleId,
+      repository: input.repository,
+      ticket: input.ticket,
+      round,
+      feedback,
+    }),
+  );
+}
+
+export function reportOf(result: ProtectedResult): DevelopReport {
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+  const value: unknown = JSON.parse(result.result ?? "null");
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("summary" in value) ||
+    typeof value.summary !== "string"
+  )
+    throw new Error("invalid-development-report");
+  const snapshot = commitSnapshot(value);
+  return {
+    summary: value.summary,
+    commit: snapshot.commit,
+    clean: snapshot.clean,
+    status: ticketStatus(
+      value.summary,
+      "ticketStatus" in value ? value.ticketStatus : undefined,
+    ),
+  };
+}
+
+function commitSnapshot(value: object) {
+  return {
+    commit:
+      "commit" in value && typeof value.commit === "string"
+        ? value.commit
+        : null,
+    clean:
+      "uncommitted" in value &&
+      Array.isArray(value.uncommitted) &&
+      value.uncommitted.length === 0,
+  };
+}
+
+export interface DevelopFeedback {
+  readonly reason: string;
+  readonly output: string;
+  readonly remaining: readonly string[];
+}
+
+export function repair(input: {
+  readonly cycleId: string;
+  readonly round: number;
+  readonly report: DevelopReport;
+  readonly result: { readonly reason: string | null; readonly output: string };
+}): DevelopFeedback | CycleOutcome {
+  const { cycleId, round, report, result } = input;
+  const reason = result.reason ?? "merge-failed";
+  const needsAnswer = reason === "review-changes" || reason === "not-approved";
+  if (
+    round === 4 ||
+    reason === "ci-pending" ||
+    reason === "check-not-configured" ||
+    (needsAnswer && result.output.trim() === "")
+  )
+    return {
+      kind: "blocked",
+      cycleId,
+      reason,
+      evidenceId: reason === "review-changes" ? "review" : "merge",
+    };
+  return {
+    reason,
+    output: result.output,
+    remaining: report.status.kind === "partial" ? report.status.remaining : [],
+  };
+}

package/templates/develop/develop/round.ts

@@ -0,0 +1,40 @@
+import type { CycleOutcome } from "cloving/workflows";
+import { mergeWhenGreen } from "cloving/workflows/steps/merge-when-green";
+import { acceptWork } from "./accept.ts";
+import { developReport } from "./report.ts";
+import { repair, type DevelopTask, type DevelopFeedback } from "./report.ts";
+import { openPull, finishPull, labelTicket } from "./pull.ts";
+
+export async function developRound(state: {
+  readonly input: DevelopTask;
+  readonly round: number;
+  readonly feedback: DevelopFeedback | null;
+}): Promise<CycleOutcome | DevelopFeedback> {
+  const { input, round } = state;
+  try {
+    const report = await developReport(state);
+    const pull = await openPull({ input, round });
+    const subject = {
+      target: pull.target,
+      number: pull.number,
+      commit: pull.commit,
+    };
+    const review = await acceptWork(subject);
+    const result = review.accepted
+      ? await mergeWhenGreen({ pull: pull, check: "beforeMerge", round: round })
+      : { merged: false, reason: "review-changes", output: review.feedback };
+    if (result.merged) return await finishPull({ input, round, report, pull });
+    return repair({ cycleId: input.cycleId, round, report, result });
+  } catch (error) {
+    try {
+      await labelTicket(input, { key: "blocked", round });
+    } catch (labelError) {
+      throw new AggregateError(
+        [error, labelError],
+        "development-and-label-failed",
+        { cause: labelError },
+      );
+    }
+    throw error;
+  }
+}

package/templates/develop/develop/scenarios.ts

@@ -0,0 +1,87 @@
+export const commit = "a".repeat(40);
+export const selection = {
+  input: "ticket",
+  select: "queue",
+  accept: "greptile",
+  merge: "green",
+  partial: "queue",
+};
+export const input = {
+  cycleId: "run-1",
+  repository: "main-checkout",
+  input: {
+    ticket: {
+      id: "42",
+      text: "# Fix the counter\n\nGitHub issue: acme/demo#42 (open)",
+    },
+  },
+};
+
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export function completed(
+  result: { readonly [key: string]: JsonValue } | null,
+) {
+  return {
+    kind: "completed" as const,
+    operationId: "operation",
+    receipt: null,
+    result: JSON.stringify(result),
+  };
+}
+
+export function effects() {
+  return {
+    "github prepare": [completed({})],
+    "github label": [completed({}), completed({})],
+    "claude run-turn": [
+      completed({ summary: "Implemented.\nTicket status: complete" }),
+    ],
+    "github open-pr": [completed({ number: 7, url: "pull/7", commit })],
+    "github wait-review": [
+      completed({ number: 7, commit, score: 5, summary: "Good", findings: [] }),
+    ],
+    "github merge": [completed({ number: 7, commit, merged: "merged" })],
+    "github close-issue": [completed({ number: 42 })],
+  };
+}
+
+export function partialEffects(
+  pullRequest: number,
+  remaining: readonly string[],
+) {
+  return {
+    ...effects(),
+    "claude run-turn": [
+      completed({
+        summary: `Remaining:\n${remaining.map((item) => `- ${item}`).join("\n")}\nTicket status: partial`,
+      }),
+    ],
+    "github open-pr": [
+      completed({
+        number: pullRequest,
+        url: `pull/${String(pullRequest)}`,
+        commit,
+      }),
+    ],
+    "github wait-review": [
+      completed({
+        number: pullRequest,
+        commit,
+        score: 5,
+        summary: "Good",
+        findings: [],
+      }),
+    ],
+    "github merge": [
+      completed({ number: pullRequest, commit, merged: "merged" }),
+    ],
+    "github partial-issue": [completed({ ticketStatus: "partial" })],
+  };
+}