cloving 1.1.0 → 1.2.0

package/dist/tools/workflow-folder-capture.d.ts

@@ -0,0 +1,17 @@
+import { type BigIntStats } from "node:fs";
+export type WorkflowCaptureCode = "unsafe-workflow-path" | "workflow-read-failed" | "workflow-source-changed" | "unsupported-source" | "invalid-declaration";
+export interface WorkflowFolder {
+    readonly path: string;
+    readonly components: readonly {
+        readonly path: string;
+        readonly stats: BigIntStats;
+    }[];
+}
+export declare function inspectWorkflowFolder(root: string, parts: readonly string[]): Promise<WorkflowFolder>;
+export declare function captureWorkflowCandidate(folder: WorkflowFolder, name: string): Promise<{
+    source: string | undefined;
+    declaration: string | undefined;
+    codes: WorkflowCaptureCode[];
+}>;
+export declare function workflowCaptureFailure(error: unknown): WorkflowCaptureCode;
+export declare function workflowFolderEntries(folder: WorkflowFolder): Promise<string[]>;

package/dist/tools/workflow-folder-capture.js

@@ -0,0 +1,216 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+function contained(root, path) {
+    const suffix = relative(root, path);
+    return (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`));
+}
+function safeComponent(name) {
+    return (name.length > 0 &&
+        name !== "." &&
+        name !== ".." &&
+        !/[/\\:]/.test(name) &&
+        !name.startsWith("~"));
+}
+export async function inspectWorkflowFolder(root, parts) {
+    const canonical = await realpath(root);
+    if (parts.some((part) => !safeComponent(part)))
+        throw new Error("unsafe-workflow-path");
+    const components = [];
+    let path = canonical;
+    for (const part of ["", ...parts]) {
+        path = join(path, part);
+        const stats = await lstat(path, { bigint: true }).catch(async (error) => {
+            await verifyFolder({ path, components });
+            throw error;
+        });
+        if (stats.isSymbolicLink())
+            throw new Error("unsafe-workflow-path");
+        if (!stats.isDirectory())
+            throw new Error("workflow-read-failed");
+        components.push({ path, stats });
+    }
+    const resolved = await realpath(path).catch(changedPathError);
+    const folder = { path, components };
+    await verifyFolder(folder);
+    if (!contained(canonical, resolved))
+        throw new Error("unsafe-workflow-path");
+    return folder;
+}
+function sameIdentity(left, right) {
+    return (left.dev === right.dev && left.ino === right.ino && left.mode === right.mode);
+}
+function sameSnapshot(left, right) {
+    return (sameIdentity(left, right) &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+async function verifyFolder(folder) {
+    for (const component of folder.components) {
+        const compare = component.path === folder.path ? sameSnapshot : sameIdentity;
+        if (!compare(component.stats, await capturedStats(component.path)))
+            throw new Error("workflow-source-changed");
+    }
+}
+function capturedStats(path) {
+    return lstat(path, { bigint: true }).catch(changedPathError);
+}
+function changedPathError(error) {
+    if (error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" ||
+            error.code === "ENOTDIR" ||
+            error.code === "ELOOP"))
+        throw new Error("workflow-source-changed");
+    throw error;
+}
+async function openSource(folder, name) {
+    const flags = constants.O_RDONLY | constants.O_NONBLOCK;
+    if (process.platform === "darwin")
+        return open(join(folder.path, name), flags | 0x20000000);
+    if (process.platform !== "linux")
+        throw new Error("workflow-read-failed");
+    const handles = [];
+    try {
+        let path = folder.components[0]?.path;
+        if (!path)
+            throw new Error("workflow-read-failed");
+        for (const component of folder.components) {
+            const handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            handles.push(handle);
+            if (!sameIdentity(component.stats, await handle.stat({ bigint: true })))
+                throw new Error("workflow-source-changed");
+            const next = folder.components[handles.length];
+            path = `/proc/self/fd/${String(handle.fd)}/${next ? relative(component.path, next.path) : name}`;
+        }
+        return await open(path, flags | constants.O_NOFOLLOW);
+    }
+    finally {
+        for (const handle of handles.reverse())
+            await handle.close();
+    }
+}
+async function inspectFile(folder, name) {
+    const path = join(folder.path, name);
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isFile())
+        throw new Error("unsafe-workflow-path");
+    const resolved = await realpath(path).catch(changedPathError);
+    if (!sameSnapshot(stats, await capturedStats(path)))
+        throw new Error("workflow-source-changed");
+    if (!contained(folder.path, resolved))
+        throw new Error("unsafe-workflow-path");
+    return { path, name, stats };
+}
+async function captureFile(folder, file) {
+    const { stats } = file;
+    const handle = await openSource(folder, file.name).catch(changedPathError);
+    try {
+        if (!sameSnapshot(stats, await handle.stat({ bigint: true })))
+            throw new Error("workflow-source-changed");
+        const bytes = await handle.readFile();
+        if (!sameSnapshot(stats, await handle.stat({ bigint: true })) ||
+            BigInt(bytes.length) !== stats.size)
+            throw new Error("workflow-source-changed");
+        return { ...file, bytes };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function captureFiles(folder, names) {
+    const inspected = [];
+    const captured = [];
+    const codes = [];
+    for (const name of names) {
+        try {
+            inspected.push(await inspectFile(folder, name));
+        }
+        catch (error) {
+            codes.push(workflowCaptureFailure(error));
+        }
+    }
+    for (const file of inspected) {
+        try {
+            captured.push(await captureFile(folder, file));
+        }
+        catch (error) {
+            codes.push(workflowCaptureFailure(error));
+        }
+    }
+    for (const file of captured) {
+        if (!sameSnapshot(file.stats, await capturedStats(file.path)))
+            throw new Error("workflow-source-changed");
+    }
+    return { captured, codes };
+}
+function decodedFile(input, codes) {
+    if (input.bytes === undefined)
+        return undefined;
+    const text = input.bytes.toString("utf8");
+    if (input.bytes.equals(Buffer.from(text)))
+        return text;
+    codes.push(input.code);
+    return undefined;
+}
+export async function captureWorkflowCandidate(folder, name) {
+    if (!safeComponent(name) || !name.endsWith(".ts") || name.endsWith(".d.ts"))
+        throw new Error("unsafe-workflow-path");
+    await verifyFolder(folder);
+    const declarationName = name.slice(0, -3) + ".declaration.json";
+    const { captured, codes } = await captureFiles(folder, [
+        name,
+        declarationName,
+    ]);
+    await verifyFolder(folder);
+    const source = decodedFile({
+        bytes: captured.find((file) => file.name === name)?.bytes,
+        code: "unsupported-source",
+    }, codes);
+    const declaration = decodedFile({
+        bytes: captured.find((file) => file.name === declarationName)?.bytes,
+        code: "invalid-declaration",
+    }, codes);
+    return {
+        source,
+        declaration,
+        codes: [
+            ...new Set(codes.includes("unsafe-workflow-path")
+                ? codes.filter((code) => code !== "workflow-read-failed")
+                : codes),
+        ].sort(),
+    };
+}
+export function workflowCaptureFailure(error) {
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
+    if (code === "ELOOP")
+        return "unsafe-workflow-path";
+    const message = error instanceof Error ? error.message : "";
+    if (message === "unsafe-workflow-path" ||
+        message === "workflow-source-changed" ||
+        message === "unsupported-source" ||
+        message === "invalid-declaration")
+        return message;
+    return "workflow-read-failed";
+}
+async function descriptorEntries(folder) {
+    const handle = await openSource(folder, ".").catch(changedPathError);
+    try {
+        const expected = folder.components.at(-1)?.stats;
+        if (!expected ||
+            !sameIdentity(expected, await handle.stat({ bigint: true })))
+            throw new Error("workflow-source-changed");
+        return await readdir(`/proc/self/fd/${String(handle.fd)}`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function workflowFolderEntries(folder) {
+    const entries = process.platform === "darwin"
+        ? await readdir(`/.nofollow${folder.path}`).catch(changedPathError)
+        : await descriptorEntries(folder);
+    await verifyFolder(folder);
+    return entries;
+}

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

@@ -1,4 +1,9 @@
 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;
@@ -6,5 +11,5 @@ interface AnalysisInput {
         readonly importId: string;
     };
 }
-export declare function analyzeChats(input: AnalysisInput): Promise<CycleOutcome>;
+export declare function analyzeChats(input: AnalysisInput, decision?: Decision): Promise<CycleOutcome>;
 export {};

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

@@ -1,7 +1,20 @@
 {
   "workflowId": "analyze-chats",
-  "effectLimit": 3,
+  "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" } }