cloving 1.4.0 → 1.5.0

package/dist/src/cli/watch-api-document.js

@@ -0,0 +1,291 @@
+export const runStates = [
+    "queued",
+    "running",
+    "waiting_gate",
+    "paused",
+    "completed",
+    "failed",
+    "cancelled",
+];
+export const runLimit = {
+    type: "integer",
+    minimum: 1,
+    maximum: 200,
+    default: 50,
+};
+const text = { type: "string" };
+const nullableText = { type: ["string", "null"] };
+const integer = { type: "integer" };
+const nullableNumber = { type: ["number", "null"] };
+const flag = { type: "boolean" };
+function reference(name) {
+    return { $ref: `#/components/schemas/${name}` };
+}
+function closed(properties) {
+    return {
+        type: "object",
+        required: Object.keys(properties),
+        properties,
+        additionalProperties: false,
+    };
+}
+function listOf(items) {
+    return { type: "array", items };
+}
+function json(description, schema) {
+    return { description, content: { "application/json": { schema } } };
+}
+function problem(description) {
+    return {
+        description,
+        content: { "application/problem+json": { schema: reference("Problem") } },
+    };
+}
+const invalidQuery = problem("A query parameter is unknown, repeated or has an invalid value.");
+const serviceUnavailable = problem("The Cloving service does not answer.");
+const unknownRun = problem("The service has no run with this ID.");
+const documentSchema = closed({
+    openapi: { const: "3.1.1" },
+    info: closed({ title: text, version: text }),
+    servers: listOf(closed({ url: text })),
+    tags: listOf(closed({ name: text, description: text })),
+    paths: { type: "object" },
+    components: { type: "object" },
+});
+const indexSchema = closed({
+    version: { const: 1 },
+    openapi: text,
+    endpoints: listOf(closed({ method: { const: "GET" }, path: text, operationId: text })),
+});
+const runParameters = [
+    {
+        name: "workflowId",
+        in: "query",
+        description: "Give only the runs of this workflow.",
+        schema: text,
+    },
+    {
+        name: "state",
+        in: "query",
+        description: "Give only the runs in this state.",
+        schema: { type: "string", enum: runStates },
+    },
+    {
+        name: "limit",
+        in: "query",
+        description: "The maximum number of runs on the page.",
+        schema: runLimit,
+    },
+    {
+        name: "cursor",
+        in: "query",
+        description: "The nextCursor value of the previous page.",
+        schema: text,
+    },
+];
+const runId = {
+    name: "runId",
+    in: "path",
+    required: true,
+    description: "The ID of the run.",
+    schema: text,
+};
+const after = {
+    name: "after",
+    in: "query",
+    description: "Give only the events with a higher sequence.",
+    schema: { type: "integer", minimum: 0, default: 0 },
+};
+const runSummary = {
+    runId: text,
+    workflowId: text,
+    ticketId: nullableText,
+    title: nullableText,
+    state: { type: "string", enum: runStates },
+    outcome: nullableText,
+    currentStep: closed({ name: text, startedAt: nullableText }),
+    latestAt: nullableText,
+    pullRequest: {
+        oneOf: [closed({ number: integer, url: text }), { type: "null" }],
+    },
+    estimatedCostUsd: nullableNumber,
+};
+export const watchApiDocument = {
+    openapi: "3.1.1",
+    info: { title: "Cloving watch API", version: "1.0.0" },
+    servers: [{ url: "/api/v1" }],
+    tags: [
+        { name: "api", description: "The index and the contract of the API." },
+        { name: "service", description: "The state of the Cloving service." },
+        { name: "workflows", description: "The workflows of the service." },
+        { name: "runs", description: "The runs of the watch page." },
+        { name: "stream", description: "The change signals of the runs." },
+    ],
+    paths: {
+        "/": {
+            get: {
+                operationId: "getApiIndex",
+                tags: ["api"],
+                summary: "Give the version and the endpoints of the API.",
+                responses: {
+                    "200": json("The index of the API.", indexSchema),
+                    "400": invalidQuery,
+                },
+            },
+        },
+        "/openapi.json": {
+            get: {
+                operationId: "getOpenApiDocument",
+                tags: ["api"],
+                summary: "Give this OpenAPI document.",
+                responses: {
+                    "200": json("The OpenAPI document of the API.", documentSchema),
+                    "400": invalidQuery,
+                },
+            },
+        },
+        "/service": {
+            get: {
+                operationId: "getService",
+                tags: ["service"],
+                summary: "Tell if the Cloving service answers.",
+                responses: {
+                    "200": json("The state of the service.", reference("Service")),
+                    "400": invalidQuery,
+                },
+            },
+        },
+        "/workflows": {
+            get: {
+                operationId: "listWorkflows",
+                tags: ["workflows"],
+                summary: "Give the workflows of the service and their card fields.",
+                responses: {
+                    "200": json("The workflows of the service.", closed({ workflows: listOf(reference("Workflow")) })),
+                    "400": invalidQuery,
+                    "503": serviceUnavailable,
+                },
+            },
+        },
+        "/runs": {
+            get: {
+                operationId: "listRuns",
+                tags: ["runs"],
+                summary: "Give the active runs and the runs with an event in the last 7 days, newest first.",
+                parameters: runParameters,
+                responses: {
+                    "200": json("One page of runs.", reference("RunPage")),
+                    "400": invalidQuery,
+                    "503": serviceUnavailable,
+                },
+            },
+        },
+        "/runs/{runId}": {
+            get: {
+                operationId: "getRun",
+                tags: ["runs"],
+                summary: "Give one run with its phases, open decisions, reviews and agent turns, also when the run is older than 7 days.",
+                parameters: [runId],
+                responses: {
+                    "200": json("The run.", closed({ run: reference("RunDetail") })),
+                    "400": invalidQuery,
+                    "404": unknownRun,
+                    "503": serviceUnavailable,
+                },
+            },
+        },
+        "/runs/{runId}/events": {
+            get: {
+                operationId: "listRunEvents",
+                tags: ["runs"],
+                summary: "Give the events of one run after a sequence, the lowest sequence first.",
+                parameters: [runId, after],
+                responses: {
+                    "200": json("The events of the run.", closed({ events: listOf(reference("Event")) })),
+                    "400": invalidQuery,
+                    "404": unknownRun,
+                    "503": serviceUnavailable,
+                },
+            },
+        },
+        "/stream": {
+            get: {
+                operationId: "streamChanges",
+                tags: ["stream"],
+                summary: 'Send the event change with the data {"updatedAt":"<time>"} at the connection and at each change of a run.',
+                responses: {
+                    "200": {
+                        description: "Server-Sent Events.",
+                        content: { "text/event-stream": { schema: text } },
+                    },
+                    "400": invalidQuery,
+                },
+            },
+        },
+    },
+    components: {
+        schemas: {
+            Service: closed({ up: flag, updatedAt: text }),
+            Workflow: closed({
+                workflowId: text,
+                activeCount: integer,
+                waitingCount: integer,
+                latestAt: nullableText,
+                inputs: listOf(reference("CardField")),
+            }),
+            CardField: closed({
+                name: text,
+                label: text,
+                multiline: flag,
+                optional: flag,
+            }),
+            RunSummary: closed(runSummary),
+            RunPage: closed({
+                runs: listOf(reference("RunSummary")),
+                nextCursor: nullableText,
+            }),
+            RunDetail: closed({
+                ...runSummary,
+                code: text,
+                detail: text,
+                round: integer,
+                spent: nullableNumber,
+                limit: nullableNumber,
+                decisions: listOf(reference("Decision")),
+                phases: listOf(reference("Phase")),
+                reviews: listOf(reference("Review")),
+                mergeCommit: nullableText,
+                turns: listOf(reference("Turn")),
+            }),
+            Decision: closed({ decisionId: text, type: text, prompt: text }),
+            Phase: closed({
+                name: text,
+                state: text,
+                startedAt: nullableText,
+                endedAt: nullableText,
+            }),
+            Review: closed({
+                round: integer,
+                commit: text,
+                score: { type: "number" },
+            }),
+            Turn: closed({
+                key: text,
+                harness: nullableText,
+                startedAt: text,
+                endedAt: nullableText,
+                outcome: text,
+                estimatedCostUsd: nullableNumber,
+                summary: text,
+            }),
+            Event: closed({ sequence: integer, type: text, recordedAt: text }),
+            Problem: closed({
+                type: text,
+                title: text,
+                status: integer,
+                detail: text,
+                code: text,
+            }),
+        },
+    },
+};

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

@@ -0,0 +1,56 @@
+import type { WatchEvent, WatchPhase, WatchReview, WatchRun } from "./watch-render.ts";
+export interface ApiRun {
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly ticketId: string | null;
+    readonly title: string | null;
+    readonly state: string;
+    readonly outcome: string | null;
+    readonly currentStep: {
+        readonly name: string;
+        readonly startedAt: string | null;
+    };
+    readonly latestAt: string | null;
+    readonly pullRequest: {
+        readonly number: number;
+        readonly url: string;
+    } | null;
+    readonly estimatedCostUsd: number | null;
+}
+interface ApiDecision {
+    readonly decisionId: string;
+    readonly type: string;
+    readonly prompt: string;
+}
+interface ApiTurn {
+    readonly key: string;
+    readonly harness: string | null;
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly outcome: string;
+    readonly estimatedCostUsd: number | null;
+    readonly summary: string;
+}
+export interface ApiRunDetail extends ApiRun {
+    readonly code: string;
+    readonly detail: string;
+    readonly round: number;
+    readonly spent: number | null;
+    readonly limit: number | null;
+    readonly decisions: readonly ApiDecision[];
+    readonly phases: readonly WatchPhase[];
+    readonly reviews: readonly WatchReview[];
+    readonly mergeCommit: string | null;
+    readonly turns: readonly ApiTurn[];
+}
+export declare function runOf(run: WatchRun): ApiRun;
+export declare function runDetailOf(run: WatchRun): ApiRunDetail;
+export declare function eventsAfter(run: WatchRun, after: number): readonly WatchEvent[];
+export interface RunKey {
+    readonly latestAt: string | null;
+    readonly runId: string;
+}
+export declare function runOrder(first: RunKey, second: RunKey): number;
+export declare function cursorOf(run: RunKey): string;
+export declare function keyOf(cursor: string): RunKey | null;
+export {};

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

@@ -0,0 +1,112 @@
+export function runOf(run) {
+    const { pullRequest, currentStep } = run;
+    return {
+        runId: run.runId,
+        workflowId: run.workflowId,
+        ticketId: run.ticketId,
+        title: run.title,
+        state: run.state,
+        outcome: run.outcome,
+        currentStep: { name: currentStep.name, startedAt: currentStep.startedAt },
+        latestAt: run.latestAt,
+        pullRequest: pullRequest === null
+            ? null
+            : { number: pullRequest.number, url: pullRequest.url },
+        estimatedCostUsd: run.estimatedCostUsd,
+    };
+}
+function decisionOf(decision) {
+    return {
+        decisionId: decision.decisionId,
+        type: decision.type,
+        prompt: decision.prompt,
+    };
+}
+function phaseOf(phase) {
+    return {
+        name: phase.name,
+        state: phase.state,
+        startedAt: phase.startedAt,
+        endedAt: phase.endedAt,
+    };
+}
+function reviewOf(review) {
+    return { round: review.round, commit: review.commit, score: review.score };
+}
+function turnOf(turn) {
+    return {
+        key: turn.key,
+        harness: turn.harness ?? null,
+        startedAt: turn.startedAt,
+        endedAt: turn.endedAt,
+        outcome: turn.outcome,
+        estimatedCostUsd: turn.estimatedCostUsd,
+        summary: turn.summary,
+    };
+}
+export function runDetailOf(run) {
+    return {
+        ...runOf(run),
+        code: run.code,
+        detail: run.detail,
+        round: run.round,
+        spent: run.spent,
+        limit: run.limit,
+        decisions: run.decisions.map(decisionOf),
+        phases: run.phases.map(phaseOf),
+        reviews: run.reviews.map(reviewOf),
+        mergeCommit: run.mergeCommit,
+        turns: run.turns.map(turnOf),
+    };
+}
+function eventOf(event) {
+    return {
+        sequence: event.sequence,
+        type: event.type,
+        recordedAt: event.recordedAt,
+    };
+}
+export function eventsAfter(run, after) {
+    return run.events.filter((event) => event.sequence > after).map(eventOf);
+}
+function instant(latestAt) {
+    const time = Date.parse(latestAt ?? "");
+    return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
+}
+function codeOrder(first, second) {
+    if (first === second)
+        return 0;
+    return first < second ? -1 : 1;
+}
+export function runOrder(first, second) {
+    const earlier = instant(first.latestAt);
+    const later = instant(second.latestAt);
+    if (earlier !== later)
+        return earlier > later ? -1 : 1;
+    return codeOrder(first.runId, second.runId);
+}
+export function cursorOf(run) {
+    return Buffer.from(JSON.stringify([run.latestAt, run.runId])).toString("base64url");
+}
+function parsedJson(text) {
+    try {
+        const value = JSON.parse(text);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function keyOf(cursor) {
+    const value = parsedJson(Buffer.from(cursor, "base64url").toString("utf8"));
+    const entries = Array.isArray(value)
+        ? value.map((item) => item)
+        : [];
+    const [latestAt, runId] = entries;
+    if (entries.length !== 2 || typeof runId !== "string")
+        return null;
+    if (latestAt !== null && typeof latestAt !== "string")
+        return null;
+    const key = { latestAt, runId };
+    return cursorOf(key) === cursor ? key : null;
+}

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

@@ -0,0 +1,17 @@
+import type { WatchModel } from "./watch-render.ts";
+export interface ApiReply {
+    readonly status: number;
+    readonly type: string;
+    readonly body: string;
+    readonly allow?: string;
+}
+export interface ApiRequest {
+    readonly method: string;
+    readonly url: URL;
+    readonly model: () => Promise<WatchModel>;
+    readonly run: (runId: string) => Promise<WatchModel>;
+}
+export type ApiAnswer = ApiReply | "stream";
+export declare const watchApiPaths: readonly string[];
+export declare function watchApiChange(): string;
+export declare function watchApiReply(request: ApiRequest): Promise<ApiAnswer | null>;

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

@@ -0,0 +1,230 @@
+import { STATUS_CODES } from "node:http";
+import { runLimit, runStates, watchApiDocument } from "./watch-api-document.js";
+import { cursorOf, eventsAfter, keyOf, runDetailOf, runOf, runOrder, } from "./watch-api-run.js";
+const base = "/api/v1";
+function found(body) {
+    return { status: 200, type: "application/json", body: JSON.stringify(body) };
+}
+function problem(status, detail) {
+    return {
+        status,
+        type: "application/problem+json",
+        body: JSON.stringify({
+            type: "about:blank",
+            title: STATUS_CODES[status],
+            status,
+            detail: detail.detail,
+            code: detail.code,
+        }),
+    };
+}
+const serviceUnavailable = problem(503, {
+    code: "service-unavailable",
+    detail: "The Cloving service does not answer.",
+});
+const unknownRun = problem(404, {
+    code: "not-found",
+    detail: "The service has no run with this ID.",
+});
+function apiIndex() {
+    return found({
+        version: 1,
+        openapi: `${base}/openapi.json`,
+        endpoints: Object.entries(watchApiDocument.paths).map(([path, item]) => ({
+            method: "GET",
+            path: `${base}${path}`,
+            operationId: item.get.operationId,
+        })),
+    });
+}
+async function service(request) {
+    const model = await request.model();
+    return found({ up: model.service === "up", updatedAt: model.updatedAt });
+}
+function inputOf(field) {
+    return {
+        name: field.name,
+        label: field.label,
+        multiline: field.multiline,
+        optional: field.optional,
+    };
+}
+function workflowOf(workflow, forms) {
+    const form = forms?.find((item) => item.workflowId === workflow.workflowId);
+    return {
+        workflowId: workflow.workflowId,
+        activeCount: workflow.activeCount,
+        waitingCount: workflow.waitingCount,
+        latestAt: workflow.latestAt,
+        inputs: (form?.fields ?? []).map(inputOf),
+    };
+}
+async function workflows(request) {
+    const model = await request.model();
+    if (model.service !== "up")
+        return serviceUnavailable;
+    return found({
+        workflows: model.workflows.map((workflow) => workflowOf(workflow, model.cardForms)),
+    });
+}
+function runQuery(url) {
+    const { searchParams } = url;
+    const cursor = searchParams.get("cursor");
+    return {
+        workflowId: searchParams.get("workflowId"),
+        state: searchParams.get("state"),
+        limit: Number(searchParams.get("limit") ?? runLimit.default),
+        after: cursor === null ? null : keyOf(cursor),
+    };
+}
+function selected(run, query) {
+    return ((query.workflowId === null || run.workflowId === query.workflowId) &&
+        (query.state === null || run.state === query.state) &&
+        (query.after === null || runOrder(run, query.after) > 0));
+}
+async function runs(request) {
+    const model = await request.model();
+    if (model.service !== "up")
+        return serviceUnavailable;
+    const query = runQuery(request.url);
+    const remaining = model.runs
+        .filter((run) => selected(run, query))
+        .toSorted(runOrder);
+    const page = remaining.slice(0, query.limit);
+    const last = page.at(-1);
+    return found({
+        runs: page.map(runOf),
+        nextCursor: remaining.length > page.length && last !== undefined
+            ? cursorOf(last)
+            : null,
+    });
+}
+function wholeNumber(value) {
+    return /^(0|[1-9]\d*)$/.test(value);
+}
+function withinLimit(value) {
+    const limit = Number(value);
+    return (wholeNumber(value) && limit >= runLimit.minimum && limit <= runLimit.maximum);
+}
+function unanswered(error) {
+    if (error instanceof Error && error.message === "service-unavailable")
+        return null;
+    throw error;
+}
+async function runReply(request, read) {
+    const model = await request
+        .run(read.path.get("runId") ?? "")
+        .catch(unanswered);
+    if (model === null)
+        return serviceUnavailable;
+    const [run] = model.runs;
+    return run === undefined ? unknownRun : found(read.body(run));
+}
+function runDetail(request, path) {
+    return runReply(request, {
+        path,
+        body: (run) => ({ run: runDetailOf(run) }),
+    });
+}
+function runEvents(request, path) {
+    const after = Number(request.url.searchParams.get("after") ?? 0);
+    return runReply(request, {
+        path,
+        body: (run) => ({ events: eventsAfter(run, after) }),
+    });
+}
+const runParameters = new Map([
+    ["workflowId", (value) => value !== ""],
+    ["state", (value) => runStates.some((state) => state === value)],
+    ["limit", withinLimit],
+    ["cursor", (value) => keyOf(value) !== null],
+]);
+function fixed(reply) {
+    return { parameters: new Map(), reply: () => Promise.resolve(reply()) };
+}
+const routes = new Map([
+    ["/", fixed(apiIndex)],
+    ["/openapi.json", fixed(() => found(watchApiDocument))],
+    ["/service", { parameters: new Map(), reply: service }],
+    ["/workflows", { parameters: new Map(), reply: workflows }],
+    ["/runs", { parameters: runParameters, reply: runs }],
+    ["/runs/{runId}", { parameters: new Map(), reply: runDetail }],
+    [
+        "/runs/{runId}/events",
+        { parameters: new Map([["after", wholeNumber]]), reply: runEvents },
+    ],
+    [
+        "/stream",
+        { parameters: new Map(), reply: () => Promise.resolve("stream") },
+    ],
+]);
+export const watchApiPaths = [...routes.keys()];
+export function watchApiChange() {
+    const change = { updatedAt: new Date().toISOString() };
+    return `event: change\ndata: ${JSON.stringify(change)}\n\n`;
+}
+const placeholder = /^\{(\w+)\}$/;
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return "";
+    }
+}
+function matchedPath(template, path) {
+    const parts = template.split("/");
+    const segments = path.split("/");
+    if (parts.length !== segments.length)
+        return null;
+    const pairs = parts.map((part, index) => [part, segments[index] ?? ""]);
+    if (pairs.some(([part, segment]) => !placeholder.test(part) && part !== segment))
+        return null;
+    const values = pairs.flatMap(([part, segment]) => {
+        const name = placeholder.exec(part)?.[1];
+        return name === undefined ? [] : [[name, decoded(segment)]];
+    });
+    if (values.some(([, value]) => value === ""))
+        return null;
+    return new Map(values);
+}
+function routeOf(path) {
+    for (const [template, route] of routes) {
+        const values = matchedPath(template, path);
+        if (values !== null)
+            return { route, values };
+    }
+    return null;
+}
+function refusedParameter(url, parameters) {
+    const names = [...url.searchParams.keys()];
+    const refused = names.find((name, index) => names.indexOf(name) !== index ||
+        parameters.get(name)?.(url.searchParams.get(name) ?? "") !== true);
+    return refused ?? null;
+}
+export async function watchApiReply(request) {
+    const { pathname } = request.url;
+    if (pathname !== base && !pathname.startsWith(`${base}/`))
+        return null;
+    if (request.method !== "GET")
+        return {
+            ...problem(405, {
+                code: "method-not-allowed",
+                detail: "The API accepts only GET.",
+            }),
+            allow: "GET",
+        };
+    const matched = routeOf(pathname.slice(base.length) || "/");
+    if (matched === null)
+        return problem(404, {
+            code: "not-found",
+            detail: "The API has no resource at this path.",
+        });
+    const refused = refusedParameter(request.url, matched.route.parameters);
+    if (refused !== null)
+        return problem(400, {
+            code: "invalid-query",
+            detail: `The query parameter ${refused} is unknown, repeated or has an invalid value.`,
+        });
+    return matched.route.reply(request, matched.values);
+}