@cruxy/cli 0.3.0 → 0.6.0

package/README.md

@@ -26,7 +26,14 @@ cruxy run                           # interactive session
 
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
   `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
-  `list_skills`, `load_skill`.
+  `list_skills`, `load_skill`, `create_pull_request`.
+- **Pull requests** — `cruxy pr` (and the `create_pull_request` tool) turn the
+  current changes into a PR: feature branch → conventional commit → push → open
+  the PR, with a generated title/body, all behind the approval gate. GitHub ships
+  first behind a swappable `ForgeProvider`; the token is read from
+  `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token` (never stored). It never commits
+  or pushes on a protected branch, never force-pushes, and never bypasses the
+  commit/push hooks.
 - **Codebase index** — a local, incremental semantic index (`cruxy index`)
   behind the `search_codebase` tool. Embeddings run on-device via fastembed
   (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
@@ -70,6 +77,44 @@ Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
 `~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
 built-in `using-skills` skill for the authoring rules.
 
+### Pull requests
+
+```bash
+export GITHUB_TOKEN=ghp_...   # or GH_TOKEN, or be logged in with `gh`
+
+cruxy pr                              # generate + open a PR for the current changes
+cruxy pr --base develop               # target a specific base branch
+cruxy pr --title "fix(cli): …"        # override the generated title
+cruxy pr --draft                      # open as a draft
+```
+
+The whole plan — branch, commit, and PR title/body — is shown for approval
+before anything runs. On a protected branch (`main`/`master`/configured via
+`git.protectedBranches`) cruxy branches off first; the base defaults to
+`git.defaultBase`, then the repo's default branch, then `main`.
+
+## Errors & exit codes
+
+Every user-facing error prints a title, the cause (when known), concrete next
+steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
+(or `--log-level debug` / `DEBUG=1`) to see the underlying error and stack;
+`NO_COLOR` disables color. Exit codes are stable per category, so scripts can
+branch on them:
+
+| Exit | Category   | Example codes                                                                                                      |
+| ---- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `0`  | success    | —                                                                                                                  |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                 |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`      |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                   |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                           |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                           |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API` |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                       |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                    |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                 |
+| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`                                                                                        |
+
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.
 

package/dist/agent/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./loop.js";
 export * from "./session.js";
 export * from "./prompts.js";
-export * from "./approval.js";

package/dist/agent/index.js

@@ -1,4 +1,3 @@
 export * from "./loop.js";
 export * from "./session.js";
 export * from "./prompts.js";
-export * from "./approval.js";

package/dist/agent/loop.js

@@ -1,3 +1,4 @@
+import { providerUnsupported } from "../errors/index.js";
 import { buildSystemPrompt } from "./prompts.js";
 /**
  * Drive the model/tool loop over an existing conversation. Streams each turn,
@@ -11,7 +12,7 @@ import { buildSystemPrompt } from "./prompts.js";
 export async function runAgent(args) {
     const { provider, registry, config, ctx } = args;
     if (!provider.supportsTools) {
-        throw new Error(`provider ${config.model.provider} does not support tool use; cruxy run requires a tool-capable provider`);
+        throw providerUnsupported(config.model.provider);
     }
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
@@ -29,7 +30,6 @@ export async function runAgent(args) {
         tools: registry
             .list()
             .map((tool) => ({ name: tool.name, description: tool.description })),
-        autoApprove: config.approval.mode === "auto",
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
     });

package/dist/agent/prompts.d.ts

@@ -26,8 +26,6 @@ export interface PromptContext {
         branch: string;
         dirty: boolean;
     } | null;
-    /** When true, the agent may act without per-step confirmation. */
-    autoApprove: boolean;
     /** Optional extra instructions (e.g. from a project CRUXY.md). */
     projectInstructions?: string | null;
 }

package/dist/agent/prompts.js

@@ -69,9 +69,9 @@ function renderTools(tools) {
 }
 /** Assemble the full system prompt for a session. */
 export function buildSystemPrompt(ctx) {
-    const approval = ctx.autoApprove
-        ? "Auto-approve is on for this session, so you may proceed without asking — but still pause and confirm before genuinely destructive or irreversible actions."
-        : "Confirm with the user before taking any destructive or irreversible action.";
+    // Every side-effecting action goes through the approval gate (U.3); the user
+    // always gets the final say before a mutation or a destructive action.
+    const approval = "Side-effecting actions (file writes, shell commands) require the user's approval; destructive or irreversible actions are flagged distinctly.";
     const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
     if (ctx.projectInstructions?.trim()) {

package/dist/approval/classify.d.ts

@@ -0,0 +1,18 @@
+import type { ApproveAction } from "../tools/types.js";
+import type { ApprovalRequest } from "./types.js";
+/**
+ * Classify a pending tool action into a {@link RiskTier} + a tight session
+ * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
+ * (most-restrictive) so a future/unknown action can never slip through as
+ * read-only or low-risk.
+ */
+export declare function classify(action: ApproveAction, cwd: string): ApprovalRequest;
+/**
+ * Tokenize a command **only if** we can positively prove it is a single, simple
+ * invocation (the granted program plus plain args, no shell features). Returns
+ * the tokens, or `null` for anything we can't prove safe — deny-by-default. This
+ * is what makes a `git` session grant refuse `git push && rm -rf /`.
+ */
+export declare function commandTokens(command: string): string[] | null;
+/** Is `target` the root itself or a descendant of it? (Also true if root is a file == target.) */
+export declare function isInside(root: string, target: string): boolean;

package/dist/approval/classify.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+/**
+ * Classify a pending tool action into a {@link RiskTier} + a tight session
+ * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
+ * (most-restrictive) so a future/unknown action can never slip through as
+ * read-only or low-risk.
+ */
+export function classify(action, cwd) {
+    const root = path.resolve(cwd);
+    switch (action.kind) {
+        case "write":
+        case "edit":
+            return fileRequest(action, "mutate", root);
+        case "patch":
+            // A patch that deletes files is destructive; create/update-only is mutate.
+            return fileRequest(action, patchHasDelete(action) ? "destructive" : "mutate", root);
+        case "shell":
+            return shellRequest(action, root);
+        case "vcs":
+            return vcsRequest(action, root);
+        default:
+            return {
+                action,
+                tier: "destructive",
+                scope: { kind: "none" },
+                summary: `perform an unrecognized action (${describeKind(action)})`,
+                targets: [],
+                cwd: root,
+            };
+    }
+}
+// ── shell ─────────────────────────────────────────────────────────────────────
+// Any shell control/expansion character means we cannot prove the command is a
+// single simple invocation. Covers && || ; | ` $ ( ) { } * ? ~ ! # ' " \ < > and
+// newlines (so >> and & background are caught by > and & too).
+const SHELL_META = /[&|;<>`$(){}*?~!#'"\\\n\r]/;
+// A token we positively accept as a simple argument — letters, digits, and a
+// small set of punctuation that has no shell meaning in an unquoted word.
+const SAFE_ARG = /^[A-Za-z0-9_./=,:+@%-]+$/;
+/**
+ * Tokenize a command **only if** we can positively prove it is a single, simple
+ * invocation (the granted program plus plain args, no shell features). Returns
+ * the tokens, or `null` for anything we can't prove safe — deny-by-default. This
+ * is what makes a `git` session grant refuse `git push && rm -rf /`.
+ */
+export function commandTokens(command) {
+    const trimmed = command.trim();
+    if (trimmed === "" || SHELL_META.test(trimmed))
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    return tokens.every((t) => SAFE_ARG.test(t)) ? tokens : null;
+}
+function shellRequest(action, root) {
+    const command = action.command ?? "";
+    // A session grant is only offered when the command is provably simple; its
+    // scope is the program token. Complex commands get `none` (approve-once only).
+    const tokens = commandTokens(command);
+    const scope = tokens
+        ? { kind: "shell-prefix", token: tokens[0] }
+        : { kind: "none" };
+    return {
+        action,
+        tier: "destructive",
+        scope,
+        summary: `run: ${command}`,
+        targets: [],
+        cwd: root,
+    };
+}
+// ── vcs (open pull request) ─────────────────────────────────────────────────────
+/**
+ * A pull-request publish (C.15): branch → commit → push → open PR. Always
+ * `destructive` (it pushes under the user's identity) and never session-grantable
+ * — scope `none`, so every PR is approved on its own. The preview carries the
+ * full plan; the summary names the PR.
+ */
+function vcsRequest(action, root) {
+    const title = action.preview?.type === "pr" ? action.preview.prTitle : "a pull request";
+    return {
+        action,
+        tier: "destructive",
+        scope: { kind: "none" },
+        summary: `open PR: ${title}`,
+        targets: [],
+        cwd: root,
+    };
+}
+// ── file (write / edit / patch) ────────────────────────────────────────────────
+function fileRequest(action, tier, root) {
+    const targets = fileTargets(action, root);
+    return {
+        action,
+        tier,
+        scope: fileScope(targets, root),
+        summary: fileSummary(action, targets, root),
+        targets,
+        cwd: root,
+    };
+}
+/** Absolute target paths for a file action (write/edit: one; patch: many). */
+function fileTargets(action, root) {
+    if (action.kind === "write" || action.kind === "edit") {
+        return action.path ? [path.resolve(root, action.path)] : [];
+    }
+    if (action.kind === "patch" && action.preview?.type === "patch") {
+        return action.preview.files.map((f) => path.resolve(root, f.path));
+    }
+    return [];
+}
+/**
+ * The tight subtree a file grant covers: the common parent directory of the
+ * targets. **Root-cap:** if that parent is the project root, never grant the
+ * whole project — narrow to the exact single file, or refuse (scope `none`) for
+ * a multi-file action spanning the root.
+ */
+function fileScope(targets, root) {
+    if (targets.length === 0)
+        return { kind: "none" };
+    const dir = commonDir(targets);
+    if (dir === root || !isInside(root, dir)) {
+        return targets.length === 1
+            ? { kind: "file-subtree", root: targets[0] } // exact-file grant
+            : { kind: "none" };
+    }
+    return { kind: "file-subtree", root: dir };
+}
+function fileSummary(action, targets, root) {
+    const verb = action.kind === "write"
+        ? "write"
+        : action.kind === "edit"
+            ? "edit"
+            : "patch";
+    if (targets.length === 1)
+        return `${verb}: ${path.relative(root, targets[0]) || targets[0]}`;
+    return `${verb}: ${targets.length} files`;
+}
+function patchHasDelete(action) {
+    return (action.preview?.type === "patch" &&
+        action.preview.files.some((f) => f.op === "delete"));
+}
+// ── shared path helpers ────────────────────────────────────────────────────────
+/** Is `target` the root itself or a descendant of it? (Also true if root is a file == target.) */
+export function isInside(root, target) {
+    return target === root || target.startsWith(root + path.sep);
+}
+/** The deepest directory that contains every path. */
+function commonDir(paths) {
+    let common = path.dirname(paths[0]);
+    for (const p of paths.slice(1)) {
+        const dir = path.dirname(p);
+        while (!isInside(common, dir)) {
+            const parent = path.dirname(common);
+            if (parent === common)
+                return common; // filesystem root
+            common = parent;
+        }
+    }
+    return common;
+}
+function describeKind(action) {
+    return String(action.kind ?? "unknown");
+}

package/dist/approval/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./classify.js";
+export * from "./policy.js";
+export * from "./prompt.js";
+export * from "./service.js";

package/dist/approval/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./classify.js";
+export * from "./policy.js";
+export * from "./prompt.js";
+export * from "./service.js";

package/dist/approval/policy.d.ts

@@ -0,0 +1,37 @@
+import { type PromptIO } from "./prompt.js";
+import type { ApprovalDecision, ApprovalPolicy, ApprovalRequest, Scope } from "./types.js";
+/**
+ * The in-memory, per-session allowlist. Grants are **scoped** (a command prefix
+ * or a path subtree) and **tier-keyed** (a `mutate` grant can never cover a
+ * `destructive` action), **never blanket**, and **never persisted**. A new
+ * session ⇒ a new allowlist (it is owned by the per-session ApprovalService).
+ */
+export declare class SessionAllowlist {
+    private grants;
+    /** Record a session grant for `request`'s scope. No-op when nothing is safe to grant. */
+    grant(request: ApprovalRequest): void;
+    /** Does an existing grant cover `request`? Requires same tier **and** scope match. */
+    allows(request: ApprovalRequest): boolean;
+    clear(): void;
+    size(): number;
+}
+/**
+ * Whether `scope` covers `request`. Shell: the command must be *provably simple*
+ * ({@link commandTokens}) and its program token must equal the granted token —
+ * so a `git` grant never matches `git push && rm -rf /`. File: every target must
+ * resolve inside the granted subtree.
+ */
+export declare function scopeCovers(scope: Exclude<Scope, {
+    kind: "none";
+}>, request: ApprovalRequest): boolean;
+/**
+ * The default policy: consult the allowlist, otherwise prompt. On "allow this
+ * session" it records the scoped grant; a rejection carries optional feedback
+ * back to the agent.
+ */
+export declare class InteractivePolicy implements ApprovalPolicy {
+    private readonly allowlist;
+    private readonly io;
+    constructor(allowlist: SessionAllowlist, io: PromptIO);
+    decide(request: ApprovalRequest): Promise<ApprovalDecision>;
+}

package/dist/approval/policy.js

@@ -0,0 +1,81 @@
+import { commandTokens, isInside } from "./classify.js";
+import { promptForApproval } from "./prompt.js";
+/**
+ * The in-memory, per-session allowlist. Grants are **scoped** (a command prefix
+ * or a path subtree) and **tier-keyed** (a `mutate` grant can never cover a
+ * `destructive` action), **never blanket**, and **never persisted**. A new
+ * session ⇒ a new allowlist (it is owned by the per-session ApprovalService).
+ */
+export class SessionAllowlist {
+    grants = [];
+    /** Record a session grant for `request`'s scope. No-op when nothing is safe to grant. */
+    grant(request) {
+        if (request.scope.kind === "none")
+            return;
+        this.grants.push({ tier: request.tier, scope: request.scope });
+    }
+    /** Does an existing grant cover `request`? Requires same tier **and** scope match. */
+    allows(request) {
+        return this.grants.some((g) => g.tier === request.tier && scopeCovers(g.scope, request));
+    }
+    clear() {
+        this.grants = [];
+    }
+    size() {
+        return this.grants.length;
+    }
+}
+/**
+ * Whether `scope` covers `request`. Shell: the command must be *provably simple*
+ * ({@link commandTokens}) and its program token must equal the granted token —
+ * so a `git` grant never matches `git push && rm -rf /`. File: every target must
+ * resolve inside the granted subtree.
+ */
+export function scopeCovers(scope, request) {
+    if (scope.kind === "shell-prefix") {
+        if (request.action.kind !== "shell")
+            return false;
+        const tokens = commandTokens(request.action.command ?? "");
+        return tokens !== null && tokens[0] === scope.token;
+    }
+    // file-subtree
+    return (request.targets.length > 0 &&
+        request.targets.every((t) => isInside(scope.root, t)));
+}
+/**
+ * The default policy: consult the allowlist, otherwise prompt. On "allow this
+ * session" it records the scoped grant; a rejection carries optional feedback
+ * back to the agent.
+ */
+export class InteractivePolicy {
+    allowlist;
+    io;
+    constructor(allowlist, io) {
+        this.allowlist = allowlist;
+        this.io = io;
+    }
+    async decide(request) {
+        if (this.allowlist.allows(request))
+            return { allow: true };
+        const choice = await promptForApproval(request, this.io);
+        switch (choice.kind) {
+            case "once":
+                return { allow: true };
+            case "session":
+                this.allowlist.grant(request);
+                return { allow: true };
+            case "reject":
+                return choice.reason
+                    ? {
+                        allow: false,
+                        feedback: `The user rejected this action. Reason: ${choice.reason}`,
+                    }
+                    : { allow: false };
+            case "instruct":
+                return {
+                    allow: false,
+                    feedback: `The user rejected this action and asked you to do this instead: ${choice.instruction}`,
+                };
+        }
+    }
+}

package/dist/approval/prompt.d.ts

@@ -0,0 +1,33 @@
+import type { ApprovalRequest } from "./types.js";
+/** The four user choices (plus the implicit default-deny). */
+export type PromptChoice = {
+    kind: "once";
+} | {
+    kind: "session";
+} | {
+    kind: "reject";
+    reason?: string;
+} | {
+    kind: "instruct";
+    instruction: string;
+};
+/** I/O surface for the prompt — injectable so tests script the keys/lines. */
+export interface PromptIO {
+    write(text: string): void;
+    /** Read a single keypress; resolves "" on EOF / Ctrl-C. */
+    readKey(): Promise<string>;
+    /** Read one line (no trailing newline); resolves "" on EOF. */
+    readLine(): Promise<string>;
+    /** Whether to emit ANSI color. */
+    color: boolean;
+}
+/**
+ * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
+ * read a follow-up line (reason / instruction). Anything else — including EOF —
+ * is a reject.
+ */
+export declare function promptForApproval(request: ApprovalRequest, io: PromptIO): Promise<PromptChoice>;
+/** Render the full prompt block: header, detail (diff or command+cwd), choices. */
+export declare function render(request: ApprovalRequest, color: boolean): string;
+/** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
+export declare function defaultPromptIO(color: boolean): PromptIO;