cloving 0.3.20 → 1.1.0

package/dist/src/cli/watch-run-input.d.ts

@@ -0,0 +1,14 @@
+import { type ServiceRequest } from "../protocol.ts";
+export interface CardField {
+    readonly name: string;
+    readonly label: string;
+    readonly multiline: boolean;
+    readonly optional: boolean;
+}
+export interface CardForm {
+    readonly workflowId: string;
+    readonly source: "ticket" | "prompt" | "input";
+    readonly fields: readonly CardField[];
+}
+export declare function builtinCardForms(): readonly CardForm[];
+export declare function cardRunRequest(forms: readonly CardForm[], value: unknown): ServiceRequest | null;

package/dist/src/cli/watch-run-input.js

@@ -0,0 +1,49 @@
+import { record } from "../protocol.js";
+export function builtinCardForms() {
+    const entries = [
+        ["develop-issue", "ticket", "Issue number"],
+        ["develop-ticket", "ticket", "Ticket ID"],
+        ["develop-prd", "prompt", "Idea"],
+        ["develop-prompt", "prompt", "Task"],
+    ];
+    return entries.map(([workflowId, name, label]) => ({
+        workflowId,
+        source: name === "ticket" ? "ticket" : "prompt",
+        fields: [{ name, label, multiline: name === "prompt", optional: false }],
+    }));
+}
+function validFields(form, fields) {
+    if (Object.keys(fields).some((name) => !form.fields.some((field) => field.name === name)))
+        return false;
+    return form.fields.every((field) => {
+        if (field.optional && !Object.hasOwn(fields, field.name))
+            return true;
+        const text = fields[field.name];
+        return typeof text === "string" && text.trim() !== "";
+    });
+}
+export function cardRunRequest(forms, value) {
+    const body = record(value);
+    if (body === undefined ||
+        Object.keys(body).some((key) => !["workflowId", "fields", "commandId"].includes(key)))
+        return null;
+    const { workflowId, commandId } = body;
+    const form = forms.find((item) => item.workflowId === workflowId);
+    const fields = record(body["fields"]);
+    if (form === undefined ||
+        fields === undefined ||
+        typeof commandId !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(commandId))
+        return null;
+    if (!validFields(form, fields))
+        return null;
+    return {
+        operation: "run",
+        parameters: {
+            workflowId,
+            source: form.source,
+            submission: fields,
+            commandId,
+        },
+    };
+}

package/dist/src/cli/watch-server.d.ts

@@ -0,0 +1,13 @@
+import { type WatchPrSettings } from "./watch-pr-settings.ts";
+export declare const defaultWatchPort = 3663;
+export interface WatchSettings {
+    readonly actions?: string;
+    readonly pullRequests?: WatchPrSettings;
+    readonly runtimeDirectory: string;
+    readonly port: number;
+    readonly client: string;
+    readonly announce: (text: string) => void;
+    readonly complain: (text: string) => void;
+    readonly stopped: Promise<void>;
+}
+export declare function watchServer(settings: WatchSettings): Promise<number>;

package/dist/src/cli/watch-server.js

@@ -0,0 +1,214 @@
+import { watchAction, watchActions, watchHost, } from "./watch-actions.js";
+import { observedBoard } from "./watch-pr-board.js";
+import { watchPrObserver } from "./watch-pr-settings.js";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { watchReader } from "./watch-reads.js";
+import { turnOf, watchModel } from "./watch-model.js";
+import { pageDocument } from "./watch-page.js";
+import { watchStream } from "./watch-stream.js";
+export const defaultWatchPort = 3663;
+const forbidden = { status: 403, type: "text/plain", body: "refused" };
+const notFound = { status: 404, type: "text/plain", body: "not found" };
+const libraryFile = fileURLToPath(import.meta.resolve("preact"));
+function parsed(text) {
+    try {
+        const value = JSON.parse(text);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+const noStream = { size: 0, lines: [], activeAt: null };
+async function streamed(watch, file) {
+    const found = await stat(file).catch(() => null);
+    if (found === null)
+        return noStream;
+    const known = watch.streams.get(file);
+    const activeAt = found.mtime.toISOString();
+    if (known?.size === found.size)
+        return { ...known, activeAt };
+    const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
+    watch.streams.set(file, { size: found.size, lines });
+    return { size: found.size, lines, activeAt };
+}
+async function stored(file) {
+    return parsed(await readFile(file, "utf8").catch(() => "null"));
+}
+async function turns(watch) {
+    const journal = join(dirname(watch.settings.runtimeDirectory), "journal");
+    const found = [];
+    for (const key of await readdir(journal).catch(() => [])) {
+        const started = await stored(join(journal, key, "started.json"));
+        if (started === null)
+            continue;
+        const stream = await streamed(watch, join(journal, key, "turn.jsonl"));
+        found.push(turnOf({
+            key,
+            started,
+            result: await stored(join(journal, key, "result.json")),
+            lines: stream.lines,
+            activeAt: stream.activeAt,
+        }));
+    }
+    return found.toSorted((first, second) => first.startedAt < second.startedAt ? -1 : 1);
+}
+async function githubRecords(watch) {
+    const journal = join(dirname(watch.settings.runtimeDirectory), "github");
+    const keys = await readdir(journal).catch(() => []);
+    for (const key of keys) {
+        const known = watch.github.get(key);
+        if (known !== undefined && known.result !== null)
+            continue;
+        const started = known?.started ?? (await stored(join(journal, key, "started.json")));
+        if (started === null)
+            continue;
+        const result = await stored(join(journal, key, "result.json"));
+        watch.github.set(key, { started, result });
+    }
+    return keys.flatMap((key) => watch.github.get(key) ?? []);
+}
+async function snapshot(watch, runId) {
+    const updatedAt = new Date().toISOString();
+    const [read, journal, github] = await Promise.all([
+        runId === null ? watch.reader.read(updatedAt) : watch.reader.run(runId),
+        turns(watch),
+        githubRecords(watch),
+    ]);
+    const model = watchModel({
+        ...read,
+        home: homedir(),
+        client: watch.settings.client,
+        updatedAt,
+        turns: journal,
+        githubRecords: github,
+    });
+    const shown = runId === null ? observedBoard(model, watch.observer) : model;
+    return {
+        ...shown,
+        cardForms: watch.actions?.forms.filter((form) => shown.workflows.some((workflow) => workflow.workflowId === form.workflowId)) ?? [],
+    };
+}
+async function answered(watch, request) {
+    if (!watchHost(request))
+        return forbidden;
+    const url = new URL(String(request.url), "http://localhost");
+    if (request.method === "GET")
+        return readReply(watch, url);
+    if (request.method !== "POST" ||
+        url.pathname !== "/actions/run" ||
+        watch.actions === null)
+        return notFound;
+    const body = await watchAction(watch.actions, request).catch(() => null);
+    return body === null
+        ? forbidden
+        : { status: 200, type: "application/json", body };
+}
+async function readReply(watch, url) {
+    const path = url.pathname;
+    if (path === "/")
+        return {
+            status: 200,
+            type: "text/html; charset=utf-8",
+            body: pageDocument(watch.actions?.token ?? null),
+        };
+    if (path === "/preact.mjs")
+        return {
+            status: 200,
+            type: "text/javascript; charset=utf-8",
+            body: await readFile(libraryFile, "utf8"),
+        };
+    if (path !== "/data.json")
+        return notFound;
+    const runId = url.searchParams.get("runId");
+    const model = await snapshot(watch, runId);
+    if (runId !== null && model.runs.length === 0)
+        return notFound;
+    return {
+        status: 200,
+        type: "application/json",
+        body: JSON.stringify(runId === null ? model : { run: model.runs[0] }),
+    };
+}
+function replied(response, reply) {
+    response.writeHead(reply.status, {
+        "content-type": reply.type,
+        "cache-control": "no-store",
+    });
+    response.end(reply.body);
+}
+function subscribed(stream, exchange) {
+    const { request, response } = exchange;
+    const changed = () => {
+        response.write("data: change\n\n");
+    };
+    response.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-store",
+    });
+    changed();
+    request.once("close", stream.subscribe(changed));
+}
+export async function watchServer(settings) {
+    const observer = await observerFor(settings);
+    const watch = {
+        actions: settings.actions === "off"
+            ? null
+            : await watchActions(settings.runtimeDirectory),
+        settings,
+        observer,
+        reader: watchReader(settings.runtimeDirectory),
+        streams: new Map(),
+        github: new Map(),
+    };
+    const stream = watchStream({
+        runtimeDirectory: settings.runtimeDirectory,
+        journal: join(dirname(settings.runtimeDirectory), "journal"),
+        retryMilliseconds: 1000,
+    });
+    const server = createServer((request, response) => {
+        if (watchHost(request) &&
+            request.method === "GET" &&
+            request.url === "/events") {
+            subscribed(stream, { request, response });
+            return;
+        }
+        answered(watch, request).then((reply) => {
+            replied(response, reply);
+        }, () => {
+            replied(response, { ...notFound, status: 500, body: "failed" });
+        });
+    });
+    return new Promise((settle) => {
+        server.once("error", (error) => {
+            observer.close();
+            stream.close();
+            settings.complain(`watch-not-started: ${error.message}\n`);
+            settle(1);
+        });
+        server.listen(settings.port, "127.0.0.1", () => {
+            const bound = Reflect.get(Object(server.address()), "port");
+            settings.announce(`Watch page: http://127.0.0.1:${String(bound)}/\n`);
+        });
+        const closed = () => {
+            observer.close();
+            stream.close();
+            server.close();
+            server.closeAllConnections();
+            settle(0);
+        };
+        settings.stopped.then(closed, closed);
+    });
+}
+function observerFor(settings) {
+    if (settings.pullRequests !== undefined)
+        return watchPrObserver(settings.pullRequests);
+    return Promise.resolve({
+        observe: () => ({ status: "unavailable", failure: "configuration" }),
+        close: () => undefined,
+    });
+}

package/dist/src/cli/watch-start-view.d.ts

@@ -0,0 +1,18 @@
+import { type Shown } from "./watch-element.ts";
+import type { Copying, WatchModel } from "./watch-render.ts";
+interface StartPrompt {
+    readonly workflowId: string;
+    readonly sentence: string;
+    readonly prompt: string;
+}
+export declare function startPrompts(): readonly StartPrompt[];
+export declare function StartCard(props: {
+    readonly item: StartPrompt;
+    readonly copying: Copying;
+}): Shown;
+export declare function StartRun(props: {
+    readonly workflows: WatchModel["workflows"];
+    readonly copying: Copying;
+    readonly shown?: boolean;
+}): Shown;
+export {};

package/dist/src/cli/watch-start-view.js

@@ -0,0 +1,77 @@
+import { component, element } from "./watch-element.js";
+import { Command } from "./watch-turn.js";
+export function startPrompts() {
+    return [
+        {
+            workflowId: "develop-issue",
+            sentence: "Work on a GitHub issue through a pull request.",
+            prompt: `Start a Cloving run for a GitHub issue in this repository.
+Run: cloving run develop-issue --ticket ISSUE_NUMBER
+Use the issue number that I give on the last line.
+Report the run ID. Then run cloving status RUN_ID until the run completes or stops, and tell me the result and the pull request.
+Do not push, merge or change labels yourself.
+Issue number:`,
+        },
+        {
+            workflowId: "develop-ticket",
+            sentence: "Work on a ticket with your review of the diff.",
+            prompt: `Start a Cloving run for a ticket in this repository.
+Run: cloving run develop-ticket --ticket TICKET_ID
+Use the ticket ID that I give on the last line.
+When the run waits for a decision, run cloving questions, show me the diff and the decision, and give me the approve and deny commands.
+Run only the command that I choose. Do not decide for me.
+Ticket ID:`,
+        },
+        {
+            workflowId: "develop-prd",
+            sentence: "Turn an idea into a GitHub issue.",
+            prompt: `Start a Cloving run that turns an idea into a GitHub issue.
+Run: cloving run develop-prd --prompt "IDEA"
+Use the idea that I give on the last line as IDEA.
+When the run completes, show me the new issue.
+Add the label cloving: ready only when I tell you to.
+Idea:`,
+        },
+        {
+            workflowId: "develop-prompt",
+            sentence: "Do a small task with your review of the diff.",
+            prompt: `Start a Cloving run for a small task in this repository.
+Run: cloving run develop-prompt --prompt "TASK"
+Use the task that I give on the last line as TASK.
+When the run waits for a decision, run cloving questions, show me the diff, and give me the approve and deny commands.
+Run only the command that I choose. Do not decide for me.
+Task:`,
+        },
+    ];
+}
+export function StartCard(props) {
+    const { item, copying } = props;
+    return element("article", {
+        class: "start-card",
+        children: [
+            element("h3", { children: item.workflowId }),
+            element("p", { children: item.sentence }),
+            component(Command, {
+                label: "Agent prompt",
+                command: item.prompt,
+                copyLabel: "Copy the prompt",
+                copying,
+            }),
+        ],
+    });
+}
+export function StartRun(props) {
+    const registered = startPrompts().filter((item) => props.workflows.some((workflow) => workflow.workflowId === item.workflowId));
+    const cards = registered.map((item) => component(StartCard, {
+        key: item.workflowId,
+        item,
+        copying: props.copying,
+    }));
+    return element("section", {
+        class: "start-run",
+        id: "start-run",
+        "aria-label": "Start a run",
+        hidden: props.shown !== true,
+        children: element("div", { class: "start-cards", children: cards }),
+    });
+}

package/dist/src/cli/watch-stream.d.ts

@@ -0,0 +1,11 @@
+export interface StreamSettings {
+    readonly runtimeDirectory: string;
+    readonly journal: string;
+    readonly retryMilliseconds: number;
+}
+export interface WatchStream {
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly close: () => void;
+}
+export declare function throttled(notify: () => void, milliseconds: number): () => void;
+export declare function watchStream(settings: StreamSettings): WatchStream;

package/dist/src/cli/watch-stream.js

@@ -0,0 +1,128 @@
+import { watch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { follow, send } from "./client.js";
+const burstMilliseconds = 100;
+export function throttled(notify, milliseconds) {
+    const burst = { open: false, again: false };
+    const fire = () => {
+        burst.open = true;
+        setTimeout(ended, milliseconds).unref();
+        notify();
+    };
+    const ended = () => {
+        burst.open = false;
+        if (!burst.again)
+            return;
+        burst.again = false;
+        fire();
+    };
+    return () => {
+        if (burst.open)
+            burst.again = true;
+        else
+            fire();
+    };
+}
+async function paused(stream) {
+    const { signal } = stream.stopping;
+    await delay(stream.settings.retryMilliseconds, undefined, { signal }).catch(() => undefined);
+}
+async function serviceFollowed(stream) {
+    const { runtimeDirectory } = stream.settings;
+    while (!stream.stopping.signal.aborted) {
+        const page = await send(runtimeDirectory, {
+            operation: "events",
+            parameters: { limit: 1 },
+        });
+        if (page.kind === "result") {
+            stream.notify();
+            const after = page.result["latestSequence"];
+            await follow(runtimeDirectory, {
+                request: { operation: "events", parameters: { after, follow: true } },
+                onEvent: stream.notify,
+                signal: stream.stopped,
+            });
+            stream.notify();
+        }
+        await paused(stream);
+    }
+}
+function present(file) {
+    return stat(file).then(() => true, () => false);
+}
+async function openTurns(journal) {
+    const files = [];
+    for (const folder of await readdir(journal).catch(() => [])) {
+        const started = await present(join(journal, folder, "started.json"));
+        const ended = await present(join(journal, folder, "result.json"));
+        if (started && !ended)
+            files.push(join(journal, folder, "turn.jsonl"));
+    }
+    return files;
+}
+function tailed(stream, file) {
+    if (stream.tails.has(file))
+        return;
+    try {
+        const watcher = watch(file, stream.notify);
+        watcher.on("error", stream.notify);
+        stream.tails.set(file, watcher);
+    }
+    catch {
+        return;
+    }
+    stream.notify();
+}
+async function tailsRefreshed(stream) {
+    const open = await openTurns(stream.settings.journal);
+    for (const [file, watcher] of stream.tails) {
+        if (open.includes(file))
+            continue;
+        watcher.close();
+        stream.tails.delete(file);
+        stream.notify();
+    }
+    for (const file of open)
+        tailed(stream, file);
+}
+async function journalWatched(stream) {
+    while (!stream.stopping.signal.aborted) {
+        await tailsRefreshed(stream);
+        await paused(stream);
+    }
+    for (const watcher of stream.tails.values())
+        watcher.close();
+}
+export function watchStream(settings) {
+    const listeners = new Set();
+    const stopping = new AbortController();
+    const stream = {
+        settings,
+        stopping,
+        stopped: new Promise((settle) => {
+            stopping.signal.addEventListener("abort", () => {
+                settle();
+            });
+        }),
+        notify: throttled(() => {
+            for (const listener of [...listeners])
+                listener();
+        }, burstMilliseconds),
+        tails: new Map(),
+    };
+    Promise.allSettled([serviceFollowed(stream), journalWatched(stream)]).then(() => undefined, () => undefined);
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        close: () => {
+            listeners.clear();
+            stopping.abort();
+        },
+    };
+}

package/dist/src/cli/watch-turn.d.ts

@@ -0,0 +1,30 @@
+import { type Shown } from "./watch-element.ts";
+import { type Copying, type WatchDecision, type WatchEvent, type WatchItem, type WatchTurn } from "./watch-render.ts";
+export declare function Item(props: {
+    readonly item: WatchItem;
+}): Shown;
+export declare function Group(props: {
+    readonly items: readonly WatchItem[];
+    readonly open: boolean;
+}): Shown;
+export declare function Turn(props: {
+    readonly turn: WatchTurn;
+    readonly now: string;
+}): Shown;
+export declare function Work(props: {
+    readonly turn: WatchTurn;
+}): Shown;
+export declare function Command(props: {
+    readonly label: string;
+    readonly command: string;
+    readonly copyLabel?: string;
+    readonly copying: Copying;
+}): Shown;
+export declare function Decision(props: {
+    readonly decision: WatchDecision;
+    readonly turn: WatchTurn | undefined;
+    readonly copying: Copying;
+}): Shown;
+export declare function Events(props: {
+    readonly events: readonly WatchEvent[];
+}): Shown;