@cruxy/cli 0.4.0 → 0.6.0

package/dist/errors/constructors.d.ts

@@ -18,6 +18,31 @@ export declare function permissionDenied(path: string, underlying?: unknown): Cr
 export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
 export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
 export declare function indexFailed(underlying?: unknown): CruxyError;
+/**
+ * A side-effecting action needs approval but cruxy can't ask (non-interactive,
+ * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI
+ * can tell "needed approval" apart from a usage error.
+ */
+export declare function approvalRequired(summary: string): CruxyError;
+/**
+ * No forge token could be resolved (PR generation, C.15). The chain is env →
+ * `gh auth token` → fail. We never prompt for, store, or persist a token, so the
+ * fix is always to provide one in the environment.
+ */
+export declare function forgeAuth(host?: string): CruxyError;
+/**
+ * A commit/push was attempted on a protected branch (`main`/`master`/configured).
+ * The PR flow must branch off first; this is the last-line guard.
+ */
+export declare function gitProtectedBranch(branch: string): CruxyError;
+/** The forge REST API returned an error (non-auth) while opening a PR. */
+export declare function forgeApi(title: string, underlying?: unknown, meta?: Record<string, unknown>): CruxyError;
+/**
+ * `git push` failed — most often the husky `pre-push` verify hook (build ·
+ * typecheck · lint · test) or a rejected non-fast-forward. We never `--force` or
+ * `--no-verify`, so the underlying reason is surfaced verbatim.
+ */
+export declare function gitPushFailed(branch: string, stderr?: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -208,6 +208,89 @@ export function indexFailed(underlying) {
         underlying,
     });
 }
+// ── approval (exit 10) ────────────────────────────────────────────────────────
+/**
+ * A side-effecting action needs approval but cruxy can't ask (non-interactive,
+ * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI
+ * can tell "needed approval" apart from a usage error.
+ */
+export function approvalRequired(summary) {
+    return new CruxyError({
+        code: ErrorCode.ApprovalRequired,
+        title: "this action needs your approval, but cruxy is running non-interactively",
+        cause: `pending action — ${summary}`,
+        nextSteps: [
+            "run cruxy in an interactive terminal so you can approve actions",
+            "or scope the task to read-only actions (no file writes or shell commands)",
+        ],
+        meta: { summary },
+    });
+}
+// ── vcs: forge + git (exit 4 / 2 / 6 / 5) ─────────────────────────────────────
+/**
+ * No forge token could be resolved (PR generation, C.15). The chain is env →
+ * `gh auth token` → fail. We never prompt for, store, or persist a token, so the
+ * fix is always to provide one in the environment.
+ */
+export function forgeAuth(host = "github.com") {
+    return new CruxyError({
+        code: ErrorCode.ForgeAuth,
+        title: `no ${host} token available to open a pull request`,
+        cause: "checked GITHUB_TOKEN, GH_TOKEN, and `gh auth token` — none provided a token",
+        nextSteps: [
+            "export GITHUB_TOKEN=… (a personal access token with `repo` scope)",
+            "or install the GitHub CLI and run `gh auth login`",
+        ],
+        meta: { host },
+    });
+}
+/**
+ * A commit/push was attempted on a protected branch (`main`/`master`/configured).
+ * The PR flow must branch off first; this is the last-line guard.
+ */
+export function gitProtectedBranch(branch) {
+    return new CruxyError({
+        code: ErrorCode.GitProtectedBranch,
+        title: `refusing to commit or push on the protected branch "${branch}"`,
+        cause: "cruxy never writes directly to a protected branch",
+        nextSteps: [
+            "switch to a feature branch first, e.g. `git switch -c feat/my-change`",
+            "adjust the protected list with `git.protectedBranches` in your config",
+        ],
+        meta: { branch },
+    });
+}
+/** The forge REST API returned an error (non-auth) while opening a PR. */
+export function forgeApi(title, underlying, meta) {
+    return new CruxyError({
+        code: ErrorCode.ForgeApi,
+        title,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "retry in a moment; if it persists, check the forge's status",
+            "re-run with --verbose to see the API response",
+        ],
+        underlying,
+        meta,
+    });
+}
+/**
+ * `git push` failed — most often the husky `pre-push` verify hook (build ·
+ * typecheck · lint · test) or a rejected non-fast-forward. We never `--force` or
+ * `--no-verify`, so the underlying reason is surfaced verbatim.
+ */
+export function gitPushFailed(branch, stderr) {
+    return new CruxyError({
+        code: ErrorCode.GitPushFailed,
+        title: `failed to push branch "${branch}"`,
+        cause: stderr?.trim() || undefined,
+        nextSteps: [
+            "check the error above (the pre-push hook runs build · typecheck · lint · test)",
+            "fix the reported issue and try again — cruxy never force-pushes or skips hooks",
+        ],
+        meta: { branch },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -16,15 +16,19 @@ export declare const ErrorCode: {
     readonly Usage: "CRUXY_E_USAGE";
     readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
     readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
+    readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";
     readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
     readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
     readonly AuthInvalid: "CRUXY_E_AUTH_INVALID";
+    readonly ForgeAuth: "CRUXY_E_FORGE_AUTH";
     readonly GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE";
+    readonly GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED";
     readonly Api: "CRUXY_E_API";
     readonly ApiRateLimit: "CRUXY_E_API_RATE_LIMIT";
     readonly ApiOverloaded: "CRUXY_E_API_OVERLOADED";
     readonly BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED";
+    readonly ForgeApi: "CRUXY_E_FORGE_API";
     readonly FileNotFound: "CRUXY_E_FILE_NOT_FOUND";
     readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
     readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
@@ -33,6 +37,7 @@ export declare const ErrorCode: {
     readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
     readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";
     readonly SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND";
+    readonly ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -18,19 +18,23 @@ export const ErrorCode = {
     Usage: "CRUXY_E_USAGE",
     ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
     ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
+    GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
     // auth (exit 4)
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
+    ForgeAuth: "CRUXY_E_FORGE_AUTH",
     // network (exit 5)
     GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE",
+    GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED",
     // api (exit 6)
     Api: "CRUXY_E_API",
     ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
     ApiOverloaded: "CRUXY_E_API_OVERLOADED",
     BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
+    ForgeApi: "CRUXY_E_FORGE_API",
     // filesystem (exit 7)
     FileNotFound: "CRUXY_E_FILE_NOT_FOUND",
     PermissionDenied: "CRUXY_E_PERMISSION_DENIED",
@@ -42,6 +46,8 @@ export const ErrorCode = {
     // skill (exit 9)
     SkillInvalid: "CRUXY_E_SKILL_INVALID",
     SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND",
+    // approval (exit 10)
+    ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -52,15 +58,19 @@ const EXIT_CODES = {
     [ErrorCode.Usage]: 2,
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
+    [ErrorCode.GitProtectedBranch]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
+    [ErrorCode.ForgeAuth]: 4,
     [ErrorCode.GatewayUnreachable]: 5,
+    [ErrorCode.GitPushFailed]: 5,
     [ErrorCode.Api]: 6,
     [ErrorCode.ApiRateLimit]: 6,
     [ErrorCode.ApiOverloaded]: 6,
     [ErrorCode.BudgetExhausted]: 6,
+    [ErrorCode.ForgeApi]: 6,
     [ErrorCode.FileNotFound]: 7,
     [ErrorCode.PermissionDenied]: 7,
     [ErrorCode.PathEscape]: 7,
@@ -69,6 +79,7 @@ const EXIT_CODES = {
     [ErrorCode.IndexFailed]: 8,
     [ErrorCode.SkillInvalid]: 9,
     [ErrorCode.SkillNotFound]: 9,
+    [ErrorCode.ApprovalRequired]: 10,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

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