cloving 0.3.20 → 1.1.0

package/dist/src/daemon/retrying-turn.js

@@ -0,0 +1,185 @@
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { priceOf, sumUsage, usageOf } from "../worker-usage.js";
+import { capacityRefusal, startTurn, } from "./claude-turn.js";
+import { readRecord, writeRecord } from "./operation-journal.js";
+const waits = [60_000, 180_000];
+const continuation = "An earlier attempt stopped because the model was at capacity; continue from the current state of the work tree.\n\n";
+function written(folder, entry) {
+    return writeRecord(folder, { ...entry, permissions: "private" });
+}
+function total(values) {
+    if (values.includes(null))
+        return null;
+    return priceOf(values.reduce((sum, value) => sum + (value ?? 0), 0));
+}
+function combined(ends) {
+    const last = ends.at(-1) ?? { exitCode: null, result: undefined };
+    if (ends.length < 2)
+        return last;
+    const result = last.result ?? ends.find((end) => end.result)?.result;
+    if (result === undefined)
+        return last;
+    return {
+        ...last,
+        result: {
+            ...result,
+            ...(last.result === undefined ? { failed: true, text: "" } : {}),
+            usage: sumUsage(ends.map((end) => end.result?.usage ?? usageOf(null))),
+            costUsd: total(ends.map((end) => end.result?.costUsd ?? null)),
+            turns: total(ends.map((end) => end.result?.turns ?? null)),
+        },
+    };
+}
+function controlled(attempts, start) {
+    const turn = startTurn(start);
+    const stop = () => {
+        turn.stop(attempts.grace.milliseconds);
+    };
+    attempts.stopping.signal.addEventListener("abort", stop, { once: true });
+    return {
+        ...turn,
+        ended: turn.ended.finally(() => {
+            attempts.stopping.signal.removeEventListener("abort", stop);
+        }),
+    };
+}
+async function launched(attempts) {
+    const { start, options, ends } = attempts;
+    const attempt = ends.length + 1;
+    const folder = start.mode === "analysis" || attempt === 1
+        ? start.folder
+        : join(start.folder, `attempt-${String(attempt)}`);
+    const entry = {
+        ...options.metadata,
+        attempt,
+        startedAt: attempt === 1 ? attempts.startedAt : new Date().toISOString(),
+    };
+    await written(start.folder, {
+        name: "started.json",
+        value: {
+            ...entry,
+            startedAt: attempts.startedAt,
+            phase: "starting",
+            processId: null,
+        },
+    });
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    if (attempts.stopping.signal.aborted)
+        return undefined;
+    const turn = controlled(attempts, {
+        ...start,
+        folder,
+        ...(attempt === 1 ? {} : { activityFolder: start.folder }),
+        prompt: attempt === 1 ? start.prompt : continuation + start.prompt,
+    });
+    try {
+        const value = { ...entry, phase: "running", processId: turn.processId };
+        await written(start.folder, {
+            name: "started.json",
+            value: { ...value, startedAt: attempts.startedAt },
+        });
+        await written(start.folder, {
+            name: `attempt-${String(attempt)}.json`,
+            value,
+        });
+        return turn;
+    }
+    catch (error) {
+        turn.stop(0);
+        await turn.ended;
+        throw error;
+    }
+}
+async function recordedEnd(attempts, completion) {
+    const { start, ends, options } = attempts;
+    const { processId, end } = completion;
+    const attempt = ends.length;
+    const name = `attempt-${String(attempt)}.json`;
+    const started = await readRecord(start.folder, name);
+    const startedAt = Reflect.get(Object(started), "startedAt");
+    if (typeof startedAt !== "string")
+        throw new Error("attempt-start-time-missing");
+    await written(start.folder, {
+        name,
+        value: {
+            ...options.metadata,
+            attempt,
+            processId,
+            startedAt,
+            endedAt: new Date().toISOString(),
+            exitCode: end.exitCode,
+            capacity: capacityRefusal(end.result),
+            usage: end.result?.usage ?? usageOf(null),
+            costUsd: end.result?.costUsd ?? null,
+        },
+    });
+}
+async function waited(attempts, milliseconds) {
+    const { start, options, stopping, ends } = attempts;
+    await written(start.folder, {
+        name: "started.json",
+        value: {
+            ...options.metadata,
+            startedAt: attempts.startedAt,
+            attempt: ends.length,
+            phase: "waiting",
+            processId: null,
+            waitMilliseconds: milliseconds,
+            waitingAt: new Date().toISOString(),
+        },
+    });
+    const wait = options.retryDelay ??
+        ((duration, signal) => delay(duration, undefined, { signal }));
+    await wait(milliseconds, stopping.signal).catch((error) => {
+        if (!stopping.signal.aborted)
+            throw error;
+    });
+}
+async function finished(attempts, first) {
+    const { ends } = attempts;
+    let turn = first;
+    while (turn !== undefined) {
+        const end = await turn.ended;
+        ends.push(end);
+        await recordedEnd(attempts, { processId: turn.processId, end });
+        const milliseconds = waits[ends.length - 1];
+        if (cancelled(attempts) ||
+            !capacityRefusal(end.result) ||
+            milliseconds === undefined)
+            break;
+        await waited(attempts, milliseconds);
+        if (cancelled(attempts))
+            return { ...combined(ends), stopped: true };
+        turn = await launched(attempts);
+    }
+    return {
+        ...combined(ends),
+        ...(cancelled(attempts) || turn === undefined ? { stopped: true } : {}),
+    };
+}
+function cancelled(attempts) {
+    return attempts.stopping.signal.aborted;
+}
+export async function startRetriedTurn(start, options) {
+    const attempts = {
+        start,
+        startedAt: new Date().toISOString(),
+        options,
+        stopping: new AbortController(),
+        ends: [],
+        grace: { milliseconds: 2_000 },
+    };
+    const turn = await launched(attempts);
+    if (turn === undefined)
+        throw new Error("turn-start-stopped");
+    return {
+        processId: turn.processId,
+        ended: finished(attempts, turn),
+        stop: (graceMilliseconds) => {
+            attempts.grace.milliseconds = graceMilliseconds;
+            attempts.stopping.abort();
+        },
+    };
+}

package/dist/src/daemon/ticket-registration.d.ts

@@ -0,0 +1,33 @@
+import type { DeclaredWorkflow } from "../workflow-declaration.ts";
+import type { Resolver, WorkflowRegistration } from "../service/registry.ts";
+export declare const ticketWorkflow = "develop-ticket";
+export declare const promptWorkflow = "develop-prompt";
+export declare const issueWorkflow = "develop-issue";
+export declare const ticketCapabilities: string[];
+export type TicketRegistrations = {
+    readonly kind: "admitted";
+    readonly registrations: readonly WorkflowRegistration[];
+} | {
+    readonly kind: "rejected";
+    readonly detail: string;
+};
+export interface TicketSource {
+    readonly repository: string;
+    readonly command: readonly string[] | undefined;
+    readonly nextCommand?: readonly string[] | undefined;
+}
+export interface TicketRegistration {
+    readonly workflowId: string;
+    readonly functionName: string;
+    readonly resolver: Resolver;
+    readonly submission: WorkflowRegistration["submission"];
+    readonly effectLimit: number;
+    readonly capabilities?: readonly string[];
+}
+export declare function ticketResolver(source: TicketSource): Resolver;
+export declare function issueResolver(source: TicketSource): Resolver;
+export declare function promptResolver(repository: string): Resolver;
+export declare function ticketRegistrationTable(source: TicketSource, declarations?: readonly DeclaredWorkflow[]): readonly TicketRegistration[];
+export declare function ticketRegistrations(manifests: Readonly<Record<string, string | undefined>>, options: {
+    readonly table: readonly TicketRegistration[];
+}): Promise<TicketRegistrations>;

package/dist/src/daemon/ticket-registration.js

@@ -0,0 +1,177 @@
+import { createHash } from "node:crypto";
+import { admitCompiled } from "../cli/validate.js";
+import { ticketCommandText, ticketText } from "./ticket-source.js";
+export const ticketWorkflow = "develop-ticket";
+export const promptWorkflow = "develop-prompt";
+export const issueWorkflow = "develop-issue";
+export const ticketCapabilities = ["claude", "github"];
+const ticketIdentifier = /^[A-Za-z0-9._:-]{1,64}$/;
+function rejected(code, detail) {
+    return { kind: "rejected", code, detail };
+}
+function digest(commandId) {
+    return createHash("sha256").update(commandId).digest("hex");
+}
+async function ticket(source, request) {
+    const { command, repository } = source;
+    const ticketId = String(request.submission["ticket"]);
+    if (ticketId === "next")
+        return nextTicket(source, request);
+    if (!ticketIdentifier.test(ticketId))
+        return rejected("invalid-ticket-id", "A ticket ID has letters, digits and the characters . _ : - only.");
+    if (command === undefined)
+        return rejected("ticket-source-not-configured", "The daemon has no ticket command. Set CLOVING_TICKET_COMMAND, or use the workflow develop-prompt.");
+    const read = await ticketText(command, { ticketId, signal: request.signal });
+    if (read.kind === "failed")
+        return rejected("ticket-not-available", read.detail);
+    const name = ticketId.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    return {
+        kind: "resolved",
+        input: {
+            cycleId: `${name}-${digest(request.commandId).slice(0, 8)}`,
+            ticketId,
+            ticket: read.text,
+            repository,
+        },
+    };
+}
+async function nextTicket(source, request) {
+    if (source.nextCommand === undefined)
+        return rejected("next-source-not-configured", "The daemon has no next-ticket command. Set CLOVING_NEXT_COMMAND.");
+    const selected = await ticketCommandText(source.nextCommand, request.signal);
+    if (selected.kind === "failed")
+        return rejected("next-ticket-not-available", selected.detail);
+    if (selected.text === "")
+        return rejected("no-ready-ticket", "The next-ticket command printed no ticket ID.");
+    if (!ticketIdentifier.test(selected.text) || selected.text === "next")
+        return rejected("invalid-ticket-id", "The next-ticket command must print one valid ticket ID other than next.");
+    return ticket(source, { ...request, submission: { ticket: selected.text } });
+}
+export function ticketResolver(source) {
+    return {
+        id: "ticket-command",
+        version: "1",
+        resolve: (request) => ticket(source, request),
+    };
+}
+export function issueResolver(source) {
+    return {
+        id: "issue-command",
+        version: "1",
+        resolve: async (request) => {
+            const resolution = await ticket(source, request);
+            if (resolution.kind === "rejected")
+                return resolution;
+            return {
+                kind: "resolved",
+                input: { ...Object(resolution.input), delivery: "pull-request" },
+            };
+        },
+    };
+}
+export function promptResolver(repository) {
+    return {
+        id: "ticket-prompt",
+        version: "1",
+        resolve: (request) => Promise.resolve({
+            kind: "resolved",
+            input: {
+                cycleId: `task-${digest(request.commandId).slice(0, 12)}`,
+                ticket: String(request.submission["prompt"]),
+                repository,
+            },
+        }),
+    };
+}
+export function ticketRegistrationTable(source, declarations = []) {
+    return [
+        {
+            workflowId: ticketWorkflow,
+            functionName: "developTicket",
+            effectLimit: 8,
+            submission: { maximumBytes: 4_096, fields: { ticket: "string" } },
+            resolver: ticketResolver(source),
+        },
+        {
+            workflowId: issueWorkflow,
+            functionName: "developTicket",
+            effectLimit: 20,
+            submission: { maximumBytes: 4_096, fields: { ticket: "string" } },
+            resolver: issueResolver(source),
+        },
+        {
+            workflowId: "develop-prd",
+            functionName: "developPrd",
+            effectLimit: 8,
+            submission: { maximumBytes: 65_536, fields: { prompt: "string" } },
+            resolver: promptResolver(source.repository),
+        },
+        {
+            workflowId: promptWorkflow,
+            functionName: "developTicket",
+            effectLimit: 8,
+            submission: { maximumBytes: 65_536, fields: { prompt: "string" } },
+            resolver: promptResolver(source.repository),
+        },
+        ...declarations.map((declaration) => ({
+            workflowId: declaration.workflowId,
+            functionName: declaration.functionName,
+            effectLimit: declaration.effectLimit,
+            capabilities: declaration.capabilities,
+            submission: declaration.input,
+            resolver: declaredResolver(source.repository),
+        })),
+    ];
+}
+function declaredResolver(repository) {
+    return {
+        id: "declared-input",
+        version: "1",
+        resolve: (request) => Promise.resolve({
+            kind: "resolved",
+            input: {
+                cycleId: `task-${digest(request.commandId).slice(0, 12)}`,
+                repository,
+                input: request.submission,
+            },
+        }),
+    };
+}
+export async function ticketRegistrations(manifests, options) {
+    const ids = new Set();
+    for (const row of options.table) {
+        if (ids.has(row.workflowId))
+            return {
+                kind: "rejected",
+                detail: `duplicate-workflow-id: ${row.workflowId}`,
+            };
+        ids.add(row.workflowId);
+    }
+    const registrations = [];
+    for (const row of options.table) {
+        const manifest = manifests[row.functionName];
+        if (manifest === undefined)
+            return {
+                kind: "rejected",
+                detail: `Missing manifest for workflow function ${row.functionName}.`,
+            };
+        const admission = await admitCompiled(manifest, {
+            file: manifest,
+            capabilities: row.capabilities ?? ticketCapabilities,
+        });
+        if (admission.kind === "rejected")
+            return {
+                kind: "rejected",
+                detail: `${admission.error.code}: ${admission.error.detail}`,
+            };
+        registrations.push({
+            workflowId: row.workflowId,
+            manifest: admission.manifest,
+            availability: "available",
+            effectLimit: row.effectLimit,
+            submission: row.submission,
+            resolver: row.resolver,
+        });
+    }
+    return { kind: "admitted", registrations };
+}

package/dist/src/daemon/ticket-source.d.ts

@@ -0,0 +1,17 @@
+export declare const ticketLimits: {
+    textBytes: number;
+    detailCharacters: number;
+};
+export type TicketRead = {
+    readonly kind: "read";
+    readonly text: string;
+} | {
+    readonly kind: "failed";
+    readonly detail: string;
+};
+export interface TicketRequest {
+    readonly ticketId: string;
+    readonly signal: AbortSignal;
+}
+export declare function ticketText(command: readonly string[], request: TicketRequest): Promise<TicketRead>;
+export declare function ticketCommandText(command: readonly string[], signal: AbortSignal): Promise<TicketRead>;

package/dist/src/daemon/ticket-source.js

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+export const ticketLimits = { textBytes: 48_000, detailCharacters: 300 };
+function failed(detail) {
+    return { kind: "failed", detail };
+}
+function printed(output) {
+    const text = output.trim();
+    if (text === "")
+        return failed("The ticket command printed no text.");
+    if (Buffer.byteLength(text) > ticketLimits.textBytes)
+        return failed(`The ticket text has more than ${String(ticketLimits.textBytes)} bytes.`);
+    return { kind: "read", text };
+}
+function ended(error) {
+    const code = Reflect.get(Object(error), "code");
+    const cause = String(Reflect.get(Object(error), "stderr"))
+        .trim()
+        .slice(0, ticketLimits.detailCharacters);
+    return typeof code === "number"
+        ? failed(`The ticket command ended with the code ${String(code)}: ${cause}`)
+        : failed(`The ticket command did not complete: ${String(code)}`);
+}
+const executed = promisify(execFile);
+export function ticketText(command, request) {
+    const [executable = "", ...fixed] = command;
+    return ticketCommandText([executable, ...fixed, request.ticketId], request.signal).then((result) => result.kind === "failed" ? result : printed(result.text));
+}
+export function ticketCommandText(command, signal) {
+    const [executable = "", ...fixed] = command;
+    return executed(executable, fixed, {
+        signal,
+        maxBuffer: 4 * ticketLimits.textBytes,
+        encoding: "utf8",
+    }).then((output) => ({ kind: "read", text: output.stdout.trim() }), ended);
+}

package/dist/src/daemon/work-tree.d.ts

@@ -0,0 +1,26 @@
+export interface WorkTree {
+    readonly path: string;
+    readonly branch: string;
+    readonly startCommit: string;
+}
+export interface TreeRequest {
+    readonly repository: string;
+    readonly worktrees: string;
+    readonly target: string;
+    readonly signal: AbortSignal;
+    readonly base?: string;
+}
+export interface Changes {
+    readonly branch: string;
+    readonly commits: readonly string[];
+    readonly files: readonly string[];
+    readonly uncommitted: readonly string[];
+}
+export declare function treeName(target: string): string;
+export declare function treePlace(request: Pick<TreeRequest, "worktrees" | "target">): {
+    readonly path: string;
+    readonly branch: string;
+};
+export declare function workTree(request: TreeRequest): Promise<WorkTree>;
+export declare function treeFailure(error: unknown): string;
+export declare function changes(tree: WorkTree): Promise<Changes>;

package/dist/src/daemon/work-tree.js

@@ -0,0 +1,206 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+const executed = promisify(execFile);
+const lineLimit = 30;
+const lineLength = 120;
+async function git(call) {
+    const { directory, parts, signal } = call;
+    const { stdout } = await executed("git", ["-C", directory, ...parts], {
+        ...(signal === undefined ? {} : { signal }),
+    });
+    return stdout;
+}
+export function treeName(target) {
+    return target
+        .replace(/[^A-Za-z0-9._-]/g, "-")
+        .replace(/\.{2,}/g, "-")
+        .replace(/^\.|\.$/g, "-")
+        .replace(/\.lock$/, "-lock");
+}
+async function added(request, tree) {
+    const { repository, worktrees, signal } = request;
+    const call = (parts) => git({ directory: repository, parts, signal });
+    await call(["worktree", "prune"]);
+    await mkdir(worktrees, { recursive: true });
+    const known = await call([
+        "rev-parse",
+        "--verify",
+        "--quiet",
+        `refs/heads/${tree.branch}`,
+    ]).then(() => true, () => false);
+    await call(known
+        ? ["worktree", "add", tree.path, tree.branch]
+        : [
+            "worktree",
+            "add",
+            "-b",
+            tree.branch,
+            tree.path,
+            request.base ?? "HEAD",
+        ]);
+}
+export function treePlace(request) {
+    const name = treeName(request.target);
+    return { path: join(request.worktrees, name), branch: `cloving/${name}` };
+}
+export async function workTree(request) {
+    if (request.target.startsWith("branch:"))
+        return branchTree(request).catch((error) => {
+            const reason = treeFailure(error);
+            throw new Error(reason === "work-tree-not-available"
+                ? "branch-worktree-not-found"
+                : reason);
+        });
+    const { path, branch } = treePlace(request);
+    if (!existsSync(join(path, ".git")))
+        await added(request, { path, branch });
+    const head = await git({
+        directory: path,
+        parts: ["rev-parse", "HEAD"],
+        signal: request.signal,
+    });
+    return { path, branch, startCommit: head.trim() };
+}
+async function branchTree(request) {
+    const branch = request.target.slice("branch:".length);
+    if (branch.startsWith("cloving/"))
+        throw new Error("branch-reserved");
+    const listing = await git({
+        directory: request.repository,
+        parts: ["worktree", "list", "--porcelain", "-z"],
+        signal: request.signal,
+    });
+    const entry = listing
+        .split("\0\0")
+        .slice(1)
+        .find((record) => record.split("\0").includes(`branch refs/heads/${branch}`));
+    const path = entry?.split("\0")[0]?.slice("worktree ".length);
+    if (path === undefined)
+        throw new Error("branch-worktree-not-found");
+    await sameBranch(request, { path, branch });
+    await outsideManaged(request, path);
+    await cleanBranch({ directory: path, signal: request.signal });
+    const head = await git({
+        directory: path,
+        parts: ["rev-parse", "HEAD"],
+        signal: request.signal,
+    });
+    return { path, branch, startCommit: head.trim() };
+}
+async function outsideManaged(request, path) {
+    const folder = await realpath(request.worktrees).catch((error) => {
+        if (typeof error !== "object" ||
+            error === null ||
+            !("code" in error) ||
+            error.code !== "ENOENT")
+            throw error;
+        return resolve(request.worktrees);
+    });
+    const location = relative(folder, await realpath(path));
+    if (location !== ".." && !location.startsWith(`..${sep}`))
+        throw new Error("branch-reserved");
+}
+async function sameBranch(request, tree) {
+    const common = async (directory) => {
+        const folder = await git({
+            directory,
+            parts: ["rev-parse", "--git-common-dir"],
+            signal: request.signal,
+        });
+        return realpath(resolve(directory, folder.trim()));
+    };
+    if ((await common(request.repository)) !== (await common(tree.path)))
+        throw new Error("branch-worktree-not-found");
+    const head = await git({
+        directory: tree.path,
+        parts: ["symbolic-ref", "--quiet", "HEAD"],
+        signal: request.signal,
+    });
+    if (head.trim() !== `refs/heads/${tree.branch}`)
+        throw new Error("branch-worktree-not-found");
+}
+async function cleanBranch(place) {
+    await cleanOutput({
+        ...place,
+        parts: [
+            "-c",
+            "core.fileMode=true",
+            "status",
+            "--porcelain",
+            "--untracked-files=all",
+            "--ignore-submodules=none",
+        ],
+    }, hasOutput);
+    await cleanOutput({ ...place, parts: ["ls-files", "-v", "-z"] }, hiddenIndex);
+}
+async function hasOutput(output) {
+    let present = false;
+    for await (const chunk of output) {
+        if (chunk.length > 0)
+            present = true;
+    }
+    return present;
+}
+async function hiddenIndex(output) {
+    let entryStart = true;
+    let hidden = false;
+    for await (const chunk of output) {
+        for (const character of chunk.toString()) {
+            if (entryStart && /[a-zS]/.test(character))
+                hidden = true;
+            entryStart = character === "\0";
+        }
+    }
+    return hidden;
+}
+async function cleanOutput(call, inspect) {
+    const child = spawn("git", ["-C", call.directory, ...call.parts], {
+        stdio: ["ignore", "pipe", "ignore"],
+        ...(call.signal === undefined ? {} : { signal: call.signal }),
+    });
+    const ended = new Promise((resolve) => {
+        child.once("error", () => {
+            resolve(false);
+        });
+        child.once("close", (code) => {
+            resolve(code === 0);
+        });
+    });
+    const dirty = await inspect(child.stdout);
+    if (!(await ended))
+        throw new Error("branch-worktree-not-found");
+    if (dirty)
+        throw new Error("branch-worktree-not-clean");
+}
+export function treeFailure(error) {
+    const reason = error instanceof Error ? error.message : "";
+    return [
+        "branch-worktree-not-found",
+        "branch-worktree-not-clean",
+        "branch-reserved",
+    ].includes(reason)
+        ? reason
+        : "work-tree-not-available";
+}
+export async function changes(tree) {
+    const lines = async (parts) => (await git({ directory: tree.path, parts }).catch(() => ""))
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .slice(0, lineLimit)
+        .map((line) => line.slice(0, lineLength));
+    const range = `${tree.startCommit}..HEAD`;
+    const [branch = tree.branch] = await lines([
+        "rev-parse",
+        "--abbrev-ref",
+        "HEAD",
+    ]);
+    return {
+        branch,
+        commits: await lines(["log", "--oneline", range]),
+        files: await lines(["diff", "--stat", range]),
+        uncommitted: await lines(["status", "--short"]),
+    };
+}