@cruxy/cli 0.4.0 → 0.7.0

package/dist/plan/submit-plan.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/**
+ * The `submit_plan` tool (C.31): the agent's only way to propose a plan. It is a
+ * normal tool on the same loop seam as everything else — no hidden control flow.
+ * During the propose phase this is the *only* non-read-only tool registered, so
+ * the agent structurally cannot act before approval.
+ *
+ * Validation is fail-loud: a malformed or empty plan returns `{ok:false}` so the
+ * model sees the error and retries, exactly like any other tool.
+ */
+const stepSchema = z.object({
+    title: z.string().min(1).describe("One-line imperative title for the step."),
+    rationale: z
+        .string()
+        .min(1)
+        .describe("Why this step exists / what it accomplishes."),
+    kind: z
+        .enum(["read", "mutate", "destructive"])
+        .describe("Risk estimate: read (no side effects), mutate (reversible file writes), " +
+        "destructive (shell, deletes, PR-open). Advisory — the approval gate re-checks each action."),
+});
+const parameters = z.object({
+    steps: z
+        .array(stepSchema)
+        .min(1)
+        .describe("Ordered steps that fully accomplish the task."),
+});
+/** Build a `submit_plan` tool bound to `holder`, which captures the last plan. */
+export function makeSubmitPlanTool(holder) {
+    return {
+        name: "submit_plan",
+        description: "Propose an ordered, step-by-step plan for the user to approve before you act. " +
+            "Call this first (and only this) in plan mode; do not take any other action until the plan is approved.",
+        parameters,
+        async execute(input) {
+            // zod already guarantees ≥1 step with non-empty fields; this is the
+            // fail-loud belt-and-suspenders for an empty array slipping through.
+            if (input.steps.length === 0) {
+                return { ok: false, error: "a plan must have at least one step" };
+            }
+            const steps = input.steps.map((s, i) => ({
+                id: String(i + 1),
+                title: s.title.trim(),
+                rationale: s.rationale.trim(),
+                kind: s.kind,
+                status: "pending",
+            }));
+            const plan = { steps };
+            holder.plan = plan;
+            return {
+                ok: true,
+                output: `Plan received (${steps.length} step${steps.length === 1 ? "" : "s"}) and shown to the user for approval. ` +
+                    "Do not take any further action now — end your turn.",
+            };
+        },
+    };
+}

package/dist/plan/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+/**
+ * The agent's risk *estimate* for a step, used only to render intent and shape
+ * the approval copy. It is NOT authoritative: the real U.3 gate re-classifies
+ * every concrete action at execution time (a step the agent calls "mutate" whose
+ * action turns out destructive still confirms).
+ */
+export type PlanStepKind = "read" | "mutate" | "destructive";
+/** Live execution status of a step. */
+export type PlanStepStatus = "pending" | "running" | "done" | "failed";
+export interface PlanStep {
+    /** Stable 1-based id assigned on submit (e.g. "1"). */
+    readonly id: string;
+    /** One-line imperative title. */
+    readonly title: string;
+    /** Why this step exists / what it accomplishes. */
+    readonly rationale: string;
+    /** The agent's risk estimate (advisory; see {@link PlanStepKind}). */
+    readonly kind: PlanStepKind;
+    /** Mutated in place as execution progresses. */
+    status: PlanStepStatus;
+}
+export interface Plan {
+    readonly steps: PlanStep[];
+}
+/**
+ * The user's decision at the plan-approval prompt.
+ * - `approve` — execute; every action still hits the U.3 gate.
+ * - `approve-grant` — execute AND auto-allow the safe (read/mutate, grantable)
+ *   steps for this run; destructive/ungrantable actions still confirm.
+ * - `revise` — send `feedback` back to the agent for a revised plan.
+ * - `abort` — cancel; nothing executes (also the default-deny for EOF/Ctrl-C).
+ */
+export type PlanDecision = {
+    readonly kind: "approve";
+} | {
+    readonly kind: "approve-grant";
+} | {
+    readonly kind: "revise";
+    readonly feedback: string;
+} | {
+    readonly kind: "abort";
+};
+/** Outcome of executing an approved plan. */
+export interface PlanExecutionResult {
+    /** True if every step reached `done`. */
+    readonly completed: boolean;
+    /** True if a step failed and the user chose to abort the run. */
+    readonly halted: boolean;
+    /** The id of the step that failed, when halted. */
+    readonly failedStepId?: string;
+}
+/** A mutable holder the `submit_plan` tool writes the captured plan into. */
+export interface PlanHolder {
+    plan: Plan | null;
+}

package/dist/plan/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+export {};

package/dist/tools/create-pull-request.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+/**
+ * Open a pull request from the agent's work (C.15): branch → conventional commit
+ * → push → open PR, all behind the one U.3 approval. The model authors `title`
+ * and `body`; anything omitted is filled deterministically (no second LLM call —
+ * the agent IS the LLM). The token is resolved from the environment / `gh`; it is
+ * never prompted for or stored.
+ */
+declare const parameters: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    base: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    body?: string | undefined;
+    base?: string | undefined;
+    title?: string | undefined;
+}, {
+    body?: string | undefined;
+    base?: string | undefined;
+    title?: string | undefined;
+}>;
+export declare const createPullRequestTool: Tool<typeof parameters>;
+export {};

package/dist/tools/create-pull-request.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { CruxyError, ErrorCode } from "../errors/index.js";
+import { createForgeProvider, createPrService, fillContent, loadCommitGuidance, resolveForgeToken, } from "../vcs/index.js";
+/**
+ * Open a pull request from the agent's work (C.15): branch → conventional commit
+ * → push → open PR, all behind the one U.3 approval. The model authors `title`
+ * and `body`; anything omitted is filled deterministically (no second LLM call —
+ * the agent IS the LLM). The token is resolved from the environment / `gh`; it is
+ * never prompted for or stored.
+ */
+const parameters = z.object({
+    title: z
+        .string()
+        .optional()
+        .describe("PR title as a conventional-commit subject (e.g. `feat(cli): add X`). " +
+        "Lowercase subject; omit to auto-generate."),
+    body: z
+        .string()
+        .optional()
+        .describe("PR body in markdown (what changed · why · verification). Omit to auto-generate."),
+    base: z
+        .string()
+        .optional()
+        .describe("Base branch to merge into (defaults to the repo's default branch)."),
+});
+export const createPullRequestTool = {
+    name: "create_pull_request",
+    description: "Open a pull request for the current changes: create a feature branch, make a " +
+        "conventional commit, push, and open the PR. Branch/commit/PR are shown for your " +
+        "approval before anything runs. Never acts on a protected branch and never force-pushes.",
+    parameters,
+    async execute(input, ctx) {
+        try {
+            const token = resolveForgeToken();
+            const forge = createForgeProvider(token);
+            const guidance = await loadCommitGuidance(ctx.cwd);
+            const service = createPrService({
+                cwd: ctx.cwd,
+                config: ctx.config,
+                forge,
+                requestApproval: ctx.requestApproval,
+                generate: async (i) => fillContent({
+                    ...i,
+                    scopes: guidance.scopes,
+                    skillBody: guidance.skillBody,
+                }),
+            });
+            const outcome = await service.openPullRequest({
+                title: input.title,
+                body: input.body,
+                base: input.base,
+            });
+            if (!outcome.approved) {
+                return {
+                    ok: false,
+                    error: outcome.feedback ?? "you declined to open the pull request",
+                };
+            }
+            const verb = outcome.alreadyExists
+                ? "a pull request already exists"
+                : "opened pull request";
+            return { ok: true, output: `${verb}: ${outcome.url}` };
+        }
+        catch (err) {
+            // The non-interactive approval error must reach the boundary (exit 10);
+            // every other coded failure is surfaced to the model so it can adapt.
+            if (err instanceof CruxyError &&
+                err.code === ErrorCode.ApprovalRequired) {
+                throw err;
+            }
+            if (err instanceof CruxyError) {
+                return { ok: false, error: formatCoded(err) };
+            }
+            throw err;
+        }
+    },
+};
+/** One-line, model-readable rendering of a coded error + its next steps. */
+function formatCoded(err) {
+    const head = err.cause ? `${err.title} — ${err.cause}` : err.title;
+    const steps = err.nextSteps.length > 0 ? ` next steps: ${err.nextSteps.join("; ")}` : "";
+    return `${head} (${err.code}).${steps}`;
+}

package/dist/tools/file/apply-patch.js

@@ -80,12 +80,12 @@ export const applyPatchTool = {
             planned.push(planResult.planned);
         }
         // One approval for the whole patch — denial writes nothing.
-        const approved = await ctx.approve({
+        const decision = await ctx.requestApproval({
             kind: "patch",
             preview: { type: "patch", files: planned.map(toPreview) },
         });
-        if (!approved) {
-            return { ok: false, error: "patch denied" };
+        if (!decision.allow) {
+            return { ok: false, error: decision.feedback ?? "patch denied" };
         }
         // Validation passed and the user approved; apply everything. A mid-apply I/O
         // failure is rare but reported with what already landed.

package/dist/tools/file/edit-file.js

@@ -57,13 +57,16 @@ export const editFileTool = {
                 error: `old_str not unique (${matches} matches); add surrounding context to disambiguate`,
             };
         }
-        const approved = await ctx.approve({
+        const decision = await ctx.requestApproval({
             kind: "edit",
             path: abs,
             preview: { type: "edit", oldStr: input.old_str, newStr: input.new_str },
         });
-        if (!approved) {
-            return { ok: false, error: `edit to ${input.path} denied` };
+        if (!decision.allow) {
+            return {
+                ok: false,
+                error: decision.feedback ?? `edit to ${input.path} denied`,
+            };
         }
         // Replace the single occurrence by index to avoid `$`-pattern interpretation.
         const idx = content.indexOf(input.old_str);

package/dist/tools/file/write-file.js

@@ -35,13 +35,16 @@ export const writeFileTool = {
         const lines = allLines.slice(0, PREVIEW_LINES);
         const omittedLines = Math.max(0, allLines.length - PREVIEW_LINES);
         // Approve BEFORE any mutation; a denial writes nothing.
-        const approved = await ctx.approve({
+        const decision = await ctx.requestApproval({
             kind: "write",
             path: abs,
             preview: { type: "write", exists, lines, omittedLines },
         });
-        if (!approved) {
-            return { ok: false, error: `write to ${input.path} denied` };
+        if (!decision.allow) {
+            return {
+                ok: false,
+                error: decision.feedback ?? `write to ${input.path} denied`,
+            };
         }
         try {
             await fs.mkdir(path.dirname(abs), { recursive: true });

package/dist/tools/index.d.ts

@@ -5,4 +5,5 @@ export * from "./git-status.js";
 export * from "./search-codebase.js";
 export * from "./list-skills.js";
 export * from "./load-skill.js";
+export * from "./create-pull-request.js";
 export * from "./file/index.js";

package/dist/tools/index.js

@@ -5,4 +5,5 @@ export * from "./git-status.js";
 export * from "./search-codebase.js";
 export * from "./list-skills.js";
 export * from "./load-skill.js";
+export * from "./create-pull-request.js";
 export * from "./file/index.js";

package/dist/tools/registry.js

@@ -6,6 +6,7 @@ import { runCommandTool } from "./shell/index.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
+import { createPullRequestTool } from "./create-pull-request.js";
 /**
  * In-memory catalogue of the tools available to the agent. Names are unique;
  * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
@@ -65,5 +66,6 @@ export function buildDefaultRegistry() {
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);
+    registry.register(createPullRequestTool);
     return registry;
 }

package/dist/tools/shell/run-command.js

@@ -14,9 +14,17 @@ export const runCommandTool = {
             .describe("The shell command to run (executed via the system shell)."),
     }),
     async execute(input, ctx) {
-        // Approve BEFORE anything runs; a denial executes nothing.
-        if (!(await ctx.approve({ kind: "shell", command: input.command }))) {
-            return { ok: false, error: "denied by user" };
+        // Approve BEFORE anything runs; a denial executes nothing. A thrown
+        // CRUXY_E_APPROVAL_REQUIRED (non-interactive) propagates — do not catch.
+        const decision = await ctx.requestApproval({
+            kind: "shell",
+            command: input.command,
+        });
+        if (!decision.allow) {
+            return {
+                ok: false,
+                error: decision.feedback ?? "command denied by the user",
+            };
         }
         return runBounded(input.command, ctx);
     },

package/dist/tools/types.d.ts

@@ -1,5 +1,6 @@
 import type { z, ZodTypeAny } from "zod";
 import type { CruxyConfig } from "../config/index.js";
+import type { ApprovalDecision } from "../approval/types.js";
 import type { logger } from "../utils/logger.js";
 /** The leveled logger instance shared across the CLI. */
 type Logger = typeof logger;
@@ -61,6 +62,20 @@ export type ActionPreview =
  | {
     type: "patch";
     files: PatchFilePreview[];
+}
+/**
+ * The whole publish plan for a `vcs` action (C.15): the feature branch, the
+ * conventional commit, and the PR title/body — shown as one block so the user
+ * approves the entire branch → commit → push → open-PR sequence at once.
+ */
+ | {
+    type: "pr";
+    branch: string;
+    base: string;
+    commitSubject: string;
+    commitBody: string;
+    prTitle: string;
+    prBody: string;
 };
 /**
  * A side-effecting action a tool wants to take, passed to `ctx.approve`. The
@@ -68,12 +83,12 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
     /** The command to run (shell). */
     command?: string;
-    /** Exact-change preview rendered above the prompt (write/edit/patch). */
+    /** Exact-change preview rendered above the prompt (write/edit/patch/vcs). */
     preview?: ActionPreview;
 }
 /**
@@ -89,11 +104,15 @@ export interface ToolContext {
     /** Shared leveled logger (diagnostics to stderr, `print` to stdout). */
     logger: Logger;
     /**
-     * Permission gate for side-effecting actions. Returns `true` when the action
-     * is allowed. Backed by the interactive `Approver` (see agent/approval.ts);
-     * tests may inject their own.
+     * The approval gate every side-effecting tool funnels through, **before** any
+     * mutation. Returns a decision: `{allow:true}` to proceed, or `{allow:false,
+     * feedback?}` (a clean rejection whose feedback is surfaced to the agent).
+     * Backed by the risk-tiered `ApprovalService` (see src/approval); it may
+     * *throw* `CRUXY_E_APPROVAL_REQUIRED` when it can't ask (non-interactive),
+     * which propagates to the boundary rather than being swallowed. Read-only
+     * tools never call this.
      */
-    approve(action: ApproveAction): Promise<boolean>;
+    requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
 }
 /**
  * The one interface every tool implements. `parameters` is a zod schema; it both

package/dist/vcs/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve a forge token (C.15). The chain is, in order:
+ *   1. `GITHUB_TOKEN`
+ *   2. `GH_TOKEN`
+ *   3. `gh auth token` (if the GitHub CLI is installed and logged in)
+ *   4. fail loud — {@link forgeAuth} (`CRUXY_E_FORGE_AUTH`)
+ *
+ * We **never** prompt for, store, or persist a token: it's read from the
+ * environment / `gh` on every run, exactly like provider API keys.
+ */
+/** Injection seams so the chain is testable without real env / a real `gh`. */
+export interface ForgeAuthDeps {
+    /** Environment to read tokens from (defaults to `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Run `gh auth token`, returning the token or `null`. Defaults to the CLI. */
+    ghToken?: () => string | null;
+}
+/**
+ * Resolve a forge token or throw {@link forgeAuth}. `host` is only used to make
+ * the error message specific.
+ */
+export declare function resolveForgeToken(deps?: ForgeAuthDeps, host?: string): string;

package/dist/vcs/auth.js

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+import { forgeAuth } from "../errors/index.js";
+/** Invoke `gh auth token`; returns the trimmed token, or `null` on any failure. */
+function ghAuthToken() {
+    const res = spawnSync("gh", ["auth", "token"], {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+    });
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string") {
+        return null;
+    }
+    const token = res.stdout.trim();
+    return token === "" ? null : token;
+}
+/**
+ * Resolve a forge token or throw {@link forgeAuth}. `host` is only used to make
+ * the error message specific.
+ */
+export function resolveForgeToken(deps = {}, host = "github.com") {
+    const env = deps.env ?? process.env;
+    const fromEnv = env.GITHUB_TOKEN?.trim() || env.GH_TOKEN?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const fromGh = (deps.ghToken ?? ghAuthToken)();
+    if (fromGh && fromGh.trim() !== "")
+        return fromGh.trim();
+    throw forgeAuth(host);
+}

package/dist/vcs/generate.d.ts

@@ -0,0 +1,72 @@
+import type { Provider } from "@cruxy/sdk";
+import type { GeneratedContent } from "./types.js";
+/**
+ * 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 declare const CONVENTIONAL_TYPES: readonly ["feat", "fix", "chore", "docs", "refactor", "test", "perf", "build", "ci", "style", "revert"];
+export interface GenerateInput {
+    /** The change set to summarize (already from `diffAgainst`). */
+    diff: string;
+    /** The PR base branch. */
+    base: string;
+    /** The branch the change is on, if already a feature branch. */
+    currentBranch?: string;
+    /** A short summary of what the agent did this session, if available. */
+    sessionSummary?: string;
+    /** commitlint scope allow-list; empty ⇒ no scope constraint. */
+    scopes: string[];
+    /** The git-commit SKILL.md body, embedded into the LLM prompt verbatim. */
+    skillBody?: string;
+    /** Caller-supplied title (e.g. the agent's), normalized rather than generated. */
+    title?: string;
+    /** Caller-supplied body. */
+    body?: string;
+}
+/** Strip anything that looks like a credential from `text`. */
+export declare function redactSecrets(text: string): string;
+/**
+ * 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 declare function normalizeSubject(raw: string, scopes?: string[]): string;
+/** A safe branch name `type/slug` derived from a conventional subject. */
+export declare function slugifyBranch(subject: string): string;
+/** Assemble a structured PR body: what changed · why · verification. */
+export declare function assembleBody(parts: {
+    what: string;
+    why?: string;
+    verification?: string;
+}): string;
+/**
+ * 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 declare function fillContent(input: GenerateInput): GeneratedContent;
+/**
+ * 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 declare function generateWithLlm(provider: Provider, input: GenerateInput): Promise<GeneratedContent>;
+interface ParsedGenerated {
+    branchName?: string;
+    commitSubject?: string;
+    commitBody?: string;
+    prTitle?: string;
+    prBody?: string;
+}
+/** Parse the model reply: a JSON object if present, else first-line/rest. */
+export declare function parseGenerated(text: string): ParsedGenerated;
+export {};