cloving 1.2.0 → 1.4.0

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

@@ -0,0 +1,156 @@
+import packageMetadata from "#package" with { type: "json" };
+import { maximumFrameBytes, record } from "../protocol.js";
+import { mcpTools, mcpToolRequest, callMcpTool } from "./mcp-tools.js";
+const versions = ["2025-11-25", "2025-06-18", "2025-03-26"];
+function append(frame, chunk) {
+    frame.bytes += chunk.length;
+    if (frame.bytes <= maximumFrameBytes)
+        frame.chunks.push(chunk);
+    else
+        frame.chunks = [];
+}
+function line(frame) {
+    return frame.bytes > maximumFrameBytes
+        ? undefined
+        : Buffer.concat(frame.chunks).toString("utf8");
+}
+async function* messages() {
+    let frame = { chunks: [], bytes: 0 };
+    for await (const value of process.stdin) {
+        const chunk = value;
+        if (!Buffer.isBuffer(chunk))
+            continue;
+        let start = 0;
+        for (let index = chunk.indexOf(10); index !== -1; index = chunk.indexOf(10, start)) {
+            append(frame, chunk.subarray(start, index));
+            yield line(frame);
+            frame = { chunks: [], bytes: 0 };
+            start = index + 1;
+        }
+        append(frame, chunk.subarray(start));
+    }
+    if (frame.bytes > 0)
+        yield line(frame);
+}
+function error(id, error) {
+    return { jsonrpc: "2.0", id, error };
+}
+function identifier(value) {
+    return typeof value === "string" || typeof value === "number" ? value : null;
+}
+function invalidMessage(id, failure) {
+    return { kind: "error", reply: error(id, failure) };
+}
+function parse(line) {
+    if (line === undefined)
+        return invalidMessage(null, {
+            code: -32600,
+            message: "Message exceeds one MiB.",
+        });
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch {
+        return invalidMessage(null, { code: -32700, message: "Parse error." });
+    }
+    const request = record(decoded);
+    const id = identifier(request?.["id"]);
+    if (request?.["jsonrpc"] !== "2.0" || typeof request["method"] !== "string")
+        return invalidMessage(id, { code: -32600, message: "Invalid request." });
+    if (Object.hasOwn(request, "id") && id === null)
+        return invalidMessage(null, {
+            code: -32600,
+            message: "Invalid request ID.",
+        });
+    return { kind: "request", request, id };
+}
+function initialize(parameters) {
+    const version = parameters["protocolVersion"];
+    return {
+        protocolVersion: typeof version === "string" && versions.includes(version)
+            ? version
+            : "2025-11-25",
+        capabilities: { tools: {} },
+        serverInfo: { name: "cloving", version: packageMetadata.version },
+    };
+}
+async function response(request, context) {
+    const { id, runtimeDirectory, signal } = context;
+    const parameters = request["params"] === undefined ? {} : record(request["params"]);
+    if (parameters === undefined)
+        return error(id, { code: -32602, message: "Invalid parameters." });
+    const method = request["method"];
+    let result;
+    if (method === "initialize")
+        result = initialize(parameters);
+    else if (method === "ping")
+        result = {};
+    else if (method === "tools/list")
+        result = { tools: mcpTools };
+    else if (method === "tools/call") {
+        const command = mcpToolRequest(parameters);
+        if (command === undefined)
+            return error(id, {
+                code: -32602,
+                message: "Unknown tool or invalid arguments.",
+            });
+        result = await callMcpTool(runtimeDirectory, { ...command, signal });
+    }
+    else
+        return error(id, { code: -32601, message: "Method not found." });
+    return { jsonrpc: "2.0", id, result };
+}
+function write(reply) {
+    process.stdout.write(`${JSON.stringify(reply)}\n`);
+}
+function dispatch(message, session) {
+    if (message.kind === "error") {
+        write(message.reply);
+        return;
+    }
+    const { request, id } = message;
+    if (id === null) {
+        if (request["method"] !== "notifications/cancelled")
+            return;
+        const requestId = identifier(record(request["params"])?.["requestId"]);
+        if (requestId === null)
+            return;
+        const call = session.calls.get(requestId);
+        if (call === undefined)
+            return;
+        call.abort();
+        return;
+    }
+    const call = new AbortController();
+    session.calls.set(id, call);
+    const pending = response(request, {
+        id,
+        runtimeDirectory: session.runtimeDirectory,
+        signal: call.signal,
+    })
+        .then((reply) => {
+        if (!call.signal.aborted)
+            write(reply);
+    })
+        .finally(() => {
+        session.calls.delete(id);
+        session.pending.delete(pending);
+    });
+    session.pending.add(pending);
+}
+export async function mcpServer(runtimeDirectory) {
+    if (runtimeDirectory === undefined) {
+        process.stderr.write("repository-unknown: Use --repository <directory> or set CLOVING_RUNTIME_DIR.\n");
+        return 2;
+    }
+    const session = {
+        runtimeDirectory,
+        calls: new Map(),
+        pending: new Set(),
+    };
+    for await (const line of messages())
+        dispatch(parse(line), session);
+    await Promise.all(session.pending);
+    return 0;
+}

package/dist/src/cli/mcp-tools.d.ts

@@ -0,0 +1,15 @@
+import { type Fields, type ServiceRequest } from "../protocol.ts";
+import type { ClientRequest } from "./client.ts";
+export declare const mcpTools: {
+    name: string;
+    inputSchema: {
+        type: string;
+        properties: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+        additionalProperties: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+    };
+}[];
+export declare function mcpToolRequest(parameters: Fields): ServiceRequest | undefined;
+export declare function callMcpTool(runtimeDirectory: string, request: ClientRequest): Promise<Fields>;

package/dist/src/cli/mcp-tools.js

@@ -0,0 +1,80 @@
+import { isRecordKey } from "../authority/commands.js";
+import { record } from "../protocol.js";
+import { commandJson, readCommandReply, readCommandRequest, } from "./command-requests.js";
+const identifier = {
+    type: "string",
+    minLength: 1,
+    maxLength: 128,
+    pattern: "^[A-Za-z0-9._:/-]+$",
+};
+const limit = { type: "integer", minimum: 1, maximum: 500 };
+function tool(name, properties) {
+    return {
+        name,
+        inputSchema: { type: "object", properties, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+    };
+}
+export const mcpTools = [
+    tool("cloving_status", { runId: identifier, limit, after: identifier }),
+    tool("cloving_questions", { runId: identifier }),
+    tool("cloving_events", {
+        runId: identifier,
+        after: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+        limit: { ...limit, maximum: 1000 },
+    }),
+];
+function validArgument(value, schema) {
+    if (schema["type"] === "string")
+        return typeof value === "string" && /^[A-Za-z0-9._:/-]{1,128}$/.test(value);
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= Number(schema["minimum"]) &&
+        value <= Number(schema["maximum"]));
+}
+function validArguments(argumentsObject, schemas) {
+    for (const [name, value] of Object.entries(argumentsObject)) {
+        const schema = schemas[name];
+        if (schema === undefined || !validArgument(value, schema))
+            return false;
+        if (name === "runId" && !isRecordKey(value))
+            return false;
+    }
+    return true;
+}
+function commandInput(kind, argumentsObject) {
+    const { runId, limit, after } = argumentsObject;
+    return {
+        kind,
+        ...(typeof runId === "string" ? { runId } : {}),
+        ...(typeof limit === "number" ? { limit } : {}),
+        ...(typeof after === "string" || typeof after === "number"
+            ? { after }
+            : {}),
+    };
+}
+export function mcpToolRequest(parameters) {
+    const selected = mcpTools.find((tool) => tool.name === parameters["name"]);
+    if (selected === undefined)
+        return undefined;
+    const argumentsObject = parameters["arguments"] === undefined
+        ? {}
+        : record(parameters["arguments"]);
+    if (argumentsObject === undefined)
+        return undefined;
+    if (!validArguments(argumentsObject, selected.inputSchema.properties))
+        return undefined;
+    const kind = selected.name.slice("cloving_".length);
+    if (kind !== "status" && kind !== "questions" && kind !== "events")
+        return undefined;
+    return readCommandRequest(commandInput(kind, argumentsObject));
+}
+export async function callMcpTool(runtimeDirectory, request) {
+    const reply = await readCommandReply(runtimeDirectory, request);
+    const structuredContent = commandJson(reply);
+    return {
+        structuredContent,
+        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+        ...(reply.kind === "error" ? { isError: true } : {}),
+    };
+}

package/dist/src/cli/phone-arguments.d.ts

@@ -0,0 +1,14 @@
+export type PhoneCommandName = "status" | "list" | "remove" | "reset";
+export type PhoneInvocation = {
+    readonly kind: "phone-help";
+} | {
+    readonly kind: "phone";
+    readonly command: PhoneCommandName;
+    readonly deviceId: string | null;
+    readonly json: boolean;
+} | {
+    readonly kind: "usage-error";
+    readonly code: string;
+    readonly json: boolean;
+};
+export declare function phoneInvocation(argumentsList: readonly string[]): PhoneInvocation;

package/dist/src/cli/phone-arguments.js

@@ -0,0 +1,37 @@
+const commands = [
+    "status",
+    "list",
+    "remove",
+    "reset",
+];
+function phoneCommandName(name) {
+    return commands.find((command) => command === name);
+}
+function unexpected(tokens, command) {
+    const allowed = command === "remove" ? 1 : 0;
+    const options = tokens.filter((token) => token.startsWith("-"));
+    const subjects = tokens.filter((token) => !token.startsWith("-"));
+    if (options.some((option) => option !== "--json"))
+        return "unexpected-option";
+    if (subjects.length > allowed)
+        return "unexpected-argument";
+    return subjects.length < allowed ? "missing-argument" : undefined;
+}
+export function phoneInvocation(argumentsList) {
+    const json = argumentsList.includes("--json");
+    if (argumentsList.includes("--help") || argumentsList.includes("-h"))
+        return { kind: "phone-help" };
+    const [name, ...rest] = argumentsList;
+    const command = phoneCommandName(name);
+    if (command === undefined)
+        return {
+            kind: "usage-error",
+            code: name === undefined ? "missing-argument" : "unknown-command",
+            json,
+        };
+    const code = unexpected(rest, command);
+    if (code !== undefined)
+        return { kind: "usage-error", code, json };
+    const deviceId = rest.find((token) => !token.startsWith("-")) ?? null;
+    return { kind: "phone", command, deviceId, json };
+}

package/dist/src/cli/phone-client.d.ts

@@ -0,0 +1,2 @@
+import { type Reply, type ServiceRequest } from "../protocol.ts";
+export declare function phoneRequest(runtimeDirectory: string, request: ServiceRequest): Promise<Reply | undefined>;

package/dist/src/cli/phone-client.js

@@ -0,0 +1,32 @@
+import net from "node:net";
+import { join } from "node:path";
+import { socketAddress } from "../broker/socket-address.js";
+import { parseReplyLine, requestLine, } from "../protocol.js";
+const absent = ["ENOENT", "ECONNREFUSED"];
+export function phoneRequest(runtimeDirectory, request) {
+    const address = socketAddress(join(runtimeDirectory, "phone.sock"));
+    if (address.kind === "refused")
+        return Promise.resolve({
+            kind: "error",
+            error: { code: address.reason, detail: address.detail },
+        });
+    return new Promise((settle, reject) => {
+        const socket = net.connect(address.path);
+        let buffered = "";
+        socket.setEncoding("utf8");
+        socket.once("connect", () => socket.write(requestLine(request)));
+        socket.on("data", (data) => {
+            buffered += data;
+        });
+        socket.once("end", () => {
+            const parsed = parseReplyLine(buffered.trim());
+            settle(parsed?.kind === "event" ? undefined : parsed);
+        });
+        socket.once("error", (error) => {
+            if (absent.includes(error.code ?? ""))
+                settle(undefined);
+            else
+                reject(error);
+        });
+    });
+}

package/dist/src/cli/phone-command.d.ts

@@ -0,0 +1,13 @@
+import type { PhoneInvocation } from "./phone-arguments.ts";
+type Invocation = Extract<PhoneInvocation, {
+    readonly kind: "phone";
+}>;
+export interface PhoneContext {
+    readonly runtimeDirectory: string | undefined;
+    readonly terminal: {
+        readonly out: (text: string) => void;
+        readonly error: (text: string) => void;
+    };
+}
+export declare function phoneCommand(invocation: Invocation, context: PhoneContext): Promise<number>;
+export {};

package/dist/src/cli/phone-command.js

@@ -0,0 +1,101 @@
+import { record } from "../protocol.js";
+import { phoneRequest } from "./phone-client.js";
+import { oneLine } from "./render.js";
+function counted(count) {
+    return count === 1 ? "1 phone" : `${String(count)} phones`;
+}
+function listed(state) {
+    const devices = state["devices"];
+    if (!Array.isArray(devices))
+        return [];
+    return devices.flatMap((device) => {
+        const fields = record(device);
+        return fields === undefined ? [] : [fields];
+    });
+}
+function stateText(state) {
+    const registration = state["registered"] === true
+        ? `Registered as ${oneLine(state["daemonId"])} with ${oneLine(state["origin"])}.`
+        : "Not registered.";
+    return `${registration} ${counted(listed(state).length)}.\n`;
+}
+function deviceLine(device) {
+    const removedAt = device["removedAt"];
+    const condition = typeof removedAt === "string" ? `removed ${removedAt}` : device["state"];
+    return `${oneLine(device["deviceId"])}  ${oneLine(device["name"])} (${oneLine(device["platform"])})  ${oneLine(condition)}  paired ${oneLine(device["pairedAt"])}\n`;
+}
+function listText(state) {
+    const devices = listed(state);
+    return devices.length === 0
+        ? "No phones.\n"
+        : devices.map(deviceLine).join("");
+}
+function failed(context, reply) {
+    if (reply.kind === "result")
+        return 0;
+    context.terminal.error(`${oneLine(reply.error.code)}: ${oneLine(reply.error.detail)}\n`);
+    return 1;
+}
+function warned(context, result) {
+    const warning = result["warning"];
+    if (typeof warning === "string")
+        context.terminal.error(`warning: ${oneLine(warning)}\n`);
+}
+const operations = {
+    status: "phone-state",
+    list: "phone-state",
+    remove: "phone-remove",
+    reset: "phone-reset",
+};
+function jsonShown(command, result) {
+    if (command === "list")
+        return { devices: listed(result) };
+    if (command === "status")
+        return { relay: "on", ...result };
+    return result;
+}
+function shown(exchange, result) {
+    const { invocation } = exchange;
+    if (invocation.json)
+        return `${JSON.stringify(jsonShown(invocation.command, result))}\n`;
+    if (invocation.command === "status")
+        return stateText(result);
+    if (invocation.command === "list")
+        return listText(result);
+    if (invocation.command === "remove")
+        return `Removed the phone ${String(invocation.deviceId)}.\n`;
+    return `Removed the registration and ${counted(Number(result["removed"]))}.\n`;
+}
+function relayOff(exchange) {
+    const { invocation, context } = exchange;
+    if (invocation.command !== "status") {
+        context.terminal.error("phone-relay-off: The phone relay is off or not started.\n");
+        return 1;
+    }
+    context.terminal.out(invocation.json
+        ? `${JSON.stringify({ relay: "off" })}\n`
+        : "The phone relay is off or not started.\n");
+    return 0;
+}
+async function exchanged(exchange) {
+    const { invocation, context, runtimeDirectory } = exchange;
+    const reply = await phoneRequest(runtimeDirectory, {
+        operation: operations[invocation.command],
+        parameters: invocation.deviceId === null ? {} : { deviceId: invocation.deviceId },
+    });
+    if (reply === undefined)
+        return relayOff(exchange);
+    if (reply.kind === "error")
+        return failed(context, reply);
+    warned(context, reply.result);
+    context.terminal.out(shown(exchange, reply.result));
+    return 0;
+}
+export async function phoneCommand(invocation, context) {
+    const { runtimeDirectory } = context;
+    if (runtimeDirectory === undefined) {
+        context.terminal.error("repository-unknown: Change to the service repository, use --repository <directory>, or set CLOVING_RUNTIME_DIR.\n");
+        return 1;
+    }
+    return exchanged({ invocation, context, runtimeDirectory });
+}

package/dist/src/cli/probe-command.d.ts

@@ -0,0 +1,36 @@
+import type { Readable } from "node:stream";
+interface ProbeChild {
+    readonly pid?: number | undefined;
+    readonly stdout: Readable;
+    kill(signal: NodeJS.Signals): boolean;
+    once(event: "error", listener: (error: Error) => void): this;
+    once(event: "close", listener: (code: number | null) => void): this;
+}
+interface ProbeEffects {
+    readonly spawn: (input: {
+        readonly executable: string;
+        readonly arguments: string[];
+        readonly options: {
+            readonly env: Readonly<NodeJS.ProcessEnv>;
+            readonly cwd?: string;
+            readonly stdio: ["ignore", "pipe", "ignore"];
+            readonly detached: true;
+        };
+    }) => ProbeChild;
+    readonly kill: (identifier: number, signal: NodeJS.Signals) => boolean;
+}
+export interface ProbeOptions {
+    readonly arguments: readonly string[];
+    readonly env: Readonly<NodeJS.ProcessEnv>;
+    readonly directory?: string;
+    readonly milliseconds?: number;
+    readonly bytes?: number;
+}
+export type ProbeRunner = (executable: string, options: ProbeOptions) => Promise<ProbeOutput>;
+export interface ProbeOutput {
+    readonly exitCode?: number | null;
+    readonly stdout: string;
+    readonly reason: string | null;
+}
+export declare function createProbeRunner(effects: ProbeEffects): ProbeRunner;
+export {};

package/dist/src/cli/probe-command.js

@@ -0,0 +1,59 @@
+function killProbe(child, effects) {
+    if (child.pid === undefined)
+        return;
+    try {
+        effects.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+export function createProbeRunner(effects) {
+    return (executable, options) => executeProbe({ executable, options, effects });
+}
+function executeProbe(input) {
+    const { executable, options, effects } = input;
+    return new Promise((complete) => {
+        const child = effects.spawn({
+            executable,
+            arguments: [...options.arguments],
+            options: {
+                env: options.env,
+                ...(options.directory === undefined ? {} : { cwd: options.directory }),
+                stdio: ["ignore", "pipe", "ignore"],
+                detached: true,
+            },
+        });
+        const chunks = [];
+        let bytes = 0;
+        let reason = null;
+        const stop = (failure) => {
+            if (reason !== null)
+                return;
+            reason = failure;
+            killProbe(child, effects);
+            child.stdout.destroy();
+        };
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > (options.bytes ?? 65536))
+                stop("probe-output-limit");
+            else
+                chunks.push(chunk);
+        });
+        const timer = setTimeout(() => {
+            stop("probe-timeout");
+        }, options.milliseconds ?? 10000);
+        child.once("error", () => {
+            reason ??= "probe-start";
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            complete({
+                exitCode: code,
+                stdout: Buffer.concat(chunks).toString("utf8"),
+                reason: reason ?? (code === 0 ? null : "probe-exit"),
+            });
+        });
+    });
+}

package/dist/src/cli/project-settings.d.ts

@@ -0,0 +1,4 @@
+import { resolveSettings } from "../project-settings.ts";
+export declare function privateSettingsPath(environment: Readonly<NodeJS.ProcessEnv>, repository: string): string;
+export declare function projectSettings(environment: Readonly<NodeJS.ProcessEnv>, repository: string): ReturnType<typeof resolveSettings>;
+export declare function settingsEnvironment(environment: Readonly<NodeJS.ProcessEnv>, repository: string): Readonly<NodeJS.ProcessEnv>;

package/dist/src/cli/project-settings.js

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { configurationRoot, resolveSettings } from "../project-settings.js";
+import { repositoryRuntimeName } from "./runtime-directory.js";
+export function privateSettingsPath(environment, repository) {
+    return join(configurationRoot(environment, homedir()), "cloving/projects", `${repositoryRuntimeName(repository)}.json`);
+}
+function read(file) {
+    try {
+        return readFileSync(file.path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new Error(`unreadable-config-file: ${file.scope}`, { cause: error });
+    }
+}
+export function projectSettings(environment, repository) {
+    return resolveSettings(environment, {
+        project: read({
+            path: join(repository, ".cloving/config.json"),
+            scope: "project",
+        }),
+        private: read({
+            path: privateSettingsPath(environment, repository),
+            scope: "private",
+        }),
+    });
+}
+export function settingsEnvironment(environment, repository) {
+    return projectSettings(environment, repository).environment;
+}

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

@@ -1,8 +1,9 @@
 import { type Fields } from "../protocol.ts";
+export { oneLine } from "./terminal-text.ts";
 export declare function errorText(error: Fields): string;
 export declare function runOverview(result: Fields): Fields;
 export declare function queueLines(value: unknown): readonly string[];
-export declare function statusJson(result: Fields): Fields;
+export { statusJson } from "./usage-render.ts";
 export declare function runStatus(result: Fields): readonly string[];
 export declare function decisionLines(decision: unknown): readonly string[];
 export declare function decisionList(result: Fields): readonly string[];