@momentiq/dark-factory-cli 0.7.0-alpha.9 → 1.0.0

package/dist/handoff/accept-verb.d.ts

@@ -0,0 +1,31 @@
+import { type GhClient } from "./ports.js";
+import { type RehydrateData } from "./rehydrate-core.js";
+export interface RunAcceptOptions {
+    readonly issue: number;
+    readonly gh: GhClient;
+}
+export interface RunAcceptResult {
+    readonly issueNumber: number;
+    /**
+     * Rehydrate data — CLI prints via renderRehydrateText (Task 10), MCP
+     * returns as structuredContent.
+     */
+    readonly rehydrate: RehydrateData;
+    /**
+     * Success-path operator info lines (each printed to stderr by the CLI).
+     * Contains exactly the two `log "…"` lines from accept.sh that fire on
+     * the success path: the assign confirmation (step 5) and the close
+     * confirmation (step 7). Fatal paths put their guidance in the thrown
+     * HandoffError message, not here.
+     */
+    readonly logs: readonly string[];
+}
+/**
+ * Take the baton on a handoff issue. Validates → refuses-on-other →
+ * strict-rehydrates → drift-checks → assigns → verifies → closes. Any failure
+ * before step 5 leaves the issue untouched on the stack; a failure between
+ * step 5 and step 7 leaves the issue open + assigned-to-@me (re-run is
+ * idempotent via the updatedAt close-failure retry path in step 4).
+ */
+export declare function runAccept(opts: RunAcceptOptions): Promise<RunAcceptResult>;
+//# sourceMappingURL=accept-verb.d.ts.map

package/dist/handoff/accept-verb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accept-verb.d.ts","sourceRoot":"","sources":["../../src/handoff/accept-verb.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAI9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,eAAe,CAAC,CAiJ1B"}

package/dist/handoff/accept-verb.js

@@ -0,0 +1,165 @@
+// packages/cli/src/handoff/accept-verb.ts
+//
+// /accept atomic chain. PORT FROM dark-factory-platform .claude/skills/handoff/
+// scripts/accept.sh@a6f711b (147 LOC). All read-only work precedes mutations;
+// a failed step leaves the issue unassigned + open on the stack.
+//
+// gh call sequence (the load-bearing race-safety contract — Task 18 asserts
+// this order via FakeGhClient.calls()):
+//   step 1: gh.issueView(issue)       — slot 1 (body-bearing)
+//                  ↓
+//           gh.apiUserLogin()         — lazy; first assigneesStatus(…, me)
+//                                       triggers it, matching bash which
+//                                       calls `me_login` inside the FIRST
+//                                       assignees_status (lib.sh:88) → not
+//                                       before step 1. Eager resolution would
+//                                       reorder apiUserLogin ahead of
+//                                       issueView and break step-1-failure
+//                                       tests + the call-sequence assertion.
+//   step 3: gh.issueView(issue)       — slot 2 (body-bearing; inside
+//                                       deriveRehydrateData)
+//           + per-linked-item gh.prView or gh.issueView (linked-item counter)
+//   step 4: gh.issueViewSlim(issue)   — slot 1 (body-less)
+//   step 5: gh.issueAssignMe(issue)
+//   step 6: gh.issueViewSlim(issue)   — slot 2 (body-less)
+//   step 7: gh.issueClose(issue)
+//
+// Both step 4 and step 6 use issueViewSlim — that's a separate counter from
+// the body-bearing slots (validates step 1 vs the strict-rehydrate step 3).
+//
+// Error-path discipline (advisor catch #1): bash prints `warn "…"` to stderr
+// BEFORE `exit 1`, so the operator sees the detailed guidance ("re-run
+// /accept", "coordinate with @other", etc.). The HandoffError shape is
+// frozen to the v1 surface (message + savedNotePath) for the Tasks 11-22
+// window — there is no field to carry an extra "log line" past a throw. So
+// on every fatal path we throw the DETAILED message itself, and `logs` only
+// carries the two SUCCESS-path info lines that actually reach the return
+// (matches handoff-verb.ts's discipline).
+import { assigneesOtherCsv, assigneesStatus, MeLoginCache, } from "./assignees.js";
+import { validateLatestBlock } from "./markers.js";
+import { HandoffError } from "./ports.js";
+import { deriveRehydrateData } from "./rehydrate-core.js";
+const HANDOFF_LABEL = "handoff";
+/**
+ * Take the baton on a handoff issue. Validates → refuses-on-other →
+ * strict-rehydrates → drift-checks → assigns → verifies → closes. Any failure
+ * before step 5 leaves the issue untouched on the stack; a failure between
+ * step 5 and step 7 leaves the issue open + assigned-to-@me (re-run is
+ * idempotent via the updatedAt close-failure retry path in step 4).
+ */
+export async function runAccept(opts) {
+    const { issue, gh } = opts;
+    const logs = [];
+    const meCache = new MeLoginCache();
+    // --- step 1: validate (read-only) ----------------------------------------
+    let view;
+    try {
+        view = await gh.issueView(issue);
+    }
+    catch {
+        throw new HandoffError(`could not fetch issue #${issue} (gh error) — not mutating.`);
+    }
+    if (view.state === "CLOSED") {
+        throw new HandoffError(`issue #${issue} is closed — the handoff was already accepted.`);
+    }
+    // (view.state is typed `"OPEN" | "CLOSED"` so the bash's catch-all
+    // "unexpected state" branch is unreachable here; left out.)
+    const hasHandoffLabel = view.labels.some((l) => l.name === HANDOFF_LABEL);
+    if (!hasHandoffLabel) {
+        throw new HandoffError(`issue #${issue} is not a handoff issue (no \`${HANDOFF_LABEL}\` label).`);
+    }
+    // The body MUST carry a parseable LATEST agent-context block (matches the
+    // extractor `do_rehydrate` uses — see bash:64-70). A stale-valid + new-
+    // malformed body would pass a first-block check yet render no reasoning,
+    // and accept would close the handoff while losing the artifact it's
+    // supposed to preserve.
+    if (!validateLatestBlock(view.body)) {
+        throw new HandoffError(`issue #${issue} has no parseable agent-context block in the body (missing, malformed, or reversed markers — or the latest block is malformed) — refusing to accept (and close) a handoff with no reasoning artifact. Use \`/handoff ${issue}\` to add a well-formed note first.`);
+    }
+    // Lazy me-login (advisor catch #2): bash calls `me_login` inside the FIRST
+    // `assignees_status` call (lib.sh:88), which happens AFTER the step-1
+    // issue view. Resolving here — after the view + body validation, just
+    // before we need it — matches bash's gh call order. Eager resolution at
+    // the top of runAccept would reorder apiUserLogin ahead of issueView in
+    // FakeGhClient.calls() AND fire on step-1-failure paths where bash never
+    // hits `gh api user`.
+    const me = await meCache.resolve(gh);
+    const initialAssignees = view.assignees;
+    const initialUpdatedAt = view.updatedAt;
+    const initialStatus = assigneesStatus(initialAssignees, me);
+    // --- step 2: refuse if assigned to @other --------------------------------
+    if (initialStatus === "other") {
+        const others = assigneesOtherCsv(initialAssignees, me);
+        throw new HandoffError(`issue #${issue} is currently assigned to @${others} — coordinate with them or ask them to re-handoff (which un-assigns).`);
+    }
+    // --- step 3: strict rehydrate (read-only — abort the chain on failure) ---
+    // deriveRehydrateData internally calls gh.issueView (slot 2, body-bearing)
+    // then sequentially per linked item. It throws HandoffError on the
+    // wholesale issueView failure path; we add the strict linkFailures>0 gate.
+    const rehydrate = await deriveRehydrateData(issue, gh);
+    if (rehydrate.linkFailures > 0) {
+        throw new HandoffError(`rehydrate failed for #${issue} — leaving on the stack; no mutation.`);
+    }
+    // --- step 4: pre-assign drift check --------------------------------------
+    // issueViewSlim — separate seam from the body-bearing issueView slots
+    // above. Slot 1 of the SLIM counter.
+    let driftView;
+    try {
+        driftView = await gh.issueViewSlim(issue);
+    }
+    catch {
+        throw new HandoffError(`could not re-fetch issue #${issue} for drift check — not mutating.`);
+    }
+    if (driftView.state !== "OPEN") {
+        throw new HandoffError(`issue #${issue} changed between validation and assign — state is now ${driftView.state}. Another receiver may have claimed it; re-run \`/accept\` to retry against the new state, or check \`/handoffs\` for the current stack.`);
+    }
+    const driftStatus = assigneesStatus(driftView.assignees, me);
+    if (driftStatus === "other") {
+        throw new HandoffError(`issue #${issue} changed between validation and assign — another receiver may have claimed it; re-run \`/accept\` to retry against the new state, or check \`/handoffs\` for the current stack.`);
+    }
+    // updatedAt drift handling. The close-failure retry path is the ONLY one
+    // allowed to pass with updatedAt drift, and it requires INITIAL was
+    // already @me (assign happened on a previous attempt, close failed). If
+    // INITIAL was empty and updatedAt drifted to @me, that's a concurrent
+    // assignment by another tool/automation/same-account session — abort, do
+    // not proceed on the stale validate snapshot.
+    if (driftView.updatedAt !== initialUpdatedAt) {
+        if (initialStatus === "me" && driftStatus === "me") {
+            // close-failure retry path — pass through (do nothing)
+        }
+        else {
+            throw new HandoffError(`issue #${issue} was edited between validation and assign (initial=${initialStatus}, drift=${driftStatus}) — re-run \`/accept\` to retry against the new state.`);
+        }
+    }
+    // --- step 5: assign @me (mutation 1) -------------------------------------
+    try {
+        await gh.issueAssignMe(issue);
+    }
+    catch {
+        throw new HandoffError(`couldn't assign @me on #${issue} (gh error) — leaving on the stack.`);
+    }
+    logs.push(`accepted #${issue} — assigned to you.`);
+    // --- step 6: post-assign verify (multi-assignee abort path) --------------
+    // Slot 2 of the SLIM counter.
+    let postView;
+    try {
+        postView = await gh.issueViewSlim(issue);
+    }
+    catch {
+        throw new HandoffError(`couldn't verify post-assign state on #${issue} — leaving open + assigned; don't close.`);
+    }
+    if (assigneesStatus(postView.assignees, me) !== "me") {
+        const others = assigneesOtherCsv(postView.assignees, me);
+        throw new HandoffError(`collision detected after assign — issue #${issue} now has assignees [${others}]. Do not close. Coordinate with the other receiver(s); the operator may \`gh issue edit ${issue} --remove-assignee <other>\` or hand the baton off explicitly.`);
+    }
+    // --- step 7: close (Commitment 10 — handoff event complete) --------------
+    try {
+        await gh.issueClose(issue);
+    }
+    catch {
+        throw new HandoffError(`assigned but not closed — re-run \`/accept ${issue}\` to complete the close, or close manually as an operator-acknowledged exception.`);
+    }
+    logs.push(`closed #${issue} — handoff event complete.`);
+    return { issueNumber: issue, rehydrate, logs };
+}
+//# sourceMappingURL=accept-verb.js.map

package/dist/handoff/accept-verb.js.map

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

package/dist/handoff/args.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validate a positive-integer issue number string → number. Empty/undefined
+ * returns undefined (the "no issue arg" path several verbs allow).
+ *
+ * Mirrors bash require_issue_number (lib.sh:46-53):
+ *   case "${1:-}" in
+ *     "")        return 0 ;;                                          # empty allowed
+ *     0|0*)      die "issue must be a positive integer (got: '$1')." ;;
+ *     *[!0-9]*)  die "issue must be a positive integer (got: '$1')." ;;
+ *     *)         return 0 ;;
+ *   esac
+ *
+ * Note: the bash impl also rejects leading-whitespace ("42 " or " 42") because
+ * `case` does literal matching. We match that by rejecting any string that is
+ * not solely digits.
+ */
+export declare function requireIssueNumber(input: string | undefined): number | undefined;
+export declare function requireSafeArgs(args: readonly string[]): void;
+//# sourceMappingURL=args.d.ts.map

package/dist/handoff/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/handoff/args.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAWhF;AAkBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAS7D"}

package/dist/handoff/args.js

@@ -0,0 +1,68 @@
+// packages/cli/src/handoff/args.ts
+//
+// Argument validators. PORT FROM dark-factory-platform lib.sh@a6f711b:
+//   require_issue_number  (lines 46-53)
+//   require_safe_args     (lines 61-75)
+//
+// requireSafeArgs is defense-in-depth: in the TS CLI, real argv kills the
+// shell-metacharacter injection vector that the bash .md/$ARGUMENTS surface
+// was defending against (the operator's payload reaches process.argv as a
+// string and cannot re-enter a shell). We keep the allow-list anyway because:
+//   (a) MCP tool callers might pass any string, and rejecting metacharacters
+//       early is cheap defense-in-depth, and
+//   (b) it preserves byte-equivalent error messages with the bash impl for
+//       the ~6 ported payload-rejection tests, simplifying the case-map.
+import { HandoffError } from "./ports.js";
+/**
+ * Validate a positive-integer issue number string → number. Empty/undefined
+ * returns undefined (the "no issue arg" path several verbs allow).
+ *
+ * Mirrors bash require_issue_number (lib.sh:46-53):
+ *   case "${1:-}" in
+ *     "")        return 0 ;;                                          # empty allowed
+ *     0|0*)      die "issue must be a positive integer (got: '$1')." ;;
+ *     *[!0-9]*)  die "issue must be a positive integer (got: '$1')." ;;
+ *     *)         return 0 ;;
+ *   esac
+ *
+ * Note: the bash impl also rejects leading-whitespace ("42 " or " 42") because
+ * `case` does literal matching. We match that by rejecting any string that is
+ * not solely digits.
+ */
+export function requireIssueNumber(input) {
+    if (input === undefined || input === "")
+        return undefined;
+    // Reject 0 (case: "0") and leading-zero (case: "0*").
+    if (input === "0" || /^0/.test(input)) {
+        throw new HandoffError(`issue must be a positive integer (got: '${input}').`);
+    }
+    // Reject anything other than bare ASCII digits.
+    if (!/^[0-9]+$/.test(input)) {
+        throw new HandoffError(`issue must be a positive integer (got: '${input}').`);
+    }
+    return Number(input);
+}
+/**
+ * Allow-list per bash require_safe_args (lib.sh:61-75). Excludes shell
+ * metacharacters (`;$()'`|&><!*[]`) while permitting URL-safe chars (?=%+~)
+ * for --link URLs like https://github.com/o/r/pull/N?tab=files.
+ *
+ * Per the bash pattern `*[!a-zA-Z0-9_/#:.,@?=%+~\ -]*`, the allowed set is:
+ *   alphanumeric (a-zA-Z0-9)
+ *   _ / # : . , @ ? = % + ~
+ *   space
+ *   - (placed at end to avoid range interpretation)
+ *
+ * Throws HandoffError with the same message wording as bash on a disallowed
+ * character.
+ */
+const SAFE_ARG_PATTERN = /^[a-zA-Z0-9_/#:.,@?=%+~ \-]*$/;
+export function requireSafeArgs(args) {
+    for (const arg of args) {
+        if (!SAFE_ARG_PATTERN.test(arg)) {
+            throw new HandoffError("argument contains disallowed characters: refusing for safety " +
+                "(allowed: alphanumeric / # : . , @ - _ ? = % + ~ space).");
+        }
+    }
+}
+//# sourceMappingURL=args.js.map

package/dist/handoff/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/handoff/args.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,uEAAuE;AACvE,wCAAwC;AACxC,wCAAwC;AACxC,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,6CAA6C;AAC7C,2EAA2E;AAC3E,yEAAyE;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1D,sDAAsD;IACtD,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,YAAY,CAAC,2CAA2C,KAAK,KAAK,CAAC,CAAC;IAChF,CAAC;IACD,gDAAgD;IAChD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,2CAA2C,KAAK,KAAK,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAEzD,MAAM,UAAU,eAAe,CAAC,IAAuB;IACrD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,YAAY,CACpB,+DAA+D;gBAC7D,0DAA0D,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/handoff/assignees.d.ts

@@ -0,0 +1,37 @@
+import type { GhClient } from "./ports.js";
+/**
+ * Classification of an issue's assignees set against @me:
+ *   - "empty"  → no assignees      (available on the stack)
+ *   - "me"     → exactly [@me]     (same-actor update / close-failure retry)
+ *   - "other"  → any non-empty set ≠ [@me] (refuse/abort per §4.1, §4.3 step 4)
+ *
+ * Note: "[@me, @me]" (a duplicated @me — defensive against GitHub returning
+ * duplicates) classifies as "other" because cardinality must be 1 for "me".
+ */
+export type ClaimStatus = "empty" | "me" | "other";
+/**
+ * Classify an assignees array. PORT FROM bash assignees_status (lib.sh:88-96):
+ *   count == 0           → "empty"
+ *   count == 1 && [@me]  → "me"
+ *   otherwise            → "other"
+ */
+export declare function assigneesStatus(assignees: ReadonlyArray<{
+    login: string;
+}>, meLogin: string): ClaimStatus;
+/**
+ * Comma-joined list of assignees with @me filtered out. Used by refuse-
+ * messages ("currently assigned to @<csv>"). Preserves input order.
+ * PORT FROM bash assignees_other_csv (lib.sh:99-103).
+ */
+export declare function assigneesOtherCsv(assignees: ReadonlyArray<{
+    login: string;
+}>, meLogin: string): string;
+/**
+ * Cache for the @me login lookup. PORT FROM bash me_login + ME_LOGIN_CACHE
+ * (lib.sh:34-41). One API hit per process; cached across repeated callers.
+ */
+export declare class MeLoginCache {
+    private cache;
+    resolve(gh: GhClient): Promise<string>;
+}
+//# sourceMappingURL=assignees.d.ts.map

package/dist/handoff/assignees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignees.d.ts","sourceRoot":"","sources":["../../src/handoff/assignees.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,OAAO,EAAE,MAAM,GACd,WAAW,CAOb;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqB;IAC5B,OAAO,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;CAM7C"}

package/dist/handoff/assignees.js

@@ -0,0 +1,46 @@
+// packages/cli/src/handoff/assignees.ts
+//
+// Assignees status + me-login cache. PORT FROM dark-factory-platform
+// .claude/skills/handoff/scripts/lib.sh@a6f711b lines 32-41 (me_login + cache),
+// 88-103 (assignees_status + assignees_other_csv).
+/**
+ * Classify an assignees array. PORT FROM bash assignees_status (lib.sh:88-96):
+ *   count == 0           → "empty"
+ *   count == 1 && [@me]  → "me"
+ *   otherwise            → "other"
+ */
+export function assigneesStatus(assignees, meLogin) {
+    if (assignees.length === 0)
+        return "empty";
+    // Length-checked, but TS with noUncheckedIndexedAccess needs the explicit
+    // binding to narrow `assignees[0]` from `T | undefined` to `T`.
+    const first = assignees[0];
+    if (assignees.length === 1 && first !== undefined && first.login === meLogin)
+        return "me";
+    return "other";
+}
+/**
+ * Comma-joined list of assignees with @me filtered out. Used by refuse-
+ * messages ("currently assigned to @<csv>"). Preserves input order.
+ * PORT FROM bash assignees_other_csv (lib.sh:99-103).
+ */
+export function assigneesOtherCsv(assignees, meLogin) {
+    return assignees
+        .map((a) => a.login)
+        .filter((l) => l !== meLogin)
+        .join(",");
+}
+/**
+ * Cache for the @me login lookup. PORT FROM bash me_login + ME_LOGIN_CACHE
+ * (lib.sh:34-41). One API hit per process; cached across repeated callers.
+ */
+export class MeLoginCache {
+    cache;
+    async resolve(gh) {
+        if (this.cache === undefined) {
+            this.cache = await gh.apiUserLogin();
+        }
+        return this.cache;
+    }
+}
+//# sourceMappingURL=assignees.js.map

package/dist/handoff/assignees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignees.js","sourceRoot":"","sources":["../../src/handoff/assignees.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,qEAAqE;AACrE,gFAAgF;AAChF,mDAAmD;AAenD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA2C,EAC3C,OAAe;IAEf,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3C,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1F,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA2C,EAC3C,OAAe;IAEf,OAAO,SAAS;SACb,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC;SAC5B,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,YAAY;IACf,KAAK,CAAqB;IAClC,KAAK,CAAC,OAAO,CAAC,EAAY;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC,YAAY,EAAE,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/handoff/handoff-verb.d.ts

@@ -0,0 +1,34 @@
+import { type Clock, type GhClient, type GitClient } from "./ports.js";
+export interface RunHandoffOptions {
+    readonly noteStdin: string;
+    readonly issue?: number;
+    readonly link?: readonly string[];
+    readonly unlink?: readonly string[];
+    readonly forceNew?: boolean;
+    readonly gh: GhClient;
+    readonly git: GitClient;
+    readonly clock: Clock;
+}
+export interface RunHandoffResult {
+    readonly issueNumber: number;
+    readonly noteUrl: string;
+    readonly created: boolean;
+    /** Operator-facing warn/log lines (each line printed to stderr by the CLI). */
+    readonly logs: readonly string[];
+}
+/**
+ * Put a work-stream on the handoff stack. Upserts the operator's
+ * marker-bounded rehydration note as a dedicated handoff GitHub Issue body,
+ * maintains its Linked-items section + label + leaves it unassigned. NO
+ * `git push` (Decision D4).
+ *
+ * Phases mirror the bash:
+ *   A: validate stdin    — markers + secret-scrub, no gh
+ *   B: dirty worktree    — warn, not refuse
+ *   C: resolve target    — explicit issue OR no-arg eligibility partition
+ *   D: linked-items      — extract → --link (with title scrub) → --unlink → auto-link
+ *   E: compose new note  — strip operator's stale section, inject script section
+ *   F: PATCH or CREATE   — with pre-PATCH race-safety drift check
+ */
+export declare function runHandoff(opts: RunHandoffOptions): Promise<RunHandoffResult>;
+//# sourceMappingURL=handoff-verb.d.ts.map

package/dist/handoff/handoff-verb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-verb.d.ts","sourceRoot":"","sources":["../../src/handoff/handoff-verb.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAgB,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AASrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAyGD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAsW3B"}