cloving 1.1.0 → 1.3.0

package/dist/src/cli/doctor-service.js

@@ -0,0 +1,11 @@
+import { send } from "./client.js";
+async function main() {
+    const runtime = process.argv[2];
+    if (runtime === undefined) {
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(JSON.stringify(await send(runtime, { operation: "status", parameters: { limit: 1 } })) + "\n");
+}
+if (process.argv[1] === import.meta.filename)
+    await main();

package/dist/src/cli/doctor-workflows.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorWorkflow } from "../doctor-report.ts";
+export declare const bundledDoctorWorkflows: DoctorWorkflow[];
+export declare function doctorWorkflows(repository: string, environment: Readonly<NodeJS.ProcessEnv>): Promise<readonly DoctorWorkflow[]>;

package/dist/src/cli/doctor-workflows.js

@@ -0,0 +1,45 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { configurationRoot, absoluteWorkflowFolder, } from "../project-settings.js";
+import { isCandidateDeclaration } from "../workflow-candidate.js";
+import { bundledWorkflowIds } from "../workflow-discovery.js";
+export const bundledDoctorWorkflows = Object.values(bundledWorkflowIds).map((workflowId) => ({
+    scope: "bundled",
+    workflowId,
+    capabilities: ["claude", "github"],
+}));
+export async function doctorWorkflows(repository, environment) {
+    const discovered = [];
+    for (const [scope, folder] of [
+        ["project", join(repository, ".cloving/workflows")],
+        [
+            "user",
+            absoluteWorkflowFolder(environment["CLOVING_WORKFLOW_FOLDER"]) ??
+                join(configurationRoot(environment, homedir()), "cloving/workflows"),
+        ],
+    ]) {
+        const files = await readdir(folder).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        for (const file of files.filter((file) => file.endsWith(".ts") &&
+            !file.endsWith(".d.ts") &&
+            !file.endsWith(".test.ts"))) {
+            const text = await readFile(join(folder, file.slice(0, -3) + ".declaration.json"), "utf8").catch(() => undefined);
+            if (text === undefined)
+                continue;
+            let declaration;
+            try {
+                declaration = JSON.parse(text);
+            }
+            catch {
+                continue;
+            }
+            if (isCandidateDeclaration(declaration))
+                discovered.push({ scope, ...declaration.workflow });
+        }
+    }
+    return [...bundledDoctorWorkflows, ...discovered];
+}

package/dist/src/cli/doctor.d.ts

@@ -0,0 +1,15 @@
+import { type DoctorCheck } from "../doctor-report.ts";
+import type { ProbeRunner } from "./probe-command.ts";
+interface DoctorOptions {
+    readonly repository: string | undefined;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly probe: ProbeRunner;
+}
+export declare function doctorReport(options: DoctorOptions): Promise<{
+    readonly version: 1;
+    readonly checks: readonly DoctorCheck[];
+}>;
+export declare function doctorCommand(options: DoctorOptions & {
+    readonly json: boolean;
+}): Promise<number>;
+export {};

package/dist/src/cli/doctor.js

@@ -0,0 +1,190 @@
+import { shellArgument } from "./runtime-directory.js";
+import { dirname, delimiter, join } from "node:path";
+import { doctorCodes, doctorExitCode, doctorFixes, requiredDoctorCodes, } from "../doctor-report.js";
+import { privateSettingsPath, projectSettings } from "./project-settings.js";
+import { githubObservations } from "./doctor-github.js";
+import { bundledDoctorWorkflows, doctorWorkflows } from "./doctor-workflows.js";
+import { runtimeObservation, serviceObservation } from "./doctor-runtime.js";
+import { harnessObservations } from "./doctor-harness.js";
+import { commandObservation, nodeObservation, privateTextsObservation, queueObservation, } from "./doctor-local.js";
+function settings(repository, environment) {
+    try {
+        const resolved = projectSettings(environment, repository);
+        return {
+            environment: resolved.environment,
+            harness: resolved.harness,
+            observation: {
+                result: "ok",
+                detail: "Settings files are valid",
+            },
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "Invalid settings files";
+        const files = [
+            join(repository, ".cloving/config.json"),
+            privateSettingsPath(environment, repository),
+        ];
+        return {
+            environment,
+            observation: {
+                result: "fail",
+                detail,
+                fix: `Edit the invalid settings: \${EDITOR:-vi} ${files.map(shellArgument).join(" ")}`,
+            },
+        };
+    }
+}
+export async function doctorReport(options) {
+    const repository = options.repository;
+    const found = repository === undefined
+        ? {
+            observations: {},
+            required: requiredDoctorCodes([], { queueSeconds: undefined }),
+        }
+        : await repositoryObservations({ ...options, repository });
+    const git = repository === undefined
+        ? { result: "fail", detail: "No git repository" }
+        : await gitObservation({ ...options, repository });
+    const observations = {
+        ...found.observations,
+        "node-version": nodeObservation(process.version),
+        "git-repository": git,
+    };
+    const checks = doctorCodes.map((code) => ({
+        code,
+        required: found.required.includes(code),
+        fix: doctorFixes[code],
+        ...(observations[code] ?? {
+            result: "skip",
+            detail: "Repository prerequisite unavailable",
+        }),
+    }));
+    return { version: 1, checks };
+}
+async function repositoryObservations(options) {
+    const { repository, probe } = options;
+    const configured = settings(repository, options.environment);
+    const { environment } = configured;
+    const observations = {
+        "settings-files": configured.observation,
+    };
+    const settingsValid = configured.observation.result === "ok";
+    const location = await runtimeObservation(repository, { environment, probe });
+    observations["runtime-directory"] = location.observation;
+    observations["service"] = await serviceObservation(location, {
+        environment,
+        probe,
+    });
+    const project = location.project;
+    const serviceEnvironment = {
+        ...environment,
+        PATH: [dirname(process.execPath), environment["PATH"]].join(delimiter),
+    };
+    const harnesses = await harnessObservations(environment, {
+        directory: repository,
+        settingsValid,
+        probe,
+        commandEnvironment: serviceEnvironment,
+        harness: "harness" in configured ? configured.harness : undefined,
+    });
+    observations["harnesses"] = harnesses.harnesses;
+    observations["default-harness"] = harnesses.selected;
+    const workflowContext = await workflowRequirements(repository, {
+        settingsValid,
+        environment,
+    });
+    const required = requiredDoctorCodes(workflowContext.workflows, {
+        queueSeconds: settingsValid
+            ? environment["CLOVING_QUEUE_SECONDS"]
+            : undefined,
+    });
+    const dependent = await configuredObservations({ ...options, environment }, { prerequisite: workflowContext.prerequisite, project, serviceEnvironment });
+    return { observations: { ...observations, ...dependent }, required };
+}
+async function workflowRequirements(repository, context) {
+    if (!context.settingsValid)
+        return {
+            workflows: bundledDoctorWorkflows,
+            prerequisite: "Settings files are invalid",
+        };
+    try {
+        return {
+            workflows: await doctorWorkflows(repository, context.environment),
+            prerequisite: undefined,
+        };
+    }
+    catch (error) {
+        return {
+            workflows: bundledDoctorWorkflows,
+            prerequisite: `Workflow requirements unavailable: ${error instanceof Error ? error.message : "discovery failed"}`,
+        };
+    }
+}
+async function configuredObservations(options, location) {
+    const { environment, repository, probe } = options;
+    const observations = {};
+    if (location.prerequisite !== undefined) {
+        for (const code of [
+            "gh-login",
+            "github-origin",
+            "greptile-review",
+            "ticket-command",
+            "next-command",
+            "check-command",
+            "queue-interval",
+            "private-texts",
+        ])
+            observations[code] = {
+                result: "skip",
+                detail: location.prerequisite,
+            };
+        return observations;
+    }
+    for (const [code, variable, directory] of [
+        ["ticket-command", "CLOVING_TICKET_COMMAND", location.project],
+        ["next-command", "CLOVING_NEXT_COMMAND", location.project],
+        ["check-command", "CLOVING_CHECK_COMMAND", repository],
+    ])
+        observations[code] =
+            directory === undefined
+                ? { result: "skip", detail: "Runtime project prerequisite unavailable" }
+                : await commandObservation(environment[variable], {
+                    directory,
+                    environment: location.serviceEnvironment,
+                });
+    const github = await githubObservations(repository, { environment, probe });
+    Object.assign(observations, github.observations);
+    const login = observations["gh-login"];
+    if (login !== undefined)
+        observations["gh-login"] = { ...login, fix: github.loginFix };
+    observations["queue-interval"] = queueObservation(environment["CLOVING_QUEUE_SECONDS"]);
+    observations["private-texts"] = privateTextsObservation(environment["CLOVING_PRIVATE_TEXTS"]);
+    return observations;
+}
+async function gitObservation(options) {
+    const given = { env: options.environment, directory: options.repository };
+    const branch = await options.probe("git", {
+        ...given,
+        arguments: ["symbolic-ref", "--short", "HEAD"],
+    });
+    const detached = branch.reason === null
+        ? branch
+        : await options.probe("git", {
+            ...given,
+            arguments: ["rev-parse", "--short", "HEAD"],
+        });
+    return {
+        result: detached.reason === null ? "ok" : "fail",
+        detail: `git repository ${options.repository}, branch ${detached.stdout.trim() || "unavailable"}`,
+    };
+}
+export async function doctorCommand(options) {
+    const report = await doctorReport(options);
+    process.stdout.write(options.json
+        ? JSON.stringify(report) + "\n"
+        : report.checks
+            .map((check) => `${check.result.padEnd(6)}${check.code}  ${check.detail}${check.result === "ok" ? "" : ". " + check.fix}${check.required ? " (required)" : ""}\n`)
+            .join(""));
+    return doctorExitCode(report.checks);
+}

package/dist/src/cli/github-ci-progress.d.ts

@@ -0,0 +1,8 @@
+import { type Reply } from "../protocol.ts";
+export interface CiRerunNotice {
+    readonly commit: string;
+    readonly run: string;
+    readonly requestedAt: number;
+}
+export declare function ciRerunNotices(folder: string): Promise<CiRerunNotice[]>;
+export declare function withCiReruns(runtimeDirectory: string, reply: Reply): Promise<Reply>;

package/dist/src/cli/github-ci-progress.js

@@ -0,0 +1,83 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { record } from "../protocol.js";
+async function stored(file) {
+    try {
+        return record(JSON.parse(await readFile(file, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+function noticeOf(value, commit) {
+    const rerun = record(value);
+    const run = rerun?.["run"];
+    const requestedAt = rerun?.["requestedAt"];
+    if (typeof run !== "string" ||
+        !/^\d+$/.test(run) ||
+        typeof requestedAt !== "number" ||
+        !Number.isFinite(requestedAt))
+        return [];
+    return [{ commit, run, requestedAt }];
+}
+export async function ciRerunNotices(folder) {
+    const notices = [];
+    for (const file of await readdir(folder).catch(() => [])) {
+        if (!/^ci-[a-f0-9]{32}\.json$/.test(file))
+            continue;
+        const wait = await stored(join(folder, file));
+        const commit = wait?.["commit"];
+        if (typeof commit !== "string" || !/^[a-f0-9]{40,64}$/.test(commit))
+            continue;
+        const reruns = Array.isArray(wait?.["reruns"])
+            ? wait["reruns"]
+            : [];
+        notices.push(...reruns.flatMap((value) => noticeOf(value, commit)));
+    }
+    return notices.toSorted((first, second) => first.requestedAt - second.requestedAt);
+}
+function requestedRunIds(result) {
+    const runs = Array.isArray(result["runs"])
+        ? result["runs"]
+        : [];
+    return new Set([result["run"], ...runs].flatMap((value) => {
+        const runId = record(value)?.["runId"];
+        return typeof runId === "string" ? [runId] : [];
+    }));
+}
+export async function withCiReruns(runtimeDirectory, reply) {
+    if (reply.kind !== "result")
+        return reply;
+    const { result } = reply;
+    const requested = requestedRunIds(result);
+    const journal = join(dirname(runtimeDirectory), "github");
+    const notices = new Map();
+    for (const key of await readdir(journal).catch(() => [])) {
+        const folder = join(journal, key);
+        const started = (await stored(join(folder, "started.json"))) ?? {};
+        const runId = started["runId"];
+        if (started["method"] !== "merge" ||
+            typeof runId !== "string" ||
+            !requested.has(runId))
+            continue;
+        notices.set(runId, [
+            ...(notices.get(runId) ?? []),
+            ...(await ciRerunNotices(folder)),
+        ]);
+    }
+    const shown = (value) => {
+        const run = record(value);
+        const found = notices.get(String(run?.["runId"])) ?? [];
+        return found.length === 0 ? value : { ...run, ciReruns: found };
+    };
+    return {
+        kind: "result",
+        result: {
+            ...result,
+            ...(result["run"] === undefined ? {} : { run: shown(result["run"]) }),
+            ...(Array.isArray(result["runs"])
+                ? { runs: result["runs"].map(shown) }
+                : {}),
+        },
+    };
+}

package/dist/src/cli/github-retry.d.ts

@@ -0,0 +1,6 @@
+export declare function githubRetry<Result>(retry: {
+    readonly signal: AbortSignal;
+    readonly pollMilliseconds: number;
+    readonly action: (attempt: number) => Promise<Result>;
+    readonly statuses?: readonly number[];
+}): Promise<Result>;

package/dist/src/cli/github-retry.js

@@ -0,0 +1,47 @@
+import { setTimeout as delay } from "node:timers/promises";
+function field(value, name) {
+    return Reflect.get(Object(value), name);
+}
+function transient(error) {
+    if (!(error instanceof Error) || error.message !== "github-call-failed")
+        return false;
+    const detail = field(error, "detail");
+    if (typeof detail !== "string")
+        return false;
+    const status = field(error, "status");
+    if ([500, 502, 503, 504].includes(Number(status)))
+        return true;
+    return ((status === undefined ||
+        (typeof status === "number" && Number.isNaN(status))) &&
+        /TLS handshake timeout|connection reset|i\/o timeout|\bEOF\b|error connecting to/i.test(detail));
+}
+function retryFactor(error, retry) {
+    const network = transient(error);
+    if (!network && !retry.statuses.includes(Number(field(error, "status"))))
+        throw error;
+    if (retry.attempt < 2)
+        return network ? retry.attempt + 1 : 1;
+    if (!network)
+        throw error;
+    throw Object.assign(new Error("github-network-failed", { cause: error }), {
+        detail: field(error, "detail"),
+    });
+}
+export async function githubRetry(retry) {
+    for (let attempt = 0;; attempt += 1) {
+        retry.signal.throwIfAborted();
+        try {
+            return await retry.action(attempt);
+        }
+        catch (error) {
+            retry.signal.throwIfAborted();
+            const factor = retryFactor(error, {
+                attempt,
+                statuses: retry.statuses ?? [],
+            });
+            await delay(retry.pollMilliseconds * factor, undefined, {
+                signal: retry.signal,
+            });
+        }
+    }
+}

package/dist/src/cli/harness-probes.d.ts

@@ -0,0 +1,22 @@
+import type { ProbeRunner } from "./probe-command.ts";
+export interface HarnessEntry {
+    readonly name: string;
+    readonly kind: "file" | "shell";
+    readonly path: string;
+    readonly version: string | null;
+    readonly working: boolean;
+    readonly reason: string | null;
+}
+export interface HarnessDiscovery {
+    readonly entries: HarnessEntry[];
+    readonly shellReason: string | null;
+}
+export interface HarnessOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export declare function discoverHarnesses(options: HarnessOptions & {
+    readonly probe: ProbeRunner;
+}): Promise<HarnessDiscovery>;
+export declare function probeHarness(target: string, options: HarnessOptions & {
+    readonly probe: ProbeRunner;
+}): Promise<HarnessDiscovery>;

package/dist/src/cli/harness-probes.js

@@ -0,0 +1,183 @@
+import { access, constants, stat } from "node:fs/promises";
+import { basename, delimiter, resolve } from "node:path";
+import { harnessDefinition, harnessVersion, knownHarnesses, } from "../agent-harness-versions.js";
+import { shellArguments, shellBlock, shellDiscoveryScript, shellEntries, shellProbeScript, } from "../agent-harness-shell.js";
+async function executableFile(path) {
+    try {
+        await access(path, constants.X_OK);
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findFile(name, env) {
+    if (name.includes("/")) {
+        const path = resolve(name);
+        return (await executableFile(path)) ? path : null;
+    }
+    for (const directory of (env["PATH"] ?? "").split(delimiter)) {
+        const path = resolve(directory, name);
+        if (await executableFile(path))
+            return path;
+    }
+    return null;
+}
+function probeEntry(entry, output) {
+    const version = harnessVersion(output.stdout, harnessDefinition(entry.name).versionPattern);
+    const reason = output.reason ?? (version === null ? "no-version" : null);
+    return {
+        ...entry,
+        version: reason === null ? version : null,
+        working: reason === null,
+        reason,
+    };
+}
+async function probeFile(entry, context) {
+    const { env, probe } = context;
+    const { name, path } = entry;
+    const output = await probe(path, {
+        arguments: [harnessDefinition(name).versionOption],
+        env,
+    });
+    return probeEntry({ name, kind: "file", path }, output);
+}
+async function discoverFiles(definitions, context) {
+    const { env } = context;
+    const entries = await Promise.all(definitions.map(async ({ name }) => {
+        const path = await findFile(name, env);
+        return path === null ? [] : [await probeFile({ name, path }, context)];
+    }));
+    return entries.flat();
+}
+async function inspectShell(names, options) {
+    const { env, mode, probe } = options;
+    const shell = env["SHELL"];
+    if (!shell)
+        return { entries: [], reason: "shell-unavailable", bash: false };
+    const output = await probe(shell, {
+        arguments: [
+            ...shellArguments(mode),
+            shellDiscoveryScript,
+            "cloving-harnesses",
+            ...names,
+        ],
+        env,
+    });
+    const found = shellEntries(output.stdout, names);
+    const reason = output.exitCode === 64 ? "unsupported-shell" : output.reason;
+    return {
+        entries: reason === null ? (found ?? []) : [],
+        reason: reason ?? (found === null ? "shell-protocol" : null),
+        bash: shellBlock(output.stdout, -1)?.trim() === "bash",
+    };
+}
+async function probeShell(candidate, context) {
+    const { env, probe } = context;
+    const { entry, mode } = candidate;
+    const { name, kind, path } = entry;
+    const output = await probe(env["SHELL"] ?? "", {
+        arguments: [
+            ...shellArguments(mode),
+            shellProbeScript,
+            "cloving-harness-probe",
+            path,
+            kind,
+        ],
+        env,
+    });
+    const stdout = shellBlock(output.stdout, 0);
+    return probeEntry({ name, kind, path }, {
+        stdout: stdout ?? "",
+        reason: output.reason ?? (stdout === null ? "shell-protocol" : null),
+    });
+}
+function entryKey(entry) {
+    return JSON.stringify([entry.name, entry.kind, entry.path]);
+}
+async function probeCandidates(candidates, options) {
+    const { files, env, probe } = options;
+    const settled = new Set(files.filter((file) => file.working).map(entryKey));
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const key = entryKey(candidate.entry);
+        if (settled.has(key))
+            continue;
+        const group = groups.get(key) ?? [];
+        group.push(candidate);
+        groups.set(key, group);
+    }
+    const entries = await Promise.all([...groups.values()].map(async (group) => {
+        let result = [];
+        for (const { entry, mode } of group) {
+            const output = await probeShell({ entry, mode }, { env, probe });
+            result = [output];
+            if (output.working)
+                break;
+        }
+        return result;
+    }));
+    return entries.flat();
+}
+async function discoverShell(names, options) {
+    const { env, files, probe } = options;
+    const login = await inspectShell(names, { env, mode: "login", probe });
+    const interactive = login.bash ||
+        (login.reason !== null && basename(env["SHELL"] ?? "") !== "zsh")
+        ? await inspectShell(names, { env, mode: "interactive", probe })
+        : null;
+    const found = [
+        ...login.entries.map((entry) => ({ entry, mode: "login" })),
+        ...(interactive?.bash ? interactive.entries : []).map((entry) => ({
+            entry,
+            mode: "interactive",
+        })),
+    ];
+    const entries = await probeCandidates(found, { files, env, probe });
+    return { entries, shellReason: login.reason ?? interactive?.reason ?? null };
+}
+async function discoverNames(definitions, context) {
+    const { env, probe } = context;
+    const files = await discoverFiles(definitions, context);
+    const shell = await discoverShell(definitions.map(({ name }) => name), { env, files, probe });
+    return {
+        entries: [
+            ...new Map([...files, ...shell.entries].map((entry) => [entryKey(entry), entry])).values(),
+        ],
+        shellReason: shell.shellReason,
+    };
+}
+export function discoverHarnesses(options) {
+    return discoverNames(knownHarnesses, {
+        env: options.env ?? process.env,
+        probe: options.probe,
+    });
+}
+export async function probeHarness(target, options) {
+    const env = options.env ?? process.env;
+    const probe = options.probe;
+    if (target.includes("/")) {
+        const path = await findFile(target, env);
+        const entry = {
+            name: basename(target),
+            kind: "file",
+            path: path ?? target,
+        };
+        const output = path === null
+            ? { stdout: "", reason: "not-found" }
+            : await probe(path, { arguments: ["--version"], env });
+        return { entries: [probeEntry(entry, output)], shellReason: null };
+    }
+    const found = await discoverNames([harnessDefinition(target)], {
+        env,
+        probe,
+    });
+    if (found.entries.length > 0)
+        return found;
+    return {
+        ...found,
+        entries: [
+            probeEntry({ name: target, kind: "file", path: target }, { stdout: "", reason: "not-found" }),
+        ],
+    };
+}

package/dist/src/cli/main.d.ts

@@ -1,2 +1,8 @@
 import type { WatchPrSettings } from "./watch-pr-settings.ts";
-export declare function main(argumentsList: readonly string[], watchPr?: WatchPrSettings): Promise<void>;
+import type { ProbeRunner } from "./probe-command.ts";
+export declare function main(argumentsList: readonly string[], context?: {
+    readonly watchPr?: WatchPrSettings;
+    readonly doctorProbe?: ProbeRunner;
+    readonly environment?: Readonly<NodeJS.ProcessEnv>;
+    readonly repository: string | undefined;
+}): Promise<void>;