cloving 0.3.20 → 1.0.1

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

@@ -0,0 +1,23 @@
+import { type RuntimeInvocation } from "./runtime-arguments.ts";
+export type Invocation = {
+    readonly kind: "help";
+} | {
+    readonly kind: "version";
+} | {
+    readonly kind: "validate-help";
+} | {
+    readonly kind: "chats-import-help";
+} | {
+    readonly kind: "chats-import";
+    readonly paths: readonly string[];
+} | {
+    readonly kind: "validate";
+    readonly manifest: string;
+    readonly input: string | null;
+    readonly json: boolean;
+} | RuntimeInvocation | {
+    readonly kind: "usage-error";
+    readonly code: string;
+    readonly json: boolean;
+};
+export declare function parseInvocation(given: readonly string[]): Invocation;

package/dist/src/cli/arguments.js

@@ -0,0 +1,154 @@
+import { parseArgs } from "node:util";
+import { isRuntimeCommand, runtimeInvocation, } from "./runtime-arguments.js";
+const errorCodes = {
+    ERR_PARSE_ARGS_UNKNOWN_OPTION: "unknown-option",
+    ERR_PARSE_ARGS_INVALID_OPTION_VALUE: "missing-value",
+};
+const options = {
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    input: { type: "string" },
+    json: { type: "boolean" },
+    prompt: { type: "string" },
+    ticket: { type: "string" },
+    next: { type: "boolean" },
+    port: { type: "string" },
+    text: { type: "string" },
+    "command-id": { type: "string" },
+    "expected-revision": { type: "string" },
+    generation: { type: "string" },
+    "subject-digest": { type: "string" },
+    limit: { type: "string" },
+    after: { type: "string" },
+    follow: { type: "boolean" },
+};
+const textOptions = ["--prompt", "--text"];
+function knownFlag(token) {
+    if (token.startsWith("--"))
+        return Object.hasOwn(options, token.slice(2));
+    return token === "-h" || token === "-v";
+}
+function attached(option, value) {
+    return value.startsWith("-") && !knownFlag(value)
+        ? [`${option}=${value}`]
+        : [option, value];
+}
+function textValues(argumentsList) {
+    const joined = [];
+    let option;
+    for (const token of argumentsList) {
+        const pending = option;
+        option =
+            pending === undefined && textOptions.includes(token) ? token : undefined;
+        if (pending !== undefined)
+            joined.push(...attached(pending, token));
+        else if (option === undefined)
+            joined.push(token);
+    }
+    return option === undefined ? joined : [...joined, option];
+}
+export function parseInvocation(given) {
+    if (given[0] === "chats" && given[1] === "import")
+        return chatsImport(given.slice(2));
+    const argumentsList = textValues(given);
+    const json = given.includes("--json");
+    const parsed = parsedArguments(argumentsList);
+    if (typeof parsed === "string")
+        return { kind: "usage-error", code: parsed, json };
+    const { values, positionals, tokens } = parsed;
+    const [command, ...remaining] = positionals;
+    if (command === undefined)
+        return topLevel(values);
+    if (command === "workflows" && remaining[0] === "validate")
+        return validation(values, remaining.slice(1));
+    const outcome = runtimeInvocation({
+        command,
+        positionals: remaining,
+        options: givenOptions(tokens),
+    });
+    if (typeof outcome === "string")
+        return { kind: "usage-error", code: outcome, json };
+    return outcome;
+}
+function chatsImport(argumentsList) {
+    const error = (code) => ({
+        kind: "usage-error",
+        code,
+        json: false,
+    });
+    if (argumentsList.length === 1 &&
+        ["--help", "-h"].includes(String(argumentsList[0])))
+        return { kind: "chats-import-help" };
+    const paths = [];
+    let literal = false;
+    for (const argument of argumentsList) {
+        if (!literal && argument === "--")
+            literal = true;
+        else if (!literal && argument.startsWith("-"))
+            return error("unexpected-option");
+        else if (argument === "")
+            return error("missing-argument");
+        else
+            paths.push(argument);
+    }
+    return paths.length === 0
+        ? error("missing-argument")
+        : { kind: "chats-import", paths };
+}
+function parsedArguments(argumentsList) {
+    try {
+        return parseArgs({
+            args: [...argumentsList],
+            allowPositionals: true,
+            options,
+            tokens: true,
+        });
+    }
+    catch (error) {
+        if (!knownCommand(lenientPositionals(argumentsList)))
+            return "unknown-command";
+        const code = error instanceof Error && "code" in error ? String(error.code) : "";
+        return errorCodes[code] ?? "invalid-invocation";
+    }
+}
+function lenientPositionals(argumentsList) {
+    return parseArgs({
+        args: [...argumentsList],
+        allowPositionals: true,
+        options,
+        strict: false,
+    }).positionals;
+}
+function knownCommand(positionals) {
+    const [command, subcommand] = positionals;
+    if (command === undefined)
+        return true;
+    if (command === "workflows")
+        return subcommand === "validate";
+    return isRuntimeCommand(command);
+}
+function givenOptions(tokens) {
+    return tokens.flatMap((token) => token.kind === "option" ? [{ name: token.name, value: token.value }] : []);
+}
+function unexpected(values, allowed) {
+    return Object.keys(values).some((name) => !allowed.includes(name));
+}
+function validation(values, remaining) {
+    const json = values.json === true;
+    if (unexpected(values, ["help", "input", "json"]))
+        return { kind: "usage-error", code: "unexpected-option", json };
+    if (values.help)
+        return { kind: "validate-help" };
+    const [manifest, ...extra] = remaining;
+    if (manifest === undefined)
+        return { kind: "usage-error", code: "missing-argument", json };
+    if (extra.length > 0)
+        return { kind: "usage-error", code: "unexpected-argument", json };
+    return { kind: "validate", manifest, input: values.input ?? null, json };
+}
+function topLevel(values) {
+    const json = values.json === true;
+    if (unexpected(values, ["help", "version"]))
+        return { kind: "usage-error", code: "unexpected-option", json };
+    return values.version ? { kind: "version" } : { kind: "help" };
+}

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

@@ -0,0 +1,15 @@
+import { type Fields, type Reply, type ServiceRequest } from "../protocol.ts";
+export interface Interruption {
+    readonly signal: Promise<void>;
+    readonly reply: Reply;
+}
+export declare function send(runtimeDirectory: string, request: ServiceRequest): Promise<Reply>;
+export declare function mutate(runtimeDirectory: string, mutation: {
+    readonly request: ServiceRequest;
+    readonly signal: Promise<void>;
+}): Promise<Reply>;
+export declare function follow(runtimeDirectory: string, stream: {
+    readonly request: ServiceRequest;
+    readonly onEvent: (event: Fields) => void;
+    readonly signal: Promise<void>;
+}): Promise<Reply>;

package/dist/src/cli/client.js

@@ -0,0 +1,122 @@
+import net from "node:net";
+import { join } from "node:path";
+import { socketAddress } from "../broker/socket-address.js";
+import { parseReplyLine, requestLine, } from "../protocol.js";
+const mutations = ["run", "decision", "run-command"];
+function unavailable(runtimeDirectory) {
+    return {
+        kind: "error",
+        error: {
+            code: "service-unavailable",
+            detail: `No Cloving service answers in ${runtimeDirectory}. Start the service, or set CLOVING_RUNTIME_DIR to its runtime directory.`,
+        },
+    };
+}
+function refused(runtimeDirectory) {
+    return {
+        kind: "error",
+        error: {
+            code: "permission-denied",
+            detail: `The service socket in ${runtimeDirectory} refused this account.`,
+        },
+    };
+}
+function lost(request, runtimeDirectory) {
+    if (!mutations.includes(request.operation))
+        return unavailable(runtimeDirectory);
+    return {
+        kind: "error",
+        error: {
+            code: "outcome-unknown",
+            detail: "The connection ended before the reply. Send the command again with the same command ID.",
+        },
+    };
+}
+function exchange(context) {
+    const { runtimeDirectory, request, onEvent, interruption } = context;
+    const address = socketAddress(join(runtimeDirectory, "control.sock"));
+    if (address.kind === "refused")
+        return Promise.resolve({
+            kind: "error",
+            error: { code: address.reason, detail: address.detail },
+        });
+    return new Promise((settle) => {
+        const socket = net.connect(address.path);
+        let buffered = "";
+        let written = false;
+        socket.setEncoding("utf8");
+        socket.on("connect", () => {
+            socket.write(requestLine(request), () => {
+                written = true;
+            });
+        });
+        socket.on("data", (data) => {
+            buffered += data;
+            const lines = buffered.split("\n");
+            buffered = lines.pop() ?? "";
+            for (const line of lines) {
+                const parsed = parseReplyLine(line);
+                if (parsed?.kind === "event")
+                    onEvent(parsed.event);
+                if (parsed?.kind === "result" || parsed?.kind === "error") {
+                    settle(parsed);
+                    socket.destroy();
+                }
+            }
+        });
+        const stopped = (reply) => () => {
+            settle(reply);
+            socket.destroy();
+        };
+        if (interruption !== undefined)
+            interruption.signal.then(stopped(interruption.reply), stopped(interruption.reply));
+        const ended = (code) => {
+            if (code === "EACCES")
+                return refused(runtimeDirectory);
+            return written
+                ? lost(request, runtimeDirectory)
+                : unavailable(runtimeDirectory);
+        };
+        socket.on("error", (error) => {
+            settle(ended(Reflect.get(error, "code")));
+        });
+        socket.on("close", () => {
+            settle(ended(undefined));
+        });
+    });
+}
+const unobserved = () => undefined;
+export function send(runtimeDirectory, request) {
+    return exchange({ runtimeDirectory, request, onEvent: unobserved });
+}
+export function mutate(runtimeDirectory, mutation) {
+    return exchange({
+        runtimeDirectory,
+        request: mutation.request,
+        onEvent: unobserved,
+        interruption: {
+            signal: mutation.signal,
+            reply: {
+                kind: "error",
+                error: {
+                    code: "outcome-unknown",
+                    detail: "A signal ended the command before the reply. Send the command again with the same command ID.",
+                },
+            },
+        },
+    });
+}
+export function follow(runtimeDirectory, stream) {
+    return exchange({
+        runtimeDirectory,
+        request: stream.request,
+        onEvent: stream.onEvent,
+        interruption: {
+            signal: stream.signal,
+            reply: {
+                kind: "result",
+                result: { schemaVersion: 1, kind: "event-page", events: [] },
+            },
+        },
+    });
+}

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

@@ -0,0 +1,14 @@
+import type { RuntimeInvocation } from "./runtime-arguments.ts";
+export interface Terminal {
+    readonly out: (text: string) => void;
+    readonly error: (text: string) => void;
+}
+export interface CommandEnvironment {
+    readonly runtimeDirectory: string | undefined;
+    readonly client?: string;
+    readonly workingDirectory: string;
+    readonly terminal: Terminal;
+    readonly identifier: () => string;
+    readonly interrupted: () => Promise<void>;
+}
+export declare function runtimeCommand(invocation: RuntimeInvocation, environment: CommandEnvironment): Promise<number>;

package/dist/src/cli/commands.js

@@ -0,0 +1,253 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { record, } from "../protocol.js";
+import { follow, mutate, send } from "./client.js";
+import { errorText, eventText, pendingSummary, rendered } from "./render.js";
+import { commandUsage } from "./usage.js";
+import { defaultWatchPort, watchServer } from "./watch-server.js";
+function errorObject(error, format) {
+    if (error.code === "event-gap")
+        return {
+            schemaVersion: 1,
+            kind: "event-gap",
+            after: error["after"],
+            earliestAvailable: error["earliestAvailable"],
+            latestSequence: error["latestSequence"],
+        };
+    return {
+        schemaVersion: 1,
+        kind: "error",
+        ...error,
+        commandId: error["commandId"] ?? format.commandId ?? null,
+        runId: error["runId"] ?? null,
+        currentRevision: error["currentRevision"] ?? null,
+    };
+}
+function failed(environment, failure) {
+    const { terminal } = environment;
+    const shown = errorObject(failure.error, failure.format);
+    if (failure.format.json) {
+        terminal.out(`${JSON.stringify(shown)}\n`);
+        return 1;
+    }
+    terminal.error(errorText(failure.error));
+    if (typeof shown["commandId"] === "string" && !failure.format.announced)
+        terminal.error(`Command ID: ${shown["commandId"]}\n`);
+    return 1;
+}
+function presented(environment, outcome) {
+    const { reply, format } = outcome;
+    if (reply.kind === "error")
+        return failed(environment, { error: reply.error, format });
+    environment.terminal.out(format.json ? `${JSON.stringify(reply.result)}\n` : rendered(reply.result));
+    return 0;
+}
+async function requested(environment, exchange) {
+    return presented(environment, {
+        reply: await send(environment.runtimeDirectory, exchange.request),
+        format: exchange.format,
+    });
+}
+async function mutated(environment, exchange) {
+    return presented(environment, {
+        reply: await mutate(environment.runtimeDirectory, {
+            request: exchange.request,
+            signal: environment.interrupted(),
+        }),
+        format: exchange.format,
+    });
+}
+function identified(environment, invocation) {
+    const { json } = invocation;
+    if (invocation.commandId !== null)
+        return { json, commandId: invocation.commandId, announced: false };
+    const commandId = environment.identifier();
+    if (!json)
+        environment.terminal.error(`Command ID: ${commandId}\n`);
+    return { json, commandId, announced: !json };
+}
+async function inputFile(environment, file) {
+    let text;
+    try {
+        text = await readFile(resolve(environment.workingDirectory, file), "utf8");
+    }
+    catch {
+        return {
+            kind: "error",
+            error: {
+                code: "unreadable-input",
+                detail: `The input file ${file} is not readable.`,
+            },
+        };
+    }
+    try {
+        return { kind: "read", submission: JSON.parse(text) };
+    }
+    catch {
+        return {
+            kind: "error",
+            error: {
+                code: "malformed-input",
+                detail: `The input file ${file} is not JSON.`,
+            },
+        };
+    }
+}
+function typed(source) {
+    return source.kind === "prompt"
+        ? { prompt: source.text }
+        : { ticket: source.id };
+}
+async function run(environment, invocation) {
+    const format = identified(environment, invocation);
+    const { commandId } = format;
+    const { source } = invocation;
+    const read = source.kind === "input"
+        ? await inputFile(environment, source.file)
+        : { kind: "read", submission: typed(source) };
+    if (read.kind === "error")
+        return failed(environment, { error: read.error, format });
+    return mutated(environment, {
+        format,
+        request: {
+            operation: "run",
+            parameters: {
+                workflowId: invocation.workflowId,
+                source: source.kind,
+                submission: read.submission,
+                commandId,
+            },
+        },
+    });
+}
+function present(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== null));
+}
+async function summarized(environment) {
+    const pending = await send(environment.runtimeDirectory, {
+        operation: "questions",
+        parameters: {},
+    });
+    if (pending.kind === "result")
+        environment.terminal.out(pendingSummary(pending.result));
+}
+async function status(environment, invocation) {
+    const { runId, limit, after, json } = invocation;
+    if (!json && runId === null)
+        await summarized(environment);
+    return requested(environment, {
+        format: { json },
+        request: {
+            operation: "status",
+            parameters: present({ runId, limit, after }),
+        },
+    });
+}
+function decision(environment, invocation) {
+    const format = identified(environment, invocation);
+    const { commandId } = format;
+    return mutated(environment, {
+        format,
+        request: {
+            operation: "decision",
+            parameters: present({
+                command: invocation.command,
+                reference: invocation.reference,
+                text: invocation.text,
+                expectedRevision: invocation.expectedRevision,
+                generation: invocation.generation,
+                subjectDigest: invocation.subjectDigest,
+                commandId,
+            }),
+        },
+    });
+}
+function runCommand(environment, invocation) {
+    const format = identified(environment, invocation);
+    const { commandId } = format;
+    return mutated(environment, {
+        format,
+        request: {
+            operation: "run-command",
+            parameters: {
+                command: invocation.command,
+                runId: invocation.runId,
+                expectedRevision: invocation.expectedRevision,
+                commandId,
+            },
+        },
+    });
+}
+async function events(environment, invocation) {
+    const { json, follow: following } = invocation;
+    const { terminal } = environment;
+    const print = (event) => {
+        terminal.out(json ? `${JSON.stringify(event)}\n` : `${eventText(event)}\n`);
+    };
+    const request = {
+        operation: "events",
+        parameters: present({
+            runId: invocation.runId,
+            after: invocation.after,
+            limit: invocation.limit,
+            follow: following,
+        }),
+    };
+    const reply = following
+        ? await follow(environment.runtimeDirectory, {
+            request,
+            onEvent: print,
+            signal: environment.interrupted(),
+        })
+        : await send(environment.runtimeDirectory, request);
+    if (reply.kind === "error")
+        return failed(environment, { error: reply.error, format: { json } });
+    const page = reply.result["events"];
+    for (const event of Array.isArray(page) ? page : [])
+        print(record(event) ?? {});
+    return 0;
+}
+export function runtimeCommand(invocation, environment) {
+    if (invocation.kind === "command-help") {
+        environment.terminal.out(commandUsage[invocation.command] ?? "");
+        return Promise.resolve(0);
+    }
+    const { runtimeDirectory } = environment;
+    if (runtimeDirectory === undefined)
+        return Promise.resolve(failed(environment, {
+            error: {
+                code: "runtime-directory-unknown",
+                detail: "No runtime directory is known. Set CLOVING_RUNTIME_DIR to the runtime directory of the service.",
+            },
+            format: { json: invocation.json },
+        }));
+    return located(invocation, { ...environment, runtimeDirectory });
+}
+function located(invocation, environment) {
+    if (invocation.kind === "run")
+        return run(environment, invocation);
+    if (invocation.kind === "status")
+        return status(environment, invocation);
+    if (invocation.kind === "decision")
+        return decision(environment, invocation);
+    if (invocation.kind === "run-command")
+        return runCommand(environment, invocation);
+    if (invocation.kind === "events")
+        return events(environment, invocation);
+    if (invocation.kind === "watch")
+        return watchServer({
+            runtimeDirectory: environment.runtimeDirectory,
+            port: invocation.port ?? defaultWatchPort,
+            client: environment.client ?? "cloving",
+            announce: environment.terminal.out,
+            complain: environment.terminal.error,
+            stopped: environment.interrupted(),
+        });
+    return requested(environment, {
+        format: { json: invocation.json },
+        request: {
+            operation: "questions",
+            parameters: present({ runId: invocation.runId }),
+        },
+    });
+}

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

@@ -0,0 +1 @@
+export declare function main(argumentsList: readonly string[]): Promise<void>;

package/dist/src/cli/main.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import packageMetadata from "#package" with { type: "json" };
+import { importChats } from "../chats/import.js";
+import { parseInvocation } from "./arguments.js";
+import { runtimeCommand } from "./commands.js";
+import { clientCommand, runtimeDirectory } from "./runtime-directory.js";
+import { chatsImportUsage, usage, validateUsage } from "./usage.js";
+import { validateWorkflow } from "./validate.js";
+export async function main(argumentsList) {
+    const invocation = parseInvocation(argumentsList);
+    if (invocation.kind === "usage-error") {
+        presentUsageError(invocation);
+    }
+    else if (invocation.kind === "validate") {
+        await validationCommand(invocation);
+    }
+    else if (invocation.kind === "version") {
+        process.stdout.write(`${packageMetadata.version}\n`);
+    }
+    else if (invocation.kind === "help") {
+        process.stdout.write(usage);
+    }
+    else if (invocation.kind === "validate-help") {
+        process.stdout.write(validateUsage);
+    }
+    else if (invocation.kind === "chats-import-help") {
+        process.stdout.write(chatsImportUsage);
+    }
+    else if (invocation.kind === "chats-import") {
+        const result = await importChats({
+            paths: invocation.paths,
+            workingDirectory: process.cwd(),
+            runtimeDirectory: runtimeDirectory(process.env),
+        });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.code === "import-complete" ? 0 : 1;
+    }
+    else {
+        process.exitCode = await runtimeCommand(invocation, {
+            runtimeDirectory: runtimeDirectory(process.env),
+            client: clientCommand(process.env),
+            workingDirectory: process.cwd(),
+            terminal: {
+                out: (text) => process.stdout.write(text),
+                error: (text) => process.stderr.write(text),
+            },
+            identifier: randomUUID,
+            interrupted: () => new Promise((settle) => {
+                for (const signal of ["SIGINT", "SIGTERM"])
+                    process.once(signal, () => {
+                        settle();
+                    });
+            }),
+        });
+    }
+}
+function presentUsageError(invocation) {
+    if (invocation.json)
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, kind: "usage-error", code: invocation.code })}\n`);
+    else
+        process.stderr.write(`${invocation.code}: run cloving --help for usage.\n`);
+    process.exitCode = 2;
+}
+async function validationCommand(invocation) {
+    const report = await validateWorkflow(process.cwd(), invocation);
+    present(report, invocation.json ? "json" : "human");
+    process.exitCode = report.status === "valid" ? 0 : 1;
+}
+function present(report, format) {
+    if (format === "json") {
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+        return;
+    }
+    if (report.status === "valid") {
+        process.stdout.write(`Workflow ${report.workflow.name} is valid.\nWorkflow ID: ${report.workflow.workflowId}\nPinned identity: ${report.pinnedIdentity}\n`);
+        return;
+    }
+    for (const error of report.errors)
+        process.stderr.write(`${error.code}: ${error.file}: ${error.detail}\n`);
+}

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

@@ -0,0 +1,8 @@
+import { type Fields } from "../protocol.ts";
+export declare function errorText(error: Fields): string;
+export declare function runStatus(result: Fields): readonly string[];
+export declare function decisionLines(decision: unknown): readonly string[];
+export declare function decisionList(result: Fields): readonly string[];
+export declare function eventText(event: Fields): string;
+export declare function rendered(result: Fields): string;
+export declare function pendingSummary(result: Fields): string;