cloving 1.2.0 → 1.3.0

package/dist/src/workflows.d.ts

@@ -1,7 +1,17 @@
 export { loadCycle, type CycleLoad } from "./steps/load-cycle.ts";
 export { protectedEffect } from "./steps/protected-effect.ts";
 export { decisionGate } from "./steps/decision-gate.ts";
+export { waitForDecision } from "./steps/wait-for-decision.ts";
+export { reviewByPerson } from "./steps/review-by-person.ts";
+export { reviewByAgent } from "./steps/review-by-agent.ts";
+export { mergeByPerson } from "./steps/merge-by-person.ts";
+export { mergeWhenGreen } from "./steps/merge-when-green.ts";
+export type { ReviewSubject, CommitReviewSubject, DraftReviewSubject, ReviewResult, Reviewer, } from "./review-subject.ts";
+export type { MergeCheckName, MergeReason, MergeRequest, MergeResult, PullRequest, } from "./merge-request.ts";
 export { handoff } from "./steps/handoff.ts";
-export type { GateRequest, GateResult, HandoffRequest, HandoffValue, ProtectedRequest, ProtectedResult, ProtectedScope, } from "./step-bridge.ts";
+export { waitForRun } from "./steps/wait-for-run.ts";
+export { runCommand } from "./steps/run-command.ts";
+export { sleep } from "./steps/sleep.ts";
+export type { CommandRequest, GateRequest, GateResult, DecisionResult, HandoffRequest, HandoffValue, RunWaitRequest, RunWaitOutcome, 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

@@ -1,5 +1,13 @@
 export { loadCycle } from "./steps/load-cycle.js";
 export { protectedEffect } from "./steps/protected-effect.js";
 export { decisionGate } from "./steps/decision-gate.js";
+export { waitForDecision } from "./steps/wait-for-decision.js";
+export { reviewByPerson } from "./steps/review-by-person.js";
+export { reviewByAgent } from "./steps/review-by-agent.js";
+export { mergeByPerson } from "./steps/merge-by-person.js";
+export { mergeWhenGreen } from "./steps/merge-when-green.js";
 export { handoff } from "./steps/handoff.js";
+export { waitForRun } from "./steps/wait-for-run.js";
+export { runCommand } from "./steps/run-command.js";
+export { sleep } from "./steps/sleep.js";
 export { ticketStatus } from "./ticket-status.js";

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

@@ -10,4 +10,5 @@ export type WorkflowCandidateAdmission = {
 export declare function admitWorkflowCandidate(input: {
     readonly source: string;
     readonly declaration: unknown;
+    readonly helpers?: Readonly<Record<string, string>>;
 }, installed?: CandidatePackageOptions): Promise<WorkflowCandidateAdmission>;

package/dist/tools/admit-workflow.js

@@ -5,30 +5,34 @@ import { tmpdir } from "node:os";
 import { findPackageJSON } from "node:module";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkWorkflowCandidate, } from "../src/workflow-candidate.js";
+import { checkWorkflowCandidate, candidateDeclarationRefusals, workflowHelperPath, } from "../src/workflow-candidate.js";
 import { candidatePackageRoot, } from "./workflow-candidate-program.js";
 import { analyzeWorkflowCandidate } from "./workflow-candidate-source.js";
 import { isWorkflowManifest } from "./workflow-manifest.js";
 export async function admitWorkflowCandidate(input, installed = {}) {
     const { source, declaration } = input;
+    const refusal = candidateDeclarationRefusals(declaration);
+    if (refusal.length > 0)
+        return { kind: "refused", codes: refusal };
     if (Buffer.from(source, "utf8").toString("utf8") !== source)
         return { kind: "refused", codes: ["unsupported-source"] };
     try {
         const packageRoot = resolve(installed.packageRoot ?? candidatePackageRoot);
-        const facts = analyzeWorkflowCandidate(source, { packageRoot });
+        const helpers = input.helpers ?? {};
+        const facts = analyzeWorkflowCandidate(source, { packageRoot, helpers });
         const codes = checkWorkflowCandidate({ declaration, ...facts });
         if (codes.length > 0)
             return { kind: "refused", codes };
-        return await compiledCandidate(source, packageRoot);
+        return await compiledCandidate({ source, helpers, packageRoot });
     }
     catch {
         return { kind: "refused", codes: ["compile-failed"] };
     }
 }
-async function compiledCandidate(source, packageRoot) {
+async function compiledCandidate(input) {
     const directory = await realpath(await mkdtemp(join(tmpdir(), "cloving-candidate-")));
     try {
-        await prepareCandidateProject(directory, { source, packageRoot });
+        await prepareCandidateProject(directory, input);
         if (!(await compile(directory)))
             return { kind: "refused", codes: ["compile-failed"] };
         const artifactDirectory = join(directory, "artifacts");
@@ -37,6 +41,8 @@ async function compiledCandidate(source, packageRoot) {
             Object.values(manifest.workflows ?? {}).flatMap((entries) => Object.values(entries)).length !== 1)
             return { kind: "refused", codes: ["compile-failed"] };
         const digest = createHash("sha256");
+        for (const [name, content] of Object.entries(input.helpers).sort(([left], [right]) => (left < right ? -1 : Number(left > right))))
+            digest.update(JSON.stringify([name, content]));
         for (const name of [
             "manifest.json",
             "flow.mjs",
@@ -73,6 +79,13 @@ async function prepareCandidateProject(directory, input) {
         include: ["workflows/candidate.ts"],
     }));
     await writeFile(join(directory, "workflows/candidate.ts"), source, "utf8");
+    for (const [name, content] of Object.entries(input.helpers)) {
+        if (workflowHelperPath("candidate.ts", `./${name}`) !== name)
+            throw new Error("invalid-workflow-helper");
+        const path = join(directory, "workflows", name);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }
 }
 function compile(directory) {
     const extension = extname(fileURLToPath(import.meta.url));

package/dist/tools/doctor-adoption.d.ts

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

package/dist/tools/doctor-adoption.js

@@ -0,0 +1,11 @@
+import { selectRuntimeDirectory } from "./self-host-runtime.js";
+const [runtime, repository, legacyRuntime, adoptionRecord] = process.argv.slice(2);
+if (runtime === undefined || repository === undefined)
+    process.exitCode = 1;
+else
+    process.stdout.write(JSON.stringify(await selectRuntimeDirectory({
+        runtime,
+        repository,
+        legacyRuntime,
+        adoptionRecord,
+    })) + "\n");

package/dist/tools/project-configuration.d.ts

@@ -0,0 +1,4 @@
+import { resolveSettings } from "../src/project-settings.ts";
+export declare function topLevel(given: string): string;
+export declare function projectRoot(given: string): Promise<string>;
+export declare function projectConfiguration(repository: string, environment: Readonly<NodeJS.ProcessEnv>): Promise<ReturnType<typeof resolveSettings>>;

package/dist/tools/project-configuration.js

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { configurationRoot, resolveSettings } from "../src/project-settings.js";
+import { repositoryFileName } from "../src/repository-identity.js";
+async function settingsFile(file) {
+    try {
+        return await readFile(file.path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new Error(`unreadable-config-file: ${file.scope}`, { cause: error });
+    }
+}
+export function topLevel(given) {
+    try {
+        return execFileSync("git", ["-C", given, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return given;
+    }
+}
+export function projectRoot(given) {
+    return realpath(topLevel(resolve(given)));
+}
+export async function projectConfiguration(repository, environment) {
+    const projectName = repositoryFileName({
+        name: basename(repository),
+        sha256: createHash("sha256").update(repository).digest("hex"),
+    });
+    return resolveSettings(environment, {
+        project: await settingsFile({
+            path: join(repository, ".cloving/config.json"),
+            scope: "project",
+        }),
+        private: await settingsFile({
+            path: join(configurationRoot(environment, homedir()), "cloving/projects", `${projectName}.json`),
+            scope: "private",
+        }),
+    });
+}

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

@@ -5,6 +5,7 @@ export interface HostProcesses {
     readonly directory: string;
     readonly repository: string;
     readonly watchPort: string;
+    readonly phoneRelay: string;
     readonly updateMilliseconds: number | undefined;
 }
 export declare function hostedPrograms(settings: HostProcesses): Promise<number>;

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

@@ -1,5 +1,6 @@
 import { execFile, spawn } from "node:child_process";
 import { addAbortListener } from "node:events";
+import { rm } from "node:fs/promises";
 import { extname, join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
@@ -21,7 +22,8 @@ function launched(argumentsList, settings) {
 }
 async function stopped(programs) {
     for (const program of programs)
-        program.child.kill("SIGTERM");
+        if (!program.child.killed)
+            program.child.kill("SIGTERM");
     await Promise.all(programs.map((program) => program.ended));
 }
 function updatingGit(settings, stopping) {
@@ -51,8 +53,10 @@ function updatingGit(settings, stopping) {
     };
 }
 async function polled(settings, lifecycle) {
-    if (settings.updateMilliseconds === undefined)
+    if (settings.updateMilliseconds === undefined) {
+        await rm(join(settings.directory, "pending-self-update"), { force: true });
         return;
+    }
     const cancelled = () => lifecycle.stopping.aborted;
     const updater = selfUpdater({
         directory: settings.directory,
@@ -87,33 +91,40 @@ async function polled(settings, lifecycle) {
     }
     return undefined;
 }
+function productChild(settings, argumentsList) {
+    const [program, ...rest] = argumentsList;
+    return launched([
+        join(settings.product, `src/${program}${extname(import.meta.filename)}`),
+        ...rest,
+    ], {
+        directory: settings.product,
+        environment: {
+            ...process.env,
+            CLOVING_RUNTIME_DIR: settings.runtime,
+            CLOVING_WATCH_REPOSITORY: settings.repository,
+        },
+    });
+}
 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,
-            },
-        }),
-    ];
+    const watch = settings.watchPort === "off"
+        ? []
+        : [
+            productChild(settings, [
+                "cli",
+                "watch",
+                "--port",
+                settings.watchPort,
+            ]),
+        ];
+    const relay = settings.phoneRelay === "off" ? [] : [productChild(settings, ["relay"])];
+    return { daemon, programs: [daemon, ...watch, ...relay] };
 }
 export async function hostedPrograms(settings) {
-    const programs = hostedChildren(settings);
-    const daemon = programs[0];
+    const { daemon, programs } = hostedChildren(settings);
     const stopping = new AbortController();
     let updating = false;
     const interrupt = () => {

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

@@ -1,14 +1,18 @@
 import { type DeclaredWorkflow } from "../src/workflow-declaration.ts";
 import type { WorkflowRefusal } from "../src/workflow-refusals.ts";
+import { type WorkflowListing } from "./workflow-folders.ts";
 interface ProjectSettings {
     readonly product: string;
     readonly project: string;
     readonly repository: string;
     readonly home: string;
     readonly xdgConfigHome?: string | undefined;
+    readonly userFolder?: string | undefined;
 }
 export interface RegisteredWorkflows {
+    readonly workflows: readonly WorkflowListing[];
     readonly repository: string;
+    readonly bundleDigest: string;
     readonly manifests: Readonly<Record<string, string>>;
     readonly declarations: readonly DeclaredWorkflow[];
     readonly workflowRefusals: readonly WorkflowRefusal[];

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

@@ -22,8 +22,13 @@ async function initializeProject(settings) {
         await copyWorkflow(settings, file);
     const modules = join(project, "node_modules");
     await mkdir(join(modules, "cloving"), { recursive: true });
-    for (const name of Object.keys(packageMetadata.dependencies)) {
-        const location = findPackageJSON(name, join(product, "package.json"));
+    const dependencies = new Map(Object.keys(packageMetadata.dependencies).map((name) => [name, join(product, "package.json")]));
+    const sdk = findPackageJSON("workflow", join(product, "package.json"));
+    if (sdk === undefined)
+        throw new Error("missing-runtime-dependency: workflow");
+    dependencies.set("@workflow/core", sdk);
+    for (const [name, from] of dependencies) {
+        const location = findPackageJSON(name, from);
         if (location === undefined)
             throw new Error(`missing-runtime-dependency: ${name}`);
         await mkdir(dirname(join(modules, name)), { recursive: true });
@@ -95,11 +100,21 @@ async function stageCandidates(project, candidates) {
             candidate.baseName,
             candidate.source,
             candidate.declaration,
+            Object.entries(candidate.helpers).sort(([left], [right]) => left < right ? -1 : Number(left > right)),
         ]))
             .digest("hex");
-        const file = join(directory, `${name}.ts`);
+        const root = Object.keys(candidate.helpers).length > 0
+            ? join(directory, name)
+            : directory;
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const file = join(root, `${name}.ts`);
         await writeFile(file, candidate.source);
-        await writeFile(join(directory, `${name}.declaration.json`), candidate.declaration);
+        await writeFile(join(root, `${name}.declaration.json`), candidate.declaration);
+        for (const [path, source] of Object.entries(candidate.helpers)) {
+            const destination = join(root, path);
+            await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+            await writeFile(destination, source);
+        }
         staged.push({ candidate, file });
     }
     return staged;
@@ -132,6 +147,37 @@ async function copyWorkflow(settings, file) {
     if (declaration !== undefined)
         await writeFile(join(project, "workflows", sidecar), declaration);
 }
+function bundledListings(input) {
+    const { product, files, manifests, declarations } = input;
+    const byFunction = new Map(declarations.map(({ functionName, ...declaration }) => [
+        functionName,
+        declaration,
+    ]));
+    return Object.entries(manifests).map(([functionName, manifest]) => {
+        const declaration = byFunction.get(functionName);
+        const file = files.find((file) => basename(file, extname(file)) === manifest.name);
+        return {
+            scope: "bundled",
+            workflowId: declaration?.workflowId ?? manifest.name,
+            file: join(product, "workflows", file ?? manifest.name),
+            admitted: true,
+            codes: [],
+            ...(declaration === undefined ? {} : { declaration }),
+        };
+    });
+}
+async function writeManifests(project, compiled) {
+    const manifests = {};
+    for (const [functionName, manifest] of Object.entries(compiled)) {
+        const path = join(project, `${manifest.name}.workflow.json`);
+        await writeFile(path, JSON.stringify(manifest));
+        Object.defineProperty(manifests, functionName, {
+            value: path,
+            enumerable: true,
+        });
+    }
+    return manifests;
+}
 export async function preparedProject(settings) {
     const { product, project } = settings;
     const files = await initializeProject(settings);
@@ -149,27 +195,28 @@ export async function preparedProject(settings) {
         ...declarations,
         ...staged.map((candidate) => operatorDeclaration({ ...candidate, project }, compiled)),
     ];
-    const manifests = {};
-    for (const [functionName, manifest] of Object.entries(workflowManifests(compiled, combined))) {
-        const path = join(project, `${manifest.name}.workflow.json`);
-        await writeFile(path, JSON.stringify(manifest));
-        Object.defineProperty(manifests, functionName, {
-            value: path,
-            enumerable: true,
-        });
-    }
+    const manifests = await writeManifests(project, workflowManifests(compiled, combined));
     await writeFile(join(project, "declarations.json"), JSON.stringify(combined));
     await writeFile(join(project, "dependencies.json"), await workflowBundleDependencies({
         product,
         packages: Object.keys(packageMetadata.dependencies),
     }));
-    await retainWorkflowBundle({
+    const bundleDigest = await retainWorkflowBundle({
         project,
         repository: folders.repository,
         directory: join(dirname(project), "workflow-bundles"),
     });
+    const workflows = bundledListings({
+        product,
+        files,
+        manifests: bundled,
+        declarations,
+    });
+    workflows.push(...folders.workflows);
     return {
+        workflows,
         repository: folders.repository,
+        bundleDigest,
         manifests,
         declarations: combined,
         workflowRefusals: folders.refusals,

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

@@ -0,0 +1,16 @@
+interface RuntimeSelection {
+    readonly runtime: string;
+    readonly repository: string;
+    readonly legacyRuntime: string | undefined;
+    readonly adoptionRecord: string | undefined;
+}
+export declare function selectRuntimeDirectory(input: RuntimeSelection): Promise<{
+    readonly runtime: string;
+    readonly note: string;
+    readonly adoptionRecord?: string;
+}>;
+export declare function adoptRuntimeDirectory(input: RuntimeSelection): Promise<{
+    readonly runtime: string;
+    readonly note: string;
+}>;
+export {};

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

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readRetainedWorkflowBundle } from "./workflow-bundles.js";
+export async function selectRuntimeDirectory(input) {
+    const { runtime, repository, legacyRuntime, adoptionRecord } = input;
+    if (legacyRuntime === undefined ||
+        adoptionRecord === undefined ||
+        runtime === legacyRuntime)
+        return { runtime, note: "" };
+    const directory = join(dirname(legacyRuntime), "workflow-bundles");
+    if (!(await belongsToRepository(directory, repository)))
+        return {
+            runtime,
+            note: `Legacy runtime ${legacyRuntime} was not adopted: retained bundles are absent, damaged or belong to another repository.`,
+        };
+    return { runtime: legacyRuntime, note: "", adoptionRecord };
+}
+export async function adoptRuntimeDirectory(input) {
+    const selected = await selectRuntimeDirectory(input);
+    const adoptionRecord = selected.adoptionRecord;
+    if (adoptionRecord === undefined)
+        return { runtime: selected.runtime, note: selected.note };
+    const { repository } = input;
+    const legacyRuntime = selected.runtime;
+    await mkdir(dirname(adoptionRecord), { recursive: true, mode: 0o700 });
+    const contents = JSON.stringify({
+        schemaVersion: 1,
+        repository,
+        runtimeDirectory: legacyRuntime,
+    });
+    const temporary = `${adoptionRecord}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, contents, {
+            flag: "wx",
+            mode: 0o600,
+            flush: true,
+        });
+        await link(temporary, adoptionRecord);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return { runtime: legacyRuntime, note: "" };
+}
+async function belongsToRepository(directory, repository) {
+    try {
+        const ids = (await readdir(directory)).filter((id) => id !== ".history");
+        if (ids.length === 0)
+            return false;
+        for (const id of ids)
+            if ((await readRetainedWorkflowBundle({ directory, repository, id }))
+                .kind !== "available")
+                return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -12,4 +12,5 @@ interface HostManifest {
 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 declare function workflowBundleLoader(): string;
 export {};

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

@@ -6,7 +6,8 @@ export async function workflowFiles(directory) {
     return entries
         .filter((entry) => entry.isFile() &&
         /\.(?:ts|js)$/.test(entry.name) &&
-        !entry.name.endsWith(".d.ts"))
+        !entry.name.endsWith(".d.ts") &&
+        !entry.name.endsWith(".test.ts"))
         .map((entry) => entry.name)
         .sort();
 }
@@ -76,3 +77,37 @@ export function workflowManifests(compiled, declarations = []) {
         });
     }));
 }
+export function workflowBundleLoader() {
+    return `
+import { AsyncLocalStorage } from "node:async_hooks";
+import { pathToFileURL } from "node:url";
+const bundleRegistries = new AsyncLocalStorage();
+const registryKeys = ["@workflow/core//registeredSteps", "workflow-class-registry"].map(Symbol.for);
+for (const key of registryKeys) {
+  let current = globalThis[key] ?? new Map();
+  Object.defineProperty(globalThis, key, {
+    configurable: true,
+    get: () => bundleRegistries.getStore()?.get(key) ?? current,
+    set: (value) => {
+      const scope = bundleRegistries.getStore();
+      if (scope === undefined) current = value;
+      else scope.set(key, value);
+    },
+  });
+}
+const loadedBundles = new Map();
+const loadWorkflowBundle = (directory) => {
+  const known = loadedBundles.get(directory);
+  if (known !== undefined) return known;
+  const scope = new Map(registryKeys.map((key) => [key, new Map()]));
+  const loaded = bundleRegistries.run(scope, async () => {
+    const workflows = await import(pathToFileURL(directory + "/artifacts/client.mjs").href);
+    const { POST } = await import(pathToFileURL(directory + "/artifacts/flow.mjs").href);
+    if (typeof POST !== "function") throw new Error("pinned-workflow-unavailable");
+    return { workflows, handler: (request) => bundleRegistries.run(scope, () => POST(request)) };
+  });
+  loadedBundles.set(directory, loaded);
+  return loaded;
+};
+`;
+}