@cruxy/cli 0.4.0 → 0.6.0

package/dist/vcs/guidance.js

@@ -0,0 +1,76 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getSkill, loadCatalog } from "../skills/loader.js";
+import { defaultSources } from "../skills/service.js";
+/** Load the git-commit skill body + commitlint scopes for `cwd`. Never throws. */
+export async function loadCommitGuidance(cwd) {
+    const [skillBody, scopes] = await Promise.all([
+        loadGitCommitSkill(cwd),
+        loadCommitlintScopes(cwd),
+    ]);
+    return { skillBody, scopes };
+}
+/** Read the git-commit skill body via the skills catalog, or `undefined`. */
+async function loadGitCommitSkill(cwd) {
+    try {
+        const catalog = await loadCatalog(defaultSources(cwd));
+        const skill = await getSkill(catalog, "git-commit");
+        return skill.body;
+    }
+    catch {
+        return undefined;
+    }
+}
+const COMMITLINT_FILES = [
+    "commitlint.config.cjs",
+    "commitlint.config.js",
+    "commitlint.config.mjs",
+    ".commitlintrc.cjs",
+    ".commitlintrc.js",
+    ".commitlintrc.json",
+    ".commitlintrc",
+];
+/**
+ * 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 async function loadCommitlintScopes(cwd) {
+    for (const name of COMMITLINT_FILES) {
+        const file = path.join(cwd, name);
+        try {
+            await fs.access(file);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const config = name.endsWith(".json") || name === ".commitlintrc"
+                ? JSON.parse(await fs.readFile(file, "utf8"))
+                : await importConfig(file);
+            const scopes = extractScopeEnum(config);
+            if (scopes.length > 0)
+                return scopes;
+        }
+        catch {
+            // Try the next candidate; a parse failure isn't fatal.
+        }
+    }
+    return [];
+}
+async function importConfig(file) {
+    const mod = (await import(pathToFileURL(file).href));
+    return mod.default ?? mod;
+}
+/** Pull `rules['scope-enum'][2]` (the allowed values array) out of a config. */
+function extractScopeEnum(config) {
+    const rules = config?.rules;
+    const rule = rules?.["scope-enum"];
+    if (!Array.isArray(rule))
+        return [];
+    const values = rule[2];
+    return Array.isArray(values)
+        ? values.filter((v) => typeof v === "string")
+        : [];
+}

package/dist/vcs/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./git.js";
+export * from "./github.js";
+export * from "./auth.js";
+export * from "./generate.js";
+export * from "./guidance.js";
+export * from "./service.js";

package/dist/vcs/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./git.js";
+export * from "./github.js";
+export * from "./auth.js";
+export * from "./generate.js";
+export * from "./guidance.js";
+export * from "./service.js";

package/dist/vcs/service.d.ts

@@ -0,0 +1,53 @@
+import type { ApprovalDecision } from "../approval/types.js";
+import type { CruxyConfig } from "../config/index.js";
+import type { ApproveAction } from "../tools/types.js";
+import type { ForgeProvider, GeneratedContent } from "./types.js";
+/**
+ * The PR-publish orchestrator (C.15): ensure a feature branch → commit → push →
+ * open PR, with the **entire** plan gated by one U.3 approval. Nothing mutates
+ * before the user approves; a rejection aborts cleanly with no commit or push.
+ *
+ * The forge and the content generator are injected, so both call sites — the
+ * `create_pull_request` tool (deterministic fill) and the `cruxy pr` command
+ * (LLM generation) — share this exact flow.
+ */
+/** Produce the publish content for a change set (LLM or deterministic). */
+export type GenerateContent = (input: {
+    diff: string;
+    base: string;
+    currentBranch?: string;
+    title?: string;
+    body?: string;
+}) => Promise<GeneratedContent>;
+export interface PrServiceDeps {
+    cwd: string;
+    config: CruxyConfig;
+    forge: ForgeProvider;
+    generate: GenerateContent;
+    /** The U.3 gate (the same capability tools receive as `ctx.requestApproval`). */
+    requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>;
+}
+export interface OpenPrOptions {
+    /** Override the base branch (else config.git.defaultBase → repo default → main). */
+    base?: string;
+    /** Caller-supplied PR title (normalized, not generated). */
+    title?: string;
+    /** Caller-supplied PR body. */
+    body?: string;
+    draft?: boolean;
+}
+export type OpenPrOutcome = {
+    approved: false;
+    feedback?: string;
+} | {
+    approved: true;
+    url: string;
+    number: number;
+    branch: string;
+    base: string;
+    alreadyExists: boolean;
+};
+/** Build a PR service from its dependencies. */
+export declare function createPrService(deps: PrServiceDeps): {
+    openPullRequest: (opts?: OpenPrOptions) => Promise<OpenPrOutcome>;
+};

package/dist/vcs/service.js

@@ -0,0 +1,79 @@
+import { usageError } from "../errors/index.js";
+import { commit, currentBranch, diffAgainst, ensureFeatureBranch, hasChanges, isProtectedBranch, push, stageAll, } from "./git.js";
+/** Build a PR service from its dependencies. */
+export function createPrService(deps) {
+    return {
+        openPullRequest: (opts = {}) => openPullRequest(deps, opts),
+    };
+}
+async function openPullRequest(deps, opts) {
+    const { cwd, config, forge, generate, requestApproval } = deps;
+    const protectedExtra = config.git.protectedBranches;
+    const branchNow = currentBranch(cwd);
+    if (branchNow === null) {
+        throw usageError("not on a branch (detached HEAD or not a git repository)", ["checkout a branch, or run cruxy inside a git repository"]);
+    }
+    // Resolve the repo + base before generating, so the diff is computed correctly.
+    const repo = await forge.getRepoInfo(cwd);
+    const base = opts.base?.trim() ||
+        config.git.defaultBase?.trim() ||
+        repo.defaultBranch ||
+        "main";
+    const diff = diffAgainst(cwd, base);
+    if (diff.trim() === "" && !hasChanges(cwd)) {
+        throw usageError(`no changes to open a pull request for (vs ${base})`, [
+            "make and save your changes, then try again",
+        ]);
+    }
+    // Keep the current branch only if it's already a feature branch; otherwise let
+    // generation propose a fresh branch name (we're on a protected branch).
+    const onProtected = isProtectedBranch(branchNow, protectedExtra);
+    const content = await generate({
+        diff,
+        base,
+        currentBranch: onProtected ? undefined : branchNow,
+        title: opts.title,
+        body: opts.body,
+    });
+    // ── the one gate: show the whole publish plan before anything mutates ──────────
+    const decision = await requestApproval({
+        kind: "vcs",
+        preview: {
+            type: "pr",
+            branch: content.branchName,
+            base,
+            commitSubject: content.commitSubject,
+            commitBody: content.commitBody,
+            prTitle: content.prTitle,
+            prBody: content.prBody,
+        },
+    });
+    if (!decision.allow) {
+        return { approved: false, feedback: decision.feedback };
+    }
+    // ── approved: execute in order; each git op fails loud with a coded error ──────
+    const ensured = ensureFeatureBranch(cwd, content.branchName, protectedExtra);
+    const head = ensured.branch;
+    if (hasChanges(cwd)) {
+        // stageAll/commit throw on a protected branch (defense-in-depth) and never
+        // pass --no-verify, so the commitlint hook runs.
+        stageAll(cwd);
+        commit(cwd, content.commitSubject, content.commitBody, protectedExtra);
+    }
+    push(cwd, head, protectedExtra);
+    const pr = await forge.createPullRequest(repo, {
+        title: content.prTitle,
+        body: content.prBody,
+        head,
+        base,
+        draft: opts.draft,
+    });
+    return {
+        approved: true,
+        url: pr.url,
+        number: pr.number,
+        branch: head,
+        base,
+        alreadyExists: pr.alreadyExists,
+    };
+}

package/dist/vcs/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Version-control / forge types for PR generation (C.15). The {@link ForgeProvider}
+ * interface is the swap seam — GitHub ships first, GitLab/Bitbucket slot in later
+ * without touching call sites (same discipline as `VectorStore`/`Embedder`).
+ */
+/** Where a repository lives and who owns it, parsed from the `origin` remote. */
+export interface RepoInfo {
+    /** Forge host, e.g. `github.com`. */
+    readonly host: string;
+    /** Repository owner (user or org). */
+    readonly owner: string;
+    /** Repository name (no `.git` suffix). */
+    readonly repo: string;
+    /** Default branch, when the provider can resolve it (PR base fallback). */
+    readonly defaultBranch?: string;
+}
+/** Everything needed to open one pull request. */
+export interface PullRequestSpec {
+    readonly title: string;
+    readonly body: string;
+    /** The branch carrying the change. */
+    readonly head: string;
+    /** The branch to merge into. */
+    readonly base: string;
+    readonly draft?: boolean;
+}
+/** The outcome of opening (or finding an already-open) pull request. */
+export interface PullRequestResult {
+    readonly url: string;
+    readonly number: number;
+    /** True when a PR for this head already existed and we returned it. */
+    readonly alreadyExists: boolean;
+}
+/**
+ * An abstract forge. The orchestrator depends only on this; the concrete
+ * GitHub/GitLab implementation is chosen by {@link createForgeProvider}.
+ */
+export interface ForgeProvider {
+    /** Stable id, e.g. `"github"`. */
+    readonly id: string;
+    /** Parse the repository's `origin` remote into structured {@link RepoInfo}. */
+    getRepoInfo(cwd: string): Promise<RepoInfo>;
+    /** Open a pull request and return its URL (idempotent on already-exists). */
+    createPullRequest(repo: RepoInfo, spec: PullRequestSpec): Promise<PullRequestResult>;
+}
+/**
+ * The full set of fields a PR publish needs, produced by `generate.ts`. The
+ * commit subject and PR title are the same conventional-commit line; the bodies
+ * may differ (the PR body is the richer, structured summary).
+ */
+export interface GeneratedContent {
+    readonly branchName: string;
+    readonly commitSubject: string;
+    readonly commitBody: string;
+    readonly prTitle: string;
+    readonly prBody: string;
+}

package/dist/vcs/types.js

@@ -0,0 +1,6 @@
+/**
+ * Version-control / forge types for PR generation (C.15). The {@link ForgeProvider}
+ * interface is the swap seam — GitHub ships first, GitLab/Bitbucket slot in later
+ * without touching call sites (same discipline as `VectorStore`/`Embedder`).
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {

package/dist/agent/approval.d.ts

@@ -1,41 +0,0 @@
-import type { ApproveAction } from "../tools/index.js";
-import { logger as defaultLogger } from "../utils/logger.js";
-type Logger = typeof defaultLogger;
-/** Reads a single keypress from the user. Returns "" on EOF. */
-export type KeypressReader = () => Promise<string>;
-export interface ApproverConfig {
-    /** "prompt" asks interactively; "auto" approves everything unattended. */
-    mode: "prompt" | "auto";
-    /** Project root, used to render action paths relative for the prompt. */
-    cwd: string;
-    /** Whether stdin is an interactive TTY. */
-    isInteractive: boolean;
-    /** Explicit unattended opt-in (e.g. --yes / --dangerously-approve). */
-    autoApprove?: boolean;
-    /** Keypress source (injectable for tests). Defaults to a raw-mode stdin read. */
-    readKey?: KeypressReader;
-    /** Where the prompt text is written (injectable). Defaults to stderr. */
-    write?: (text: string) => void;
-    /** Logger for unattended / denial diagnostics. */
-    logger?: Logger;
-}
-/**
- * Decides whether a side-effecting tool action may proceed. The single gate every
- * mutating tool funnels through (write/edit today, run_command later).
- *
- * Interactive: prints the action (plus a change preview when the tool supplied
- * one) and reads one key — `y` allow once, `a` allow-all for this run, anything
- * else (including EOF) denies. **Fails closed.**
- * Non-interactive: denies by default unless an explicit opt-in (`mode:"auto"` or
- * `autoApprove`) is set, in which case it auto-approves and warns it's unattended.
- */
-export declare class Approver {
-    /** Session allow-all — scoped to this instance, never persisted. */
-    private allowAll;
-    private warnedUnattended;
-    private readonly cfg;
-    constructor(cfg: ApproverConfig);
-    approve(action: ApproveAction): Promise<boolean>;
-}
-export declare function createApprover(cfg: ApproverConfig): Approver;
-export {};

package/dist/agent/approval.js

@@ -1,179 +0,0 @@
-import path from "node:path";
-import pc from "picocolors";
-import { logger as defaultLogger } from "../utils/logger.js";
-/** Cap on rendered preview lines before collapsing the rest into "...N more". */
-const PREVIEW_MAX_LINES = 40;
-/** Human-readable verb + detail for a pending action. */
-function renderAction(cwd, action) {
-    switch (action.kind) {
-        case "write":
-            return `write  ${path.relative(cwd, action.path ?? "") || action.path}`;
-        case "edit":
-            return `edit  ${path.relative(cwd, action.path ?? "") || action.path}`;
-        case "shell":
-            return `run  ${action.command ?? ""}`;
-        case "patch": {
-            const n = action.preview?.type === "patch" ? action.preview.files.length : 0;
-            return `apply patch (${n} file${n === 1 ? "" : "s"})`;
-        }
-    }
-}
-/**
- * A minimal unified-style diff for one hunk: the removed block (red `-`) then the
- * added block (green `+`). The `-`/`+` prefixes keep it readable without color.
- * Shared by the `edit` and `patch` previews (the C.6 renderer).
- */
-function diffLines(oldStr, newStr) {
-    const removed = oldStr.split("\n").map((l) => pc.red(`- ${l}`));
-    const added = newStr.split("\n").map((l) => pc.green(`+ ${l}`));
-    return [...removed, ...added];
-}
-/**
- * Render every file in an `apply_patch` preview as a combined diff: a per-file
- * header (op + path) followed by its hunk diffs (update), created content
- * (create), or nothing (delete).
- */
-function renderPatchFiles(files) {
-    const out = [];
-    for (const file of files) {
-        if (file.op === "delete") {
-            out.push(pc.red(`delete ${file.path}`));
-        }
-        else if (file.op === "create") {
-            out.push(pc.green(`create ${file.path}`));
-            out.push(...file.lines.map((l) => pc.green(`+ ${l}`)));
-            if (file.omittedLines > 0) {
-                out.push(pc.dim(`  ...${file.omittedLines} more lines`));
-            }
-        }
-        else {
-            out.push(pc.yellow(`update ${file.path}`));
-            for (const hunk of file.hunks) {
-                out.push(...diffLines(hunk.oldStr, hunk.newStr));
-            }
-        }
-    }
-    return out;
-}
-/**
- * Render the exact-change preview for a write/edit action as indented lines, so
- * the user sees what they're approving. Caps the output at `PREVIEW_MAX_LINES`
- * and collapses the overflow into a "...N more" notice. Returns "" when there's
- * nothing to preview. Colors are decorative — the `-`/`+`/header prefixes keep
- * it readable without them.
- */
-function renderPreview(preview) {
-    if (!preview)
-        return "";
-    let lines;
-    if (preview.type === "edit") {
-        lines = diffLines(preview.oldStr, preview.newStr);
-    }
-    else if (preview.type === "patch") {
-        lines = renderPatchFiles(preview.files);
-    }
-    else {
-        const header = preview.exists
-            ? pc.yellow("OVERWRITE existing")
-            : pc.green("create");
-        const body = preview.lines.map((l) => `  ${l}`);
-        if (preview.omittedLines > 0) {
-            body.push(pc.dim(`  ...${preview.omittedLines} more lines`));
-        }
-        lines = [header, ...body];
-    }
-    // Cap the rendered block; collapse the rest into a count.
-    if (lines.length > PREVIEW_MAX_LINES) {
-        const hidden = lines.length - PREVIEW_MAX_LINES;
-        lines = [...lines.slice(0, PREVIEW_MAX_LINES), pc.dim(`...${hidden} more`)];
-    }
-    return lines.map((l) => `  ${l}\n`).join("");
-}
-/**
- * Decides whether a side-effecting tool action may proceed. The single gate every
- * mutating tool funnels through (write/edit today, run_command later).
- *
- * Interactive: prints the action (plus a change preview when the tool supplied
- * one) and reads one key — `y` allow once, `a` allow-all for this run, anything
- * else (including EOF) denies. **Fails closed.**
- * Non-interactive: denies by default unless an explicit opt-in (`mode:"auto"` or
- * `autoApprove`) is set, in which case it auto-approves and warns it's unattended.
- */
-export class Approver {
-    /** Session allow-all — scoped to this instance, never persisted. */
-    allowAll = false;
-    warnedUnattended = false;
-    cfg;
-    constructor(cfg) {
-        this.cfg = {
-            ...cfg,
-            readKey: cfg.readKey ?? readKeyFromStdin,
-            write: cfg.write ?? ((t) => process.stderr.write(t)),
-            logger: cfg.logger ?? defaultLogger,
-        };
-    }
-    async approve(action) {
-        const log = this.cfg.logger ?? defaultLogger;
-        if (this.allowAll)
-            return true;
-        // Explicit unattended opt-in — approve everywhere, warn once.
-        if (this.cfg.mode === "auto" || this.cfg.autoApprove) {
-            if (!this.warnedUnattended) {
-                log.warn("running unattended — auto-approving all tool actions");
-                this.warnedUnattended = true;
-            }
-            return true;
-        }
-        // No way to ask → fail closed.
-        if (!this.cfg.isInteractive) {
-            log.warn(`denied (${renderAction(this.cfg.cwd, action)}): non-interactive — pass --yes or set approval.mode=auto`);
-            return false;
-        }
-        const write = this.cfg.write ?? ((t) => process.stderr.write(t));
-        write(`${pc.yellow("?")} cruxy wants to ${renderAction(this.cfg.cwd, action)}\n` +
-            renderPreview(action.preview) +
-            `  ${pc.dim("[y] allow once · [n] deny · [a] allow all:")} `);
-        const key = (await (this.cfg.readKey ?? readKeyFromStdin)()).toLowerCase();
-        write("\n");
-        if (key === "y")
-            return true;
-        if (key === "a") {
-            this.allowAll = true;
-            return true;
-        }
-        // n, EOF (""), Ctrl-C, or any other key → deny.
-        return false;
-    }
-}
-export function createApprover(cfg) {
-    return new Approver(cfg);
-}
-/**
- * Read a single keypress from stdin in raw mode. Resolves to the first character
- * of the chunk, or "" on EOF. Always restores cooked mode and pauses stdin.
- */
-function readKeyFromStdin() {
-    const stdin = process.stdin;
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onData = (buf) => {
-            cleanup();
-            resolve(buf.toString("utf8").slice(0, 1));
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve("");
-        };
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.once("data", onData);
-        stdin.once("end", onEnd);
-    });
-}