dorfl 0.0.0 → 0.1.0

package/dist/start.d.ts

@@ -0,0 +1,97 @@
+import type { InteractiveLauncher } from './harness.js';
+/**
+ * `dorfl start [<slug>]` — the human convenience that claims a task (only
+ * if necessary) and onboards the human onto its work branch in their CURRENT
+ * checkout. It is a thin sequencer over the `claim` CAS (claim-cas.ts): it never
+ * reimplements or weakens the claim, and it creates the work branch ONLY after a
+ * claim provably lands.
+ *
+ * The decision of WHAT to do is made on the item's current FOLDER on
+ * `<arbiter>/main` — never on the advisory `claimed_by` frontmatter field
+ * (WORK-CONTRACT rule 6: the folder + git history are the source of truth).
+ *
+ *   work/backlog/<slug>.md     → claim it; on a winning claim, switch to
+ *                                work/<slug> off the arbiter. On a lost/contended
+ *                                claim, behave exactly like `claim`: user
+ *                                restored, NO work branch, exit code propagated.
+ *   work/in-progress/<slug>.md → already claimed. Refuse by default with a clear
+ *                                message; with --resume, switch to work/<slug>
+ *                                off the arbiter WITHOUT claiming (the human
+ *                                explicitly asserts ownership).
+ *   work/needs-attention/<slug>.md → stuck (a runner bounced it). Print the
+ *                                recorded reason, transition it back to
+ *                                in-progress THROUGH the write seam (which in
+ *                                mode M clears the `main` surface via the reverse
+ *                                move), then switch onto work/<slug>. UNGUARDED
+ *                                (no --resume): a stuck item is up-for-grabs, so a
+ *                                human can just pick it up with no manual move.
+ *   work/done/<slug>.md or absent → refuse (nothing to start).
+ *
+ * It is harness-agnostic: it lands the human on the work branch and gets out of
+ * the way. It launches no agent/editor.
+ *
+ * Exit codes:
+ *   0  on the work branch (claimed-and-switched, or resumed)
+ *   1  usage / environment error, or a refusal (in-progress without --resume,
+ *      done/absent, no slug + not on a work/<slug> branch)
+ *   2  lost the race (propagated from `claim`)
+ *   3  contended (propagated from `claim`)
+ */
+export type StartOutcome = 'started' | 'resumed' | 'resolved' | 'needs-attention' | 'surface-unmoved' | 'refused' | 'lost' | 'contended' | 'usage-error';
+export interface StartOptions {
+    /** The slug to start. If omitted, inferred from a `work/<slug>` branch. */
+    slug?: string;
+    /** The working clone/checkout to onboard the human into. */
+    cwd: string;
+    /** Name of the arbiter git remote. Defaults to `origin`. */
+    arbiter?: string;
+    /** Assert ownership of an already-in-progress item (switch without claiming). */
+    resume?: boolean;
+    /**
+     * Override the readiness guard (`--force` / `--ignore-not-ready`): claim a task
+     * with an unmet `blockedBy` anyway, and silence the `needsAnswers` warning —
+     * loudly. Forwarded to the claim CAS's human-path guard.
+     */
+    override?: boolean;
+    /**
+     * `--allow-backlog` (prd
+     * `do-allow-backlog-drive-staged-tasks-without-promotion`): recognise a
+     * `tasks/backlog/`-resident body (staging) as a valid start/onboard residence,
+     * so the no-checkout `do --remote/--isolated … --allow-backlog` flow (which
+     * onboards via `start` after a backlog-aware claim) does not read the staged
+     * task as `absent`. It widens ONLY the folder RESOLUTION (`tasks-backlog` is
+     * treated like the pool for the lock re-key + the backlog onboard); claim/lock/
+     * build are identical. Default off ⇒ staging is invisible, exactly as today.
+     */
+    allowBacklog?: boolean;
+    /**
+     * `--agent` (task `agent-interactive-launch`): after onboarding onto
+     * `work/<slug>`, launch the configured harness INTERACTIVELY in the checkout —
+     * a foreground session the human drives (no prepared prompt). Injected as a
+     * thin launcher so `start.ts` stays decoupled from `createHarness`: the CLI
+     * wires it to the resolved harness's `launchInteractive` (model/session/cwd
+     * resolved there). When omitted, start onboards and gets out of the way (its
+     * historical behaviour, unchanged). It is NOT a tracked job (decision #3): no
+     * job record, no gate — after exit the human drives `complete`/`requeue`.
+     */
+    launchInteractive?: InteractiveLauncher;
+    /** Environment for child git processes (identity etc.). */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+export interface StartResult {
+    exitCode: 0 | 1 | 2 | 3;
+    outcome: StartOutcome;
+    /** The work branch the user landed on, when one was created/switched-to. */
+    branch?: string;
+    /** Human-readable summary of the terminal condition. */
+    message: string;
+}
+/**
+ * Run the start ritual. Never throws for the expected lost/contended/refused
+ * cases — those are returned with the appropriate exit code. Usage/environment
+ * problems and refusals surface as exit 1.
+ */
+export declare function performStart(options: StartOptions): Promise<StartResult>;
+//# sourceMappingURL=start.d.ts.map

package/dist/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,MAAM,YAAY,GACrB,SAAS,GACT,SAAS,GACT,UAAU,GACV,iBAAiB,GACjB,iBAAiB,GACjB,SAAS,GACT,MAAM,GACN,WAAW,GACX,aAAa,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC5B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CAChB;AAsBD;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,GACnB,OAAO,CAAC,WAAW,CAAC,CActB"}