cloving 1.0.1 → 1.2.0

package/dist/tools/workflow-folders.d.ts

@@ -0,0 +1,33 @@
+import type { WorkflowCandidateCode } from "../src/workflow-candidate.ts";
+import { type WorkflowConflictCode, type WorkflowReservation } from "../src/workflow-discovery.ts";
+import type { CandidatePackageOptions } from "./workflow-candidate-program.ts";
+import { type WorkflowCaptureCode } from "./workflow-folder-capture.ts";
+export interface WorkflowFolderInput {
+    readonly repository: string;
+    readonly home: string;
+    readonly xdgConfigHome?: string | undefined;
+    readonly bundled: readonly WorkflowReservation[];
+}
+interface WorkflowLabel {
+    readonly scope: "project" | "user";
+    readonly label: string;
+}
+interface WorkflowSnapshot extends WorkflowLabel {
+    readonly baseName: string;
+    readonly source: string;
+    readonly declaration: string;
+}
+export interface WorkflowFolderCandidate extends WorkflowSnapshot {
+    readonly repository: string;
+    readonly artifactDigest: string;
+}
+export interface WorkflowFolderRefusal extends WorkflowLabel {
+    readonly codes: readonly (WorkflowCandidateCode | WorkflowCaptureCode | WorkflowConflictCode | "compile-failed")[];
+}
+export interface WorkflowFolderResult {
+    readonly repository: string;
+    readonly candidates: readonly WorkflowFolderCandidate[];
+    readonly refusals: readonly WorkflowFolderRefusal[];
+}
+export declare function loadWorkflowFolders(input: WorkflowFolderInput, installed?: CandidatePackageOptions): Promise<WorkflowFolderResult>;
+export {};

package/dist/tools/workflow-folders.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import ts from "typescript";
+import { record } from "../src/protocol.js";
+import { workflowConflicts, } from "../src/workflow-discovery.js";
+import { admitWorkflowCandidate } from "./admit-workflow.js";
+import { captureWorkflowCandidate, inspectWorkflowFolder, workflowCaptureFailure, workflowFolderEntries, } from "./workflow-folder-capture.js";
+function fileLabel(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.ts$/.test(name)
+        ? name
+        : "file-" + createHash("sha256").update(name).digest("hex").slice(0, 16);
+}
+function parsedDeclaration(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function identity(entry) {
+    const snapshot = entry.kind === "captured" ? entry.snapshot : entry;
+    const source = ts.createSourceFile("candidate.ts", snapshot.source ?? "", ts.ScriptTarget.Latest, true);
+    const workflowId = record(record(parsedDeclaration(snapshot.declaration ?? ""))?.["workflow"])?.["workflowId"];
+    return {
+        baseName: snapshot.baseName,
+        workflowId: typeof workflowId === "string" ? workflowId : undefined,
+        functionNames: source.statements
+            .filter(ts.isFunctionDeclaration)
+            .filter((node) => (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0)
+            .flatMap((node) => (node.name ? [node.name.text] : [])),
+    };
+}
+function compareLabels(left, right) {
+    const a = `${left.scope}\0${left.label}`;
+    const b = `${right.scope}\0${right.label}`;
+    return a < b ? -1 : Number(a > b);
+}
+async function scanFolder(location, refusals) {
+    let folder;
+    let entries;
+    try {
+        folder = await inspectWorkflowFolder(location.root, location.parts);
+        entries = await workflowFolderEntries(folder);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            refusals.push({
+                scope: location.scope,
+                label: "workflows/",
+                codes: [workflowCaptureFailure(error)],
+            });
+        return [];
+    }
+    const snapshots = [];
+    for (const name of entries
+        .filter((name) => name.endsWith(".ts") && !name.endsWith(".d.ts"))
+        .sort()) {
+        snapshots.push(await captureEntry(folder, {
+            scope: location.scope,
+            label: fileLabel(name),
+            name,
+        }));
+    }
+    return snapshots;
+}
+async function captureEntry(folder, file) {
+    const label = {
+        scope: file.scope,
+        label: file.label,
+        baseName: file.name.slice(0, -3),
+    };
+    try {
+        const capture = await captureWorkflowCandidate(folder, file.name);
+        if (capture.source === undefined ||
+            capture.declaration === undefined ||
+            capture.codes.length > 0)
+            return { kind: "refused", ...label, ...capture };
+        return {
+            kind: "captured",
+            snapshot: {
+                ...label,
+                source: capture.source,
+                declaration: capture.declaration,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            kind: "refused",
+            ...label,
+            codes: [workflowCaptureFailure(error)],
+            source: undefined,
+            declaration: undefined,
+        };
+    }
+}
+async function scanFolders(input, refusals) {
+    const repository = await realpath(input.repository);
+    const configuration = input.xdgConfigHome && isAbsolute(input.xdgConfigHome)
+        ? input.xdgConfigHome
+        : join(input.home, ".config");
+    const snapshots = [
+        ...(await scanFolder({ scope: "project", root: repository, parts: [".cloving", "workflows"] }, refusals)),
+        ...(await scanFolder({ scope: "user", root: configuration, parts: ["cloving", "workflows"] }, refusals)),
+    ];
+    return { repository, snapshots };
+}
+export async function loadWorkflowFolders(input, installed = {}) {
+    const candidates = [];
+    const refusals = [];
+    const { repository, snapshots } = await scanFolders(input, refusals);
+    const conflicts = workflowConflicts(snapshots.map(identity), input.bundled);
+    for (const [index, entry] of snapshots.entries()) {
+        const label = entry.kind === "captured" ? entry.snapshot : entry;
+        const codes = [
+            ...new Set([
+                ...(entry.kind === "refused" ? entry.codes : []),
+                ...(conflicts[index] ?? []),
+            ]),
+        ].sort();
+        if (entry.kind === "refused" || codes.length > 0) {
+            refusals.push({ scope: label.scope, label: label.label, codes });
+            continue;
+        }
+        const { snapshot } = entry;
+        const result = await admitWorkflowCandidate({
+            source: snapshot.source,
+            declaration: parsedDeclaration(snapshot.declaration),
+        }, installed);
+        if (result.kind === "refused")
+            refusals.push({
+                scope: snapshot.scope,
+                label: snapshot.label,
+                codes: result.codes,
+            });
+        else
+            candidates.push({
+                ...snapshot,
+                repository,
+                artifactDigest: result.artifactDigest,
+            });
+    }
+    return {
+        repository,
+        candidates: candidates.sort(compareLabels),
+        refusals: refusals.sort(compareLabels),
+    };
+}

package/dist/tools/workflow-source-effects.d.ts

@@ -0,0 +1,10 @@
+import ts from "typescript";
+export interface ReferenceContext {
+    readonly parent: ts.Node | undefined;
+    readonly checker: ts.TypeChecker;
+    readonly profile?: "candidate";
+}
+export declare function referenceSymbol(node: ts.Identifier, context: ReferenceContext): ts.Symbol | undefined;
+export declare function typeOnlyEffectNode(node: ts.Node): boolean;
+export declare function restrictedEffect(node: ts.Node, context: ReferenceContext): boolean;
+export declare function sourceEffectNodes(source: ts.SourceFile, context: Omit<ReferenceContext, "parent">): readonly ts.Node[];

package/dist/tools/workflow-source-effects.js

@@ -0,0 +1,213 @@
+import ts from "typescript";
+const ambientNames = new Set([
+    "globalThis",
+    "global",
+    "window",
+    "self",
+    "process",
+    "Date",
+    "performance",
+    "fetch",
+    "WebSocket",
+    "Worker",
+    "crypto",
+    "setTimeout",
+    "setInterval",
+    "setImmediate",
+    "queueMicrotask",
+    "eval",
+    "Function",
+    "require",
+    "console",
+    "navigator",
+    "Atomics",
+    "SharedArrayBuffer",
+    "WeakRef",
+    "FinalizationRegistry",
+    "Intl",
+]);
+const candidateNames = new Set([
+    "Buffer",
+    "document",
+    "screen",
+    "history",
+    "location",
+    "localStorage",
+    "sessionStorage",
+    "indexedDB",
+    "caches",
+    "Deno",
+    "Bun",
+    "__dirname",
+    "__filename",
+    "File",
+    "FileReader",
+    "readFile",
+    "writeFile",
+    "XMLHttpRequest",
+    "EventSource",
+    "WebTransport",
+    "BroadcastChannel",
+    "MessageChannel",
+    "MessagePort",
+    "postMessage",
+    "clearTimeout",
+    "clearInterval",
+    "clearImmediate",
+    "requestAnimationFrame",
+    "requestIdleCallback",
+    "cancelAnimationFrame",
+    "cancelIdleCallback",
+    "AbortSignal",
+    "Reflect",
+    "Proxy",
+    "constructor",
+    "WebAssembly",
+]);
+const reflectiveProperties = new Set(["constructor", "__proto__", "prototype"]);
+const candidateProperties = new Set([
+    "getPrototypeOf",
+    "setPrototypeOf",
+    "getOwnPropertyDescriptor",
+    "getOwnPropertyDescriptors",
+]);
+const pureMathMembers = new Set([
+    "E",
+    "LN10",
+    "LN2",
+    "LOG10E",
+    "LOG2E",
+    "PI",
+    "SQRT1_2",
+    "SQRT2",
+    "abs",
+    "acos",
+    "acosh",
+    "asin",
+    "asinh",
+    "atan",
+    "atan2",
+    "atanh",
+    "cbrt",
+    "ceil",
+    "clz32",
+    "cos",
+    "cosh",
+    "exp",
+    "expm1",
+    "floor",
+    "fround",
+    "hypot",
+    "imul",
+    "log",
+    "log10",
+    "log1p",
+    "log2",
+    "max",
+    "min",
+    "pow",
+    "round",
+    "sign",
+    "sin",
+    "sinh",
+    "sqrt",
+    "tan",
+    "tanh",
+    "trunc",
+]);
+function localBinding(symbol) {
+    return (symbol.declarations ?? []).some((declaration) => !declaration.getSourceFile().isDeclarationFile &&
+        (ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Ambient) ===
+            0);
+}
+export function referenceSymbol(node, context) {
+    const { parent, checker } = context;
+    if (parent &&
+        (ts.isPropertyAccessExpression(parent) ||
+            ts.isPropertyAssignment(parent)) &&
+        parent.name === node)
+        return undefined;
+    if (parent && ts.isShorthandPropertyAssignment(parent))
+        return checker.getShorthandAssignmentValueSymbol(parent);
+    return checker.getSymbolAtLocation(node);
+}
+function referenceIdentifier(node, parent) {
+    if (!ts.isIdentifier(node))
+        return false;
+    if (!parent)
+        return true;
+    if ((ts.isPropertyAccessExpression(parent) ||
+        ts.isPropertyAssignment(parent)) &&
+        parent.name === node)
+        return false;
+    return !ts.isImportSpecifier(parent);
+}
+function restrictedAmbientName(name, context) {
+    return (ambientNames.has(name) ||
+        name === "Math" ||
+        (context.profile === "candidate" && candidateNames.has(name)));
+}
+function pureMathAccess(node, parent) {
+    return (!!parent &&
+        ts.isPropertyAccessExpression(parent) &&
+        parent.expression === node &&
+        pureMathMembers.has(parent.name.text));
+}
+function ambientReference(node, context) {
+    const { parent } = context;
+    if (!referenceIdentifier(node, parent))
+        return false;
+    if (!restrictedAmbientName(node.text, context))
+        return false;
+    const candidate = context.profile === "candidate";
+    const symbol = referenceSymbol(node, context);
+    if ((!symbol && !candidate) || (symbol && localBinding(symbol)))
+        return false;
+    return node.text !== "Math" || !pureMathAccess(node, parent);
+}
+function reflectiveAccess(node, context) {
+    const candidate = context.profile === "candidate";
+    const restricted = (name) => reflectiveProperties.has(name) ||
+        (candidate && candidateProperties.has(name));
+    if (ts.isPropertyAccessExpression(node))
+        return restricted(node.name.text);
+    if (ts.isElementAccessExpression(node) &&
+        ts.isStringLiteralLike(node.argumentExpression))
+        return restricted(node.argumentExpression.text);
+    if (!candidate || !ts.isBindingElement(node))
+        return false;
+    const name = node.propertyName ?? node.name;
+    return ((ts.isIdentifier(name) || ts.isStringLiteralLike(name)) &&
+        restricted(name.text));
+}
+function dynamicCapability(node, checker) {
+    if (!ts.isElementAccessExpression(node))
+        return false;
+    const target = checker.getTypeAtLocation(node.expression);
+    return (target.getCallSignatures().length > 0 ||
+        target.getConstructSignatures().length > 0);
+}
+export function typeOnlyEffectNode(node) {
+    return ((ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node)) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node));
+}
+export function restrictedEffect(node, context) {
+    return (ambientReference(node, context) ||
+        reflectiveAccess(node, context) ||
+        dynamicCapability(node, context.checker));
+}
+export function sourceEffectNodes(source, context) {
+    const findings = [];
+    function visit(node, parent) {
+        if (typeOnlyEffectNode(node))
+            return;
+        if (restrictedEffect(node, { ...context, parent }))
+            findings.push(node);
+        ts.forEachChild(node, (child) => {
+            visit(child, node);
+        });
+    }
+    visit(source);
+    return findings;
+}

package/dist/workflows/analyze-chats.d.ts

@@ -0,0 +1,15 @@
+import type { CycleOutcome } from "cloving/workflows";
+interface Decision {
+    readonly gateId: string;
+    readonly decision: string;
+    readonly answer: string | null;
+}
+interface AnalysisInput {
+    readonly cycleId: string;
+    readonly repository: string;
+    readonly input: {
+        readonly importId: string;
+    };
+}
+export declare function analyzeChats(input: AnalysisInput, decision?: Decision): Promise<CycleOutcome>;
+export {};

package/dist/workflows/analyze-chats.declaration.json

@@ -0,0 +1,22 @@
+{
+  "workflowId": "analyze-chats",
+  "effectLimit": 11,
+  "capabilities": ["chats", "claude"],
+  "stages": [
+    {
+      "name": "read-input",
+      "label": "Read input",
+      "operations": ["read-analysis"]
+    },
+    { "name": "analyze", "label": "Analyze", "operations": ["turn-analysis"] },
+    {
+      "name": "save-result",
+      "label": "Save result",
+      "operations": ["save-analysis"]
+    }
+  ],
+  "input": {
+    "maximumBytes": 4096,
+    "fields": { "importId": { "type": "string" } }
+  }
+}

package/dist/workflows/analyze-chats.js

@@ -0,0 +1,250 @@
+import { decisionGate } from "cloving/workflows/steps/decision-gate";
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+function request(importId, step) {
+    const { operation, payload } = step;
+    return {
+        scope: { phase: "analysis", operation, round: step.round ?? 1 },
+        capability: operation === "turn-analysis" ? "claude" : "chats",
+        method: operation === "turn-analysis" ? "run-turn:analyze-chats" : operation,
+        target: importId,
+        payload: JSON.stringify(payload),
+        units: 1,
+    };
+}
+function blocked(cycleId, failure) {
+    const { operation, result } = failure;
+    return {
+        kind: "blocked",
+        cycleId,
+        evidenceId: operation,
+        reason: "reason" in result && result.reason !== null
+            ? result.reason
+            : result.kind,
+    };
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fields(result) {
+    try {
+        const value = JSON.parse(result ?? "null");
+        return record(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+function usableDraft(cycleId, draft) {
+    return (draft["cycleId"] === cycleId &&
+        typeof draft["candidateDigest"] === "string" &&
+        /^[a-f0-9]{64}$/.test(draft["candidateDigest"]) &&
+        typeof draft["expiresAt"] === "string" &&
+        record(draft["question"]));
+}
+function draftAnswer(draft, decision) {
+    if (decision.decision === "expired")
+        return "analysis-answer-missing";
+    const question = draft["question"];
+    const choices = record(question) ? question["choices"] : undefined;
+    if (decision.gateId !== "analysis-question" ||
+        decision.decision !== "answered" ||
+        typeof decision.answer !== "string" ||
+        !Array.isArray(choices) ||
+        !choices.some((choice) => record(choice) && choice["id"] === decision.answer))
+        return "analysis-answer-invalid";
+    return null;
+}
+async function askDraft(cycleId, continuation) {
+    const { draft, decision } = continuation;
+    if (!usableDraft(cycleId, draft))
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: "analysis-input-refused",
+            evidenceId: "save-analysis",
+        };
+    if (decision !== undefined) {
+        const reason = draftAnswer(draft, decision);
+        if (reason === null)
+            return { kind: "answered", answer: decision.answer ?? "" };
+        return {
+            kind: "blocked",
+            cycleId,
+            reason,
+            evidenceId: "analysis-question",
+        };
+    }
+    const gate = await decisionGate({
+        gateId: "analysis-question",
+        kind: "question",
+        prompt: JSON.stringify({
+            candidateDigest: draft["candidateDigest"],
+            question: draft["question"],
+        }),
+        expiresAt: draft.expiresAt,
+    });
+    if (gate.kind !== "opened")
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: gate.reason,
+            evidenceId: "analysis-question",
+        };
+    return { kind: "waiting_for_decision", cycleId, decisionId: gate.decisionId };
+}
+async function firstTurn(input) {
+    const { cycleId } = input;
+    const { importId } = input.input;
+    const read = await protectedEffect(request(importId, { operation: "read-analysis", payload: { importId } }));
+    if (read.kind !== "completed")
+        return blocked(cycleId, { operation: "read-analysis", result: read });
+    const captured = fields(read.result);
+    const snapshot = captured["snapshot"];
+    if (!record(snapshot) || snapshot["importId"] !== importId)
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: "analysis-input-refused",
+            evidenceId: "read-analysis",
+        };
+    return runTurn(input, batchData(captured, snapshot));
+}
+function batchData(value, snapshot) {
+    const context = value["context"];
+    const batch = value["batch"];
+    return {
+        snapshot,
+        ...(record(context) ? { context } : {}),
+        ...(record(batch) ? { batch } : {}),
+    };
+}
+async function runTurn(input, data) {
+    const { cycleId } = input;
+    const { snapshot, followUp, context } = data;
+    const turn = await protectedEffect(request(input.input.importId, {
+        operation: "turn-analysis",
+        payload: {
+            snapshot,
+            ...(context === undefined ? {} : { context }),
+            ...(followUp === undefined ? {} : { followUp }),
+        },
+        round: turnRound(data),
+    }));
+    if (turn.kind !== "completed")
+        return blocked(cycleId, { operation: "turn-analysis", result: turn });
+    const reply = fields(turn.result)["reply"];
+    if (typeof reply !== "string")
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: "analysis-turn-failed",
+            evidenceId: "turn-analysis",
+        };
+    return { kind: "analyzed", data, reply };
+}
+function handoff(cycleId, importId) {
+    return {
+        kind: "handoff_requested",
+        cycleId,
+        promotionId: `analysis:${importId}:${cycleId}`,
+    };
+}
+function turnRound(data) {
+    if (data.followUp !== undefined)
+        return data.batch === undefined ? 2 : 5;
+    return Number(data.batch?.["batchIndex"] ?? 0) + 1;
+}
+async function saveTurn(input, turn) {
+    const { batch, followUp } = turn.data;
+    return protectedEffect(request(input.input.importId, {
+        operation: "save-analysis",
+        round: turnRound(turn.data),
+        payload: {
+            importId: input.input.importId,
+            cycleId: input.cycleId,
+            reply: turn.reply,
+            ...(batch === undefined ? {} : { batch }),
+            ...(followUp === undefined ? {} : { followUp }),
+        },
+    }));
+}
+export async function analyzeChats(input, decision) {
+    "use workflow";
+    const { cycleId } = input;
+    const { importId } = input.input;
+    let analyzed = await firstTurn(input);
+    let answered = false;
+    while (analyzed.kind === "analyzed") {
+        const { data, reply } = analyzed;
+        const save = await saveTurn(input, analyzed);
+        if (save.kind !== "completed")
+            return blocked(cycleId, { operation: "save-analysis", result: save });
+        const saved = fields(save.result);
+        if (saved["kind"] === "analysis_draft") {
+            analyzed = await questionTurn(input, {
+                saved,
+                data,
+                reply,
+                decision,
+                answered,
+            });
+            answered = true;
+            continue;
+        }
+        if (saved["kind"] !== "analysis_batch")
+            return finishBatch(input, {
+                saved,
+                decision: answered ? undefined : decision,
+            });
+        const nextSnapshot = saved["snapshot"];
+        if (!record(nextSnapshot) || nextSnapshot["importId"] !== importId)
+            return blocked(cycleId, {
+                operation: "save-analysis",
+                result: { kind: "refused", reason: "analysis-input-refused" },
+            });
+        analyzed = await runTurn(input, batchData(saved, nextSnapshot));
+    }
+    return analyzed;
+}
+async function questionTurn(input, continuation) {
+    const { saved, data, reply, decision, answered } = continuation;
+    if (answered)
+        return blocked(input.cycleId, {
+            operation: "save-analysis",
+            result: { kind: "refused", reason: "analysis-question-limit" },
+        });
+    const answer = await askDraft(input.cycleId, { draft: saved, decision });
+    if (answer.kind !== "answered")
+        return answer;
+    return runTurn(input, {
+        ...data,
+        followUp: { draft: fields(reply), answer: answer.answer },
+    });
+}
+function finishBatch(input, result) {
+    const { cycleId } = input;
+    const { importId } = input.input;
+    const { saved, decision } = result;
+    if (saved["kind"] === "analysis_partial")
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: String(saved["reason"]),
+            evidenceId: "save-analysis",
+        };
+    if (decision !== undefined)
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: "analysis-answer-invalid",
+            evidenceId: "analysis-question",
+        };
+    if (saved["kind"] !== "handoff_requested")
+        return {
+            kind: "blocked",
+            cycleId,
+            reason: "analysis-input-refused",
+            evidenceId: "save-analysis",
+        };
+    return handoff(cycleId, importId);
+}