dorfl 0.0.0 → 0.1.0

package/dist/claim-cas.js

@@ -0,0 +1,312 @@
+import { runAsync } from './git.js';
+import { acquireItemLock, releaseItemLock, heldTaskSlugs } from './item-lock.js';
+import { extractPromptSection } from './prompt.js';
+import { resolveReadiness } from './readiness.js';
+import { workBranchRef } from './slug-namespace.js';
+import { workItemRel } from './work-layout.js';
+/**
+ * The "lost" diagnostic for a held-lock loss, reused so its message carries the
+ * recovery hints a human re-running their OWN item needs. The body now STAYS in
+ * `work/backlog/` (claim never moves it), so a held item is identified by its LOCK
+ * (`action: implement` held on the per-item ref), not an `in-progress/` folder: a
+ * held lock + the body still in `backlog/` is the normal claimed state. We fetch
+ * the lock refs and, when the slug's lock is held, surface the resume/requeue
+ * recovery hints; otherwise (the body left `backlog/` entirely — done/removed) we
+ * fall back to the generic message.
+ */
+async function lostMessage(slug, arbiter, cwd, env, fallback) {
+    const held = await heldTaskSlugs(cwd, arbiter, env);
+    if (held.has(slug)) {
+        return `'${slug}' is already claimed on ${arbiter}/main (its per-item lock is held). If someone else claimed it, pick another item; if it's your own (e.g. an interrupted run), continue it with \`dorfl resume ${slug}\` (or \`work-on\`), or recover via \`requeue\`.`;
+    }
+    return fallback;
+}
+/** Raised for usage/environment errors (exit 1). */
+class ClaimUsageError extends Error {
+}
+/**
+ * Raised for a deliberate readiness REFUSAL (exit 1, outcome 'not-ready') —
+ * distinct from a usage/environment error. The task has an unmet `blockedBy`
+ * and the override was not supplied, so nothing is claimed.
+ */
+class ClaimNotReady extends Error {
+}
+const DEFAULT_ARBITER = 'origin';
+/**
+ * Perform the claim CAS. Never throws for the expected "lost the race" or
+ * "contended" cases — those are returned as exit 2 / 3. Usage/environment
+ * problems surface as exit 1. A successful claim is exit 0. This mirrors
+ * claim.sh's control flow exactly (refuse dirty tree → loop attempts → on
+ * rejection refetch & decide lost-vs-advanced → cap retries → back off).
+ */
+export async function performClaim(options) {
+    const note = options.note ?? (() => { });
+    try {
+        return await runClaim(options, note);
+    }
+    catch (err) {
+        if (err instanceof ClaimNotReady) {
+            return { exitCode: 1, outcome: 'not-ready', message: err.message };
+        }
+        if (err instanceof ClaimUsageError) {
+            return { exitCode: 1, outcome: 'usage-error', message: err.message };
+        }
+        // Any other unexpected failure is an environment error (exit 1), never a
+        // false "claimed". claim.sh treats unexpected rc the same way (die → 1).
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+}
+async function runClaim(options, note) {
+    const slug = options.slug;
+    const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+    const dryRun = options.dryRun ?? false;
+    const cwd = options.cwd;
+    const env = options.env;
+    if (!slug) {
+        throw new ClaimUsageError('missing <slug>. usage: dorfl claim <slug> [--arbiter remote]');
+    }
+    if ((await gitSoft(['rev-parse', '--git-dir'], cwd, env)).status !== 0) {
+        throw new ClaimUsageError('not inside a git repository');
+    }
+    if ((await gitSoft(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+        throw new ClaimUsageError(`no git remote named '${arbiter}' (set one, or pass --arbiter)`);
+    }
+    // Refuse to run with a dirty tree — the claim must be a clean, isolated commit.
+    const dirtyWorktree = (await gitSoft(['diff', '--quiet'], cwd, env)).status !== 0;
+    const dirtyIndex = (await gitSoft(['diff', '--cached', '--quiet'], cwd, env)).status !== 0;
+    if (dirtyWorktree || dirtyIndex) {
+        throw new ClaimUsageError('working tree has uncommitted changes; commit/stash them before claiming');
+    }
+    // HUMAN-path readiness guard (run BEFORE the CAS so a not-ready task is never
+    // claimed). Reads the task frontmatter + `work/done/` from `<arbiter>/main`
+    // (the same source of truth the folder check uses) and resolves `blockedBy`
+    // via the shared resolveBlockedBy. Skipped entirely for the autonomous runner
+    // (no `humanPath`), whose eligibility filter already handles these upstream.
+    if (options.humanPath) {
+        await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+        const readiness = await resolveReadiness({
+            slug,
+            cwd,
+            arbiter,
+            override: options.override === true,
+            env,
+        });
+        if (readiness.refuse) {
+            const missing = readiness.missing.join(', ');
+            const message = `'${slug}' is not ready: blocked by unmet dependencies not yet in ` +
+                `work/done/ on ${arbiter}/main: ${missing}. ` +
+                'Re-run with --force (or --ignore-not-ready) to claim it anyway.';
+            note(message);
+            throw new ClaimNotReady(message);
+        }
+        if (readiness.overridden && readiness.missing.length > 0) {
+            note(`!! readiness guard OVERRIDDEN: claiming '${slug}' despite unmet ` +
+                `blockedBy: ${readiness.missing.join(', ')} (not yet in work/done/).`);
+        }
+        if (readiness.needsAnswers && !readiness.overridden) {
+            note(`!! WARNING: '${slug}' is flagged needsAnswers: true — it has open ` +
+                'questions (see the task body). Claiming it anyway (human path); ' +
+                'resolve the questions before/while building.');
+        }
+        else if (readiness.needsAnswers && readiness.overridden) {
+            note(`!! readiness guard OVERRIDDEN: silencing the needsAnswers warning for '${slug}'.`);
+        }
+    }
+    const backlog = workItemRel('tasks-ready', `${slug}.md`);
+    const staged = workItemRel('tasks-backlog', `${slug}.md`);
+    const branch = workBranchRef('task', slug);
+    /**
+     * The CLAIMABLE-RESIDENCE half of the predicate: the body rests in the pool
+     * (`tasks/ready/`) on `<arbiter>/main`, OR \u2014 under `--allow-backlog` \u2014 in
+     * `tasks/backlog/` (staging). The held-lock half is the create-only acquire.
+     * Folder-agnostic exclusion is the lock, never the folder, so a staged body is
+     * a legitimate claimable residence under the flag; otherwise staging is invisible.
+     */
+    async function claimableBodyRel() {
+        if (await catFileExists(`${arbiter}/main:${backlog}`, cwd, env)) {
+            return backlog;
+        }
+        if (options.allowBacklog === true &&
+            (await catFileExists(`${arbiter}/main:${staged}`, cwd, env))) {
+            return staged;
+        }
+        return undefined;
+    }
+    async function bodyRestsClaimable() {
+        return (await claimableBodyRel()) !== undefined;
+    }
+    /**
+     * The human-facing folder label for a resolved claimable body path (`work/<dir>`,
+     * e.g. `work/tasks/ready` or `work/tasks/backlog`). Derived from the ACTUAL
+     * resolved residence so the claim message never hard-codes the wrong folder.
+     */
+    function residenceFolder(bodyRel) {
+        const dir = bodyRel.slice(0, bodyRel.lastIndexOf('/'));
+        return dir === '' ? bodyRel : dir;
+    }
+    /**
+     * PRE-CLAIM WELL-FORMEDNESS GUARD (this task's interim guard against the
+     * promptless-promoted-task strand). The validator `resolveTask` /
+     * `extractPromptSection` (`prompt.ts`) requires a task body to carry a
+     * `## Prompt` section; it runs at DISPATCH (`do.ts` step 5), AFTER the claim,
+     * so a body missing `## Prompt` was caught only post-claim — the failure routed
+     * to `saveAgentFailure`, which left the lock `state: stuck`. We run the SAME
+     * validator (`extractPromptSection`, the single source of truth for "what makes
+     * a task dispatchable") HERE, BEFORE the lock is acquired, so a malformed body
+     * from ANY source (promotion, hand-authored, externally edited) is refused with a
+     * clean usage error and NO lock is taken. `bodyRel` is the resolved claimable
+     * residence (`tasks/ready/` or, under the flag, `tasks/backlog/`). A genuinely
+     * absent body is NOT this guard's concern (the claimability check returns `lost`
+     * separately) — this only fires when a body that DOES rest claimable lacks a
+     * `## Prompt`.
+     */
+    async function assertBodyWellFormed(bodyRel) {
+        const show = await gitSoft(['show', `${arbiter}/main:${bodyRel}`], cwd, env);
+        if (show.status !== 0) {
+            // The body vanished between the residence check and this read — leave it to
+            // the claimability path to report `lost`; do not synthesise a guard error.
+            return;
+        }
+        if (extractPromptSection(show.stdout) === undefined) {
+            throw new ClaimUsageError(`'${slug}' (${bodyRel}) has no '## Prompt' section, so it is not ` +
+                'dispatchable — add a `## Prompt` section to the task body before ' +
+                'claiming it. NO lock was acquired.');
+        }
+    }
+    // UNIFIED PER-ITEM LOCK — the WHOLE of the claim now (prd
+    // `ledger-status-per-item-lock-refs` US #1/#15/#16; ADR
+    // `ledger-status-on-per-item-lock-refs`). The interim dual-write is GONE: claim
+    // acquires the item's per-item lock (`action: implement`) and writes NOTHING to
+    // `main` — the body STAYS at `work/backlog/<slug>.md`, the claimable predicate is
+    // "in `backlog/` on `main` AND no lock held", and the held lock IS the claim. So
+    // a protected-`main` repo can be claimed (claim touches no protected ref).
+    //
+    // A dry-run takes no lock (it mutates nothing) and just reports it WOULD claim.
+    /** The not-found diagnostic, naming the pool (and staging under the flag). */
+    const notFoundFallback = options.allowBacklog === true
+        ? `neither '${backlog}' nor '${staged}' found on ${arbiter}/main (already done/removed, or wrong slug).`
+        : `'${backlog}' not found on ${arbiter}/main (already done/removed, or wrong slug).`;
+    if (dryRun) {
+        await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+        const bodyRel = await claimableBodyRel();
+        if (bodyRel === undefined) {
+            const message = await lostMessage(slug, arbiter, cwd, env, notFoundFallback);
+            note(message);
+            return { exitCode: 2, outcome: 'lost', message };
+        }
+        // A dry-run still runs the pre-claim well-formedness guard so it reports a
+        // promptless body as a usage error rather than "would claim" it.
+        await assertBodyWellFormed(bodyRel);
+        const message = `DRY-RUN: would acquire the per-item lock for '${slug}' (body stays in ${residenceFolder(bodyRel)}/).`;
+        note(message);
+        return { exitCode: 0, outcome: 'claimed', message };
+    }
+    // PRE-CLAIM WELL-FORMEDNESS GUARD: fetch + read the claimable body and refuse a
+    // task missing its `## Prompt` BEFORE the lock is acquired (so a malformed body
+    // never strands a `state: stuck` lock at dispatch). A genuinely absent body is
+    // left to the post-lock claimability re-check to report as `lost`; this guard
+    // only fires for a body that DOES rest claimable but is not dispatchable.
+    await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+    {
+        const bodyRel = await claimableBodyRel();
+        if (bodyRel !== undefined) {
+            await assertBodyWellFormed(bodyRel);
+        }
+    }
+    // Acquire the lock FIRST. A lock `lost` (someone already holds this SAME item's
+    // lock) makes claim lose DEFINITIVELY — exit 2, NO retry budget (a per-item ref
+    // never falsely contends, so a rejection is a GENUINE same-item conflict the
+    // loser should lose). We do NOT try to tell "our own orphaned lock" apart by
+    // holder identity and auto-reclaim it: holder ids are NOT unique (a CI bot claims
+    // many items under one `user.name`), so a release+re-acquire "reclaim" could let a
+    // concurrent LOSER release the WINNER's still-valid lock — and an automatic sweep
+    // contradicts the ADR's recovery model (`ledger-status-on-per-item-lock-refs`:
+    // "no liveness heartbeat, no auto-sweep; a human asserts a lock is dead"). A
+    // genuinely orphaned lock is cleared by the human-mediated `release-lock` verb +
+    // `gc --ledger` report, never an auto-steal at claim time.
+    const lock = await acquireItemLock({
+        item: `task:${slug}`,
+        action: 'implement',
+        cwd,
+        arbiter,
+        env,
+    });
+    if (lock.outcome === 'error') {
+        // Environment/usage problem acquiring the lock — surface as exit 1, never a
+        // false claim. Nothing was acquired.
+        throw new ClaimUsageError(`failed to acquire the item lock for '${slug}': ${lock.message}`);
+    }
+    if (lock.outcome === 'lost') {
+        const message = await lostMessage(slug, arbiter, cwd, env, lock.message);
+        note(message);
+        return { exitCode: 2, outcome: 'lost', message };
+    }
+    /** Release the lock we just acquired (best-effort) — used when the claimability
+     * re-check finds the item is no longer in the pool, so the lock is never
+     * orphaned (the body never moved, so the item is cleanly returned to the pool). */
+    async function releaseHeldLock() {
+        await releaseItemLock({ item: `task:${slug}`, cwd, arbiter, env });
+    }
+    // The RESOLVED claimable residence (`tasks/ready/` or, under `--allow-backlog`,
+    // `tasks/backlog/`), captured by the post-lock claimability re-check below so the
+    // success message reports the real folder rather than a hard-coded guess.
+    let claimedBodyRel;
+    try {
+        // CLAIMABLE PREDICATE (US #15): "in `tasks/ready/` (the pool) on `main` AND no
+        // lock held" \u2014 widened under `--allow-backlog` to ALSO accept a
+        // `tasks/backlog/`-resident body (staging), so a human can drive a staged task
+        // in place. The HELD-LOCK half is the create-only acquire above (a held slug
+        // already lost the race). Confirm the residence here \u2014 the body STAYS where it
+        // rested (claim moves nothing, even under the flag), so a `done`/absent item is
+        // not claimable: release the lock we just took (it never protected any in-flight
+        // work) and lose (exit 2).
+        await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+        claimedBodyRel = await claimableBodyRel();
+        if (claimedBodyRel === undefined) {
+            await releaseHeldLock();
+            const message = await lostMessage(slug, arbiter, cwd, env, notFoundFallback);
+            note(message);
+            return { exitCode: 2, outcome: 'lost', message };
+        }
+    }
+    catch (err) {
+        // A plumbing failure after we took the lock: release it so the held lock does
+        // not orphan an item that never started, then re-throw for the top-level
+        // handler to classify (exit 1).
+        await releaseHeldLock();
+        throw err;
+    }
+    // CLAIMED. The body rests where it was claimed from (`tasks/ready/` normally, or
+    // `tasks/backlog/` under `--allow-backlog`) on `<arbiter>/main` and the lock is
+    // held. There is NO claim commit and nothing on `main` to branch from —
+    // onboarding cuts the work branch straight off `<arbiter>/main` (which carries the
+    // body). The folder is the RESOLVED residence, not a hard-coded guess: a `ready/`
+    // claim must not falsely report `backlog/` (it misled a whole CI-incident triage).
+    // `claimedBodyRel` is always set here (the claimability re-check above returns
+    // `lost` otherwise); fall back to the pool residence (`backlog` IS the
+    // `tasks-ready` path constant) for type-safety — derived via the layout helper,
+    // never a raw `work/<folder>` literal (the work-layout guard).
+    const residence = residenceFolder(claimedBodyRel ?? backlog);
+    const message = `CLAIMED '${slug}' (lock held; body stays in ${residence}/ on ${arbiter}/main).`;
+    note(message);
+    note(`Start work:  git fetch ${arbiter} && git switch -C ${branch} ${arbiter}/main`);
+    return { exitCode: 0, outcome: 'claimed', message };
+}
+/** `git cat-file -e <object>` — true iff the object exists. */
+async function catFileExists(object, cwd, env) {
+    return (await gitSoft(['cat-file', '-e', object], cwd, env)).status === 0;
+}
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(args, cwd, env) {
+    const result = await runAsync('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+//# sourceMappingURL=claim-cas.js.map

package/dist/claim-cas.js.map

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

package/dist/cli-spinner.d.ts

@@ -0,0 +1,112 @@
+/**
+ * A small, isolated terminal-spinner helper for the standalone
+ * `dorfl claim <slug>` CLI command (prd/task `claim-cas-spinner`).
+ *
+ * The push the claim CAS performs can take a few seconds (network +
+ * arbiter round-trip), so the terminal looked frozen. This helper wraps
+ * ONLY that CLI call site: it animates a single-line spinner on stderr
+ * while {@link import('./claim-cas.js').performClaim} is in flight, and
+ * tears it down cleanly on completion / SIGINT / a thrown error.
+ *
+ * Design constraints (all surfaced as injected seams so the helper is
+ * unit-testable without real timers or a real TTY):
+ *   - `stream`   — the WritableStream sink (stderr in production).
+ *   - `isTTY`    — whether to animate at all. Defaults to `false` (the
+ *                  non-TTY path), so tests stay deterministic by default.
+ *   - `clock`    — `setInterval` / `clearInterval` pair. Defaults to a
+ *                  no-op pair (no real timers in tests).
+ *
+ * Output contract:
+ *   - In NON-TTY mode the helper is a pure no-op for animation. `note`
+ *     writes `>> <message>\n` to the stream (byte-identical to today's
+ *     `console.error('>> ' + message)`); `finish(result)` writes
+ *     `error: <message>\n` ONLY on a non-zero exit (byte-identical to
+ *     today's `if (result.exitCode !== 0) console.error('error: ' + ...)`).
+ *     No new status line is introduced — silent on success, exactly as
+ *     today's CLI tests and CI log scrapers expect.
+ *   - In TTY mode the spinner frame is drawn/redrawn on a fake-clock
+ *     tick; `note(message)` clears the current frame, writes the note
+ *     line, then redraws (so notes and frames never trample each other);
+ *     `finish(result)` clears the frame, restores the cursor, and writes
+ *     ONE terminal status line describing the outcome.
+ *   - `stop()` is the pure teardown path used for SIGINT / a thrown
+ *     error: clear the frame, restore the cursor, NO status line.
+ *
+ * This module is consumed ONLY by the `dorfl claim <slug>` CLI
+ * surface in `cli.ts`. The autonomous `performClaim` call sites
+ * (`do.ts`, `run.ts`, `start.ts`, `work-on.ts`, `continue-branch.ts`)
+ * are explicitly OUT OF SCOPE and MUST NOT be wrapped — the claim-cas
+ * return contract, exit codes, and seam contract are unchanged.
+ */
+import type { ClaimCasResult } from './claim-cas.js';
+/** The clock seam: `setInterval` / `clearInterval`, faked in tests. */
+export interface SpinnerClock {
+    setInterval: (fn: () => void, ms: number) => unknown;
+    clearInterval: (handle: unknown) => void;
+}
+/** The minimal writable surface the spinner needs (stderr in production). */
+export interface SpinnerStream {
+    write(chunk: string): boolean;
+}
+export interface CreateClaimSpinnerOptions {
+    /** The sink the spinner animates / notes / status line are written to. */
+    stream: SpinnerStream;
+    /**
+     * Whether to animate at all. Defaults to `false` — the non-TTY path,
+     * which is a no-op for animation and keeps stderr byte-identical to
+     * today. Production passes `process.stdout.isTTY === true`.
+     */
+    isTTY?: boolean;
+    /**
+     * The `setInterval`/`clearInterval` seam. Defaults to a NO-OP pair so a
+     * test that forgets to inject a fake clock cannot accidentally spin a
+     * real timer (and so the non-TTY default truly never starts one).
+     * Production passes the global timers.
+     */
+    clock?: SpinnerClock;
+    /** The short label drawn next to the animating frame (e.g. `Claiming alpha…`). */
+    label: string;
+    /** Frame cadence in ms. Default 80ms (a calm braille spinner). */
+    intervalMs?: number;
+    /** The animation frames. Default: the standard 10-frame braille spinner. */
+    frames?: readonly string[];
+}
+export interface ClaimSpinner {
+    /** True iff this spinner instance will actually animate (TTY mode). */
+    readonly isTTY: boolean;
+    /** Begin animating (no-op in non-TTY mode, or if already started). */
+    start(): void;
+    /**
+     * Route the `performClaim` `note` callback through the spinner. In TTY
+     * mode this clears the current frame, writes `>> <message>\n`, then
+     * redraws the frame so notes and frames never trample each other. In
+     * non-TTY mode it writes the line directly — byte-identical to today.
+     */
+    note(message: string): void;
+    /**
+     * Finish with the claim result. In TTY mode: tear down (clear frame,
+     * restore cursor) and emit ONE terminal status line describing the
+     * outcome. In non-TTY mode: emit `error: <message>` ONLY on a non-zero
+     * exit, otherwise stay silent — byte-identical to today's CLI.
+     */
+    finish(result: ClaimCasResult): void;
+    /**
+     * Pure teardown for SIGINT / a thrown error: clear the frame and
+     * restore the cursor. NO status line. Safe to call multiple times.
+     */
+    stop(): void;
+}
+/**
+ * Format the single terminal status line that replaces the spinner in TTY
+ * mode. The outcome label tracks the existing exit-code semantics
+ * (0=claimed / 2=lost (not claimable) / 3=contended / 1=usage-error or
+ * not-ready); `result.message` is reused verbatim as the body.
+ */
+export declare function formatClaimStatusLine(result: ClaimCasResult): string;
+/**
+ * Build a {@link ClaimSpinner} from injected seams. See the module-level
+ * docstring for the contract; see the per-method JSDoc for the per-method
+ * semantics in TTY vs non-TTY mode.
+ */
+export declare function createClaimSpinner(options: CreateClaimSpinnerOptions): ClaimSpinner;
+//# sourceMappingURL=cli-spinner.d.ts.map

package/dist/cli-spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-spinner.d.ts","sourceRoot":"","sources":["../src/cli-spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAC;AAEnD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC5B,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACzC;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,yBAAyB;IACzC,0EAA0E;IAC1E,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;CACb;AA2BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAcpE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,yBAAyB,GAChC,YAAY,CAkEd"}

package/dist/cli-spinner.js

@@ -0,0 +1,157 @@
+/**
+ * A small, isolated terminal-spinner helper for the standalone
+ * `dorfl claim <slug>` CLI command (prd/task `claim-cas-spinner`).
+ *
+ * The push the claim CAS performs can take a few seconds (network +
+ * arbiter round-trip), so the terminal looked frozen. This helper wraps
+ * ONLY that CLI call site: it animates a single-line spinner on stderr
+ * while {@link import('./claim-cas.js').performClaim} is in flight, and
+ * tears it down cleanly on completion / SIGINT / a thrown error.
+ *
+ * Design constraints (all surfaced as injected seams so the helper is
+ * unit-testable without real timers or a real TTY):
+ *   - `stream`   — the WritableStream sink (stderr in production).
+ *   - `isTTY`    — whether to animate at all. Defaults to `false` (the
+ *                  non-TTY path), so tests stay deterministic by default.
+ *   - `clock`    — `setInterval` / `clearInterval` pair. Defaults to a
+ *                  no-op pair (no real timers in tests).
+ *
+ * Output contract:
+ *   - In NON-TTY mode the helper is a pure no-op for animation. `note`
+ *     writes `>> <message>\n` to the stream (byte-identical to today's
+ *     `console.error('>> ' + message)`); `finish(result)` writes
+ *     `error: <message>\n` ONLY on a non-zero exit (byte-identical to
+ *     today's `if (result.exitCode !== 0) console.error('error: ' + ...)`).
+ *     No new status line is introduced — silent on success, exactly as
+ *     today's CLI tests and CI log scrapers expect.
+ *   - In TTY mode the spinner frame is drawn/redrawn on a fake-clock
+ *     tick; `note(message)` clears the current frame, writes the note
+ *     line, then redraws (so notes and frames never trample each other);
+ *     `finish(result)` clears the frame, restores the cursor, and writes
+ *     ONE terminal status line describing the outcome.
+ *   - `stop()` is the pure teardown path used for SIGINT / a thrown
+ *     error: clear the frame, restore the cursor, NO status line.
+ *
+ * This module is consumed ONLY by the `dorfl claim <slug>` CLI
+ * surface in `cli.ts`. The autonomous `performClaim` call sites
+ * (`do.ts`, `run.ts`, `start.ts`, `work-on.ts`, `continue-branch.ts`)
+ * are explicitly OUT OF SCOPE and MUST NOT be wrapped — the claim-cas
+ * return contract, exit codes, and seam contract are unchanged.
+ */
+const DEFAULT_FRAMES = [
+    '⠋',
+    '⠙',
+    '⠹',
+    '⠸',
+    '⠼',
+    '⠴',
+    '⠦',
+    '⠧',
+    '⠇',
+    '⠏',
+];
+const DEFAULT_INTERVAL_MS = 80;
+// Bare ANSI for hide-cursor / show-cursor / clear-current-line — kept tiny and
+// inline so the helper has no runtime dependency. Only emitted in TTY mode.
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+const NOOP_CLOCK = {
+    setInterval: () => undefined,
+    clearInterval: () => undefined,
+};
+/**
+ * Format the single terminal status line that replaces the spinner in TTY
+ * mode. The outcome label tracks the existing exit-code semantics
+ * (0=claimed / 2=lost (not claimable) / 3=contended / 1=usage-error or
+ * not-ready); `result.message` is reused verbatim as the body.
+ */
+export function formatClaimStatusLine(result) {
+    switch (result.outcome) {
+        case 'claimed':
+            return `✓ claimed — ${result.message}`;
+        case 'lost':
+            return `✗ not claimable — ${result.message}`;
+        case 'contended':
+            return `✗ contended — ${result.message}`;
+        case 'not-ready':
+            return `✗ not ready — ${result.message}`;
+        case 'usage-error':
+        default:
+            return `✗ error — ${result.message}`;
+    }
+}
+/**
+ * Build a {@link ClaimSpinner} from injected seams. See the module-level
+ * docstring for the contract; see the per-method JSDoc for the per-method
+ * semantics in TTY vs non-TTY mode.
+ */
+export function createClaimSpinner(options) {
+    const stream = options.stream;
+    const isTTY = options.isTTY === true;
+    const clock = options.clock ?? NOOP_CLOCK;
+    const frames = options.frames ?? DEFAULT_FRAMES;
+    const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const label = options.label;
+    let handle;
+    let frameIndex = 0;
+    let active = false;
+    const drawFrame = () => {
+        stream.write(`${frames[frameIndex % frames.length]} ${label}`);
+    };
+    const clearFrame = () => {
+        stream.write(CLEAR_LINE);
+    };
+    const teardown = () => {
+        if (!active)
+            return;
+        clock.clearInterval(handle);
+        handle = undefined;
+        clearFrame();
+        stream.write(SHOW_CURSOR);
+        active = false;
+    };
+    return {
+        isTTY,
+        start() {
+            if (!isTTY || active)
+                return;
+            active = true;
+            stream.write(HIDE_CURSOR);
+            drawFrame();
+            handle = clock.setInterval(() => {
+                frameIndex = (frameIndex + 1) % frames.length;
+                clearFrame();
+                drawFrame();
+            }, intervalMs);
+        },
+        note(message) {
+            if (!isTTY) {
+                // Non-TTY: byte-identical to today's `console.error('>> ' + msg)`.
+                stream.write(`>> ${message}\n`);
+                return;
+            }
+            if (active)
+                clearFrame();
+            stream.write(`>> ${message}\n`);
+            if (active)
+                drawFrame();
+        },
+        finish(result) {
+            if (isTTY) {
+                teardown();
+                stream.write(`${formatClaimStatusLine(result)}\n`);
+                return;
+            }
+            // Non-TTY: silent on success, `error: <message>` on failure —
+            // byte-identical to today's CLI behaviour.
+            if (result.exitCode !== 0) {
+                stream.write(`error: ${result.message}\n`);
+            }
+        },
+        stop() {
+            teardown();
+        },
+    };
+}
+//# sourceMappingURL=cli-spinner.js.map

package/dist/cli-spinner.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare function buildProgram(): Command;
+/**
+ * Run the CLI: build the program and parse argv. Split from {@link buildProgram}
+ * so tests can build + introspect/parse the program WITHOUT triggering a real
+ * argv parse + `process.exit` on import (the module-level bootstrap below only
+ * fires when this file is the process entry point).
+ */
+export declare function runCli(argv?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,OAAO,EAAS,MAAM,WAAW,CAAC;AA2nC1C,wBAAgB,YAAY,IAAI,OAAO,CA8gGtC;AA+FD;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzE"}