vouchington-tooling 0.7.2 → 0.8.1

package/README.md

@@ -207,6 +207,7 @@ import {
 import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-transcript'
 import { appendJournal, probeBlackboard } from 'vouchington-tooling/agent-blackboard'
 import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
+import { createPullRequest, getDiffAgainstBase, runGh, runGit } from 'vouchington-tooling/gh-cli'
 ```
 
 `checkWorkspaceGatesPolicy` rejects tracked test assertions that hard-code the exact version of a

package/dist/gh-cli/diff.d.mts

@@ -0,0 +1,6 @@
+import type { RunTextCommand } from './exec.mts';
+/**
+ * Runs `git diff <base>...HEAD` and returns the raw diff text. The base is parameterized rather
+ * than hardcoded so callers can diff against any ref (`origin/main`, a release branch, etc.).
+ */
+export declare function getDiffAgainstBase(runGit: RunTextCommand, base: string): Promise<string>;

package/dist/gh-cli/diff.mjs

@@ -0,0 +1,7 @@
+/**
+ * Runs `git diff <base>...HEAD` and returns the raw diff text. The base is parameterized rather
+ * than hardcoded so callers can diff against any ref (`origin/main`, a release branch, etc.).
+ */
+export async function getDiffAgainstBase(runGit, base) {
+    return runGit(['diff', `${base}...HEAD`]);
+}

package/dist/gh-cli/exec.d.mts

@@ -0,0 +1,16 @@
+/** A text-mode command runner: argv in, stdout out. Rejects on a non-zero exit. */
+export type RunTextCommand = (args: string[]) => Promise<string>;
+/** The `child_process.execFile` shape `createCommandRunner` wraps — injectable for tests. */
+export type ExecFileText = (command: string, args: string[]) => Promise<{
+    stdout: string;
+}>;
+/**
+ * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
+ * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
+ * are this factory applied to the two binaries this module cares about.
+ */
+export declare function createCommandRunner(command: string, exec?: ExecFileText): RunTextCommand;
+/** Runs `gh` and returns its stdout. */
+export declare const runGh: RunTextCommand;
+/** Runs `git` and returns its stdout. */
+export declare const runGit: RunTextCommand;

package/dist/gh-cli/exec.mjs

@@ -0,0 +1,18 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
+ * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
+ * are this factory applied to the two binaries this module cares about.
+ */
+export function createCommandRunner(command, exec = (cmd, args) => execFileAsync(cmd, args)) {
+    return async (args) => {
+        const { stdout } = await exec(command, args);
+        return stdout;
+    };
+}
+/** Runs `gh` and returns its stdout. */
+export const runGh = createCommandRunner('gh');
+/** Runs `git` and returns its stdout. */
+export const runGit = createCommandRunner('git');

package/dist/gh-cli/index.d.mts

@@ -0,0 +1,5 @@
+export { createCommandRunner, runGh, runGit } from './exec.mts';
+export type { ExecFileText, RunTextCommand } from './exec.mts';
+export { getDiffAgainstBase } from './diff.mts';
+export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './pr-create.mts';
+export type { AssertHeadPushedOptions, BuildGhPrCreateArgsOptions, CreatePullRequestExecutors, CreatePullRequestOptions, } from './pr-create.mts';

package/dist/gh-cli/index.mjs

@@ -0,0 +1,3 @@
+export { createCommandRunner, runGh, runGit } from './exec.mjs';
+export { getDiffAgainstBase } from './diff.mjs';
+export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './pr-create.mjs';

package/dist/gh-cli/pr-create.d.mts

@@ -0,0 +1,61 @@
+import type { RunTextCommand } from './exec.mts';
+/** Thrown by {@link resolveHeadBranch} when `git branch --show-current` reports a detached HEAD. */
+export declare class DetachedHeadError extends Error {
+    constructor();
+}
+/** Thrown by {@link assertHeadPushed} when the branch has no matching ref on the remote. */
+export declare class HeadNotPushedError extends Error {
+    constructor(branch: string, remote: string);
+}
+/**
+ * Thrown by {@link assertHeadPushed} when `branch` exists on `remote` but at a different commit
+ * than the local branch — creating the pull request now would silently use the stale remote tip.
+ */
+export declare class HeadOutOfDateError extends Error {
+    constructor(branch: string, remote: string);
+}
+/** Resolves the current branch via `git branch --show-current`, trimmed. */
+export declare function resolveHeadBranch(runGit: RunTextCommand): Promise<string>;
+export type AssertHeadPushedOptions = {
+    branch: string;
+    remote?: string;
+};
+/**
+ * Confirms `branch` has a matching, up-to-date ref on `remote` (default `origin`) via
+ * `git ls-remote --heads` and `git rev-parse`. Both use the full `refs/heads/<branch>` path
+ * rather than the bare branch name: `ls-remote`'s pattern otherwise matches any ref whose name
+ * ends with `branch` (not just an exact `refs/heads/<branch>`), and bare `rev-parse <branch>`
+ * resolves `refs/tags/<branch>` before `refs/heads/<branch>` when a same-named tag exists, either
+ * of which could compare the wrong commit. `ls-remote --heads` exits `0` with empty stdout when
+ * there is no match, so a missing branch is checked via stdout rather than the exit code. A
+ * remote ref that exists but points at a different commit than the local branch means local HEAD
+ * has commits the remote does not — that fails with {@link HeadOutOfDateError} rather than
+ * silently creating the pull request from the stale remote tip.
+ */
+export declare function assertHeadPushed(runGit: RunTextCommand, { branch, remote }: AssertHeadPushedOptions): Promise<void>;
+export type BuildGhPrCreateArgsOptions = {
+    base?: string;
+    bodyFile: string;
+    draft?: boolean;
+    head: string;
+    labels?: readonly string[];
+    reviewers?: readonly string[];
+    title: string;
+};
+/** Pure argv builder for `gh pr create`. `head` is always passed explicitly (never omitted). */
+export declare function buildGhPrCreateArgs(options: BuildGhPrCreateArgsOptions): string[];
+export type CreatePullRequestExecutors = {
+    runGh: RunTextCommand;
+    runGit: RunTextCommand;
+};
+export type CreatePullRequestOptions = Omit<BuildGhPrCreateArgsOptions, 'head'> & {
+    head?: string;
+    remote?: string;
+};
+/**
+ * Creates a pull request with `gh pr create --head <branch>`, resolving and verifying the head
+ * branch first so the "must first push the current branch" non-interactive abort can never
+ * happen — instead an unpushed branch fails fast with {@link HeadNotPushedError}. Returns the
+ * trimmed PR URL that `gh pr create` prints to stdout.
+ */
+export declare function createPullRequest({ runGh, runGit }: CreatePullRequestExecutors, options: CreatePullRequestOptions): Promise<string>;

package/dist/gh-cli/pr-create.mjs

@@ -0,0 +1,80 @@
+/** Thrown by {@link resolveHeadBranch} when `git branch --show-current` reports a detached HEAD. */
+export class DetachedHeadError extends Error {
+    constructor() {
+        super('cannot resolve a pull request head branch from a detached HEAD');
+        this.name = 'DetachedHeadError';
+    }
+}
+/** Thrown by {@link assertHeadPushed} when the branch has no matching ref on the remote. */
+export class HeadNotPushedError extends Error {
+    constructor(branch, remote) {
+        super(`branch "${branch}" is not on remote "${remote}" — push it before creating the pull request`);
+        this.name = 'HeadNotPushedError';
+    }
+}
+/**
+ * Thrown by {@link assertHeadPushed} when `branch` exists on `remote` but at a different commit
+ * than the local branch — creating the pull request now would silently use the stale remote tip.
+ */
+export class HeadOutOfDateError extends Error {
+    constructor(branch, remote) {
+        super(`branch "${branch}" on remote "${remote}" does not match the local branch — push the latest commits before creating the pull request`);
+        this.name = 'HeadOutOfDateError';
+    }
+}
+/** Resolves the current branch via `git branch --show-current`, trimmed. */
+export async function resolveHeadBranch(runGit) {
+    const branch = (await runGit(['branch', '--show-current'])).trim();
+    if (branch === '')
+        throw new DetachedHeadError();
+    return branch;
+}
+/**
+ * Confirms `branch` has a matching, up-to-date ref on `remote` (default `origin`) via
+ * `git ls-remote --heads` and `git rev-parse`. Both use the full `refs/heads/<branch>` path
+ * rather than the bare branch name: `ls-remote`'s pattern otherwise matches any ref whose name
+ * ends with `branch` (not just an exact `refs/heads/<branch>`), and bare `rev-parse <branch>`
+ * resolves `refs/tags/<branch>` before `refs/heads/<branch>` when a same-named tag exists, either
+ * of which could compare the wrong commit. `ls-remote --heads` exits `0` with empty stdout when
+ * there is no match, so a missing branch is checked via stdout rather than the exit code. A
+ * remote ref that exists but points at a different commit than the local branch means local HEAD
+ * has commits the remote does not — that fails with {@link HeadOutOfDateError} rather than
+ * silently creating the pull request from the stale remote tip.
+ */
+export async function assertHeadPushed(runGit, { branch, remote = 'origin' }) {
+    const ref = `refs/heads/${branch}`;
+    const remoteLine = (await runGit(['ls-remote', '--heads', remote, ref])).trim();
+    if (remoteLine === '')
+        throw new HeadNotPushedError(branch, remote);
+    const [remoteSha] = remoteLine.split(/\s+/);
+    const localSha = (await runGit(['rev-parse', ref])).trim();
+    if (localSha !== remoteSha)
+        throw new HeadOutOfDateError(branch, remote);
+}
+/** Pure argv builder for `gh pr create`. `head` is always passed explicitly (never omitted). */
+export function buildGhPrCreateArgs(options) {
+    const { base, bodyFile, draft = false, head, labels = [], reviewers = [], title } = options;
+    const args = ['pr', 'create', '--title', title, '--body-file', bodyFile, '--head', head];
+    if (base !== undefined)
+        args.push('--base', base);
+    if (draft)
+        args.push('--draft');
+    for (const label of labels)
+        args.push('--label', label);
+    for (const reviewer of reviewers)
+        args.push('--reviewer', reviewer);
+    return args;
+}
+/**
+ * Creates a pull request with `gh pr create --head <branch>`, resolving and verifying the head
+ * branch first so the "must first push the current branch" non-interactive abort can never
+ * happen — instead an unpushed branch fails fast with {@link HeadNotPushedError}. Returns the
+ * trimmed PR URL that `gh pr create` prints to stdout.
+ */
+export async function createPullRequest({ runGh, runGit }, options) {
+    const { remote = 'origin', head: suppliedHead, ...rest } = options;
+    const head = suppliedHead ?? (await resolveHeadBranch(runGit));
+    await assertHeadPushed(runGit, { branch: head, remote });
+    const stdout = await runGh(buildGhPrCreateArgs({ ...rest, head }));
+    return stdout.trim();
+}

package/dist/index.d.mts

@@ -84,3 +84,8 @@ export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
 export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mts';
 export type { DiagnosticReportLimitOptions, DiagnosticReportSummary, } from './vitest-diagnostics/index.mts';
+export { createCommandRunner, runGh, runGit } from './gh-cli/index.mts';
+export type { ExecFileText, RunTextCommand } from './gh-cli/index.mts';
+export { getDiffAgainstBase } from './gh-cli/index.mts';
+export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './gh-cli/index.mts';
+export type { AssertHeadPushedOptions, BuildGhPrCreateArgsOptions, CreatePullRequestExecutors, CreatePullRequestOptions, } from './gh-cli/index.mts';

package/dist/index.mjs

@@ -47,3 +47,6 @@ export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';
 export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mjs';
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mjs';
+export { createCommandRunner, runGh, runGit } from './gh-cli/index.mjs';
+export { getDiffAgainstBase } from './gh-cli/index.mjs';
+export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './gh-cli/index.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -262,6 +262,11 @@
       "import": "./dist/vitest-diagnostics/index.mjs",
       "default": "./dist/vitest-diagnostics/index.mjs"
     },
+    "./gh-cli": {
+      "types": "./dist/gh-cli/index.d.mts",
+      "import": "./dist/gh-cli/index.mjs",
+      "default": "./dist/gh-cli/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {