cloving 1.2.0 → 1.3.0

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,17 +104,60 @@ 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 = [];
@@ -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/dist/workflows/develop-ticket.js

@@ -190,7 +190,7 @@ export async function developTicket(input, decision) {
     });
     if (turn.kind !== "completed")
         return blocked(cycleId, {
-            reason: `The Claude turn has the result ${turn.kind}.`,
+            reason: `The worker turn has the result ${turn.kind}.`,
             evidenceId: "claude-turn",
         });
     const gate = await decisionGate({

package/dist/workflows/ticket-prompts.js

@@ -38,8 +38,12 @@ function denial(round) {
 }
 export function review(input, turnResult) {
     const turn = fields(turnResult.result);
+    const harness = turn["harness"];
+    const worker = typeof harness === "string" && harness !== ""
+        ? `the ${harness} worker`
+        : "the worker";
     return [
-        `Review the work of the Claude worker for ${named(input)}.`,
+        `Review the work of ${worker} for ${named(input)}.`,
         `Round: ${String(turnResult.round)} of ${String(lastRound)}`,
         `Branch: ${part(turn, "branch")}`,
         `Work tree: ${part(turn, "worktree")}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloving",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local durable development workflow service",
   "license": "MIT",
   "repository": {
@@ -35,15 +35,56 @@
       "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/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"
     }
   },
   "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 +100,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": [
@@ -73,12 +114,13 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json && node tools/copy-workflow-declarations.ts workflows dist/workflows",
     "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,7 +148,7 @@
     "@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"
   }

package/templates/develop/README.md

@@ -0,0 +1,78 @@
+# 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.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" },
+  });
+}