cloving 1.2.0 → 1.4.0

package/dist/src/workflow-candidate.js

@@ -1,22 +1,59 @@
 import { record } from "./protocol.js";
-import { isWorkflowDeclaration, } from "./workflow-declaration.js";
+import { isWorkflowDeclaration, workflowQueueRefusals, } from "./workflow-declaration.js";
 const workflowModules = [
     "cloving/workflows",
     "cloving/workflows/steps/decision-gate",
+    "cloving/workflows/steps/wait-for-decision",
+    "cloving/workflows/steps/review-by-person",
+    "cloving/workflows/steps/review-by-agent",
+    "cloving/workflows/steps/merge-by-person",
+    "cloving/workflows/steps/merge-when-green",
+    "cloving/workflows/steps/review-subject",
     "cloving/workflows/steps/load-cycle",
     "cloving/workflows/steps/protected-effect",
     "cloving/workflows/steps/handoff",
+    "cloving/workflows/steps/wait-for-run",
+    "cloving/workflows/steps/run-command",
+    "cloving/workflows/steps/sleep",
+    "cloving/workflows/steps/wait-for-command",
 ];
+export function workflowHelperPath(source, imported) {
+    if (!imported.startsWith("./"))
+        return undefined;
+    const parts = [
+        ...source.split("/").slice(0, -1),
+        ...imported.slice(2).split("/"),
+    ];
+    if (parts.length < 2 ||
+        parts.some((part) => part.length === 0 ||
+            part === "." ||
+            part === ".." ||
+            part.toUpperCase() === "NODE_MODULES" ||
+            /[\\:\0]/.test(part) ||
+            part.startsWith("~")))
+        return undefined;
+    const path = parts.join("/");
+    return path.endsWith(".ts") && !path.endsWith(".d.ts") ? path : undefined;
+}
+function allowedImport(entry, analysis) {
+    if (workflowModules.includes(entry.module))
+        return true;
+    const path = workflowHelperPath(entry.source ?? "candidate.ts", entry.module);
+    return path !== undefined && (analysis.localSources ?? []).includes(path);
+}
 function isMethodList(value) {
     return (Array.isArray(value) &&
         value.length > 0 &&
         Array.from(value).every((method) => typeof method === "string" && method.trim().length > 0) &&
         new Set(value).size === value.length);
 }
-function isCandidateDeclaration(value) {
+export function isCandidateDeclaration(value) {
     const fields = record(value);
     if (!fields ||
-        Object.keys(fields).some((key) => key !== "workflow" && key !== "methods"))
+        Object.keys(fields).some((key) => !["workflow", "methods", "template"].includes(key)) ||
+        (Object.hasOwn(fields, "template") &&
+            (typeof fields["template"] !== "string" ||
+                !/^[a-z][a-z0-9-]{0,63}$/.test(fields["template"]))))
         return false;
     const workflow = fields["workflow"];
     const methods = record(fields["methods"]);
@@ -28,10 +65,10 @@ function isCandidateDeclaration(value) {
 }
 export function checkWorkflowCandidate(input) {
     if (!isCandidateDeclaration(input.declaration))
-        return ["invalid-declaration"];
+        return candidateDeclarationRefusals(input.declaration);
     const { analysis, declaration, installedExports } = input;
-    const codes = [];
-    if (analysis.imports.some((entry) => !workflowModules.includes(entry.module)))
+    const codes = commandWaitRefusals(analysis, declaration);
+    if (analysis.imports.some((entry) => !allowedImport(entry, analysis)))
         codes.push("forbidden-import");
     if (analysis.imports.some((entry) => {
         if (!workflowModules.includes(entry.module))
@@ -58,3 +95,19 @@ export function checkWorkflowCandidate(input) {
         codes.push("unsupported-source");
     return [...new Set(codes)].sort();
 }
+export function candidateDeclarationRefusals(value) {
+    if (isCandidateDeclaration(value))
+        return [];
+    const codes = workflowQueueRefusals(record(value)?.["workflow"]);
+    return codes.length > 0 ? codes : ["invalid-declaration"];
+}
+function commandWaitRefusals(analysis, declaration) {
+    const waits = analysis.commandWaits ?? [];
+    const codes = [];
+    if (waits.includes(null))
+        codes.push("dynamic-effect");
+    if (waits.some((name) => name !== null &&
+        !Object.hasOwn(declaration.workflow.commandWaits ?? {}, name)))
+        codes.push("undeclared-effect");
+    return codes;
+}

package/dist/src/workflow-contracts.d.ts

@@ -17,6 +17,7 @@ export type CycleOutcome = {
     readonly ticketStatus?: "complete" | "partial";
     readonly issueUpdate?: "failed";
     readonly reason?: string;
+    readonly report?: string;
 };
 export type Validation<Value> = {
     readonly kind: "valid";

package/dist/src/workflow-contracts.js

@@ -43,7 +43,7 @@ const outcomes = {
     },
     handoff_requested: {
         keys: ["cycleId", "kind", "promotionId"],
-        optional: ["ticketStatus", "issueUpdate", "reason"],
+        optional: ["ticketStatus", "issueUpdate", "reason", "report"],
         parse: (fields) => {
             const cycleId = textField(fields, {
                 key: "cycleId",
@@ -58,6 +58,9 @@ const outcomes = {
             const ticketStatus = fields["ticketStatus"];
             const issueUpdate = fields["issueUpdate"];
             const reason = fields["reason"];
+            const report = fields["report"];
+            if (!validReport(report))
+                return null;
             if (issueUpdate !== undefined && issueUpdate !== "failed")
                 return null;
             if (ticketStatus !== undefined && !isTicketStatus(ticketStatus))
@@ -68,11 +71,15 @@ const outcomes = {
                 kind: "handoff_requested",
                 cycleId,
                 promotionId,
-                ...Object.fromEntries(Object.entries({ issueUpdate, ticketStatus, reason }).filter(([, value]) => value !== undefined)),
+                ...Object.fromEntries(Object.entries({ issueUpdate, ticketStatus, reason, report }).filter(([, value]) => value !== undefined)),
             };
         },
     },
 };
+function validReport(report) {
+    return (report === undefined ||
+        (typeof report === "string" && report.length > 0 && report.length <= 65536));
+}
 export function validateDevelopmentInput(value) {
     const fields = exactFields(value, { required: ["cycleId"] });
     const cycleId = fields && textField(fields, { key: "cycleId", pattern: identifier });

package/dist/src/workflow-declaration.d.ts

@@ -1,22 +1,40 @@
-import type { SubmissionContract } from "./submission.ts";
+import { type SubmissionContract } from "./submission.ts";
+import { type WorkflowSchedule } from "./workflow-schedule.ts";
 export interface WorkflowStage {
     readonly name: string;
     readonly label: string;
     readonly operations?: readonly string[];
     readonly gateKinds?: readonly ("approval" | "question")[];
+    readonly gateIds?: readonly string[];
 }
 export type WorkflowStages = Readonly<Record<string, readonly WorkflowStage[]>>;
+export interface CommandWaitDeclaration {
+    readonly command: string;
+    readonly maximumWaitSeconds: number;
+    readonly pollEverySeconds: number;
+}
+export type CommandWaits = Readonly<Record<string, CommandWaitDeclaration>>;
 export interface WorkflowDeclaration {
     readonly workflowId: string;
     readonly effectLimit: number;
-    readonly capabilities: readonly ("claude" | "github" | "chats")[];
+    readonly capabilities: readonly ("claude" | "github" | "command")[];
     readonly input: SubmissionContract;
     readonly stages?: readonly WorkflowStage[];
     readonly handoffs?: readonly string[];
+    readonly commands?: readonly string[];
+    readonly commandWaits?: CommandWaits;
+    readonly queue?: boolean;
+    readonly schedule?: WorkflowSchedule;
 }
 export interface DeclaredWorkflow extends WorkflowDeclaration {
     readonly functionName: string;
 }
+export type WorkflowQueueCode = "queue-needs-ticket-field" | "queue-input-incomplete";
+export declare function workflowQueueRefusals(value: unknown): readonly WorkflowQueueCode[];
 export declare function isWorkflowStages(value: unknown): value is readonly WorkflowStage[];
-export declare function isWorkflowHandoffs(value: unknown): value is readonly string[];
+export declare function isWorkflowNames(value: unknown): value is readonly string[];
+export declare function isCommandWaits(value: unknown, permissions: {
+    readonly capabilities: readonly string[];
+    readonly commands: readonly string[];
+}): value is CommandWaits;
 export declare function isWorkflowDeclaration(value: unknown): value is WorkflowDeclaration;

package/dist/src/workflow-declaration.js

@@ -1,4 +1,17 @@
 import { record } from "./protocol.js";
+import { hasTicketField, } from "./submission.js";
+import { checkWorkflowSchedule, } from "./workflow-schedule.js";
+export function workflowQueueRefusals(value) {
+    const declaration = record(value);
+    if (declaration?.["queue"] !== true || !isInput(declaration["input"]))
+        return [];
+    const input = declaration["input"];
+    if (!hasTicketField(input))
+        return ["queue-needs-ticket-field"];
+    return Object.entries(input.fields).some(([name, rule]) => name !== "ticket" && (rule === "string" || rule.optional !== true))
+        ? ["queue-input-incomplete"]
+        : [];
+}
 function keys(fields, allowed) {
     return (fields !== undefined &&
         Object.keys(fields).every((key) => allowed.includes(key)));
@@ -28,7 +41,9 @@ function isField(value) {
         return false;
     if (fields["type"] === "integer")
         return integerBounds(fields);
-    return ((fields["type"] === "string" || fields["type"] === "boolean") &&
+    return ((fields["type"] === "string" ||
+        fields["type"] === "boolean" ||
+        fields["type"] === "ticket") &&
         !Object.hasOwn(fields, "minimum") &&
         !Object.hasOwn(fields, "maximum"));
 }
@@ -39,7 +54,7 @@ function isInput(value) {
     const fields = record(input["fields"]);
     return (integer(input["maximumBytes"], { minimum: 1, maximum: 1_048_576 }) &&
         fields !== undefined &&
-        Object.values(fields).every(isField));
+        Object.entries(fields).every(([name, rule]) => isField(rule) && (rule.type !== "ticket" || name === "ticket")));
 }
 function matches(value, pattern) {
     return typeof value === "string" && pattern.test(value);
@@ -56,18 +71,20 @@ function isStageLabel(label) {
 }
 function isStage(value) {
     const stage = record(value);
-    if (!keys(stage, ["name", "label", "operations", "gateKinds"]))
+    if (!keys(stage, ["name", "label", "operations", "gateKinds", "gateIds"]))
         return false;
     const { name, label } = stage;
     const operations = Object.hasOwn(stage, "operations")
         ? stage["operations"]
         : [];
     const gateKinds = Object.hasOwn(stage, "gateKinds") ? stage["gateKinds"] : [];
+    const gateIds = Object.hasOwn(stage, "gateIds") ? stage["gateIds"] : [];
     return (matches(name, /^[A-Za-z0-9-]{1,64}$/) &&
         isStageLabel(label) &&
         selectors(operations, /^[A-Za-z0-9._:/-]{1,128}$/) &&
         selectors(gateKinds, /^(approval|question)$/) &&
-        operations.length + gateKinds.length > 0);
+        selectors(gateIds, /^[A-Za-z0-9._:/-]{1,128}$/) &&
+        operations.length + gateKinds.length + gateIds.length > 0);
 }
 function unique(values) {
     return new Set(values).size === values.length;
@@ -81,18 +98,55 @@ export function isWorkflowStages(value) {
     return (unique(stages.map((stage) => stage.name)) &&
         unique(stages.map((stage) => stage.label)) &&
         unique(stages.flatMap((stage) => stage.operations ?? [])) &&
-        unique(stages.flatMap((stage) => stage.gateKinds ?? [])));
+        unique(stages.flatMap((stage) => stage.gateKinds ?? [])) &&
+        unique(stages.flatMap((stage) => stage.gateIds ?? [])));
 }
 function isCapabilities(value) {
     return (Array.isArray(value) &&
         value.length > 0 &&
         value.every((capability) => capability === "claude" ||
             capability === "github" ||
-            capability === "chats"));
+            capability === "command"));
 }
-export function isWorkflowHandoffs(value) {
+export function isWorkflowNames(value) {
     return selectors(value, /^[A-Za-z0-9-]{1,64}$/) && unique(value);
 }
+function declaredCommands(declaration, capabilities) {
+    const commands = declaration["commands"];
+    if (Object.hasOwn(declaration, "commands") && !isWorkflowNames(commands))
+        return false;
+    return ((!capabilities.includes("command") ||
+        (Array.isArray(commands) && commands.length > 0)) &&
+        declaredCommandWaits(declaration, capabilities));
+}
+function isCommandWait(value) {
+    const wait = record(value);
+    if (!keys(wait, ["command", "maximumWaitSeconds", "pollEverySeconds"]))
+        return false;
+    return (typeof wait["command"] === "string" &&
+        integer(wait["maximumWaitSeconds"], { minimum: 60, maximum: 2_592_000 }) &&
+        integer(wait["pollEverySeconds"], { minimum: 60, maximum: 86_400 }) &&
+        Number(wait["pollEverySeconds"]) <= Number(wait["maximumWaitSeconds"]));
+}
+export function isCommandWaits(value, permissions) {
+    const waits = record(value);
+    if (waits === undefined)
+        return false;
+    return Object.entries(waits).every(([name, wait]) => matches(name, /^[A-Za-z0-9-]{1,64}$/) &&
+        name.trim() === name &&
+        isCommandWait(wait) &&
+        permissions.capabilities.includes("command") &&
+        permissions.commands.includes(wait.command));
+}
+function declaredCommandWaits(declaration, capabilities) {
+    if (!Object.hasOwn(declaration, "commandWaits"))
+        return true;
+    const commands = declaration["commands"];
+    return isCommandWaits(declaration["commandWaits"], {
+        capabilities,
+        commands: isWorkflowNames(commands) ? commands : [],
+    });
+}
 export function isWorkflowDeclaration(value) {
     const declaration = record(value);
     if (!keys(declaration, [
@@ -102,14 +156,28 @@ export function isWorkflowDeclaration(value) {
         "input",
         "stages",
         "handoffs",
+        "commands",
+        "commandWaits",
+        "queue",
+        "schedule",
     ]))
         return false;
-    const { workflowId, effectLimit, capabilities, input, handoffs } = declaration;
+    const { workflowId, effectLimit, capabilities, input } = declaration;
     return (matches(workflowId, /^[A-Za-z0-9-]{1,64}$/) &&
         integer(effectLimit, { minimum: 1, maximum: 100 }) &&
         isCapabilities(capabilities) &&
+        declaredCommands(declaration, capabilities) &&
         isInput(input) &&
+        declaredOptions(declaration, input));
+}
+function declaredOptions(declaration, input) {
+    return ((!Object.hasOwn(declaration, "queue") ||
+        typeof declaration["queue"] === "boolean") &&
+        workflowQueueRefusals(declaration).length === 0 &&
         (!Object.hasOwn(declaration, "stages") ||
             isWorkflowStages(declaration["stages"])) &&
-        (!Object.hasOwn(declaration, "handoffs") || isWorkflowHandoffs(handoffs)));
+        (!Object.hasOwn(declaration, "handoffs") ||
+            isWorkflowNames(declaration["handoffs"])) &&
+        (!Object.hasOwn(declaration, "schedule") ||
+            checkWorkflowSchedule(input, declaration["schedule"]).kind === "valid"));
 }

package/dist/src/workflow-discovery.d.ts

@@ -1,18 +1,8 @@
-export interface WorkflowReservation {
-    readonly baseName?: string;
-    readonly workflowId?: string;
-    readonly functionName?: string;
-}
 export interface WorkflowDiscoveryIdentity {
+    readonly queue?: boolean;
     readonly baseName: string;
     readonly workflowId: string | undefined;
     readonly functionNames: readonly string[];
 }
-export type WorkflowConflictCode = "workflow-conflict" | "bundled-name-reserved";
-export declare function workflowConflicts(candidates: readonly WorkflowDiscoveryIdentity[], bundled: readonly WorkflowReservation[]): readonly (readonly WorkflowConflictCode[])[];
-export declare const bundledWorkflowIds: {
-    readonly ticket: "develop-ticket";
-    readonly issue: "develop-issue";
-    readonly prompt: "develop-prompt";
-    readonly prd: "develop-prd";
-};
+export type WorkflowConflictCode = "workflow-conflict" | "queue-workflow-conflict";
+export declare function workflowConflicts(candidates: readonly WorkflowDiscoveryIdentity[]): readonly (readonly WorkflowConflictCode[])[];

package/dist/src/workflow-discovery.js

@@ -5,29 +5,20 @@ function identityKeys(identity) {
         ...identity.functionNames.map((name) => `function:${name}`),
     ];
 }
-export function workflowConflicts(candidates, bundled) {
+export function workflowConflicts(candidates) {
     const keys = candidates.map(identityKeys);
     const counts = new Map();
     for (const names of keys) {
         for (const name of new Set(names))
             counts.set(name, (counts.get(name) ?? 0) + 1);
     }
-    const reserved = new Set(bundled.flatMap((entry) => identityKeys({
-        ...entry,
-        functionNames: entry.functionName === undefined ? [] : [entry.functionName],
-    })));
-    return keys.map((names) => {
+    const queued = candidates.filter((candidate) => candidate.queue === true);
+    return keys.map((names, index) => {
         const codes = [];
-        if (names.some((name) => reserved.has(name)))
-            codes.push("bundled-name-reserved");
+        if (queued.length > 1 && candidates[index]?.queue === true)
+            codes.push("queue-workflow-conflict");
         if (names.some((name) => (counts.get(name) ?? 0) > 1))
             codes.push("workflow-conflict");
         return codes;
     });
 }
-export const bundledWorkflowIds = {
-    ticket: "develop-ticket",
-    issue: "develop-issue",
-    prompt: "develop-prompt",
-    prd: "develop-prd",
-};

package/dist/src/workflow-refusals.js

@@ -1,6 +1,9 @@
 import { record } from "./protocol.js";
 const refusalCodes = new Set([
     "invalid-declaration",
+    "queue-needs-ticket-field",
+    "queue-input-incomplete",
+    "queue-workflow-conflict",
     "forbidden-import",
     "missing-export",
     "unsupported-source",
@@ -9,7 +12,6 @@ const refusalCodes = new Set([
     "effect-limit",
     "direct-effect",
     "workflow-conflict",
-    "bundled-name-reserved",
     "unsafe-workflow-path",
     "workflow-read-failed",
     "workflow-source-changed",

package/dist/src/workflow-schedule.d.ts

@@ -0,0 +1,22 @@
+import { type Fields } from "./protocol.ts";
+import { type SubmissionContract } from "./submission.ts";
+export interface WorkflowSchedule {
+    readonly everySeconds: number;
+    readonly input: Fields;
+}
+export type ScheduleCheck = {
+    readonly kind: "valid";
+    readonly schedule: WorkflowSchedule;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+};
+interface ScheduleSource {
+    readonly workflowId: string;
+    readonly input: SubmissionContract;
+    readonly schedule?: WorkflowSchedule;
+}
+export declare function parseSchedulesSetting(value: string | undefined): unknown;
+export declare function configuredSchedules(declarations: readonly ScheduleSource[], overrides: unknown): Readonly<Record<string, WorkflowSchedule>>;
+export declare function checkWorkflowSchedule(contract: SubmissionContract, value: unknown): ScheduleCheck;
+export {};

package/dist/src/workflow-schedule.js

@@ -0,0 +1,53 @@
+import { record } from "./protocol.js";
+import { checkSubmission } from "./submission.js";
+export function parseSchedulesSetting(value) {
+    try {
+        return JSON.parse(value ?? "{}");
+    }
+    catch {
+        throw new Error("invalid-schedules");
+    }
+}
+export function configuredSchedules(declarations, overrides) {
+    const settings = record(overrides);
+    if (settings === undefined)
+        throw new Error("invalid-schedules");
+    if (Object.keys(settings).some((id) => !declarations.some((entry) => entry.workflowId === id)))
+        throw new Error("unknown-schedule-workflow");
+    const schedules = [];
+    for (const declaration of declarations) {
+        const { workflowId } = declaration;
+        const selected = Object.hasOwn(settings, workflowId)
+            ? settings[workflowId]
+            : declaration.schedule;
+        if (selected === undefined && !Object.hasOwn(settings, workflowId))
+            continue;
+        const checked = checkWorkflowSchedule(declaration.input, selected);
+        if (checked.kind === "rejected")
+            throw new Error(checked.code);
+        schedules.push([workflowId, checked.schedule]);
+    }
+    return Object.fromEntries(schedules);
+}
+export function checkWorkflowSchedule(contract, value) {
+    const fields = record(value);
+    const seconds = fields?.["everySeconds"];
+    if (fields === undefined ||
+        Object.keys(fields).some((key) => !["everySeconds", "input"].includes(key)) ||
+        typeof seconds !== "number" ||
+        !Number.isInteger(seconds) ||
+        seconds < 60 ||
+        seconds > 86400)
+        return { kind: "rejected", code: "invalid-schedule-interval" };
+    const checked = checkSubmission(contract, {
+        workflowId: "schedule",
+        source: "declared",
+        submission: fields["input"],
+    });
+    if (checked.kind === "rejected")
+        return { kind: "rejected", code: "invalid-schedule-input" };
+    return {
+        kind: "valid",
+        schedule: { everySeconds: seconds, input: checked.submission },
+    };
+}

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 { waitForCommand, type CommandWaitRequest, type CommandWaitOutcome, } from "./steps/wait-for-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 { waitForCommand, } from "./steps/wait-for-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>>;