cloving 0.3.20 → 1.1.0

package/dist/src/workflow-candidate.d.ts

@@ -0,0 +1,29 @@
+import { type WorkflowDeclaration } from "./workflow-declaration.ts";
+export interface CandidateDeclaration {
+    readonly workflow: WorkflowDeclaration;
+    readonly methods: Readonly<Record<string, readonly string[]>>;
+}
+export interface CandidateImport {
+    readonly module: string;
+    readonly names: readonly string[];
+}
+export interface CandidateEffect {
+    readonly capability: string | null;
+    readonly method: string | null;
+}
+export interface CandidateAnalysis {
+    readonly imports: readonly CandidateImport[];
+    readonly effects: readonly CandidateEffect[];
+    readonly directEffects: readonly string[];
+    readonly unsupportedForms: readonly string[];
+    readonly knownCallCount: number;
+    readonly knownUnitTotal: number;
+}
+export type InstalledWorkflowExports = Readonly<Record<string, readonly string[]>>;
+export type WorkflowCandidateCode = "invalid-declaration" | "forbidden-import" | "missing-export" | "unsupported-source" | "dynamic-effect" | "undeclared-effect" | "effect-limit" | "direct-effect";
+export interface WorkflowCandidateInput {
+    readonly declaration: unknown;
+    readonly analysis: CandidateAnalysis;
+    readonly installedExports: InstalledWorkflowExports;
+}
+export declare function checkWorkflowCandidate(input: WorkflowCandidateInput): readonly WorkflowCandidateCode[];

package/dist/src/workflow-candidate.js

@@ -0,0 +1,59 @@
+import { record } from "./protocol.js";
+import { isWorkflowDeclaration, } from "./workflow-declaration.js";
+const workflowModules = [
+    "cloving/workflows",
+    "cloving/workflows/steps/decision-gate",
+    "cloving/workflows/steps/load-cycle",
+    "cloving/workflows/steps/protected-effect",
+];
+function isMethodList(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        Array.from(value).every((method) => typeof method === "string" && method.trim().length > 0) &&
+        new Set(value).size === value.length);
+}
+function isCandidateDeclaration(value) {
+    const fields = record(value);
+    if (!fields ||
+        Object.keys(fields).some((key) => key !== "workflow" && key !== "methods"))
+        return false;
+    const workflow = fields["workflow"];
+    const methods = record(fields["methods"]);
+    if (!isWorkflowDeclaration(workflow) || !methods)
+        return false;
+    const capabilities = workflow.capabilities;
+    return (Object.keys(methods).every((key) => capabilities.includes(key)) &&
+        capabilities.every((capability) => isMethodList(methods[capability])));
+}
+export function checkWorkflowCandidate(input) {
+    if (!isCandidateDeclaration(input.declaration))
+        return ["invalid-declaration"];
+    const { analysis, declaration, installedExports } = input;
+    const codes = [];
+    if (analysis.imports.some((entry) => !workflowModules.includes(entry.module)))
+        codes.push("forbidden-import");
+    if (analysis.imports.some((entry) => {
+        if (!workflowModules.includes(entry.module))
+            return false;
+        const names = installedExports[entry.module];
+        return (names === undefined || entry.names.some((name) => !names.includes(name)));
+    }))
+        codes.push("missing-export");
+    if (analysis.effects.some((effect) => effect.capability !== null &&
+        effect.method !== null &&
+        (!Object.hasOwn(declaration.methods, effect.capability) ||
+            !declaration.methods[effect.capability]?.includes(effect.method))))
+        codes.push("undeclared-effect");
+    if (analysis.effects.some((effect) => effect.capability === null || effect.method === null))
+        codes.push("dynamic-effect");
+    const counts = [analysis.knownCallCount, analysis.knownUnitTotal];
+    if (counts.some((count) => !Number.isSafeInteger(count) || count < 0))
+        codes.push("unsupported-source");
+    else if (counts.some((count) => count > declaration.workflow.effectLimit))
+        codes.push("effect-limit");
+    if (analysis.directEffects.length > 0)
+        codes.push("direct-effect");
+    if (analysis.unsupportedForms.length > 0)
+        codes.push("unsupported-source");
+    return [...new Set(codes)].sort();
+}

package/dist/src/workflow-contracts.d.ts

@@ -0,0 +1,29 @@
+export interface DevelopmentInput {
+    readonly cycleId: string;
+}
+export type CycleOutcome = {
+    readonly kind: "waiting_for_decision";
+    readonly cycleId: string;
+    readonly decisionId: string;
+} | {
+    readonly kind: "blocked";
+    readonly cycleId: string;
+    readonly reason: string;
+    readonly evidenceId: string;
+} | {
+    readonly kind: "handoff_requested";
+    readonly cycleId: string;
+    readonly promotionId: string;
+    readonly ticketStatus?: "complete" | "partial";
+    readonly issueUpdate?: "failed";
+};
+export type Validation<Value> = {
+    readonly kind: "valid";
+    readonly value: Value;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export declare function isBlockedReason(value: unknown): value is string;
+export declare function validateDevelopmentInput(value: unknown): Validation<DevelopmentInput>;
+export declare function validateCycleOutcome(value: unknown, input: DevelopmentInput): Validation<CycleOutcome>;

package/dist/src/workflow-contracts.js

@@ -0,0 +1,110 @@
+import { isTicketStatus } from "./ticket-status.js";
+const identifier = /^[A-Za-z0-9._:-]{1,128}$/;
+const reason = /^\S[\s\S]{0,255}$/;
+export function isBlockedReason(value) {
+    return typeof value === "string" && reason.test(value);
+}
+const outcomes = {
+    waiting_for_decision: {
+        keys: ["cycleId", "decisionId", "kind"],
+        parse: (fields) => {
+            const cycleId = textField(fields, {
+                key: "cycleId",
+                pattern: identifier,
+            });
+            const decisionId = textField(fields, {
+                key: "decisionId",
+                pattern: identifier,
+            });
+            if (cycleId === null || decisionId === null)
+                return null;
+            return { kind: "waiting_for_decision", cycleId, decisionId };
+        },
+    },
+    blocked: {
+        keys: ["cycleId", "evidenceId", "kind", "reason"],
+        parse: (fields) => {
+            const cycleId = textField(fields, {
+                key: "cycleId",
+                pattern: identifier,
+            });
+            const evidenceId = textField(fields, {
+                key: "evidenceId",
+                pattern: identifier,
+            });
+            const blocker = fields["reason"];
+            if (cycleId === null || evidenceId === null || !isBlockedReason(blocker))
+                return null;
+            return { kind: "blocked", cycleId, reason: blocker, evidenceId };
+        },
+    },
+    handoff_requested: {
+        keys: ["cycleId", "kind", "promotionId"],
+        optional: ["ticketStatus", "issueUpdate"],
+        parse: (fields) => {
+            const cycleId = textField(fields, {
+                key: "cycleId",
+                pattern: identifier,
+            });
+            const promotionId = textField(fields, {
+                key: "promotionId",
+                pattern: identifier,
+            });
+            if (cycleId === null || promotionId === null)
+                return null;
+            const ticketStatus = fields["ticketStatus"];
+            const issueUpdate = fields["issueUpdate"];
+            if (issueUpdate !== undefined && issueUpdate !== "failed")
+                return null;
+            if (ticketStatus !== undefined && !isTicketStatus(ticketStatus))
+                return null;
+            return {
+                kind: "handoff_requested",
+                cycleId,
+                promotionId,
+                ...(issueUpdate === "failed" ? { issueUpdate } : {}),
+                ...(ticketStatus === undefined ? {} : { ticketStatus }),
+            };
+        },
+    },
+};
+export function validateDevelopmentInput(value) {
+    const fields = exactFields(value, { required: ["cycleId"] });
+    const cycleId = fields && textField(fields, { key: "cycleId", pattern: identifier });
+    if (!cycleId)
+        return { kind: "invalid", reason: "invalid-development-input" };
+    return { kind: "valid", value: { cycleId } };
+}
+export function validateCycleOutcome(value, input) {
+    const kind = exactFields(value, null)?.["kind"];
+    const contract = typeof kind === "string" && Object.hasOwn(outcomes, kind)
+        ? outcomes[kind]
+        : undefined;
+    const fields = contract &&
+        exactFields(value, {
+            required: contract.keys,
+            optional: contract.optional ?? [],
+        });
+    const outcome = fields && contract.parse(fields);
+    if (!outcome || outcome.cycleId !== input.cycleId)
+        return { kind: "invalid", reason: "invalid-cycle-outcome" };
+    return { kind: "valid", value: outcome };
+}
+function exactFields(value, shape) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const fields = Object.fromEntries(Object.entries(value));
+    const keys = shape?.required;
+    const optional = shape?.optional ?? [];
+    if (keys &&
+        JSON.stringify(Object.keys(fields)
+            .filter((key) => !optional.includes(key))
+            .sort()) !== JSON.stringify(keys))
+        return null;
+    return fields;
+}
+function textField(fields, field) {
+    const { key, pattern } = field;
+    const value = fields[key];
+    return typeof value === "string" && pattern.test(value) ? value : null;
+}

package/dist/src/workflow-declaration.d.ts

@@ -0,0 +1,11 @@
+import type { SubmissionContract } from "./submission.ts";
+export interface WorkflowDeclaration {
+    readonly workflowId: string;
+    readonly effectLimit: number;
+    readonly capabilities: readonly ("claude" | "github" | "chats")[];
+    readonly input: SubmissionContract;
+}
+export interface DeclaredWorkflow extends WorkflowDeclaration {
+    readonly functionName: string;
+}
+export declare function isWorkflowDeclaration(value: unknown): value is WorkflowDeclaration;

package/dist/src/workflow-declaration.js

@@ -0,0 +1,59 @@
+import { record } from "./protocol.js";
+function keys(fields, allowed) {
+    return Object.keys(fields).every((key) => allowed.includes(key));
+}
+function integer(value, bounds) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= bounds.minimum &&
+        value <= bounds.maximum);
+}
+function integerBounds(fields) {
+    const { minimum, maximum } = fields;
+    if (minimum !== undefined && !Number.isInteger(minimum))
+        return false;
+    if (maximum !== undefined && !Number.isInteger(maximum))
+        return false;
+    return (typeof minimum !== "number" ||
+        typeof maximum !== "number" ||
+        minimum <= maximum);
+}
+function isField(value) {
+    const fields = record(value);
+    if (fields === undefined ||
+        !keys(fields, ["type", "optional", "minimum", "maximum"]))
+        return false;
+    if (fields["optional"] !== undefined &&
+        typeof fields["optional"] !== "boolean")
+        return false;
+    if (fields["type"] === "integer")
+        return integerBounds(fields);
+    return ((fields["type"] === "string" || fields["type"] === "boolean") &&
+        !Object.hasOwn(fields, "minimum") &&
+        !Object.hasOwn(fields, "maximum"));
+}
+function isInput(value) {
+    const input = record(value);
+    if (input === undefined || !keys(input, ["maximumBytes", "fields"]))
+        return false;
+    const fields = record(input["fields"]);
+    return (integer(input["maximumBytes"], { minimum: 1, maximum: 1_048_576 }) &&
+        fields !== undefined &&
+        Object.values(fields).every(isField));
+}
+export function isWorkflowDeclaration(value) {
+    const declaration = record(value);
+    if (declaration === undefined ||
+        !keys(declaration, ["workflowId", "effectLimit", "capabilities", "input"]))
+        return false;
+    const { workflowId, effectLimit, capabilities, input } = declaration;
+    return (typeof workflowId === "string" &&
+        /^[A-Za-z0-9-]{1,64}$/.test(workflowId) &&
+        integer(effectLimit, { minimum: 1, maximum: 100 }) &&
+        Array.isArray(capabilities) &&
+        capabilities.length > 0 &&
+        capabilities.every((capability) => capability === "claude" ||
+            capability === "github" ||
+            capability === "chats") &&
+        isInput(input));
+}

package/dist/src/workflow-resources.d.ts

@@ -0,0 +1,8 @@
+export type ResolvedResources = {
+    readonly kind: "resolved";
+    readonly resources: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "inaccessible";
+    readonly path: string;
+};
+export declare function resolveResources(declared: readonly string[], discovered: unknown): ResolvedResources;

package/dist/src/workflow-resources.js

@@ -0,0 +1,14 @@
+const digest = /^[0-9a-f]{64}$/;
+export function resolveResources(declared, discovered) {
+    const available = discovered && typeof discovered === "object" && !Array.isArray(discovered)
+        ? Object.fromEntries(Object.entries(discovered))
+        : {};
+    const entries = [];
+    for (const path of declared) {
+        const value = Object.hasOwn(available, path) ? available[path] : undefined;
+        if (typeof value !== "string" || !digest.test(value))
+            return { kind: "inaccessible", path };
+        entries.push([path, value]);
+    }
+    return { kind: "resolved", resources: Object.fromEntries(entries) };
+}

package/dist/src/workflows.d.ts

@@ -0,0 +1,6 @@
+export { loadCycle, type CycleLoad } from "./steps/load-cycle.ts";
+export { protectedEffect } from "./steps/protected-effect.ts";
+export { decisionGate } from "./steps/decision-gate.ts";
+export type { GateRequest, GateResult, ProtectedRequest, ProtectedResult, ProtectedScope, } from "./step-bridge.ts";
+export type { CycleOutcome, DevelopmentInput } from "./workflow-contracts.ts";
+export { ticketStatus, type TicketStatus } from "./ticket-status.ts";

package/dist/src/workflows.js

@@ -0,0 +1,4 @@
+export { loadCycle } from "./steps/load-cycle.js";
+export { protectedEffect } from "./steps/protected-effect.js";
+export { decisionGate } from "./steps/decision-gate.js";
+export { ticketStatus } from "./ticket-status.js";

package/dist/tools/compile-workflows.d.ts

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

package/dist/tools/compile-workflows.js

@@ -0,0 +1,33 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { BaseBuilder } from "@workflow/builders";
+import { serializeManifest } from "./workflow-manifest.js";
+const [sourceDirectory, outputDirectory] = process.argv.slice(2);
+if (!sourceDirectory || !outputDirectory) {
+    throw new Error("Usage: npm run build:workflows -- SOURCE_DIRECTORY OUTPUT_DIRECTORY");
+}
+const output = resolve(outputDirectory);
+class WorkflowBuilder extends BaseBuilder {
+    async build() {
+        const inputFiles = await this.getInputFiles();
+        await mkdir(output, { recursive: true });
+        const result = await this.createCombinedBundle({
+            inputFiles,
+            stepsOutfile: resolve(output, "steps.mjs"),
+            flowOutfile: resolve(output, "flow.mjs"),
+            format: "esm",
+        });
+        await writeFile(resolve(output, "manifest.json"), serializeManifest(result.manifest));
+        await this.createClientLibrary();
+    }
+}
+await new WorkflowBuilder({
+    buildTarget: "standalone",
+    workingDir: process.cwd(),
+    dirs: [resolve(sourceDirectory)],
+    stepsBundlePath: resolve(output, "steps.mjs"),
+    workflowsBundlePath: resolve(output, "flow.mjs"),
+    webhookBundlePath: resolve(output, "webhook.mjs"),
+    clientBundlePath: resolve(output, "client.mjs"),
+    sourcemap: false,
+}).build();

package/dist/tools/self-host-processes.d.ts

@@ -0,0 +1,10 @@
+export interface HostProcesses {
+    readonly project: string;
+    readonly product: string;
+    readonly runtime: string;
+    readonly directory: string;
+    readonly repository: string;
+    readonly watchPort: string;
+    readonly updateMilliseconds: number | undefined;
+}
+export declare function hostedPrograms(settings: HostProcesses): Promise<number>;

package/dist/tools/self-host-processes.js

@@ -0,0 +1,156 @@
+import { execFile, spawn } from "node:child_process";
+import { addAbortListener } from "node:events";
+import { extname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { selfUpdater } from "./self-update.js";
+import { selfUpdateActive } from "./self-update-host.js";
+function launched(argumentsList, settings) {
+    const child = spawn(process.execPath, argumentsList, {
+        cwd: settings.directory,
+        env: settings.environment,
+        stdio: "inherit",
+    });
+    const ended = new Promise((settle, reject) => {
+        child.once("error", reject);
+        child.once("close", (status) => {
+            settle(status ?? 1);
+        });
+    });
+    return { child, ended };
+}
+async function stopped(programs) {
+    for (const program of programs)
+        program.child.kill("SIGTERM");
+    await Promise.all(programs.map((program) => program.ended));
+}
+function updatingGit(settings, stopping) {
+    const git = promisify(execFile);
+    return async (argumentsList) => {
+        if (argumentsList[0] === "merge")
+            return (await git("git", ["-C", settings.repository, ...argumentsList], {
+                encoding: "utf8",
+            })).stdout;
+        const command = git("git", ["-C", settings.repository, ...argumentsList], {
+            encoding: "utf8",
+            signal: stopping,
+            killSignal: "SIGKILL",
+            timeout: argumentsList[0] === "fetch" || argumentsList[0] === "remote"
+                ? 30000
+                : 0,
+        });
+        const listener = addAbortListener(stopping, () => {
+            command.child.kill("SIGKILL");
+        });
+        try {
+            return (await command).stdout;
+        }
+        finally {
+            listener[Symbol.dispose]();
+        }
+    };
+}
+async function polled(settings, lifecycle) {
+    if (settings.updateMilliseconds === undefined)
+        return;
+    const cancelled = () => lifecycle.stopping.aborted;
+    const updater = selfUpdater({
+        directory: settings.directory,
+        git: updatingGit(settings, lifecycle.stopping),
+        active: async () => lifecycle.stopping.aborted ||
+            (await selfUpdateActive({
+                directory: settings.directory,
+                runtimeDirectory: settings.runtime,
+                signal: lifecycle.stopping,
+            })),
+        stop: async () => {
+            if (lifecycle.stopping.aborted)
+                throw new Error("self-update-stopped");
+            await lifecycle.stop();
+        },
+        error: (line) => {
+            process.stderr.write(line);
+        },
+    });
+    while (!cancelled()) {
+        await delay(settings.updateMilliseconds, undefined, {
+            signal: lifecycle.stopping,
+        }).catch((error) => {
+            if (!(error instanceof Error) || error.name !== "AbortError")
+                throw error;
+        });
+        if (cancelled())
+            return;
+        const status = await updater.check();
+        if (status !== undefined)
+            return status;
+    }
+    return undefined;
+}
+function hostedChildren(settings) {
+    const daemon = launched([join(settings.project, "start.mjs")], {
+        directory: settings.project,
+        environment: process.env,
+    });
+    if (settings.watchPort === "off")
+        return [daemon];
+    return [
+        daemon,
+        launched([
+            join(settings.product, `src/cli${extname(import.meta.filename)}`),
+            "watch",
+            "--port",
+            settings.watchPort,
+        ], {
+            directory: settings.product,
+            environment: {
+                ...process.env,
+                CLOVING_RUNTIME_DIR: settings.runtime,
+                CLOVING_WATCH_REPOSITORY: settings.repository,
+            },
+        }),
+    ];
+}
+export async function hostedPrograms(settings) {
+    const programs = hostedChildren(settings);
+    const daemon = programs[0];
+    const stopping = new AbortController();
+    let updating = false;
+    const interrupt = () => {
+        stopping.abort();
+        for (const program of programs)
+            program.child.kill("SIGINT");
+    };
+    const terminate = () => {
+        stopping.abort();
+        for (const program of programs)
+            program.child.kill("SIGTERM");
+    };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    const polling = polled(settings, {
+        stopping: stopping.signal,
+        stop: async () => {
+            updating = true;
+            await stopped(programs);
+        },
+    });
+    try {
+        const [status, updateStatus] = await Promise.all([
+            daemon.ended.then((status) => {
+                if (!updating)
+                    stopping.abort();
+                return status;
+            }),
+            polling,
+        ]);
+        return updateStatus ?? status;
+    }
+    finally {
+        stopping.abort();
+        await stopped(programs);
+        await polling;
+        process.off("SIGINT", interrupt);
+        process.off("SIGTERM", terminate);
+    }
+}

package/dist/tools/self-host-workflows.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowManifest } from "@workflow/builders";
+import { type DeclaredWorkflow } from "../src/workflow-declaration.ts";
+interface HostManifest {
+    readonly schemaVersion: 1;
+    readonly name: string;
+    readonly workflowId: string;
+    readonly steps: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly resources: readonly string[];
+    readonly artifacts: string;
+}
+export declare function workflowFiles(directory: string): Promise<string[]>;
+export declare function workflowDeclarations(directory: string, manifests: Readonly<Record<string, HostManifest>>): Promise<readonly DeclaredWorkflow[]>;
+export declare function workflowManifests(compiled: WorkflowManifest, declarations?: readonly DeclaredWorkflow[]): Readonly<Record<string, HostManifest>>;
+export {};

package/dist/tools/self-host-workflows.js

@@ -0,0 +1,78 @@
+import { readdir, readFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { isWorkflowDeclaration, } from "../src/workflow-declaration.js";
+export async function workflowFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() &&
+        /\.(?:ts|js)$/.test(entry.name) &&
+        !entry.name.endsWith(".d.ts"))
+        .map((entry) => entry.name)
+        .sort();
+}
+export async function workflowDeclarations(directory, manifests) {
+    const declarations = [];
+    for (const file of await workflowFiles(directory)) {
+        const name = basename(file, extname(file));
+        const declarationFile = `${name}.declaration.json`;
+        const text = await readFile(join(directory, declarationFile), "utf8").catch((error) => {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT")
+                return undefined;
+            throw new Error(`invalid-workflow-declaration: ${declarationFile}`, {
+                cause: error,
+            });
+        });
+        if (text === undefined)
+            continue;
+        const entry = Object.entries(manifests).find(([, manifest]) => manifest.name === name);
+        try {
+            const value = JSON.parse(text);
+            if (!isWorkflowDeclaration(value) || entry === undefined)
+                throw new Error("Invalid declaration or missing workflow function.");
+            declarations.push({
+                ...value,
+                functionName: entry[0],
+                capabilities: [...new Set(value.capabilities)],
+            });
+        }
+        catch (error) {
+            throw new Error(`invalid-workflow-declaration: ${declarationFile}`, {
+                cause: error,
+            });
+        }
+    }
+    return declarations;
+}
+export function workflowManifests(compiled, declarations = []) {
+    const names = new Set();
+    const steps = Object.values(compiled.steps ?? {})
+        .flatMap((entries) => Object.values(entries))
+        .map((entry) => entry.stepId)
+        .filter((identifier) => identifier.startsWith("step//cloving/"));
+    return Object.fromEntries(Object.entries(compiled.workflows ?? {}).flatMap(([file, entries]) => {
+        const functions = Object.values(entries);
+        if (functions.length > 1)
+            throw new Error(`${file} must contain only one workflow function.`);
+        return functions.map((entry) => {
+            const workflowId = entry.workflowId;
+            const functionName = workflowId.slice(workflowId.lastIndexOf("//") + 2);
+            if (names.has(functionName))
+                throw new Error(`duplicate-workflow-function: ${functionName}`);
+            names.add(functionName);
+            return [
+                functionName,
+                {
+                    schemaVersion: 1,
+                    name: basename(file, extname(file)),
+                    workflowId,
+                    steps,
+                    capabilities: declarations.find((declaration) => declaration.functionName === functionName)?.capabilities ?? ["claude", "github"],
+                    resources: [],
+                    artifacts: "artifacts",
+                },
+            ];
+        });
+    }));
+}

package/dist/tools/self-host.d.ts

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