dorfl 0.0.0 → 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,221 @@
+import { type Config } from './config.js';
+import type { ConfigOverrideMap } from './config-override.js';
+import { type ScanReport } from './scan.js';
+import type { Harness } from './harness.js';
+import { type IntegrateResult, type ReviewProvider } from './integrator.js';
+import type { ReviewGate } from './review-gate.js';
+import type { BackoffOptions, Sleep } from './retry-backoff.js';
+/** What happened to one selected item across the whole pipeline. */
+export type ItemStatus = 'claimed-done' | 'lost-race' | 'claim-contended' | 'claim-error' | 'tests-failed' | 'needs-attention' | 'surface-unmoved' | 'agent-failed' | 'transient-infra' | 'config-error' | 'agent-stopped';
+export interface ItemResult {
+    repoPath: string;
+    slug: string;
+    status: ItemStatus;
+    /** Integration outcome, when the item reached done. */
+    integration?: IntegrateResult;
+    detail?: string;
+}
+export interface RunOnceResult {
+    claimedAndDone: number;
+    skipped: number;
+    failed: number;
+    /** Items routed to needs-attention (rebase conflict, red gate). */
+    needsAttention: number;
+    items: ItemResult[];
+}
+/** The agent invocation: edits code in `cwd` to satisfy the prompt. */
+export type Dorfl = (input: {
+    cwd: string;
+    prompt: string;
+    slug: string;
+    env?: NodeJS.ProcessEnv;
+}) => {
+    ok: boolean;
+    detail?: string;
+    /**
+     * The agent's FINAL SUMMARY (the harness seam's `LaunchResult.output`): the
+     * channel the propose-mode PR BODY is built from (mirrors `do`'s
+     * `DoDorfl.output`). Optional so a test agent may supply one; production
+     * surfaces the build agent's last assistant message. Absent ⇒ no body ⇒ the
+     * provider degrades to `--fill` (no regression).
+     */
+    output?: string;
+};
+export interface RunOnceOptions {
+    config: Config;
+    /**
+     * Pre-computed scan report; if omitted, discovery falls back to the registry
+     * (the hub-mirror set, ADR §1). Callers that still operate on working checkouts
+     * (the CLI / its tests) inject an explicit `report` built from working-tree
+     * paths; the registry reframe landed in `run-daemon-reframe` (work/done/).
+     */
+    report?: ScanReport;
+    /**
+     * The execution working area (bare hub mirrors + per-job worktrees). Defaults
+     * to `config.workspacesDir`. STATE, not cache (ADR §3).
+     */
+    workspace?: string;
+    /**
+     * How to invoke the configured agent. When omitted, the work runs through the
+     * harness seam (null adapter by default) shelling out to `config.agentCmd`.
+     * Tests inject this to edit files directly without a real agent.
+     */
+    dorfl?: Dorfl;
+    /** The harness seam (ADR §5); defaults to the null adapter. */
+    harness?: Harness;
+    /**
+     * The PR/code review gate (Gate 2) SEAM, threaded into the shared
+     * `performIntegration` core. Tests inject a canned `approve`/`block` verdict
+     * (no real model); the CLI passes the production `harnessReviewGate()` ONLY
+     * when `config.review` resolves on. Unset ⇒ no review (the default). The core
+     * throws if `review` is on but this is absent — `runOneItem` guards that.
+     */
+    reviewGate?: ReviewGate;
+    /**
+     * An explicitly-injected, fully-formed review provider INSTANCE that overrides
+     * per-item auto-detection (tests / embedding). Forwarded to
+     * `performIntegration` as `providerInstance` (carrying title/body/url). Unset ⇒
+     * the core selects the provider PURELY from the arbiter URL (no override axis).
+     */
+    provider?: ReviewProvider;
+    /**
+     * The `gh` AUTH/AVAILABILITY PROBE the PR-INTENT pre-flight guard runs UP FRONT
+     * per item (propose + GitHub arbiter + `noPR` unset): `true` ⇒ `gh` CAN open a
+     * PR. The SAME signal in-place `do` (and `do --remote`) uses, run BEFORE the
+     * claim so no item is left claimed when `gh` is genuinely unauthed. The probe
+     * (not a config check) is the signal — an absent `providers.github` identity
+     * falls back to ambient `gh` auth, which the probe reports available, so the run
+     * PROCEEDS. Injectable so tests stub `gh` without a real binary; production
+     * defaults to `new GitHubProvider().available(repoPath, env)`.
+     */
+    ghCanOpenPr?: (cwd: string, env: NodeJS.ProcessEnv | undefined) => boolean;
+    /** Optional injectable PR opener for `integration: propose` (legacy bridge). */
+    openPr?: (opts: {
+        cwd: string;
+        branch: string;
+        env?: NodeJS.ProcessEnv;
+    }) => void;
+    /** Environment for git/agent child processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Override agent-id generation (tests). Retained for API compat; unused for branch naming. */
+    agentId?: () => string;
+    /**
+     * Sink for non-fatal warnings (e.g. a repo's `.dorfl.json` naming
+     * runner/host-only keys that were ignored). Defaults to a no-op so the core
+     * stays pure; the CLI wires this to stderr.
+     */
+    onWarn?: (message: string) => void;
+    /**
+     * The per-machine {@link ConfigOverrideMap} (from `loadConfigOverride`),
+     * threaded into the per-repo resolution `runOneItem` performs so the override
+     * applies to every tick item (ADR `per-machine-config-override-layer`).
+     * Default: empty (no override).
+     */
+    override?: ConfigOverrideMap;
+    /**
+     * Bounded-backoff bounds for the needs-attention route's git network ops
+     * (surface fetch+push, branch push). Defaults to the shared `DEFAULT_BACKOFF`.
+     * Threaded into the failure-routing seam so a degraded run gives up cleanly
+     * rather than hanging the tick.
+     */
+    backoff?: BackoffOptions;
+    /**
+     * Injectable sleep for that backoff — the SAME seam {@link runLoop} uses for
+     * its inter-tick sleep. Defaults to a real `setTimeout`. Tests inject a no-op
+     * so a fully-offline-arbiter failure route resolves with NO real waits.
+     */
+    sleep?: Sleep;
+}
+/**
+ * Run one supervised tick: claim up to `maxParallel` eligible items
+ * (≤ `perRepoMax` per repo), run the agent on each in an isolated **job
+ * worktree** (the shared execution substrate — hub mirror + worktree + seams),
+ * gate on acceptance tests, rebase onto the latest arbiter main, and integrate
+ * the green ones. The runner owns EVERY git-state transition (claim, done-move,
+ * completion commit, integration); the agent only edits code. A lost race (claim
+ * exit 2) is skipped cleanly; failing work never reaches `work/done/`; a rebase
+ * conflict is aborted and routed to needs-attention (ADR §10).
+ */
+export declare function runOnce(options: RunOnceOptions): Promise<RunOnceResult>;
+/** A throwaway default workspace under the OS temp dir (CLI convenience). */
+export declare function defaultRunWorkspace(): string;
+/**
+ * One supervised TICK over the registry, as a swappable unit. Today the tick IS
+ * `runOnce` (claim+build+integrate a concurrent batch of eligible TASKS). The
+ * loop ({@link runLoop}) is deliberately written against this signature — NOT
+ * against `runOnce` directly — so the advance-loop prd can later swap the tick
+ * (build / task / triage / surface / apply) WITHOUT re-architecting the loop
+ * (the forward-pointer: the loop owns concurrency/scheduling, the tick owns one
+ * item's work). The loop never reaches inside a tick.
+ */
+export type RunTick = (options: RunOnceOptions) => Promise<RunOnceResult>;
+export interface RunLoopOptions extends RunOnceOptions {
+    /**
+     * Stop after this many ticks. Unset ⇒ no iteration bound (the forever daemon,
+     * the future system service). A bounded session (an operator's stop discipline,
+     * absorbing the retired `watch` verb) sets this and/or `maxDurationMs`.
+     */
+    maxIterations?: number;
+    /**
+     * Stop once this many ms of wall-clock have elapsed (checked before each tick
+     * AND before each inter-tick sleep). Unset ⇒ no duration bound.
+     */
+    maxDurationMs?: number;
+    /**
+     * Pause between ticks (ms). Default 0 (back-to-back). The loop sleeps via the
+     * injectable {@link RunLoopOptions.sleep} so tests need not wait real time.
+     */
+    intervalMs?: number;
+    /** The tick to loop. Defaults to {@link runOnce}; tests/advance-loop inject. */
+    tick?: RunTick;
+    /** Clock seam (tests). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Sleep seam (tests). Defaults to a real `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Cooperative stop signal, polled before each tick. When it returns true the
+     * loop ends cleanly after the current tick. The CLI wires this to a SIGINT/
+     * SIGTERM flag so the long-running daemon shuts down gracefully; tests use it to
+     * end an otherwise-forever loop deterministically.
+     */
+    stop?: () => boolean;
+    /** Called once per completed tick with its result + 1-based index (CLI logging). */
+    onTick?: (result: RunOnceResult, iteration: number) => void;
+}
+/** Aggregate outcome of a {@link runLoop} session. */
+export interface RunLoopResult {
+    /** Number of ticks actually executed. */
+    iterations: number;
+    /** Why the loop ended. */
+    stoppedBy: 'max-iterations' | 'max-duration' | 'signal';
+    /** Sum of `claimedAndDone` across all ticks. */
+    claimedAndDone: number;
+    /** Sum of `skipped` across all ticks. */
+    skipped: number;
+    /** Sum of `failed` across all ticks. */
+    failed: number;
+    /** Sum of `needsAttention` across all ticks. */
+    needsAttention: number;
+    /** Each tick's result, in order. */
+    ticks: RunOnceResult[];
+}
+/**
+ * `run` (no flag) — the cross-repo, parallel, **forever-looping daemon** (ADR §3):
+ * loop the supervised concurrent tick over the registry until a stop bound
+ * (max-iterations / max-duration / a stop signal) or forever (the future system
+ * service). Each tick claims + runs a CONCURRENT batch ({@link runOnce}’s
+ * `maxParallel`/`perRepoMax` in-flight execution), integrates, then the loop
+ * continues. This absorbs the retired `watch` verb’s bounded-session + surface-
+ * failures behaviour: a stuck item (timeout / red gate / rebase conflict) is
+ * routed through the EXISTING ledger needs-attention seam INSIDE the tick
+ * (`runOneItem` → `applyNeedsAttentionTransition`, surfaced on `main`) — the loop
+ * does NOT infinite-retry it and adds NO bespoke failure reporting; it just keeps
+ * ticking. `run --once` is exactly ONE tick (call {@link runOnce} directly, the
+ * debug/test affordance — NOT the CI path; CI is `do`).
+ *
+ * The loop owns ONLY scheduling (when/whether to tick); the TICK owns one batch’s
+ * work — kept separable so advance-loop can swap the tick later (see {@link
+ * RunTick}).
+ */
+export declare function runLoop(options: RunLoopOptions): Promise<RunLoopResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}