cloving 1.2.0 → 1.3.0

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

@@ -0,0 +1,242 @@
+import { constants, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { shellArguments, shellBlock, shellProbeScript, } from "../agent-harness-shell.js";
+import { harnessDefinition, harnessVersion, } from "../agent-harness-versions.js";
+import { harnessDefaults, nativeHarness, turnHarness, } from "../harness-defaults.js";
+import { accessibleFile, commandObservation, executableProgram, listedSetting, } from "./doctor-local.js";
+import { discoverHarnesses } from "./harness-probes.js";
+export async function harnessObservations(environment, location) {
+    const discovery = await discoverHarnesses({
+        env: environment,
+        probe: location.probe,
+    });
+    const harnesses = {
+        result: discovery.entries.some((entry) => entry.working) ? "ok" : "fail",
+        detail: JSON.stringify(discovery),
+    };
+    if (!location.settingsValid)
+        return {
+            harnesses,
+            selected: { result: "skip", detail: "Settings files are invalid" },
+        };
+    return {
+        harnesses,
+        selected: await selectedHarnessObservation(environment, location),
+    };
+}
+function shellScriptIndex(arguments_, shell) {
+    const terminators = shell === "zsh" ? ["--", "-b"] : ["--"];
+    let optionOperand = false;
+    for (const [index, argument] of arguments_.entries()) {
+        if (optionOperand) {
+            optionOperand = false;
+            continue;
+        }
+        if (terminators.includes(argument))
+            return index + 1;
+        if (/^-[^-oO]*c/.test(argument) ||
+            ["--command", "--version", "--help"].includes(argument))
+            return undefined;
+        if (/^[-+][^-]*[oO]$/.test(argument) ||
+            ["--rcfile", "--init-file", "--emulate"].includes(argument)) {
+            optionOperand = true;
+            continue;
+        }
+        if (/^[-+]/.test(argument))
+            continue;
+        return index;
+    }
+    return undefined;
+}
+async function missingFile(path) {
+    try {
+        await stat(path);
+        return false;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "ENOENT";
+    }
+}
+const envOptionsWithValue = ["-u", "--unset", "-C", "--chdir", "-P"];
+function envProgram(arguments_) {
+    let index = 0;
+    while (index < arguments_.length) {
+        const part = arguments_[index] ?? "";
+        if (["-S", "--split-string"].includes(part))
+            return { index: index + 1, split: true };
+        if (/^(-S|--split-string=)./.test(part))
+            return { index, split: true };
+        if (!/^(-|[A-Za-z_]\w*=)/.test(part))
+            return { index, split: false };
+        index += envOptionsWithValue.includes(part) ? 2 : 1;
+    }
+    return { index, split: false };
+}
+const shells = ["sh", "bash", "dash", "zsh", "ksh"];
+function envVersionArguments(arguments_, worker) {
+    const { index, split } = envProgram(arguments_);
+    if (index >= arguments_.length)
+        return [];
+    const prefix = arguments_.slice(0, index + 1);
+    if (split)
+        return [...prefix, "--version"];
+    const wrapped = wrappedVersionArguments(arguments_.slice(index), worker);
+    return wrapped.length === 0 ? [] : [...prefix, ...wrapped];
+}
+function wrappedVersionArguments(command, worker) {
+    const [program = "", ...arguments_] = command;
+    const name = basename(program);
+    if (name === "env")
+        return envVersionArguments(arguments_, worker);
+    if (!shells.includes(name))
+        return launcherVersionArguments(name, { arguments: arguments_, worker });
+    const script = shellScriptIndex(arguments_, name);
+    return script === undefined
+        ? []
+        : [...arguments_.slice(0, script + 1), "--version"];
+}
+function launcherVersionArguments(program, launch) {
+    const arguments_ = launch.arguments;
+    if (program === "node") {
+        const script = arguments_[arguments_[0] === "--" ? 1 : 0];
+        return script !== undefined && !script.startsWith("-")
+            ? ["--", script, "--version"]
+            : [];
+    }
+    return !nativeHarness(launch.worker) ||
+        arguments_.length === 0 ||
+        [launch.worker, "claude", "codex"].includes(program)
+        ? ["--version"]
+        : [];
+}
+async function harnessVersionArguments(command, location) {
+    const [program = "", ...arguments_] = command;
+    const shell = basename(program);
+    if (shell === "env")
+        return envVersionArguments(arguments_, location.worker);
+    if (!shells.includes(shell))
+        return launcherVersionArguments(shell, {
+            arguments: arguments_,
+            worker: location.worker,
+        });
+    const index = shellScriptIndex(arguments_, shell);
+    const script = index === undefined ? undefined : arguments_[index];
+    if (script === undefined)
+        return [];
+    let path = resolve(location.directory, script);
+    if (!script.includes("/") &&
+        ["sh", "bash", "dash"].includes(shell) &&
+        (await missingFile(path)))
+        path =
+            (await accessibleFile(script, { ...location, mode: constants.R_OK })) ??
+                path;
+    return [...arguments_.slice(0, index), path, "--version"];
+}
+function existingDirectory(path) {
+    return stat(path).then((entry) => (entry.isDirectory() ? path : undefined), () => undefined);
+}
+async function usableHarnessCommand(command, location) {
+    const configured = listedSetting(command) ?? [];
+    const program = configured[0];
+    if (!program)
+        return false;
+    const arguments_ = await harnessVersionArguments(configured, {
+        directory: location.directory,
+        environment: location.commandEnvironment,
+        worker: location.worker,
+    });
+    if (arguments_.length === 0)
+        return false;
+    const path = await executableProgram(program, {
+        directory: location.directory,
+        environment: location.commandEnvironment,
+    });
+    if (path === undefined)
+        return false;
+    const directory = await existingDirectory(location.directory);
+    const output = await location.probe(path, {
+        arguments: arguments_,
+        env: location.commandEnvironment,
+        ...(directory === undefined ? {} : { directory }),
+    });
+    return (output.reason === null &&
+        harnessVersion(output.stdout, harnessDefinition(basename(path)).versionPattern) !== null);
+}
+function workerCommands(environment, name) {
+    const variable = harnessDefaults(name).variable;
+    if (variable === undefined)
+        return {};
+    const command = listedSetting(environment[variable]);
+    return command === undefined ? {} : { [name]: command };
+}
+function selectedHarness(environment, harness) {
+    try {
+        return turnHarness({
+            ...(environment["CLOVING_WORKER"] === undefined
+                ? {}
+                : { worker: environment["CLOVING_WORKER"] }),
+            workerCommands: workerCommands(environment, configuredHarnessName(environment, harness) ?? "claude"),
+            ...(harness === undefined ? {} : { harness }),
+            shell: environment["SHELL"] ?? "/bin/sh",
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+async function usableShellHarness(selected, location) {
+    const directory = await existingDirectory(location.directory);
+    const output = await location.probe(selected.shell, {
+        arguments: [
+            ...shellArguments("login"),
+            shellProbeScript,
+            "cloving-harness-probe",
+            selected.command[0] ?? selected.worker,
+            "shell",
+        ],
+        env: location.commandEnvironment,
+        ...(directory === undefined ? {} : { directory }),
+    });
+    return (output.reason === null &&
+        harnessVersion(shellBlock(output.stdout, 0) ?? "", harnessDefinition(selected.worker).versionPattern) !== null);
+}
+async function selectedProbe(selected, location) {
+    const shell = selected.shell;
+    if (shell !== undefined)
+        return {
+            usable: await usableShellHarness({ ...selected, shell }, location),
+            effective: {
+                result: "ok",
+                detail: `${JSON.stringify(selected.command)} through the login shell ${shell}`,
+            },
+        };
+    const command = JSON.stringify(selected.command);
+    return {
+        usable: await usableHarnessCommand(command, {
+            ...location,
+            worker: selected.worker,
+        }),
+        effective: await commandObservation(command, {
+            directory: location.directory,
+            environment: location.commandEnvironment,
+        }),
+    };
+}
+function configuredHarnessName(environment, harness) {
+    return environment["CLOVING_WORKER"] ?? harness?.name;
+}
+async function selectedHarnessObservation(environment, location) {
+    const configured = configuredHarnessName(environment, location.harness);
+    const selected = selectedHarness(environment, location.harness);
+    if (selected === undefined)
+        return {
+            result: "fail",
+            detail: `harness ${configured ?? "claude"}; harness-no-worker`,
+        };
+    const { usable, effective } = await selectedProbe(selected, location);
+    const label = configured === undefined ? " (default)" : "";
+    return {
+        result: usable && effective.result === "ok" ? "ok" : "fail",
+        detail: `harness ${selected.worker}${label}; probe ${usable ? "ok" : "failed or unsupported command"}; ${effective.detail}`,
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { DoctorObservation } from "../doctor-report.ts";
+export declare function listedSetting(text: string | undefined): readonly string[] | undefined;
+export declare function nodeObservation(version: string): DoctorObservation;
+export declare function executableProgram(program: string, location: {
+    readonly directory: string;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+}): Promise<string | undefined>;
+export declare function accessibleFile(program: string, location: {
+    readonly directory: string;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly mode: number;
+}): Promise<string | undefined>;
+export declare function commandObservation(text: string | undefined, location: {
+    readonly directory: string;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+}): Promise<DoctorObservation>;
+export declare function queueObservation(text: string | undefined): DoctorObservation;
+export declare function privateTextsObservation(text: string | undefined): DoctorObservation;

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

@@ -0,0 +1,77 @@
+import { access, constants, stat } from "node:fs/promises";
+import { delimiter, resolve } from "node:path";
+import { supportedNode, supportedNodes } from "./toolchain.js";
+export function listedSetting(text) {
+    try {
+        const list = JSON.parse(text ?? "null");
+        if (Array.isArray(list) &&
+            list.every((item) => typeof item === "string" && !item.includes("\0")))
+            return list.map(String);
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export function nodeObservation(version) {
+    return {
+        result: supportedNode(version) ? "ok" : "fail",
+        detail: `Node ${version}; workflow admission requires Node ${supportedNodes}`,
+    };
+}
+export async function executableProgram(program, location) {
+    return accessibleFile(program, { ...location, mode: constants.X_OK });
+}
+export async function accessibleFile(program, location) {
+    const paths = program.includes("/")
+        ? [program]
+        : (location.environment["PATH"] ?? "")
+            .split(delimiter)
+            .map((directory) => resolve(location.directory, directory, program));
+    for (const candidate of paths) {
+        const path = resolve(location.directory, candidate);
+        try {
+            await access(path, location.mode);
+            if ((await stat(path)).isFile())
+                return path;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+export async function commandObservation(text, location) {
+    const command = listedSetting(text);
+    const program = command?.[0];
+    if (!program)
+        return { result: "fail", detail: "An executable command list is required" };
+    const path = await executableProgram(program, location);
+    return {
+        result: path === undefined ? "fail" : "ok",
+        detail: `${JSON.stringify(command)} from ${location.directory}; ${path ?? "program is not executable"}. Availability now does not guarantee an untracked file exists in a later worktree`,
+    };
+}
+export function queueObservation(text) {
+    const seconds = Number(text);
+    const valid = text !== undefined &&
+        /^\d+$/.test(text) &&
+        Number.isInteger(seconds) &&
+        seconds >= 10 &&
+        seconds <= 3600;
+    return {
+        result: valid ? "ok" : "fail",
+        detail: valid
+            ? `${String(seconds)} seconds`
+            : "queue.everySeconds must be a whole number from 10 to 3600",
+    };
+}
+export function privateTextsObservation(text) {
+    const valid = listedSetting(text)?.some((value) => value.trim().length > 0) === true;
+    return {
+        result: valid ? "ok" : "fail",
+        detail: valid
+            ? "Nonblank private texts configured"
+            : "privateTexts needs at least one nonblank text",
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { DoctorObservation } from "../doctor-report.ts";
+import type { ProbeRunner } from "./probe-command.ts";
+export interface DoctorRuntime {
+    readonly runtime: string | undefined;
+    readonly project: string | undefined;
+    readonly observation: DoctorObservation;
+}
+export declare function runtimeObservation(repository: string, options: {
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly probe: ProbeRunner;
+}): Promise<DoctorRuntime>;
+export declare function serviceObservation(location: DoctorRuntime, options: {
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly probe: ProbeRunner;
+}): Promise<DoctorObservation>;

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

@@ -0,0 +1,176 @@
+import { access, constants, lstat, realpath, stat } from "node:fs/promises";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { socketAddress } from "../broker/socket-address.js";
+import { record } from "../protocol.js";
+import { adoptionRecordPath, runtimeDirectory, legacyRuntimeDirectory, } from "./runtime-directory.js";
+async function writableDirectory(path) {
+    let existing = path;
+    for (;;) {
+        try {
+            const entry = await stat(existing);
+            if (!entry.isDirectory())
+                throw new Error(`${existing} is not a directory`);
+            await access(existing, constants.W_OK | constants.X_OK);
+            return existing;
+        }
+        catch (error) {
+            if (!(error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw new Error(`Folder is not writable: ${existing}`, {
+                    cause: error,
+                });
+            const parent = dirname(existing);
+            if (parent === existing)
+                throw error;
+            existing = parent;
+        }
+    }
+}
+async function runtimePrivacy(path) {
+    const entry = await lstat(path).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (entry === undefined)
+        return "owner and mode will be set at creation";
+    if (!entry.isDirectory())
+        throw new Error("Runtime is not a directory");
+    if (entry.uid !== process.getuid?.())
+        throw new Error("Runtime owner is a different user");
+    const mode = entry.mode & 0o777;
+    if ((mode & 0o077) !== 0)
+        throw new Error(`Runtime mode ${mode.toString(8)} is not private`);
+    return `owner ${String(entry.uid)}, mode ${mode.toString(8)}`;
+}
+async function selectedRuntime(repository, options) {
+    const { environment, probe } = options;
+    const runtime = runtimeDirectory(environment, repository);
+    if (runtime === undefined)
+        throw new Error("Runtime directory is not configured");
+    const recordPath = adoptionRecordPath(environment, repository);
+    if (environment["CLOVING_RUNTIME_DIR"] || recordPath === undefined)
+        return { runtime: resolve(runtime), recordPath: undefined };
+    const recorded = await lstat(recordPath).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (recorded !== undefined)
+        return { runtime, recordPath };
+    const legacy = legacyRuntimeDirectory(environment);
+    if (legacy === undefined)
+        return { runtime, recordPath: undefined };
+    const output = await probe(process.execPath, {
+        arguments: [
+            join(import.meta.dirname, "../../tools", `doctor-adoption${extname(import.meta.filename)}`),
+            resolve(runtime),
+            repository,
+            resolve(legacy),
+            recordPath,
+        ],
+        env: environment,
+    });
+    if (output.reason !== null)
+        throw new Error("Unable to inspect legacy runtime adoption");
+    return parsedSelection(output.stdout, recordPath);
+}
+function parsedSelection(text, recordPath) {
+    const selected = record(JSON.parse(text));
+    const path = selected?.["runtime"];
+    if (typeof path !== "string")
+        throw new Error("Invalid runtime selection");
+    return {
+        runtime: resolve(path),
+        recordPath: typeof selected?.["adoptionRecord"] === "string" ? recordPath : undefined,
+    };
+}
+async function generatedProjectDirectory(parent) {
+    const existing = await writableDirectory(parent);
+    return join(await realpath(existing), relative(existing, parent), "project");
+}
+export async function runtimeObservation(repository, options) {
+    let runtime;
+    let project;
+    try {
+        const selected = await selectedRuntime(repository, options);
+        const runtimePath = selected.runtime;
+        runtime = runtimePath;
+        const privacy = await runtimePrivacy(runtime);
+        project = await generatedProjectDirectory(dirname(runtime));
+        const address = socketAddress(join(runtime, "control.sock"), {
+            directory: project,
+        });
+        if (address.kind === "refused")
+            throw new Error(address.detail);
+        const paths = [
+            runtime,
+            dirname(runtime),
+            ...[
+                "project",
+                "workflow-bundles",
+                "state",
+                "world",
+                "journal",
+                "worktrees",
+                "github",
+                "handoffs",
+            ].map((folder) => join(dirname(runtimePath), folder)),
+        ];
+        if (selected.recordPath !== undefined)
+            paths.push(dirname(selected.recordPath));
+        for (const path of paths)
+            await writableDirectory(path);
+        return {
+            runtime,
+            project,
+            observation: {
+                result: "ok",
+                detail: `${runtime}; socket ${address.path} (${String(Buffer.byteLength(address.path))} bytes); ${privacy}; runtime, parent, adoption record and start folders are writable`,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            runtime,
+            project,
+            observation: {
+                result: "fail",
+                detail: error instanceof Error ? error.message : "Runtime inspection failed",
+            },
+        };
+    }
+}
+export async function serviceObservation(location, options) {
+    const { environment, probe } = options;
+    const { runtime, project } = location;
+    if (runtime === undefined ||
+        project === undefined ||
+        location.observation.result !== "ok")
+        return { result: "skip", detail: "Runtime prerequisite unavailable" };
+    const entry = await lstat(join(runtime, "control.sock")).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (entry === undefined)
+        return { result: "skip", detail: "No service for this repository" };
+    const result = await probe(process.execPath, {
+        arguments: [
+            join(import.meta.dirname, `doctor-service${extname(import.meta.filename)}`),
+            runtime,
+        ],
+        env: environment,
+        directory: project,
+        milliseconds: 5000,
+    });
+    const usable = result.reason === null &&
+        record(JSON.parse(result.stdout))?.["kind"] === "result";
+    return {
+        result: usable ? "ok" : "fail",
+        detail: usable
+            ? "Service answers from its generated project folder"
+            : "Service did not answer successfully within 5 seconds",
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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 {};