@cruxy/cli 0.3.0 → 0.6.0

package/dist/indexing/service.js

@@ -1,6 +1,7 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { globalDir } from "../config/index.js";
+import { indexStoreUnavailable } from "../errors/index.js";
 import { GLOBAL_DIR_NAME } from "../constants.js";
 import { createEmbedder } from "./embedder.js";
 import { Indexer } from "./indexer.js";
@@ -124,8 +125,10 @@ async function openStore(root, kind, logger) {
         return { store, storePath: dbPath };
     }
     catch (err) {
+        // store=sqlite is explicit: fail loud with a code. store=auto degrades to
+        // an in-memory index with a warning (no quality loss, just no persistence).
         if (kind === "sqlite")
-            throw err;
+            throw indexStoreUnavailable(err);
         logger.warn(`sqlite index unavailable (${err.message}); using an in-memory index`);
         return { store: new InMemoryVectorStore(), storePath: null };
     }

package/dist/skills/loader.d.ts

@@ -1,3 +1,4 @@
+import { CruxyError } from "../errors/index.js";
 import { type Skill, type SkillCatalog, type SkillError, type SkillSource } from "./types.js";
 /** The three source directories the loader scans. */
 export interface LoaderSources {
@@ -16,7 +17,7 @@ interface SkillCandidate {
     dir: string;
 }
 /** Thrown by `getSkill` when no catalog entry matches the requested name. */
-export declare class SkillNotFoundError extends Error {
+export declare class SkillNotFoundError extends CruxyError {
     constructor(message: string);
 }
 /**

package/dist/skills/parser.d.ts

@@ -1,10 +1,12 @@
+import { CruxyError } from "../errors/index.js";
 import { type SkillFrontmatter } from "./types.js";
 /**
- * Thrown when a SKILL.md is malformed or fails validation. The message is
- * actionable (it names the problem) and is caught by the loader, which records
- * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
  */
-export declare class SkillValidationError extends Error {
+export declare class SkillValidationError extends CruxyError {
     constructor(message: string);
 }
 /** The validated frontmatter plus the markdown body that followed it. */

package/dist/skills/parser.js

@@ -1,12 +1,20 @@
+import { CruxyError, ErrorCode } from "../errors/index.js";
 import { SkillFrontmatterSchema } from "./types.js";
 /**
- * Thrown when a SKILL.md is malformed or fails validation. The message is
- * actionable (it names the problem) and is caught by the loader, which records
- * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
  */
-export class SkillValidationError extends Error {
+export class SkillValidationError extends CruxyError {
     constructor(message) {
-        super(message);
+        super({
+            code: ErrorCode.SkillInvalid,
+            title: message,
+            nextSteps: [
+                "see the built-in `using-skills` skill for the SKILL.md rules",
+            ],
+        });
         this.name = "SkillValidationError";
     }
 }

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/paths.d.ts

@@ -1,10 +1,12 @@
+import { CruxyError } from "../../errors/index.js";
 import type { ToolContext } from "../types.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export declare class PathEscapeError extends Error {
+export declare class PathEscapeError extends CruxyError {
     constructor(message: string);
 }
 /**

package/dist/tools/file/paths.js

@@ -1,13 +1,15 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { CruxyError, ErrorCode } from "../../errors/index.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export class PathEscapeError extends Error {
+export class PathEscapeError extends CruxyError {
     constructor(message) {
-        super(message);
+        super({ code: ErrorCode.PathEscape, title: message });
         this.name = "PathEscapeError";
     }
 }

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 {};