@wildorder/nightshift 0.5.0 → 0.6.0

package/dist/exit-codes.js

@@ -0,0 +1,49 @@
+/**
+ * The process exit codes a `nightshift run` terminates with — the one place
+ * they are defined. A CI author and the generated GitHub Actions workflow
+ * (WS-05) both read these; there is exactly one source.
+ *
+ *   0  COMPLETE         every workstream built; the handover is a clean PR.
+ *   2  PARTIAL          the run terminated with a reviewable handover, but at
+ *                       least one workstream failed or was parked. A red job is
+ *                       the correct signal — the run report is worth reading.
+ *   3  COULD_NOT_START  the run never began: a dependency cycle, a missing or
+ *                       invalid manifest, an unconfigured implementer, or a
+ *                       branch precondition refused before any agent spawned.
+ *                       There is no run report, because there was no run.
+ *
+ * 1 is deliberately NOT one of these three. It stays the generic "unexpected
+ * error" code that Node (uncaught throw) and Commander (usage error) already
+ * emit, so a tool crash or a mistyped command is never read as a run outcome.
+ */
+export const EXIT_CODES = {
+    COMPLETE: 0,
+    GENERIC: 1,
+    PARTIAL: 2,
+    COULD_NOT_START: 3,
+};
+/**
+ * Thrown for every condition that stops a run before it starts. The CLI maps
+ * it to EXIT_CODES.COULD_NOT_START; anything else thrown out of a run is a
+ * genuine, unclassified error and stays EXIT_CODES.GENERIC. The message is the
+ * actionable guidance the operator reads — keep it a single readable sentence,
+ * exactly as the guards already write it.
+ */
+export class CouldNotStartError extends Error {
+    exitCode = EXIT_CODES.COULD_NOT_START;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CouldNotStartError";
+    }
+}
+/** Complete → 0; partial → 2. The only mapping a returned run outcome needs. */
+export function exitCodeForResult(result) {
+    return result.complete ? EXIT_CODES.COMPLETE : EXIT_CODES.PARTIAL;
+}
+/** A could-not-start throw → 3; every other throw → the generic 1. */
+export function exitCodeForError(error) {
+    return error instanceof CouldNotStartError
+        ? EXIT_CODES.COULD_NOT_START
+        : EXIT_CODES.GENERIC;
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,eAAe,EAAE,CAAC;CACV,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC;IAC/C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,MAA6B;IAC7D,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;AACpE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,YAAY,kBAAkB;QACxC,CAAC,CAAC,UAAU,CAAC,eAAe;QAC5B,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -13,10 +13,15 @@ export * from "./decision-ledger.js";
 export * from "./manifest.js";
 export * from "./author.js";
 export * from "./run-program.js";
+export * from "./publish.js";
+export * from "./run-publish.js";
+export * from "./report-path.js";
 export * from "./decide.js";
 export * from "./init-project.js";
 export * from "./install-skills.js";
 export * from "./install-prefs.js";
 export * from "./install-wizard.js";
 export * from "./package-assets.js";
+export * from "./exit-codes.js";
+export * from "./ci-init.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -13,10 +13,15 @@ export * from "./decision-ledger.js";
 export * from "./manifest.js";
 export * from "./author.js";
 export * from "./run-program.js";
+export * from "./publish.js";
+export * from "./run-publish.js";
+export * from "./report-path.js";
 export * from "./decide.js";
 export * from "./init-project.js";
 export * from "./install-skills.js";
 export * from "./install-prefs.js";
 export * from "./install-wizard.js";
 export * from "./package-assets.js";
+export * from "./exit-codes.js";
+export * from "./ci-init.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/program-branch.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The fixed prefix for every program branch. Not a config key — the charter
+ * keeps tuning knobs off the config surface, and a second source of truth
+ * next to this function is exactly what this module exists to prevent.
+ */
+export declare const PROGRAM_BRANCH_PREFIX = "program/";
+/**
+ * The one place a program ID becomes a branch name. The runner's
+ * preconditions and the branch command both call this; nothing else derives
+ * a branch name anywhere in the codebase.
+ */
+export declare function programBranchName(programId: string): string;
+/**
+ * Git operations the branch command and the default-branch heuristic need,
+ * injectable so tests can force a specific state. The default implementation
+ * shells out to real git; tests otherwise drive real temporary repositories.
+ */
+export interface ProgramBranchGit {
+    isRepository(cwd: string): Promise<boolean>;
+    /** undefined when HEAD is detached. */
+    currentBranch(cwd: string): Promise<string | undefined>;
+    localBranchExists(cwd: string, branch: string): Promise<boolean>;
+    /** `origin/HEAD`'s target, with the leading `origin/` stripped; undefined when unset. */
+    originHeadBranch(cwd: string): Promise<string | undefined>;
+    /** `git config init.defaultBranch`; undefined when unset. */
+    configDefaultBranch(cwd: string): Promise<string | undefined>;
+    /** Switches to an existing local branch; never discards uncommitted work. */
+    switchTo(cwd: string, branch: string): Promise<void>;
+    /** Creates a branch from HEAD and switches to it; never discards uncommitted work. */
+    createAndSwitch(cwd: string, branch: string): Promise<void>;
+}
+export declare const defaultProgramBranchGit: ProgramBranchGit;
+export interface CreateOrSwitchProgramBranchOptions {
+    cwd?: string;
+    git?: ProgramBranchGit;
+}
+export interface CreateOrSwitchProgramBranchResult {
+    action: "created" | "switched";
+    branch: string;
+}
+/**
+ * Creates a program's branch and switches to it, or switches to it when a
+ * prior run already made it, and reports which. Never discards uncommitted
+ * work: creating carries the working tree onto the new branch, and switching
+ * to an existing branch with conflicting local changes surfaces git's own
+ * refusal rather than overriding it.
+ */
+export declare function createOrSwitchProgramBranch(programId: string, options?: CreateOrSwitchProgramBranchOptions): Promise<CreateOrSwitchProgramBranchResult>;
+/**
+ * Resolves the repository's default branch name, in order: `origin/HEAD`,
+ * then the first of `main`/`master` that exists locally, then
+ * `init.defaultBranch`, then `"main"`.
+ *
+ * This is a heuristic, not a guarantee. It is authoritative when
+ * `origin/HEAD` is set and correct for the common `main`/`master` local
+ * repositories, but it cannot identify a custom default (say `trunk`) with
+ * neither `origin/HEAD` nor a matching `init.defaultBranch` — it will return
+ * `main` in that case. This does not create a safety hole: the run
+ * preconditions in `run-program.ts` never rely on this alone. If this
+ * function misnames the default, the wrong-branch precondition still refuses
+ * a run on any branch that is not the one derived from the program ID; only
+ * the specificity of the refusal message degrades.
+ */
+export declare function detectDefaultBranch(cwd: string, git?: ProgramBranchGit): Promise<string>;
+//# sourceMappingURL=program-branch.d.ts.map

package/dist/program-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-branch.d.ts","sourceRoot":"","sources":["../src/program-branch.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,uCAAuC;IACvC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxD,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,yFAAyF;IACzF,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3D,6DAA6D;IAC7D,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,sFAAsF;IACtF,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,eAAO,MAAM,uBAAuB,EAAE,gBAiErC,CAAC;AAEF,MAAM,WAAW,kCAAkC;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACxB;AAED,MAAM,WAAW,iCAAiC;IAChD,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kCAAkC,GAC3C,OAAO,CAAC,iCAAiC,CAAC,CAuB5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,gBAA0C,GAC9C,OAAO,CAAC,MAAM,CAAC,CASjB"}

package/dist/program-branch.js

@@ -0,0 +1,123 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * The fixed prefix for every program branch. Not a config key — the charter
+ * keeps tuning knobs off the config surface, and a second source of truth
+ * next to this function is exactly what this module exists to prevent.
+ */
+export const PROGRAM_BRANCH_PREFIX = "program/";
+/**
+ * The one place a program ID becomes a branch name. The runner's
+ * preconditions and the branch command both call this; nothing else derives
+ * a branch name anywhere in the codebase.
+ */
+export function programBranchName(programId) {
+    return `${PROGRAM_BRANCH_PREFIX}${programId}`;
+}
+export const defaultProgramBranchGit = {
+    async isRepository(cwd) {
+        try {
+            await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async currentBranch(cwd) {
+        try {
+            const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd });
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async localBranchExists(cwd, branch) {
+        try {
+            await execFileAsync("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], { cwd });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async originHeadBranch(cwd) {
+        try {
+            const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], { cwd });
+            const ref = stdout.trim();
+            return ref.startsWith("origin/") ? ref.slice("origin/".length) : ref;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async configDefaultBranch(cwd) {
+        try {
+            const { stdout } = await execFileAsync("git", ["config", "--get", "init.defaultBranch"], { cwd });
+            const value = stdout.trim();
+            return value === "" ? undefined : value;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async switchTo(cwd, branch) {
+        await execFileAsync("git", ["switch", branch], { cwd });
+    },
+    async createAndSwitch(cwd, branch) {
+        await execFileAsync("git", ["switch", "-c", branch], { cwd });
+    },
+};
+/**
+ * Creates a program's branch and switches to it, or switches to it when a
+ * prior run already made it, and reports which. Never discards uncommitted
+ * work: creating carries the working tree onto the new branch, and switching
+ * to an existing branch with conflicting local changes surfaces git's own
+ * refusal rather than overriding it.
+ */
+export async function createOrSwitchProgramBranch(programId, options) {
+    const cwd = options?.cwd ?? process.cwd();
+    const git = options?.git ?? defaultProgramBranchGit;
+    const branch = programBranchName(programId);
+    if (!(await git.isRepository(cwd))) {
+        throw new Error(`${cwd} is not a git repository; run \`git init\` or plan from inside your repository.`);
+    }
+    const current = await git.currentBranch(cwd);
+    if (current === undefined) {
+        throw new Error("HEAD is detached; check out your default branch, then re-run.");
+    }
+    if (await git.localBranchExists(cwd, branch)) {
+        await git.switchTo(cwd, branch);
+        return { action: "switched", branch };
+    }
+    await git.createAndSwitch(cwd, branch);
+    return { action: "created", branch };
+}
+/**
+ * Resolves the repository's default branch name, in order: `origin/HEAD`,
+ * then the first of `main`/`master` that exists locally, then
+ * `init.defaultBranch`, then `"main"`.
+ *
+ * This is a heuristic, not a guarantee. It is authoritative when
+ * `origin/HEAD` is set and correct for the common `main`/`master` local
+ * repositories, but it cannot identify a custom default (say `trunk`) with
+ * neither `origin/HEAD` nor a matching `init.defaultBranch` — it will return
+ * `main` in that case. This does not create a safety hole: the run
+ * preconditions in `run-program.ts` never rely on this alone. If this
+ * function misnames the default, the wrong-branch precondition still refuses
+ * a run on any branch that is not the one derived from the program ID; only
+ * the specificity of the refusal message degrades.
+ */
+export async function detectDefaultBranch(cwd, git = defaultProgramBranchGit) {
+    const originHead = await git.originHeadBranch(cwd);
+    if (originHead !== undefined)
+        return originHead;
+    for (const candidate of ["main", "master"]) {
+        if (await git.localBranchExists(cwd, candidate))
+            return candidate;
+    }
+    return (await git.configDefaultBranch(cwd)) ?? "main";
+}
+//# sourceMappingURL=program-branch.js.map

package/dist/program-branch.js.map

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

package/dist/publish.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The handover from a finished run to a reviewable pull request: pushes the
+ * program branch, opens or updates exactly one draft PR through `gh`,
+ * renders the run report as its body (continuing oversized reports into
+ * comments), and upserts one comment per escalated decision. Idempotent —
+ * re-publishing edits the existing PR and its comments rather than
+ * duplicating them.
+ *
+ * `publish` is deliberately separate from `runProgram`: the runner owns
+ * commits and knows nothing about forges, and this command owns the forge
+ * and knows nothing about building. Authentication is entirely `gh`'s job —
+ * nightshift never reads, stores, or passes a token.
+ */
+export declare const GITHUB_PR_BODY_LIMIT = 65536;
+export interface GhComment {
+    /** The forge's own comment id, opaque; used to edit or delete it. */
+    id: string;
+    body: string;
+}
+export interface GhPullRequest {
+    number: number;
+    url: string;
+    /** open | closed | merged — so publish can tell a live handover from history. */
+    state: "open" | "closed" | "merged";
+    /** Whether the PR is still a draft; asserted by the SC-06 test. */
+    isDraft: boolean;
+}
+export interface GhClient {
+    /**
+     * Preflight: succeeds when `gh` is installed and authenticated, and throws
+     * the actionable "not installed" / "not authenticated" errors otherwise.
+     * Called once at the very start of publish, before any push or PR work.
+     */
+    checkAuth(cwd: string): Promise<void>;
+    /**
+     * The open PR whose head is this branch, or undefined. Returns only an
+     * OPEN PR — a closed or merged PR for the branch is history, not the live
+     * handover. Never returns two: GitHub permits at most one open PR per
+     * head->base pair.
+     */
+    findOpenPullRequest(cwd: string, headBranch: string): Promise<GhPullRequest | undefined>;
+    /** Opens a draft PR; returns its number, url, state, and draft flag. */
+    createDraftPullRequest(cwd: string, input: {
+        headBranch: string;
+        baseBranch: string;
+        title: string;
+        body: string;
+    }): Promise<GhPullRequest>;
+    /** Rewrites the body of an existing PR; does not change its draft/ready state. */
+    updatePullRequestBody(cwd: string, number: number, body: string): Promise<void>;
+    listComments(cwd: string, number: number): Promise<GhComment[]>;
+    createComment(cwd: string, number: number, body: string): Promise<void>;
+    updateComment(cwd: string, commentId: string, body: string): Promise<void>;
+    /** Removes a now-stale nightshift-authored comment. */
+    deleteComment(cwd: string, commentId: string): Promise<void>;
+}
+/**
+ * Git operations `publish` needs beyond `program-branch.ts`'s derivation —
+ * kept local to this module, mirroring `ProgramBranchGit`, so the runner's
+ * `GitOps` stays about building, not remotes.
+ */
+export interface PublishGit {
+    /** The branch HEAD points at, for the provenance check; `git rev-parse --abbrev-ref HEAD`. */
+    currentBranch(cwd: string): Promise<string>;
+    /** Is the branch ahead of base? `git rev-list --count <base>..<branch>`. */
+    commitsAhead(cwd: string, base: string, branch: string): Promise<number>;
+    push(cwd: string, remote: string, branch: string): Promise<void>;
+}
+export declare const defaultPublishGit: PublishGit;
+export declare const defaultGhClient: GhClient;
+export interface PublishOptions {
+    cwd: string;
+    programId: string;
+    /** Injected GitHub boundary; default spawns `gh`. */
+    gh?: GhClient;
+    /** Injected git boundary; default execFile-backed. */
+    git?: PublishGit;
+    log?: (line: string) => void;
+}
+export interface PublishResult {
+    prNumber: number;
+    prUrl: string;
+    action: "created" | "updated";
+    /** Escalation comments upserted this publish. */
+    escalationComments: number;
+    /** Report-continuation comments upserted this publish (0 when the report fits). */
+    continuationComments: number;
+}
+interface ReportChunk {
+    /** A verbatim, contiguous slice of the report — never rewritten or decorated. */
+    payload: string;
+    /** True when this chunk's payload ends mid-section (the degenerate fallback). */
+    cutMidSection: boolean;
+}
+/**
+ * Splits the run report into chunks whose payloads are verbatim, contiguous
+ * slices of the report — concatenating every payload in order reproduces the
+ * report byte-for-byte. A report that fits under the limit is a single
+ * chunk; an oversized report is packed on section boundaries, falling back
+ * to paragraph/character boundaries only for a section too large on its own.
+ */
+export declare function splitReportIntoChunks(report: string): ReportChunk[];
+export declare function publish(options: PublishOptions): Promise<PublishResult>;
+export {};
+//# sourceMappingURL=publish.d.ts.map

package/dist/publish.d.ts.map

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