@cruxy/cli 0.4.0 → 0.6.0

package/dist/vcs/generate.js

@@ -0,0 +1,265 @@
+/**
+ * Turn a diff + session context into the PR publish content (C.15): a
+ * conventional-commit subject, a structured body, a branch name, and the PR
+ * title/body. The repo's commit rules (the C.18 git-commit skill + the
+ * commitlint scope list) are honored two ways: they're handed to the LLM in the
+ * prompt, **and** every field is run through deterministic normalizers so the
+ * lowercase-subject rule (and scope allow-list) hold even if the model slips.
+ *
+ * Secrets never leave: the diff is redacted before the LLM sees it, and the
+ * generated bodies are redacted again (defense-in-depth).
+ */
+/** Conventional-commit types accepted by `@commitlint/config-conventional`. */
+export const CONVENTIONAL_TYPES = [
+    "feat",
+    "fix",
+    "chore",
+    "docs",
+    "refactor",
+    "test",
+    "perf",
+    "build",
+    "ci",
+    "style",
+    "revert",
+];
+const SUBJECT_MAX = 72;
+// ── secret redaction ────────────────────────────────────────────────────────────
+const REDACTED = "«redacted secret»";
+/** Ordered redaction patterns. Each match's secret span is replaced. */
+const SECRET_PATTERNS = [
+    // PEM private key blocks.
+    {
+        re: /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g,
+        replace: () => REDACTED,
+    },
+    // GitHub tokens (PAT, OAuth, app, refresh) + fine-grained PATs.
+    { re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: () => REDACTED },
+    { re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, replace: () => REDACTED },
+    // Slack tokens.
+    { re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, replace: () => REDACTED },
+    // AWS access key id.
+    { re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, replace: () => REDACTED },
+    // Bearer tokens in headers/snippets.
+    {
+        re: /\bBearer\s+[A-Za-z0-9._-]{20,}/g,
+        replace: () => `Bearer ${REDACTED}`,
+    },
+    // Generic `key = value` / `key: "value"` secret assignments.
+    {
+        re: /\b((?:api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key|client[_-]?secret|auth[_-]?token)\s*[:=]\s*)(['"]?)([A-Za-z0-9_./+=-]{12,})\2/gi,
+        replace: (m) => `${m[1]}${m[2]}${REDACTED}${m[2]}`,
+    },
+];
+/** Strip anything that looks like a credential from `text`. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const { re, replace } of SECRET_PATTERNS) {
+        out = out.replace(re, (...args) => {
+            // String.replace passes (match, ...groups, offset, string); rebuild an
+            // exec-style array so the replacer can index capture groups.
+            const groups = args.slice(0, -2);
+            const m = groups;
+            return replace(m);
+        });
+    }
+    return out;
+}
+// ── conventional-commit normalization ────────────────────────────────────────────
+/**
+ * Force `raw` into a valid conventional-commit subject: a known `type`, an
+ * allow-listed scope (dropped if it isn't), a **lowercase** first word, no
+ * trailing period, clamped to 72 chars. This is the deterministic guarantee that
+ * the commitlint `subject-case` + `scope-enum` rules pass.
+ */
+export function normalizeSubject(raw, scopes = []) {
+    const cleaned = raw.replace(/\s+/g, " ").trim();
+    const m = /^([a-zA-Z]+)(?:\(([^)]*)\))?(!)?:\s*(.*)$/.exec(cleaned);
+    let type = "chore";
+    let scope;
+    let desc = cleaned;
+    if (m) {
+        type = m[1].toLowerCase();
+        scope = m[2]?.trim() || undefined;
+        desc = m[4]?.trim() || "";
+    }
+    if (!CONVENTIONAL_TYPES.includes(type)) {
+        // Unknown type ⇒ fold the original text into a chore subject.
+        type = "chore";
+        desc = m ? desc : cleaned;
+    }
+    // Drop a scope the repo doesn't allow (scope is optional, so this still passes).
+    if (scope && scopes.length > 0 && !scopes.includes(scope)) {
+        scope = undefined;
+    }
+    desc = desc.replace(/\.+$/, "").trim();
+    if (desc === "")
+        desc = "update";
+    desc = lowercaseLead(desc);
+    const prefix = scope ? `${type}(${scope}): ` : `${type}: `;
+    const budget = Math.max(1, SUBJECT_MAX - prefix.length);
+    if (desc.length > budget)
+        desc = desc.slice(0, budget).trimEnd();
+    return `${prefix}${desc}`;
+}
+/** Lowercase the first alphabetic character (the commitlint subject-case rule). */
+function lowercaseLead(text) {
+    const i = text.search(/[A-Za-z]/);
+    if (i === -1)
+        return text;
+    return text.slice(0, i) + text[i].toLowerCase() + text.slice(i + 1);
+}
+/** A safe branch name `type/slug` derived from a conventional subject. */
+export function slugifyBranch(subject) {
+    const m = /^([a-z]+)(?:\([^)]*\))?:\s*(.*)$/.exec(subject);
+    const type = m ? m[1] : "chore";
+    const desc = (m ? m[2] : subject) || "change";
+    const slug = desc
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return `${type}/${slug || "change"}`;
+}
+/** Assemble a structured PR body: what changed · why · verification. */
+export function assembleBody(parts) {
+    const sections = [`## What changed\n\n${parts.what.trim()}`];
+    if (parts.why?.trim())
+        sections.push(`## Why\n\n${parts.why.trim()}`);
+    if (parts.verification?.trim())
+        sections.push(`## Verification\n\n${parts.verification.trim()}`);
+    return sections.join("\n\n");
+}
+// ── deterministic fill (the tool path — no LLM) ───────────────────────────────────
+/** Count `diff --git` headers to summarize a change set without an LLM. */
+function changedFileCount(diff) {
+    const matches = diff.match(/^diff --git /gm);
+    const untracked = diff.match(/^\+ /gm); // from diffAgainst's untracked list
+    return (matches?.length ?? 0) + (untracked?.length ?? 0);
+}
+/**
+ * Build the publish content deterministically (used by the `create_pull_request`
+ * tool, where the agent itself authored the title/body). Missing fields are
+ * derived; every field is still normalized + redacted.
+ */
+export function fillContent(input) {
+    const n = changedFileCount(input.diff);
+    const rawSubject = input.title?.trim() || `chore: update ${n} file${n === 1 ? "" : "s"}`;
+    return finalize(rawSubject, input.body, input);
+}
+// ── LLM generation (the command path) ─────────────────────────────────────────────
+/**
+ * Generate publish content from the diff with the model, honoring the commit
+ * rules, then normalize + redact. Resilient: if the model's reply isn't the
+ * expected JSON, the first line becomes the subject and the rest the body.
+ */
+export async function generateWithLlm(provider, input) {
+    const redactedDiff = redactSecrets(input.diff);
+    const system = buildSystemPrompt(input);
+    const user = buildUserPrompt({ ...input, diff: redactedDiff });
+    let text = "";
+    for await (const ev of provider.stream({
+        system,
+        messages: [{ role: "user", content: user }],
+    })) {
+        if (ev.type === "text_delta")
+            text += ev.text;
+        else if (ev.type === "error")
+            throw ev.error;
+    }
+    const parsed = parseGenerated(text);
+    const rawSubject = parsed.commitSubject || parsed.prTitle || "";
+    const body = parsed.prBody || parsed.commitBody;
+    return finalize(rawSubject, body, input, {
+        branchName: parsed.branchName,
+        commitBody: parsed.commitBody,
+        prBody: parsed.prBody,
+    });
+}
+/** Shared final assembly: normalize the subject, redact bodies, pick a branch. */
+function finalize(rawSubject, rawBody, input, extra = {}) {
+    const commitSubject = normalizeSubject(rawSubject, input.scopes);
+    const body = redactSecrets((rawBody ?? extra.prBody ?? "").trim() ||
+        assembleBody({
+            what: rawSubject || commitSubject,
+            verification: "`pnpm -r typecheck && pnpm lint && pnpm -r test`",
+        }));
+    const commitBody = redactSecrets((extra.commitBody ?? rawBody ?? "").trim());
+    const branchName = input.currentBranch ??
+        sanitizeBranch(extra.branchName) ??
+        slugifyBranch(commitSubject);
+    return {
+        branchName,
+        commitSubject,
+        commitBody,
+        prTitle: commitSubject,
+        prBody: body,
+    };
+}
+/** Accept a model-proposed branch only if it's a plausible ref; else null. */
+function sanitizeBranch(name) {
+    if (!name)
+        return null;
+    const clean = name.trim();
+    if (clean === "" || /\s/.test(clean) || clean.length > 80)
+        return null;
+    return /^[A-Za-z0-9._/-]+$/.test(clean) ? clean : null;
+}
+/** Parse the model reply: a JSON object if present, else first-line/rest. */
+export function parseGenerated(text) {
+    const obj = extractJsonObject(text);
+    if (obj)
+        return obj;
+    const trimmed = text.trim();
+    const nl = trimmed.indexOf("\n");
+    return nl === -1
+        ? { commitSubject: trimmed }
+        : {
+            commitSubject: trimmed.slice(0, nl),
+            prBody: trimmed.slice(nl + 1).trim(),
+        };
+}
+/** Pull the first balanced `{…}` out of `text` and JSON-parse it. */
+function extractJsonObject(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return null;
+    try {
+        const obj = JSON.parse(text.slice(start, end + 1));
+        return obj && typeof obj === "object" ? obj : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildSystemPrompt(input) {
+    const lines = [
+        "You write the pull request for a code change: a conventional-commit subject, a structured PR body, and a branch name.",
+        "Respond with ONLY a JSON object — no markdown fences, no prose — with these string fields:",
+        '{ "branchName", "commitSubject", "commitBody", "prTitle", "prBody" }.',
+        "",
+        "Rules for commitSubject (and prTitle, which must equal it):",
+        "- Conventional Commits: `type(scope): subject` (scope optional).",
+        "- The subject MUST NOT start with a capital letter (commitlint subject-case).",
+        "- Imperative mood, no trailing period, ≤ 72 characters.",
+    ];
+    if (input.scopes.length > 0) {
+        lines.push(`- If you use a scope, it must be one of: ${input.scopes.join(", ")}.`);
+    }
+    lines.push("", "prBody: GitHub-flavored markdown with sections '## What changed', '## Why', '## Verification'.", "branchName: short kebab-case `type/slug`, no spaces.", "Never include secrets, tokens, or credentials in any field.");
+    if (input.skillBody) {
+        lines.push("", "Repository commit conventions (authoritative):", input.skillBody);
+    }
+    return lines.join("\n");
+}
+function buildUserPrompt(input) {
+    const lines = [`Base branch: ${input.base}`];
+    if (input.currentBranch)
+        lines.push(`Current branch: ${input.currentBranch}`);
+    if (input.sessionSummary)
+        lines.push("", "What I did this session:", input.sessionSummary);
+    lines.push("", "Diff:", "```diff", input.diff || "(no textual diff)", "```");
+    return lines.join("\n");
+}

package/dist/vcs/git.d.ts

@@ -0,0 +1,52 @@
+export interface GitResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+}
+/** Run `git <args>` in `cwd`, capturing stdout/stderr/exit. Never throws. */
+export declare function runGitCapture(args: string[], cwd: string): GitResult;
+/** The current branch name, or `null` when detached / not a repo. */
+export declare function currentBranch(cwd: string): string | null;
+/** The default set of branch names cruxy will never write to directly. */
+export declare const DEFAULT_PROTECTED_BRANCHES: readonly ["main", "master"];
+/**
+ * Is `branch` protected? The built-in `main`/`master` plus any names from config.
+ * Case-insensitive so `Main`/`MASTER` are caught too.
+ */
+export declare function isProtectedBranch(branch: string, extra?: readonly string[]): boolean;
+export interface EnsureBranchResult {
+    /** The branch we ended up on (always a non-protected branch). */
+    readonly branch: string;
+    /** Whether we created/switched (true) or were already on a feature branch. */
+    readonly switched: boolean;
+}
+/**
+ * Guarantee we're on a non-protected feature branch before any commit/push. If
+ * already on a feature branch, stay there. If on a protected branch, switch to
+ * `desired` (creating it if needed). Throws if `desired` is itself protected.
+ */
+export declare function ensureFeatureBranch(cwd: string, desired: string, protectedExtra?: readonly string[]): EnsureBranchResult;
+/** Stage every change in the working tree (`git add -A`). */
+export declare function stageAll(cwd: string): void;
+/** Whether the working tree (staged or not) has any changes to commit. */
+export declare function hasChanges(cwd: string): boolean;
+/**
+ * Commit the staged changes with a conventional message. Refuses on a protected
+ * branch (last-line guard) and **never** passes `--no-verify`, so the commitlint
+ * `commit-msg` hook runs. Subject and body go as separate `-m` flags.
+ */
+export declare function commit(cwd: string, subject: string, body: string, protectedExtra?: readonly string[]): void;
+/**
+ * Push `branch` to `origin`, setting upstream. **Never** `--force`, **never**
+ * `--no-verify` — the pre-push hook (build · typecheck · lint · test + main
+ * guard) runs and a failure is surfaced verbatim. Refuses on a protected branch.
+ */
+export declare function push(cwd: string, branch: string, protectedExtra?: readonly string[]): void;
+/**
+ * The change set for content generation: the working-tree diff relative to
+ * `base` (covers committed-on-branch *and* uncommitted edits), plus the names of
+ * untracked files (which a plain `git diff` omits). Falls back to the diff vs
+ * `HEAD` when `base` isn't reachable (shallow clone / brand-new repo).
+ */
+export declare function diffAgainst(cwd: string, base: string): string;

package/dist/vcs/git.js

@@ -0,0 +1,152 @@
+import { spawnSync } from "node:child_process";
+import { gitProtectedBranch, gitPushFailed } from "../errors/index.js";
+/**
+ * Typed git wrappers for the PR flow (C.15). Unlike the read-only helpers in
+ * `utils/git.ts`, these run *mutating* commands and must surface failures loudly,
+ * so {@link runGitCapture} returns stdout **and** stderr + exit code rather than
+ * collapsing everything to `null`.
+ *
+ * Safety rails are baked in here (defense-in-depth, independent of the gate):
+ *   • never commit or push on a protected branch,
+ *   • never `--force`, never `--no-verify` (the husky hooks are load-bearing).
+ */
+/** Hard ceiling per git invocation. Push runs the pre-push verify hook, which
+ * builds + tests the whole repo, so it gets a generous timeout. */
+const GIT_TIMEOUT_MS = 10 * 60_000;
+/** Run `git <args>` in `cwd`, capturing stdout/stderr/exit. Never throws. */
+export function runGitCapture(args, cwd) {
+    const res = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+        // Push must reach the network and run the pre-push hook; don't cap output.
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const stdout = typeof res.stdout === "string" ? res.stdout : "";
+    const stderr = typeof res.stderr === "string" ? res.stderr : "";
+    if (res.error) {
+        return {
+            ok: false,
+            stdout,
+            stderr: stderr || res.error.message,
+            code: null,
+        };
+    }
+    return { ok: res.status === 0, stdout, stderr, code: res.status };
+}
+/** The current branch name, or `null` when detached / not a repo. */
+export function currentBranch(cwd) {
+    const res = runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    if (!res.ok)
+        return null;
+    const branch = res.stdout.trim();
+    return branch === "" || branch === "HEAD" ? null : branch;
+}
+/** The default set of branch names cruxy will never write to directly. */
+export const DEFAULT_PROTECTED_BRANCHES = ["main", "master"];
+/**
+ * Is `branch` protected? The built-in `main`/`master` plus any names from config.
+ * Case-insensitive so `Main`/`MASTER` are caught too.
+ */
+export function isProtectedBranch(branch, extra = []) {
+    const all = new Set([...DEFAULT_PROTECTED_BRANCHES, ...extra].map((b) => b.toLowerCase()));
+    return all.has(branch.trim().toLowerCase());
+}
+/** Does a local branch already exist? */
+function branchExists(cwd, branch) {
+    return runGitCapture(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], cwd).ok;
+}
+/**
+ * Guarantee we're on a non-protected feature branch before any commit/push. If
+ * already on a feature branch, stay there. If on a protected branch, switch to
+ * `desired` (creating it if needed). Throws if `desired` is itself protected.
+ */
+export function ensureFeatureBranch(cwd, desired, protectedExtra = []) {
+    const current = currentBranch(cwd);
+    if (current && !isProtectedBranch(current, protectedExtra)) {
+        return { branch: current, switched: false };
+    }
+    if (isProtectedBranch(desired, protectedExtra)) {
+        // Refusing to "switch" onto another protected branch — that's not a fix.
+        throw gitProtectedBranch(desired);
+    }
+    const args = branchExists(cwd, desired)
+        ? ["switch", desired]
+        : ["switch", "-c", desired];
+    const res = runGitCapture(args, cwd);
+    if (!res.ok) {
+        throw gitPushFailed(desired, res.stderr || `git ${args.join(" ")} failed`);
+    }
+    return { branch: desired, switched: true };
+}
+/** Stage every change in the working tree (`git add -A`). */
+export function stageAll(cwd) {
+    const res = runGitCapture(["add", "-A"], cwd);
+    if (!res.ok) {
+        throw gitPushFailed(currentBranch(cwd) ?? "(unknown)", res.stderr || "git add -A failed");
+    }
+}
+/** Whether the working tree (staged or not) has any changes to commit. */
+export function hasChanges(cwd) {
+    return runGitCapture(["status", "--porcelain"], cwd).stdout.trim() !== "";
+}
+/**
+ * Commit the staged changes with a conventional message. Refuses on a protected
+ * branch (last-line guard) and **never** passes `--no-verify`, so the commitlint
+ * `commit-msg` hook runs. Subject and body go as separate `-m` flags.
+ */
+export function commit(cwd, subject, body, protectedExtra = []) {
+    const branch = currentBranch(cwd);
+    if (branch && isProtectedBranch(branch, protectedExtra)) {
+        throw gitProtectedBranch(branch);
+    }
+    const args = ["commit", "-m", subject];
+    if (body.trim() !== "")
+        args.push("-m", body);
+    const res = runGitCapture(args, cwd);
+    if (!res.ok) {
+        // A rejected commit is almost always the commitlint hook — surface it as a
+        // push failure carrying git's own stderr (we never bypass the hook).
+        throw gitPushFailed(branch ?? "(unknown)", res.stderr || "git commit failed");
+    }
+}
+/**
+ * Push `branch` to `origin`, setting upstream. **Never** `--force`, **never**
+ * `--no-verify` — the pre-push hook (build · typecheck · lint · test + main
+ * guard) runs and a failure is surfaced verbatim. Refuses on a protected branch.
+ */
+export function push(cwd, branch, protectedExtra = []) {
+    if (isProtectedBranch(branch, protectedExtra)) {
+        throw gitProtectedBranch(branch);
+    }
+    const res = runGitCapture(["push", "-u", "origin", branch], cwd);
+    if (!res.ok) {
+        throw gitPushFailed(branch, res.stderr || "git push failed");
+    }
+}
+/** Does a commit-ish (branch, ref, SHA) resolve in this repo? */
+function revExists(cwd, rev) {
+    return runGitCapture(["rev-parse", "--verify", "--quiet", rev], cwd).ok;
+}
+/**
+ * The change set for content generation: the working-tree diff relative to
+ * `base` (covers committed-on-branch *and* uncommitted edits), plus the names of
+ * untracked files (which a plain `git diff` omits). Falls back to the diff vs
+ * `HEAD` when `base` isn't reachable (shallow clone / brand-new repo).
+ */
+export function diffAgainst(cwd, base) {
+    const ref = revExists(cwd, base) ? base : "HEAD";
+    const tracked = revExists(cwd, ref)
+        ? runGitCapture(["diff", ref], cwd).stdout
+        : "";
+    const untracked = runGitCapture(["ls-files", "--others", "--exclude-standard"], cwd).stdout.trim();
+    const parts = [tracked.trimEnd()];
+    if (untracked !== "") {
+        parts.push(`\n# untracked files (new):\n${untracked
+            .split("\n")
+            .map((f) => `+ ${f}`)
+            .join("\n")}`);
+    }
+    return parts.filter((p) => p.trim() !== "").join("\n");
+}

package/dist/vcs/github.d.ts

@@ -0,0 +1,44 @@
+import type { ForgeProvider, PullRequestResult, PullRequestSpec, RepoInfo } from "./types.js";
+/**
+ * GitHub implementation of {@link ForgeProvider} (C.15) — the only forge that
+ * ships today. It talks to the REST API directly (no octokit dependency) and
+ * keeps `fetch` injectable for tests. Everything GitHub-specific lives here;
+ * nothing above {@link ForgeProvider} knows it's GitHub.
+ */
+export interface GitHubProviderOptions {
+    /** The resolved forge token (see `auth.ts`). */
+    token: string;
+    /** Injected fetch (tests / advanced); defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class GitHubProvider implements ForgeProvider {
+    readonly id = "github";
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(opts: GitHubProviderOptions);
+    getRepoInfo(cwd: string): Promise<RepoInfo>;
+    createPullRequest(repo: RepoInfo, spec: PullRequestSpec): Promise<PullRequestResult>;
+    /** Look up an open PR for `owner:head`, or `null` if there isn't one. */
+    private findOpenPr;
+    private fetchDefaultBranch;
+    /** Issue an authenticated REST call, resolving the API base from the host. */
+    private api;
+}
+/**
+ * Parse a git remote URL into `{ host, owner, repo }`, supporting the https,
+ * `scp`-style ssh, and `ssh://` forms. Returns `null` for anything we can't
+ * confidently parse as `host/owner/repo`.
+ */
+export declare function parseRemote(url: string): {
+    host: string;
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Construct the forge provider for a token. GitHub today; the GitLab/Bitbucket
+ * branch slots in here later (e.g. switch on a configured provider id) without
+ * touching the orchestrator.
+ */
+export declare function createForgeProvider(token: string, opts?: {
+    fetchImpl?: typeof fetch;
+}): ForgeProvider;

package/dist/vcs/github.js

@@ -0,0 +1,145 @@
+import { forgeApi, forgeAuth, usageError } from "../errors/index.js";
+import { runGitCapture } from "./git.js";
+export class GitHubProvider {
+    id = "github";
+    token;
+    fetchImpl;
+    constructor(opts) {
+        this.token = opts.token;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async getRepoInfo(cwd) {
+        const remote = runGitCapture(["remote", "get-url", "origin"], cwd);
+        if (!remote.ok || remote.stdout.trim() === "") {
+            throw usageError("no `origin` remote is configured for this repository", [
+                "add one with `git remote add origin <url>`",
+                "cruxy opens pull requests against the `origin` remote",
+            ]);
+        }
+        const parsed = parseRemote(remote.stdout.trim());
+        if (!parsed) {
+            throw usageError(`could not parse the origin remote as a GitHub repository: ${remote.stdout.trim()}`, ["ensure `origin` points at a github.com (or GitHub Enterprise) repo"]);
+        }
+        // Best-effort: resolve the default branch so the PR base can default to it.
+        const defaultBranch = await this.fetchDefaultBranch(parsed).catch(() => undefined);
+        return { ...parsed, defaultBranch };
+    }
+    async createPullRequest(repo, spec) {
+        const res = await this.api(repo, `/repos/${repo.owner}/${repo.repo}/pulls`, {
+            method: "POST",
+            body: JSON.stringify({
+                title: spec.title,
+                body: spec.body,
+                head: spec.head,
+                base: spec.base,
+                draft: spec.draft ?? false,
+            }),
+        });
+        if (res.status === 201) {
+            const pr = (await res.json());
+            return { url: pr.html_url, number: pr.number, alreadyExists: false };
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw forgeAuth(repo.host);
+        }
+        // A PR for this head already exists — find and return it instead of failing.
+        if (res.status === 422) {
+            const existing = await this.findOpenPr(repo, spec.head).catch(() => null);
+            if (existing) {
+                return {
+                    url: existing.html_url,
+                    number: existing.number,
+                    alreadyExists: true,
+                };
+            }
+            throw forgeApi("GitHub rejected the pull request (422) and no existing PR was found", await safeBody(res), { status: 422, owner: repo.owner, repo: repo.repo });
+        }
+        throw forgeApi(`GitHub returned HTTP ${res.status} while opening the pull request`, await safeBody(res), { status: res.status, owner: repo.owner, repo: repo.repo });
+    }
+    /** Look up an open PR for `owner:head`, or `null` if there isn't one. */
+    async findOpenPr(repo, head) {
+        const q = `head=${encodeURIComponent(`${repo.owner}:${head}`)}&state=open`;
+        const res = await this.api(repo, `/repos/${repo.owner}/${repo.repo}/pulls?${q}`, { method: "GET" });
+        if (!res.ok)
+            return null;
+        const prs = (await res.json());
+        return prs.length > 0 ? prs[0] : null;
+    }
+    async fetchDefaultBranch(repo) {
+        const res = await this.api(repo, `/repos/${repo.owner}/${repo.repo}`, {
+            method: "GET",
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body.default_branch;
+    }
+    /** Issue an authenticated REST call, resolving the API base from the host. */
+    api(repo, path, init) {
+        return this.fetchImpl(`${apiBase(repo.host)}${path}`, {
+            ...init,
+            headers: {
+                accept: "application/vnd.github+json",
+                authorization: `Bearer ${this.token}`,
+                "x-github-api-version": "2022-11-28",
+                "content-type": "application/json",
+                "user-agent": "cruxy-cli",
+                ...init.headers,
+            },
+        });
+    }
+}
+/** The REST API base for a host: github.com → api.github.com; GHE → /api/v3. */
+function apiBase(host) {
+    return host === "github.com"
+        ? "https://api.github.com"
+        : `https://${host}/api/v3`;
+}
+/**
+ * Parse a git remote URL into `{ host, owner, repo }`, supporting the https,
+ * `scp`-style ssh, and `ssh://` forms. Returns `null` for anything we can't
+ * confidently parse as `host/owner/repo`.
+ */
+export function parseRemote(url) {
+    const trimmed = url.trim().replace(/\.git$/, "");
+    // scp-style: git@github.com:owner/repo
+    const scp = /^[^@]+@([^:]+):(.+)$/.exec(trimmed);
+    if (scp)
+        return splitOwnerRepo(scp[1], scp[2]);
+    // url-style: https://… , ssh://… , git://…
+    try {
+        const u = new URL(trimmed);
+        return splitOwnerRepo(u.host, u.pathname.replace(/^\//, ""));
+    }
+    catch {
+        return null;
+    }
+}
+function splitOwnerRepo(host, ownerRepo) {
+    const parts = ownerRepo.split("/").filter((p) => p !== "");
+    if (parts.length < 2)
+        return null;
+    // Owner is the first segment, repo the last (handles GHE org/sub paths simply).
+    const owner = parts[0];
+    const repo = parts[parts.length - 1];
+    if (!owner || !repo)
+        return null;
+    return { host, owner, repo };
+}
+/** Read a response body for error context without throwing on a parse failure. */
+async function safeBody(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return `HTTP ${res.status}`;
+    }
+}
+/**
+ * Construct the forge provider for a token. GitHub today; the GitLab/Bitbucket
+ * branch slots in here later (e.g. switch on a configured provider id) without
+ * touching the orchestrator.
+ */
+export function createForgeProvider(token, opts = {}) {
+    return new GitHubProvider({ token, fetchImpl: opts.fetchImpl });
+}

package/dist/vcs/guidance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The repo's commit conventions, gathered best-effort so PR generation honors
+ * them automatically (C.15): the C.18 git-commit skill body and the commitlint
+ * scope allow-list. Both are optional — a repo may have neither — so every lookup
+ * degrades to a sensible empty default rather than failing the PR flow.
+ */
+export interface CommitGuidance {
+    /** The git-commit SKILL.md body, embedded verbatim into the LLM prompt. */
+    skillBody?: string;
+    /** commitlint `scope-enum` values; empty ⇒ no scope constraint. */
+    scopes: string[];
+}
+/** Load the git-commit skill body + commitlint scopes for `cwd`. Never throws. */
+export declare function loadCommitGuidance(cwd: string): Promise<CommitGuidance>;
+/**
+ * Extract the `scope-enum` allow-list from a repo's commitlint config. Supports
+ * the JS/CJS module forms (imported) and JSON. Any failure ⇒ `[]` (no
+ * constraint), so a malformed or absent config never blocks a PR.
+ */
+export declare function loadCommitlintScopes(cwd: string): Promise<string[]>;