dorfl 0.0.0 → 0.1.0

package/dist/merge-question-surfacer.d.ts.map

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

package/dist/merge-question-surfacer.js

@@ -0,0 +1,297 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './git.js';
+import { isGitHubArbiterUrl, DEFAULT_GH_BIN } from './github.js';
+import { parseSidecar, sidecarPathFor, isEntryAnswered, } from './sidecar.js';
+import { persistSurfacedQuestions, } from './surface-persist.js';
+import { workItemRel } from './work-layout.js';
+/** Raised for fatal usage errors (a missing repo, etc.). */
+export class MergeQuestionSurfacerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MergeQuestionSurfacerError';
+    }
+}
+/** The lifecycle folders a task body may rest in (the FOLDERS the persist
+ * needs to find the item file to set `needsAnswers:true` on). Matches
+ * `advance.ts`'s `findItemPath` task-folder set. */
+const TASK_FOLDERS = [
+    'tasks-ready',
+    'tasks-backlog',
+    'done',
+    'cancelled',
+];
+/**
+ * Surface merge-questions for every unmerged `work/*` branch in `cwd`.
+ *
+ * The FLOOR (git reachability) is authoritative; the CEILING (`gh pr list`)
+ * runs only when {@link isGitHubArbiterUrl} accepts the arbiter URL, and is
+ * pure enrichment (a missing/failed `gh` degrades silently — the floor still
+ * surfaces the question).
+ *
+ * Idempotency: a branch whose sidecar ALREADY carries a PENDING `kind: merge`
+ * entry is SKIPPED (with `already-pending-merge-question`). A branch with no
+ * item body on `main` is SKIPPED (with `no-item-body`) — the cross-cutting
+ * branch-keyed sidecar identity (PRD sidecar Q5-i) is OOS for this task; an
+ * unmerged-branch-with-no-body lands on the same skip path until that
+ * generalisation arrives.
+ */
+export function surfaceMergeQuestions(options) {
+    const { cwd } = options;
+    const base = options.base ?? 'main';
+    const env = options.env;
+    const note = options.note ?? (() => { });
+    const persist = options.persist ?? persistSurfacedQuestions;
+    const listBranches = options.listUnmergedWorkBranches ?? listUnmergedWorkBranchesViaGit;
+    const branches = listBranches({ cwd, base, env });
+    // CEILING: only consult `gh pr list` when the arbiter is GitHub-shaped. A
+    // bare / non-GitHub arbiter never spawns `gh` (the floor is sufficient).
+    let prs = new Map();
+    const ghEnabled = options.arbiterUrl !== undefined && isGitHubArbiterUrl(options.arbiterUrl);
+    if (ghEnabled && branches.length > 0) {
+        const listPRs = options.listOpenPullRequests ?? listOpenPullRequestsViaGh;
+        try {
+            prs = listPRs({
+                cwd,
+                ghBin: options.ghBin ?? DEFAULT_GH_BIN,
+                base,
+                env,
+            });
+        }
+        catch (err) {
+            // `gh` is the ENRICHMENT layer — a failure must NEVER suppress the
+            // floor's surfacing. Note it and proceed with an empty PR map.
+            const detail = err instanceof Error ? err.message : String(err);
+            note(`merge-question surfacer: gh pr list failed (${detail}) — continuing with the git-only floor.`);
+            prs = new Map();
+        }
+    }
+    const surfaced = [];
+    const skipped = [];
+    for (const branch of branches) {
+        const item = `task:${branch.slug}`;
+        // Idempotency: if the sidecar already carries a PENDING `kind: merge`
+        // entry, this surfacer must not append a duplicate. (An ANSWERED merge
+        // entry is fine — apply will dispatch it; appending a new entry would
+        // re-pause the sidecar unnecessarily.)
+        if (alreadyHasPendingMergeQuestion(cwd, item)) {
+            skipped.push({
+                ref: branch.ref,
+                slug: branch.slug,
+                reason: 'already-pending-merge-question',
+            });
+            continue;
+        }
+        const itemPath = findTaskItemPath(cwd, branch.slug);
+        if (itemPath === undefined) {
+            // The `branch:`/`ref:`-keyed sidecar identity (PRD sidecar Q5-i, the
+            // cross-cutting open question SHARED with the stuck-lock surfacer) is
+            // OUT OF SCOPE for this task — without a body to flip `needsAnswers`
+            // on, persist would tear the invariant. Skip with the reason so the
+            // case is visible to the caller.
+            skipped.push({
+                ref: branch.ref,
+                slug: branch.slug,
+                reason: 'no-item-body',
+            });
+            continue;
+        }
+        const pr = prs.get(branch.ref);
+        const question = buildMergeQuestion(branch, pr);
+        const result = persist({
+            cwd,
+            item,
+            itemPath,
+            questions: [question],
+            env,
+            note,
+        });
+        if (result.outcome === 'nothing') {
+            skipped.push({
+                ref: branch.ref,
+                slug: branch.slug,
+                reason: 'persist-nothing',
+            });
+            continue;
+        }
+        surfaced.push({
+            item,
+            slug: branch.slug,
+            ref: branch.ref,
+            sidecarPath: result.sidecarPath,
+            commit: result.commit,
+            prUrl: pr?.url,
+        });
+    }
+    return { considered: branches.length, surfaced, skipped };
+}
+/**
+ * Build the merge-question for ONE unmerged branch.
+ *
+ *   - The QUESTION is a plain English "should this branch land?" prompt.
+ *   - The CONTEXT carries the floor evidence (the unmerged branch ref) and, if
+ *     a host PR matched, the ceiling enrichment (PR number, url, title).
+ *   - The DEFAULT carries `merge | hold | drop` as a HUMAN-READABLE HINT only.
+ *     The MACHINE dispatch signal is `kind: merge`, NEVER the shape of
+ *     `default` (the workaround the first build was blocked for).
+ *   - The KIND is the typed dispatch axis from `sidecar-kind-field` —
+ *     `kind: merge` is what the apply rung reads to route the answer to the
+ *     deterministic land primitive.
+ */
+function buildMergeQuestion(branch, pr) {
+    const contextLines = [
+        `The branch \`${branch.ref}\` is not reachable from \`main\` — it carries pushed work that has not yet landed.`,
+    ];
+    if (pr !== undefined) {
+        const titleSuffix = pr.title ? `: ${pr.title}` : '';
+        const urlSuffix = pr.url ? ` (${pr.url})` : '';
+        const stateSuffix = pr.state ? ` [${pr.state}]` : '';
+        contextLines.push(`Open PR #${pr.number}${stateSuffix}${titleSuffix}${urlSuffix}.`);
+    }
+    else {
+        contextLines.push(`No host PR metadata available (git-alone floor — the branch is the source of truth).`);
+    }
+    return {
+        question: `Land \`${branch.ref}\`? An unmerged \`work/*\` branch is awaiting an integration decision.`,
+        context: contextLines.join('\n'),
+        // HUMAN HINT only — the apply layer MUST NOT string-sniff this.
+        default: 'merge | hold | drop',
+        // MACHINE dispatch signal — the apply layer routes on this, not on `default`.
+        kind: 'merge',
+    };
+}
+/** Probe the sidecar for an existing pending `kind: merge` entry. */
+function alreadyHasPendingMergeQuestion(cwd, item) {
+    const rel = sidecarPathFor(item);
+    const abs = join(cwd, rel);
+    if (!existsSync(abs)) {
+        return false;
+    }
+    try {
+        const model = parseSidecar(readFileSync(abs, 'utf8'));
+        return model.entries.some((e) => e.kind === 'merge' && !isEntryAnswered(e));
+    }
+    catch {
+        // A malformed sidecar is not THIS surfacer's problem — pretend there is
+        // no pending merge-question and let the persist write surface the issue.
+        return false;
+    }
+}
+/** Locate the task body `work/<folder>/<slug>.md` across lifecycle folders. */
+function findTaskItemPath(cwd, slug) {
+    for (const folder of TASK_FOLDERS) {
+        const rel = workItemRel(folder, `${slug}.md`);
+        if (existsSync(join(cwd, rel))) {
+            return rel;
+        }
+    }
+    return undefined;
+}
+// --- Production seams ----------------------------------------------------
+function gitSoft(args, cwd, env) {
+    return run('git', args, cwd, { env });
+}
+/**
+ * Production FLOOR: enumerate every `refs/heads/work/*` whose tip is NOT
+ * reachable from `<base>`. A repo with no `<base>` (e.g. a fresh init before
+ * the first commit) yields the empty list — the surfacer is a no-op until
+ * `main` exists.
+ */
+export function listUnmergedWorkBranchesViaGit(input) {
+    const { cwd, base, env } = input;
+    // Bail if `<base>` does not resolve — without a base, "unmerged" is
+    // meaningless and we'd over-surface every branch as unmerged.
+    const haveBase = gitSoft(['rev-parse', '--verify', '--quiet', base], cwd, env);
+    if (haveBase.status !== 0) {
+        return [];
+    }
+    const refs = gitSoft([
+        'for-each-ref',
+        '--format=%(refname:short) %(objectname)',
+        'refs/heads/work/',
+    ], cwd, env);
+    if (refs.status !== 0) {
+        return [];
+    }
+    const lines = refs.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '');
+    const unmerged = [];
+    for (const line of lines) {
+        const space = line.indexOf(' ');
+        if (space === -1) {
+            continue;
+        }
+        const ref = line.slice(0, space);
+        const sha = line.slice(space + 1).trim();
+        if (!ref.startsWith('work/')) {
+            continue;
+        }
+        const slug = ref.slice('work/'.length);
+        if (slug === '') {
+            continue;
+        }
+        // `git merge-base --is-ancestor <sha> <base>` — exit 0 ⇒ reachable
+        // (merged), exit 1 ⇒ unmerged.
+        const reach = gitSoft(['merge-base', '--is-ancestor', sha, base], cwd, env);
+        if (reach.status !== 0) {
+            unmerged.push({ ref, slug, sha });
+        }
+    }
+    return unmerged;
+}
+/**
+ * Production CEILING: shell `gh pr list --state open --json …` and index the
+ * results by their `headRefName` so the surfacer can enrich the matching
+ * branch's question. A non-zero / missing `gh` is treated as "no host
+ * metadata available" — the floor still surfaces every unmerged branch.
+ */
+export function listOpenPullRequestsViaGh(input) {
+    const { cwd, ghBin, base, env } = input;
+    const result = run(ghBin, [
+        'pr',
+        'list',
+        '--state',
+        'open',
+        '--base',
+        base,
+        '--limit',
+        '200',
+        '--json',
+        'number,url,title,headRefName,state',
+    ], cwd, { env });
+    if (result.status !== 0) {
+        return new Map();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return new Map();
+    }
+    if (!Array.isArray(parsed)) {
+        return new Map();
+    }
+    const out = new Map();
+    for (const raw of parsed) {
+        if (typeof raw !== 'object' || raw === null) {
+            continue;
+        }
+        const r = raw;
+        const headRefName = typeof r.headRefName === 'string' ? r.headRefName : '';
+        const number = typeof r.number === 'number' ? r.number : undefined;
+        if (headRefName === '' || number === undefined) {
+            continue;
+        }
+        out.set(headRefName, {
+            number,
+            url: typeof r.url === 'string' ? r.url : undefined,
+            title: typeof r.title === 'string' ? r.title : undefined,
+            state: typeof r.state === 'string' ? r.state : undefined,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=merge-question-surfacer.js.map

package/dist/merge-question-surfacer.js.map

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

package/dist/mint-adr.d.ts

@@ -0,0 +1,126 @@
+import { type CasContentionBudget } from './advancing-lock.js';
+/** Raised for usage errors (an empty slug, an unreadable observation). */
+export declare class MintAdrError extends Error {
+    constructor(message: string);
+}
+/**
+ * The repo-relative `docs/adr/` home for minted ADRs. ADRs live OUTSIDE the
+ * `work/` governance tree (so they are NOT in `work-layout.ts`'s registry); this
+ * is the single literal the route roots its target on. `docs/adr/` is created
+ * lazily by {@link createItemThroughCas} (it `mkdir -p`s the target's dirname).
+ */
+export declare const ADR_DIR_REL = "docs/adr";
+/** The repo-relative path of a minted ADR file: `docs/adr/<slug>.md`. */
+export declare function adrItemRel(slug: string): string;
+export interface MintAdrOptions {
+    /** Working clone/worktree the mint runs in. */
+    cwd: string;
+    /** The namespaced source identity (`observation:<slug>`). */
+    item: string;
+    /** The source item file path RELATIVE to `cwd` (e.g. `work/notes/observations/foo.md`). */
+    itemPath: string;
+    /**
+     * The ADR slug to draft. Defaults to the source observation's own slug, so the
+     * minted ADR is `docs/adr/<obs-slug>.md`. The CAS is keyed on the new ADR's
+     * PATH, so a same-slug ADR race ⇒ the loser fails the CAS and backs off.
+     */
+    adrSlug?: string;
+    /**
+     * The ADR's short title (the `# {title}` heading line). Defaults to the slug
+     * when absent.
+     */
+    adrTitle?: string;
+    /**
+     * The ADR's content — the markdown AFTER the frontmatter (the
+     * context/decision/why record). When omitted, a SELF-CONTAINED body is built
+     * FROM the source observation + its answered question(s) (see
+     * {@link buildAdrBody}), so the decision's WHY is carried in and the source is
+     * safely deletable.
+     */
+    adrBody?: string;
+    /**
+     * The answered question(s) + answers the decision rests on, carried into the
+     * built body's Context/Decision when no explicit `adrBody` is supplied (so the
+     * minted ADR is self-contained even without an agent-drafted body).
+     */
+    answers?: {
+        question: string;
+        answer: string;
+    }[];
+    /** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
+    arbiter?: string;
+    /** Advisory committer id for the commit subject. Defaults to git user.name. */
+    by?: string;
+    /** Environment for child git processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Show the intended CAS push without mutating the arbiter (`--dry-run`). */
+    dryRun?: boolean;
+    /**
+     * The CAS CONTENTION-RETRY BUDGET (jittered inter-retry delay + widened
+     * attempt / wall-clock envelope). Threaded through to
+     * {@link createItemThroughCas}. The lifecycle driver passes
+     * `LIFECYCLE_CAS_CONTENTION` here so a propose-tick FAN-OUT of parallel
+     * `mint-adr` legs desynchronises and DRAINS instead of thrashing to `contended`.
+     * Absent ⇒ the interactive default (3 retries, no delay).
+     */
+    contention?: CasContentionBudget;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+export interface MintAdrResult {
+    /**
+     * `minted` (the ADR landed via the CAS + the observation+sidecar were deleted
+     * in the SAME commit), `lost` (the same-slug ADR race was lost — the loser backs
+     * off, observation left INTACT), or `contended` (the CAS push kept failing).
+     * Maps onto the claim-CAS exit codes.
+     */
+    outcome: 'minted' | 'lost' | 'contended' | 'usage-error';
+    exitCode: 0 | 1 | 2 | 3;
+    /** The new ADR's path (relative to repo root) on a WIN. */
+    adrPath?: string;
+    /** A human-readable summary. */
+    message: string;
+}
+/**
+ * Mint a NEW, SELF-CONTAINED ADR FROM an answered observation (the agentic apply
+ * `mint-adr` verdict, US #2): CAS-create `docs/adr/<slug>.md` keyed on the new
+ * ADR's identity (its path), with the source observation + its answered sidecar
+ * `git rm`-ed IN THE SAME atomic commit. The mint is ONE commit (create + delete).
+ *
+ * The minted body is built FROM the source + the answered question(s) (see
+ * {@link buildAdrBody}) so an engineer can read the decision's WHY from the ADR
+ * ALONE — that self-containment is the PRECONDITION for the same-commit deletion
+ * of the source. An agent-drafted `adrBody` (when present) is used verbatim.
+ *
+ * The CAS-create is the new-item-creation helper ({@link createItemThroughCas}):
+ * a same-slug ADR race needs NO special case — exactly one creator lands the
+ * file, the LOSER fails the CAS (exit 2) and backs off WITHOUT deleting the
+ * source (so a retry can re-mint). The source (+ its sidecar) is deleted ONLY on a
+ * WIN, riding the winning creator's commit.
+ */
+export declare function mintAdr(options: MintAdrOptions): Promise<MintAdrResult>;
+/**
+ * Build a SELF-CONTAINED ADR file FROM an answered observation + its answer(s),
+ * in the repo's existing `docs/adr/` shape (recorded `## Decisions`): a `---`
+ * frontmatter fence (`title` / `status: accepted` / `created`) then a
+ * `# ADR: {title}` heading and the three ADR-FORMAT sections — **Context**
+ * (the source signal that prompted the decision), **Decision** (what was decided,
+ * from the human's answer), and **Why** (the rationale the answer carries). The
+ * decision's WHY is carried IN (the answer prose), so the ADR reads alone — the
+ * precondition for deleting the source in the same commit.
+ *
+ * The mechanism prose of the observation (everything before its first
+ * `## Open questions` heading, frontmatter dropped) seeds Context; the
+ * question(s)+answer(s) seed Decision + Why. When no answers are threaded the
+ * Decision/Why fall back to the observation's prose so the file is never empty.
+ */
+export declare function buildAdrBody(input: {
+    slug: string;
+    title: string;
+    observation: string;
+    answers: {
+        question: string;
+        answer: string;
+    }[];
+}): string;
+//# sourceMappingURL=mint-adr.d.ts.map

package/dist/mint-adr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint-adr.d.ts","sourceRoot":"","sources":["../src/mint-adr.ts"],"names":[],"mappings":"AAGA,OAAO,EAEN,KAAK,mBAAmB,EAExB,MAAM,qBAAqB,CAAC;AAqE7B,0EAA0E;AAC1E,qBAAa,YAAa,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,MAAM,WAAW,cAAc;IAC9B,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAC/C,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,aAAa,CAAC;IACzD,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAgE7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;CAC9C,GAAG,MAAM,CAmCT"}