cloving 1.2.0 → 1.4.0

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

@@ -1,6 +1,8 @@
 import { constants } from "node:fs";
 import { lstat, open, readdir, realpath, } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
+import ts from "typescript";
+import { workflowHelperPath } from "../src/workflow-candidate.js";
 function contained(root, path) {
     const suffix = relative(root, path);
     return (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`));
@@ -92,6 +94,19 @@ async function openSource(folder, name) {
     }
 }
 async function inspectFile(folder, name) {
+    const parts = name.split("/");
+    const fileName = parts.pop();
+    if (!fileName || parts.some((part) => !safeComponent(part)))
+        throw new Error("unsafe-workflow-path");
+    let parent = folder;
+    for (const part of parts) {
+        const path = join(parent.path, part);
+        const stats = await lstat(path, { bigint: true });
+        if (!stats.isDirectory())
+            throw new Error("unsafe-workflow-path");
+        parent = { path, components: [...parent.components, { path, stats }] };
+    }
+    await verifyFolder(parent);
     const path = join(folder.path, name);
     const stats = await lstat(path, { bigint: true });
     if (!stats.isFile())
@@ -101,11 +116,12 @@ async function inspectFile(folder, name) {
         throw new Error("workflow-source-changed");
     if (!contained(folder.path, resolved))
         throw new Error("unsafe-workflow-path");
-    return { path, name, stats };
+    return { path, name, stats, folder: parent, fileName };
 }
 async function captureFile(folder, file) {
     const { stats } = file;
-    const handle = await openSource(folder, file.name).catch(changedPathError);
+    await verifyFolder(folder);
+    const handle = await openSource(file.folder, file.fileName).catch(changedPathError);
     try {
         if (!sameSnapshot(stats, await handle.stat({ bigint: true })))
             throw new Error("workflow-source-changed");
@@ -140,11 +156,38 @@ async function captureFiles(folder, names) {
         }
     }
     for (const file of captured) {
+        await verifyFolder(file.folder);
         if (!sameSnapshot(file.stats, await capturedStats(file.path)))
             throw new Error("workflow-source-changed");
     }
     return { captured, codes };
 }
+async function captureImports(folder, snapshot) {
+    const { captured, codes } = snapshot;
+    const helpers = {};
+    for (const source of captured) {
+        if (!source.name.endsWith(".ts"))
+            continue;
+        for (const imported of ts.preProcessFile(source.bytes.toString("utf8"))
+            .importedFiles) {
+            const name = workflowHelperPath(source.name, imported.fileName);
+            if (!name || captured.some((file) => file.name === name))
+                continue;
+            const result = await captureFiles(folder, [name]);
+            codes.push(...result.codes);
+            captured.push(...result.captured);
+            const text = decodedFile({ bytes: result.captured[0]?.bytes, code: "unsupported-source" }, codes);
+            if (text !== undefined)
+                helpers[name] = text;
+        }
+    }
+    for (const file of captured) {
+        await verifyFolder(file.folder);
+        if (!sameSnapshot(file.stats, await capturedStats(file.path)))
+            throw new Error("workflow-source-changed");
+    }
+    return helpers;
+}
 function decodedFile(input, codes) {
     if (input.bytes === undefined)
         return undefined;
@@ -163,6 +206,7 @@ export async function captureWorkflowCandidate(folder, name) {
         name,
         declarationName,
     ]);
+    const helpers = await captureImports(folder, { captured, codes });
     await verifyFolder(folder);
     const source = decodedFile({
         bytes: captured.find((file) => file.name === name)?.bytes,
@@ -175,6 +219,7 @@ export async function captureWorkflowCandidate(folder, name) {
     return {
         source,
         declaration,
+        helpers,
         codes: [
             ...new Set(codes.includes("unsafe-workflow-path")
                 ? codes.filter((code) => code !== "workflow-read-failed")

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

@@ -1,12 +1,13 @@
-import type { WorkflowCandidateCode } from "../src/workflow-candidate.ts";
-import { type WorkflowConflictCode, type WorkflowReservation } from "../src/workflow-discovery.ts";
+import type { WorkflowDeclaration } from "../src/workflow-declaration.ts";
+import { type CandidateDeclaration, type WorkflowCandidateCode } from "../src/workflow-candidate.ts";
+import { type WorkflowConflictCode } 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[];
+    readonly userFolder?: string | undefined;
 }
 interface WorkflowLabel {
     readonly scope: "project" | "user";
@@ -16,6 +17,7 @@ interface WorkflowSnapshot extends WorkflowLabel {
     readonly baseName: string;
     readonly source: string;
     readonly declaration: string;
+    readonly helpers: Readonly<Record<string, string>>;
 }
 export interface WorkflowFolderCandidate extends WorkflowSnapshot {
     readonly repository: string;
@@ -24,10 +26,23 @@ export interface WorkflowFolderCandidate extends WorkflowSnapshot {
 export interface WorkflowFolderRefusal extends WorkflowLabel {
     readonly codes: readonly (WorkflowCandidateCode | WorkflowCaptureCode | WorkflowConflictCode | "compile-failed")[];
 }
+export interface WorkflowListing {
+    readonly scope: "project" | "user";
+    readonly workflowId: string | null;
+    readonly file: string;
+    readonly admitted: boolean;
+    readonly codes: readonly string[];
+    readonly declaration?: CandidateDeclaration | WorkflowDeclaration;
+}
 export interface WorkflowFolderResult {
+    readonly workflows: readonly WorkflowListing[];
     readonly repository: string;
     readonly candidates: readonly WorkflowFolderCandidate[];
     readonly refusals: readonly WorkflowFolderRefusal[];
 }
+export declare function userLocation(input: Pick<WorkflowFolderInput, "home" | "xdgConfigHome" | "userFolder">): {
+    readonly root: string;
+    readonly parts: readonly string[];
+};
 export declare function loadWorkflowFolders(input: WorkflowFolderInput, installed?: CandidatePackageOptions): Promise<WorkflowFolderResult>;
 export {};

package/dist/tools/workflow-folders.js

@@ -1,7 +1,9 @@
+import { absoluteWorkflowFolder } from "../src/project-settings.js";
 import { createHash } from "node:crypto";
 import { realpath } from "node:fs/promises";
-import { isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import ts from "typescript";
+import { isCandidateDeclaration, } from "../src/workflow-candidate.js";
 import { record } from "../src/protocol.js";
 import { workflowConflicts, } from "../src/workflow-discovery.js";
 import { admitWorkflowCandidate } from "./admit-workflow.js";
@@ -22,8 +24,11 @@ function parsedDeclaration(text) {
 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"];
+    const parsed = parsedDeclaration(snapshot.declaration ?? "");
+    const declaration = record(record(parsed)?.["workflow"]);
+    const workflowId = declaration?.["workflowId"];
     return {
+        queue: isCandidateDeclaration(parsed) && parsed.workflow.queue === true,
         baseName: snapshot.baseName,
         workflowId: typeof workflowId === "string" ? workflowId : undefined,
         functionNames: source.statements
@@ -55,7 +60,9 @@ async function scanFolder(location, refusals) {
     }
     const snapshots = [];
     for (const name of entries
-        .filter((name) => name.endsWith(".ts") && !name.endsWith(".d.ts"))
+        .filter((name) => name.endsWith(".ts") &&
+        !name.endsWith(".d.ts") &&
+        !name.endsWith(".test.ts"))
         .sort()) {
         snapshots.push(await captureEntry(folder, {
             scope: location.scope,
@@ -83,6 +90,7 @@ async function captureEntry(folder, file) {
                 ...label,
                 source: capture.source,
                 declaration: capture.declaration,
+                helpers: capture.helpers,
             },
         };
     }
@@ -96,22 +104,65 @@ async function captureEntry(folder, file) {
         };
     }
 }
-async function scanFolders(input, refusals) {
-    const repository = await realpath(input.repository);
+export function userLocation(input) {
+    const folder = absoluteWorkflowFolder(input.userFolder);
+    if (folder !== undefined)
+        return { root: dirname(folder), parts: [basename(folder)] };
     const configuration = input.xdgConfigHome && isAbsolute(input.xdgConfigHome)
         ? input.xdgConfigHome
         : join(input.home, ".config");
+    return { root: configuration, parts: ["cloving", "workflows"] };
+}
+async function scanFolders(input, refusals) {
+    const repository = await realpath(input.repository);
     const snapshots = [
         ...(await scanFolder({ scope: "project", root: repository, parts: [".cloving", "workflows"] }, refusals)),
-        ...(await scanFolder({ scope: "user", root: configuration, parts: ["cloving", "workflows"] }, refusals)),
+        ...(await scanFolder({ scope: "user", ...userLocation(input) }, refusals)),
     ];
     return { repository, snapshots };
 }
+function workflowFolder(input, scope) {
+    if (scope === "project")
+        return join(input.repository, ".cloving", "workflows");
+    const { root, parts } = userLocation(input);
+    return join(root, ...parts);
+}
+function folderListings(input, found) {
+    const { repository, snapshots, refusals } = found;
+    const workflows = snapshots.map((entry) => {
+        const snapshot = entry.kind === "captured" ? entry.snapshot : entry;
+        const declaration = parsedDeclaration(snapshot.declaration ?? "");
+        const refusal = refusals.find((item) => item.scope === snapshot.scope && item.label === snapshot.label);
+        const folder = workflowFolder({ ...input, repository }, snapshot.scope);
+        return {
+            scope: snapshot.scope,
+            workflowId: isCandidateDeclaration(declaration)
+                ? declaration.workflow.workflowId
+                : null,
+            file: join(folder, snapshot.baseName + ".ts"),
+            admitted: refusal === undefined,
+            codes: refusal?.codes ?? [],
+            ...(isCandidateDeclaration(declaration) ? { declaration } : {}),
+        };
+    });
+    return [
+        ...workflows,
+        ...refusals
+            .filter((refusal) => refusal.label === "workflows/")
+            .map((refusal) => ({
+            scope: refusal.scope,
+            workflowId: null,
+            file: workflowFolder({ ...input, repository }, refusal.scope),
+            admitted: false,
+            codes: refusal.codes,
+        })),
+    ];
+}
 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);
+    const conflicts = workflowConflicts(snapshots.map(identity));
     for (const [index, entry] of snapshots.entries()) {
         const label = entry.kind === "captured" ? entry.snapshot : entry;
         const codes = [
@@ -128,6 +179,7 @@ export async function loadWorkflowFolders(input, installed = {}) {
         const result = await admitWorkflowCandidate({
             source: snapshot.source,
             declaration: parsedDeclaration(snapshot.declaration),
+            helpers: snapshot.helpers,
         }, installed);
         if (result.kind === "refused")
             refusals.push({
@@ -143,6 +195,7 @@ export async function loadWorkflowFolders(input, installed = {}) {
             });
     }
     return {
+        workflows: folderListings(input, { repository, snapshots, refusals }),
         repository,
         candidates: candidates.sort(compareLabels),
         refusals: refusals.sort(compareLabels),

package/dist/tools/workflow-test-hook.d.ts

@@ -0,0 +1,7 @@
+export declare function workflowTestHook(input: {
+    readonly root: string;
+    readonly extension: string;
+    readonly exports: Readonly<Record<string, {
+        readonly import: string;
+    }>>;
+}): string;

package/dist/tools/workflow-test-hook.js

@@ -0,0 +1,16 @@
+export function workflowTestHook(input) {
+    const modules = Object.fromEntries(Object.entries(input.exports).map(([subpath, target]) => {
+        const path = target.import
+            .replace("./dist/", "./")
+            .replace(/\.js$/, input.extension);
+        return ["cloving" + subpath.slice(1), new URL(path, input.root).href];
+    }));
+    const hook = `import { registerHooks } from "node:module";
+const modules = ${JSON.stringify(modules)};
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    return nextResolve(modules[specifier] ?? specifier, context);
+  },
+});`;
+    return "data:text/javascript," + encodeURIComponent(hook);
+}

package/dist/tools/workflow-test-loader.d.ts

@@ -0,0 +1 @@
+export declare function workflowTestLoader(): string;

package/dist/tools/workflow-test-loader.js

@@ -0,0 +1,10 @@
+import { extname } from "node:path";
+import packageMetadata from "#package" with { type: "json" };
+import { workflowTestHook } from "./workflow-test-hook.js";
+export function workflowTestLoader() {
+    return workflowTestHook({
+        root: new URL("../", import.meta.url).href,
+        extension: extname(import.meta.filename),
+        exports: packageMetadata.exports,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloving",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Local durable development workflow service",
   "license": "MIT",
   "repository": {
@@ -31,19 +31,67 @@
       "types": "./dist/src/steps/protected-effect.d.ts",
       "import": "./dist/src/steps/protected-effect.js"
     },
-    "./workflows/steps/decision-gate": {
-      "types": "./dist/src/steps/decision-gate.d.ts",
-      "import": "./dist/src/steps/decision-gate.js"
+    "./workflows/steps/review-subject": {
+      "types": "./dist/src/steps/review-subject.d.ts",
+      "import": "./dist/src/steps/review-subject.js"
+    },
+    "./workflows/steps/review-by-person": {
+      "types": "./dist/src/steps/review-by-person.d.ts",
+      "import": "./dist/src/steps/review-by-person.js"
+    },
+    "./workflows/steps/review-by-agent": {
+      "types": "./dist/src/steps/review-by-agent.d.ts",
+      "import": "./dist/src/steps/review-by-agent.js"
+    },
+    "./workflows/steps/merge-by-person": {
+      "types": "./dist/src/steps/merge-by-person.d.ts",
+      "import": "./dist/src/steps/merge-by-person.js"
+    },
+    "./workflows/steps/merge-when-green": {
+      "types": "./dist/src/steps/merge-when-green.d.ts",
+      "import": "./dist/src/steps/merge-when-green.js"
+    },
+    "./workflows/steps/open-decision-wait": {
+      "types": "./dist/src/steps/open-decision-wait.d.ts",
+      "import": "./dist/src/steps/open-decision-wait.js"
+    },
+    "./workflows/steps/wait-for-decision": {
+      "types": "./dist/src/steps/wait-for-decision.d.ts",
+      "import": "./dist/src/steps/wait-for-decision.js"
     },
     "./workflows/steps/handoff": {
       "types": "./dist/src/steps/handoff.d.ts",
       "import": "./dist/src/steps/handoff.js"
+    },
+    "./workflows/steps/wait-for-run": {
+      "types": "./dist/src/steps/wait-for-run.d.ts",
+      "import": "./dist/src/steps/wait-for-run.js"
+    },
+    "./workflows/steps/run-command": {
+      "types": "./dist/src/steps/run-command.d.ts",
+      "import": "./dist/src/steps/run-command.js"
+    },
+    "./workflows/testing": {
+      "types": "./dist/src/testing.d.ts",
+      "import": "./dist/src/testing.js"
+    },
+    "./workflows/steps/sleep": {
+      "types": "./dist/src/steps/sleep.d.ts",
+      "import": "./dist/src/steps/sleep.js"
+    },
+    "./workflows/steps/wait-for-command": {
+      "types": "./dist/src/steps/wait-for-command.d.ts",
+      "import": "./dist/src/steps/wait-for-command.js"
+    },
+    "./workflows/steps/command-wait": {
+      "types": "./dist/src/steps/command-wait.d.ts",
+      "import": "./dist/src/steps/command-wait.js"
     }
   },
   "files": [
     "dist/src",
     "dist/tools",
-    "dist/workflows",
+    "templates",
     "assets/watch-fonts/fira-code-latin-400-normal.woff2",
     "assets/watch-fonts/fira-code-latin-500-normal.woff2",
     "assets/watch-fonts/fira-code-OFL.md",
@@ -59,7 +107,7 @@
     "assets/watch-fonts/manifest.json"
   ],
   "engines": {
-    "node": ">=26.9.0 <27",
+    "node": ">=24.22.1 <25 || >=26.9.0 <27",
     "npm": ">=11.19.1 <12"
   },
   "os": [
@@ -71,14 +119,15 @@
     "x64"
   ],
   "scripts": {
-    "build": "tsc --project tsconfig.build.json && node tools/copy-workflow-declarations.ts workflows dist/workflows",
+    "build": "tsc --project tsconfig.build.json",
     "build:workflows": "node tools/compile-workflows.ts",
-    "check:setup": "tsc --project tsconfig.json --noEmit",
+    "check:setup": "node tools/check-shells.ts && tsc --project tsconfig.json --noEmit",
     "check:quality": "node tools/check-quality.ts",
     "check:clean": "node tools/check-clean.ts",
     "check:lint": "eslint src tools quality test eslint.config.mjs --max-warnings 0",
     "check:format": "prettier --check src tools quality test eslint.config.mjs package.json tsconfig.json tsconfig.build.json",
     "test:quality": "node --test test/quality/*.test.ts",
+    "record:test-durations": "node tools/record-test-durations.ts",
     "test:scale": "node --test --test-concurrency=1 test/authority-opening-scale.benchmark.ts",
     "check": "node tools/quality-pending.ts",
     "test:concurrency": "node tools/quality-pending.ts"
@@ -106,8 +155,9 @@
     "@workflow/builders": "5.0.2",
     "entities": "8.1.0",
     "preact": "11.0.0",
-    "solid-objects": "0.17.8",
+    "solid-objects": "1.0.2",
     "typescript": "6.0.3",
-    "workflow": "5.1.0"
+    "workflow": "5.1.0",
+    "yaml": "2.9.1"
   }
 }

package/templates/develop/README.md

@@ -0,0 +1,90 @@
+# Develop template decisions
+
+`template.json` describes the five decisions used by the develop template.
+The default workflow in `develop.ts` accepts the declared ticket input, selects
+from the queue, opens a pull request, waits for Greptile at 5/5, and calls
+`mergeWhenGreen` with `check: "beforeMerge"`. Its declaration and helper files
+pass folder admission, including compilation with the Workflow SDK in a packed
+installation. Copy this directory's contents into a workflow folder.
+
+The host supplies `{ cycleId, repository, input: { ticket: { id, text } } }`.
+`develop/report.ts` extracts the resolved text and preserves the worker's ticket
+status. `develop/round.ts` composes development, review and merge. A failed
+review or repairable merge result gives its full output and remaining work to
+the next worker turn. Review, local-check, conflict and CI fixes share a limit
+of three fix rounds. Pending CI and an unconfigured check stop the run.
+
+`develop/pull.ts` keeps the first line of the ticket as the pull request title,
+removes leading `#` characters and limits it to 200 characters. For a task with
+a GitHub issue, the pull request body links that issue and names its number:
+
+```text
+Refs cloving-ai/cloving-ai#375
+
+Cloving made this change for the ticket 375.
+```
+
+A task without a GitHub issue uses only `Cloving made this change for this task.`
+
+`develop.test.ts` and `develop/flow-tests.ts` test the default composition through the public fake
+step bridge. The alternative configurations use `develop/option-tests.ts`, with the selected
+point IDs in `develop/scenarios.ts`. For an edited copy, replace the default
+`flowTests` and `refusalTests` imports in `develop.test.ts` with
+`optionTests as flowTests`, then run every `flowTests` scenario. Keep the shared
+turn and partial-helper tests. Package tests apply each source edit, validate
+its requirements, and test seven complete configurations through the folder
+loader and the installed package, covering every option.
+
+`develop/turn.ts` implements the development turn for either a resolved
+`ticket` or a task `prompt`. It calls the public protected effect helper and
+returns the broker result unchanged. Its `feedback` takes the previous
+result's `reason`, full `output`, and `remaining` items. Rounds 1 through 4
+allow the initial turn and three fix turns; the workflow must stop after that.
+`develop.test.ts` exercises this helper with `cloving/workflows/testing`.
+The package tests also load small compositions of this helper through folder
+admission for both input forms and test both forms in complete workflows.
+
+`develop/partial.ts` implements the person's partial-work question.
+`develop/partial-choice.ts` connects its answer to a development report and the
+next round, or returns a blocked outcome without opening a review or merging. `reviewPartial`
+opens a question with an identity scoped to the run and round. It returns
+nonempty feedback from an explicit answer, or stops. It opens no question
+after the initial turn and three fix turns. The separate `develop/queue-partial.ts`
+helper, `queuePartial`, forwards the issue,
+merged pull request and remaining items to the protected `partial-issue`
+operation, preserving its result. The GitHub worker owns partial-run history
+and requeues the first two runs, then blocks the ticket from the third.
+Folder-admission tests cover both helpers in the checkout and packed install.
+The default workflow calls `queuePartial` after merging partial work, closes
+complete issues, and reports a failed issue update in its outcome.
+The person-only composition needs no GitHub capability. `develop/local.ts`
+implements its round: develop, ask about partial work, review the immutable
+commit, and leave the branch for the person to merge. It refuses missing or
+malformed commit IDs and reports of uncommitted work. `develop/accept.ts`
+contains the editable pull-request acceptance call. `promptInput` in
+`develop/report.ts` adapts task text without looking up a ticket.
+Only resolved ticket input supplies an issue identity for lifecycle updates.
+Task text keeps its full contents, including any issue-looking lines, without
+selecting an issue to label, close or return to the queue.
+
+The first option of each point is the default: ticket input, queue selection,
+Greptile at 5/5, merge after checks, and return partial work to the queue.
+Selecting `person` at selection, acceptance and partial work, with `local` at
+merge, describes the existing reviewed local-branch process.
+
+Each option has an `id`, `label`, `summary`, `change`, `requires` and `needs`.
+`change` describes the step call or declaration edit for the setup agent.
+It is guidance for editing source, rather than an executable patch.
+
+`requires` maps another point ID to its allowed option IDs. All named points
+must satisfy their requirement; any listed option for one point satisfies that
+point. For example, `"merge": ["person", "green"]` requires either pull-request
+merge option. An empty object imposes no additional requirement. Select exactly
+one known option at each point and validate the complete selection after edits.
+
+`needs` lists `cloving doctor` codes required by that option. The configured
+workflow also needs the common runtime and harness checks reported by doctor.
+
+Changing metadata does not change runtime behavior. The setup agent must apply
+the source and declaration edits, run the workflow's scenario tests, and load
+the edited configuration through folder admission before using it.

package/templates/develop/develop/accept.ts

@@ -0,0 +1,11 @@
+import type { ReviewSubject, ReviewResult } from "cloving/workflows";
+import { reviewByAgent } from "cloving/workflows/steps/review-by-agent";
+
+export async function acceptWork(
+  subject: ReviewSubject,
+): Promise<ReviewResult> {
+  return await reviewByAgent({
+    subject: subject,
+    reviewer: { kind: "greptile" },
+  });
+}