@cruxy/cli 0.4.0 → 0.7.0

package/dist/cli/onboard.d.ts

@@ -0,0 +1,25 @@
+import type { CruxyConfig } from "../config/index.js";
+import { type OnboardingResult } from "../onboarding/index.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export declare function apiKeyEnvVar(provider: string): string;
+/** Run one first-win task end-to-end against the just-saved key. */
+export declare function runFirstWinTask(config: CruxyConfig, cwd: string, prompt: string): Promise<void>;
+export interface MaybeOnboardOptions {
+    /** Whether stdin is a TTY (the gate). */
+    ttyInteractive: boolean;
+    /** Offer the first-win demo run (no real task queued). */
+    offerFirstWin: boolean;
+    cwd: string;
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export declare function maybeRunOnboarding(config: CruxyConfig, opts: MaybeOnboardOptions): Promise<OnboardingResult> | null;

package/dist/cli/onboard.js

@@ -0,0 +1,54 @@
+import { resolveApiKey } from "../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
+import { createStreamPrinter } from "./stream-print.js";
+import { buildAgentSession } from "./session-factory.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}
+/** Run one first-win task end-to-end against the just-saved key. */
+export async function runFirstWinTask(config, cwd, prompt) {
+    const apiKey = resolveApiKey(config.model.provider);
+    if (!apiKey)
+        return; // defensive — the key was just persisted
+    const session = buildAgentSession(config, apiKey, cwd, true);
+    const print = createStreamPrinter((text) => process.stdout.write(text));
+    await session.send(prompt, print);
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export function maybeRunOnboarding(config, opts) {
+    const provider = config.model.provider;
+    if (!isFirstRun({ provider, interactive: opts.ttyInteractive }))
+        return null;
+    const deps = createDefaultDeps({
+        config,
+        cwd: opts.cwd,
+        runTask: opts.offerFirstWin
+            ? (prompt) => runFirstWinTask(config, opts.cwd, prompt)
+            : undefined,
+    });
+    return runOnboarding({
+        provider,
+        mode: "first-run",
+        offerFirstWin: opts.offerFirstWin,
+        io: defaultOnboardingIO(),
+        deps,
+    });
+}

package/dist/cli/program.js

@@ -7,6 +7,11 @@ import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
 import { skillsCommand } from "./commands/skills.js";
+import { prCommand } from "./commands/pr.js";
+import { loginCommand } from "./commands/login.js";
+import { initCommand } from "./commands/init.js";
+import { loadConfig } from "../config/index.js";
+import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -28,15 +33,30 @@ export function buildProgram() {
     program.addCommand(configCommand());
     program.addCommand(indexCommand());
     program.addCommand(skillsCommand());
+    program.addCommand(prCommand());
+    program.addCommand(loginCommand());
+    program.addCommand(initCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.
-    program.action((_opts, command) => {
+    program.action(async (_opts, command) => {
         if (command.args.length > 0) {
             throw usageError(`unknown command: ${command.args[0]}`, [
                 "run `cruxy --help` to see available commands",
             ]);
         }
+        // First-run with no key (and a TTY) → guided setup, with the first-win demo.
+        // Otherwise fall through to the banner (an already-set-up user, or non-TTY).
+        const { config } = loadConfig();
+        const onboarding = maybeRunOnboarding(config, {
+            ttyInteractive: Boolean(process.stdin.isTTY),
+            offerFirstWin: true,
+            cwd: process.cwd(),
+        });
+        if (onboarding) {
+            await onboarding;
+            return;
+        }
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
         logger.print(pc.dim("an agentic coding CLI\n"));
         logger.print("The interactive REPL lands in C.3 (terminal UI).");

package/dist/cli/repl.js

@@ -9,6 +9,7 @@ const HELP = `Commands:
   /clear         clear the conversation history (keep the session)
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
+  /plan          toggle plan mode (propose a plan before executing)
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -18,7 +19,7 @@ const defaultIO = () => ({
 /**
  * Read one line using a readline interface that is created and then **closed
  * before this resolves**. This is the crux of the stdin coordination: while a
- * turn runs (`session.send`), approvals grab stdin in raw mode via the Approver
+ * turn runs (`session.send`), approvals grab stdin in raw mode via the approval prompt
  * — so no readline interface may be live at that moment. Creating a fresh
  * interface per line, and closing it the instant we have input, guarantees the
  * two never contend.
@@ -107,6 +108,14 @@ export async function runInteractive(session, io = defaultIO()) {
                 : "no project instructions found"));
             continue;
         }
+        if (trimmed === "/plan") {
+            session.setPlanMode(!session.getPlanMode());
+            const on = session.getPlanMode();
+            logger.print(pc.dim(on
+                ? "plan mode on — the next prompt proposes a plan for approval"
+                : "plan mode off"));
+            continue;
+        }
         if (trimmed === "/help") {
             logger.print(HELP);
             continue;

package/dist/cli/session-factory.d.ts

@@ -0,0 +1,12 @@
+import type { CruxyConfig } from "../config/index.js";
+import { Session } from "../agent/index.js";
+/**
+ * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
+ * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
+ * The approval gate's interactivity tracks the TTY, exactly as in `run`.
+ *
+ * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
+ * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
+ * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ */
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean): Session;

package/dist/cli/session-factory.js

@@ -0,0 +1,88 @@
+import { createProvider } from "@cruxy/sdk";
+import { loadProjectInstructions } from "../config/index.js";
+import { logger } from "../utils/logger.js";
+import { getGitInfo } from "../utils/git.js";
+import { ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, } from "../approval/index.js";
+import { shouldUseColor } from "../errors/index.js";
+import { buildDefaultRegistry } from "../tools/index.js";
+import { Session } from "../agent/index.js";
+import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+/**
+ * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
+ * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
+ * The approval gate's interactivity tracks the TTY, exactly as in `run`.
+ *
+ * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
+ * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
+ * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ */
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false) {
+    const provider = createProvider({
+        provider: config.model.provider,
+        apiKey,
+        model: config.model.model,
+        maxTokens: config.model.maxTokens,
+        temperature: config.model.temperature,
+        gatewayUrl: config.cruxy.gatewayUrl,
+    });
+    const execRegistry = buildDefaultRegistry();
+    const git = getGitInfo(cwd);
+    const projectInstructions = loadProjectInstructions(cwd);
+    if (planMode) {
+        // One io + allowlist shared by the plan-approval prompt and the per-action
+        // gate, so a grant recorded during execution is honored by U.3's own check.
+        const io = defaultPromptIO(shouldUseColor());
+        const allowlist = new SessionAllowlist();
+        const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
+        const approval = new ApprovalService({
+            cwd,
+            interactive: ttyInteractive,
+            policy: planPolicy,
+            io,
+        });
+        const ctx = {
+            cwd,
+            config,
+            logger,
+            requestApproval: (action) => approval.requestApproval(action),
+        };
+        const planRunner = ({ messages, projectInstructions, onText, }) => runPlanSession({
+            provider,
+            config,
+            ctx,
+            execRegistry,
+            planPolicy,
+            io,
+            interactive: ttyInteractive,
+            messages,
+            git,
+            projectInstructions,
+            onText,
+        });
+        return new Session({
+            provider,
+            registry: execRegistry,
+            config,
+            ctx,
+            git,
+            projectInstructions,
+            planMode: true,
+            planRunner,
+        });
+    }
+    const approval = new ApprovalService({ cwd, interactive: ttyInteractive });
+    const ctx = {
+        cwd,
+        config,
+        logger,
+        requestApproval: (action) => approval.requestApproval(action),
+    };
+    return new Session({
+        provider,
+        registry: execRegistry,
+        config,
+        ctx,
+        git,
+        projectInstructions,
+    });
+}

package/dist/config/credentials.d.ts

@@ -0,0 +1,10 @@
+/** `~/.cruxy/credentials.json` */
+export declare function credentialsPath(): string;
+/** The stored key for `provider`, or `undefined`. Never throws. */
+export declare function readCredential(provider: string, file?: string): string | undefined;
+/**
+ * Persist `key` for `provider`, merging into any existing store. The file is
+ * written `0600` and its directory `0700` so the secret is owner-only — enforced
+ * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ */
+export declare function writeCredential(provider: string, key: string, file?: string): void;

package/dist/config/credentials.js

@@ -0,0 +1,69 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { CREDENTIALS_FILE_NAME } from "../constants.js";
+import { globalDir } from "./paths.js";
+/**
+ * The credentials store (U.6) — the one place a provider API key is persisted.
+ * It lives **outside** `config.json` on purpose: config is secret-free by design
+ * ("the API key comes from env"), so secrets get their own file with restrictive
+ * permissions (`0600`, dir `0700`), the same shape as gh/aws/npm. `resolveApiKey`
+ * reads it as a fallback after the environment.
+ */
+/** Bumped if the on-disk shape ever changes. */
+const CREDENTIALS_VERSION = 1;
+/** `~/.cruxy/credentials.json` */
+export function credentialsPath() {
+    return join(globalDir(), CREDENTIALS_FILE_NAME);
+}
+/** Parse the store at `file`, or `null` if absent/unreadable/malformed. */
+function readStore(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed &&
+            typeof parsed === "object" &&
+            "keys" in parsed &&
+            typeof parsed.keys === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // A corrupt store is treated as absent — onboarding can rewrite it.
+    }
+    return null;
+}
+/** The stored key for `provider`, or `undefined`. Never throws. */
+export function readCredential(provider, file = credentialsPath()) {
+    const store = readStore(file);
+    const key = store?.keys[provider];
+    return typeof key === "string" && key !== "" ? key : undefined;
+}
+/**
+ * Persist `key` for `provider`, merging into any existing store. The file is
+ * written `0600` and its directory `0700` so the secret is owner-only — enforced
+ * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ */
+export function writeCredential(provider, key, file = credentialsPath()) {
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best-effort on platforms without POSIX modes (e.g. Windows).
+    }
+    const store = readStore(file) ?? { version: CREDENTIALS_VERSION, keys: {} };
+    store.version = CREDENTIALS_VERSION;
+    store.keys[provider] = key;
+    writeFileSync(file, JSON.stringify(store, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Best-effort (see above).
+    }
+}

package/dist/config/index.d.ts

@@ -2,3 +2,4 @@ export * from "./schema.js";
 export * from "./paths.js";
 export * from "./manager.js";
 export * from "./project.js";
+export * from "./credentials.js";

package/dist/config/index.js

@@ -2,3 +2,4 @@ export * from "./schema.js";
 export * from "./paths.js";
 export * from "./manager.js";
 export * from "./project.js";
+export * from "./credentials.js";

package/dist/config/manager.d.ts

@@ -30,5 +30,10 @@ export declare function initConfig(file: string): {
     path: string;
     created: boolean;
 };
-/** Provider API key, read from the environment only (never persisted). */
+/**
+ * Provider API key, resolved **env → credentials store → undefined**. The
+ * environment always wins (CI / one-off overrides); the credentials store
+ * (`~/.cruxy/credentials.json`, written by onboarding / `cruxy login`) is the
+ * persistent fallback. The key is never read from `config.json`.
+ */
 export declare function resolveApiKey(provider: string): string | undefined;

package/dist/config/manager.js

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 import { configInvalid, configParse } from "../errors/index.js";
 import { CruxyConfigSchema } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
+import { readCredential } from "./credentials.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -137,8 +138,17 @@ export function initConfig(file) {
     writeFileSync(file, JSON.stringify(defaults, null, 2) + "\n", "utf8");
     return { path: file, created: true };
 }
-/** Provider API key, read from the environment only (never persisted). */
+/**
+ * Provider API key, resolved **env → credentials store → undefined**. The
+ * environment always wins (CI / one-off overrides); the credentials store
+ * (`~/.cruxy/credentials.json`, written by onboarding / `cruxy login`) is the
+ * persistent fallback. The key is never read from `config.json`.
+ */
 export function resolveApiKey(provider) {
+    return envApiKey(provider) ?? readCredential(provider);
+}
+/** The API key from the environment for `provider`, or `undefined`. */
+function envApiKey(provider) {
     switch (provider) {
         case "cruxy":
             return process.env.CRUXY_API_KEY;

package/dist/config/schema.d.ts

@@ -30,12 +30,16 @@ export declare const AgentConfigSchema: z.ZodObject<{
     maxIterations: z.ZodDefault<z.ZodNumber>;
     /** Skip per-action confirmation prompts. */
     autoApprove: z.ZodDefault<z.ZodBoolean>;
+    /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+    planMode: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     maxIterations: number;
     autoApprove: boolean;
+    planMode: boolean;
 }, {
     maxIterations?: number | undefined;
     autoApprove?: boolean | undefined;
+    planMode?: boolean | undefined;
 }>;
 export declare const ToolsConfigSchema: z.ZodObject<{
     fileEdit: z.ZodDefault<z.ZodBoolean>;
@@ -52,10 +56,20 @@ export declare const ToolsConfigSchema: z.ZodObject<{
 }>;
 export declare const GitConfigSchema: z.ZodObject<{
     autoCommit: z.ZodDefault<z.ZodBoolean>;
+    /** Branches cruxy never commits/pushes to directly (PR flow branches off
+     * first). `main` and `master` are always protected; these add to them. */
+    protectedBranches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Default base branch for generated pull requests; falls back to the
+     * repo's default branch, then `main`, when unset. */
+    defaultBase: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     autoCommit: boolean;
+    protectedBranches: string[];
+    defaultBase?: string | undefined;
 }, {
     autoCommit?: boolean | undefined;
+    protectedBranches?: string[] | undefined;
+    defaultBase?: string | undefined;
 }>;
 /** Execution bounds for the `run_command` shell tool (distinct from the
  * `tools.shell` enable flag above). */
@@ -89,13 +103,18 @@ export declare const ContextConfigSchema: z.ZodObject<{
     compactThreshold?: number | undefined;
     keepRecentMessages?: number | undefined;
 }>;
-/** How tool-action approval is resolved. */
+/**
+ * How tool-action approval is resolved. Only `prompt` exists: ask interactively
+ * and **deny by default** when non-interactive. There is deliberately no
+ * auto-approve / skip mode — the policy seam for a future CI mode lives in
+ * `src/approval` (see U.3), not behind a footgun flag.
+ */
 export declare const ApprovalConfigSchema: z.ZodObject<{
-    mode: z.ZodDefault<z.ZodEnum<["prompt", "auto"]>>;
+    mode: z.ZodDefault<z.ZodEnum<["prompt"]>>;
 }, "strict", z.ZodTypeAny, {
-    mode: "auto" | "prompt";
+    mode: "prompt";
 }, {
-    mode?: "auto" | "prompt" | undefined;
+    mode?: "prompt" | undefined;
 }>;
 /**
  * Codebase semantic index (C.17): the local embedding index that backs the
@@ -227,12 +246,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxIterations: z.ZodDefault<z.ZodNumber>;
         /** Skip per-action confirmation prompts. */
         autoApprove: z.ZodDefault<z.ZodBoolean>;
+        /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+        planMode: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         maxIterations: number;
         autoApprove: boolean;
+        planMode: boolean;
     }, {
         maxIterations?: number | undefined;
         autoApprove?: boolean | undefined;
+        planMode?: boolean | undefined;
     }>>;
     tools: z.ZodDefault<z.ZodObject<{
         fileEdit: z.ZodDefault<z.ZodBoolean>;
@@ -249,10 +272,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }>>;
     git: z.ZodDefault<z.ZodObject<{
         autoCommit: z.ZodDefault<z.ZodBoolean>;
+        /** Branches cruxy never commits/pushes to directly (PR flow branches off
+         * first). `main` and `master` are always protected; these add to them. */
+        protectedBranches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Default base branch for generated pull requests; falls back to the
+         * repo's default branch, then `main`, when unset. */
+        defaultBase: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         autoCommit: boolean;
+        protectedBranches: string[];
+        defaultBase?: string | undefined;
     }, {
         autoCommit?: boolean | undefined;
+        protectedBranches?: string[] | undefined;
+        defaultBase?: string | undefined;
     }>>;
     shell: z.ZodDefault<z.ZodObject<{
         /** Kill the command (and its process tree) after this many ms. */
@@ -284,11 +317,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages?: number | undefined;
     }>>;
     approval: z.ZodDefault<z.ZodObject<{
-        mode: z.ZodDefault<z.ZodEnum<["prompt", "auto"]>>;
+        mode: z.ZodDefault<z.ZodEnum<["prompt"]>>;
     }, "strict", z.ZodTypeAny, {
-        mode: "auto" | "prompt";
+        mode: "prompt";
     }, {
-        mode?: "auto" | "prompt" | undefined;
+        mode?: "prompt" | undefined;
     }>>;
     index: z.ZodDefault<z.ZodObject<{
         /** Master switch for `search_codebase` and `cruxy index`. */
@@ -403,6 +436,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     agent: {
         maxIterations: number;
         autoApprove: boolean;
+        planMode: boolean;
     };
     tools: {
         fileEdit: boolean;
@@ -411,6 +445,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     git: {
         autoCommit: boolean;
+        protectedBranches: string[];
+        defaultBase?: string | undefined;
     };
     context: {
         maxTokens: number;
@@ -418,7 +454,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages: number;
     };
     approval: {
-        mode: "auto" | "prompt";
+        mode: "prompt";
     };
     index: {
         search: {
@@ -458,6 +494,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     agent?: {
         maxIterations?: number | undefined;
         autoApprove?: boolean | undefined;
+        planMode?: boolean | undefined;
     } | undefined;
     tools?: {
         fileEdit?: boolean | undefined;
@@ -466,6 +503,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     git?: {
         autoCommit?: boolean | undefined;
+        protectedBranches?: string[] | undefined;
+        defaultBase?: string | undefined;
     } | undefined;
     context?: {
         maxTokens?: number | undefined;
@@ -473,7 +512,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages?: number | undefined;
     } | undefined;
     approval?: {
-        mode?: "auto" | "prompt" | undefined;
+        mode?: "prompt" | undefined;
     } | undefined;
     index?: {
         search?: {

package/dist/config/schema.js

@@ -28,6 +28,8 @@ export const AgentConfigSchema = z
     maxIterations: z.number().int().positive().default(25),
     /** Skip per-action confirmation prompts. */
     autoApprove: z.boolean().default(false),
+    /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+    planMode: z.boolean().default(false),
 })
     .strict();
 export const ToolsConfigSchema = z
@@ -40,6 +42,12 @@ export const ToolsConfigSchema = z
 export const GitConfigSchema = z
     .object({
     autoCommit: z.boolean().default(false),
+    /** Branches cruxy never commits/pushes to directly (PR flow branches off
+     * first). `main` and `master` are always protected; these add to them. */
+    protectedBranches: z.array(z.string()).default([]),
+    /** Default base branch for generated pull requests; falls back to the
+     * repo's default branch, then `main`, when unset. */
+    defaultBase: z.string().optional(),
 })
     .strict();
 /** Execution bounds for the `run_command` shell tool (distinct from the
@@ -64,12 +72,15 @@ export const ContextConfigSchema = z
     keepRecentMessages: z.number().int().positive().default(6),
 })
     .strict();
-/** How tool-action approval is resolved. */
+/**
+ * How tool-action approval is resolved. Only `prompt` exists: ask interactively
+ * and **deny by default** when non-interactive. There is deliberately no
+ * auto-approve / skip mode — the policy seam for a future CI mode lives in
+ * `src/approval` (see U.3), not behind a footgun flag.
+ */
 export const ApprovalConfigSchema = z
     .object({
-    // "prompt": ask interactively (deny when non-interactive). "auto": approve
-    // every action unattended (CI / explicit opt-in).
-    mode: z.enum(["prompt", "auto"]).default("prompt"),
+    mode: z.enum(["prompt"]).default("prompt"),
 })
     .strict();
 /**

package/dist/constants.d.ts

@@ -5,6 +5,12 @@ export declare const APP_DESCRIPTION: string;
 /** Directory/file names cruxy looks for. */
 export declare const GLOBAL_DIR_NAME = ".cruxy";
 export declare const CONFIG_FILE_NAME = "config.json";
+/** Secret store under the global dir — `0600`, never holds non-secret config. */
+export declare const CREDENTIALS_FILE_NAME = "credentials.json";
+/** Onboarding state + completion marker under the global dir (U.6). */
+export declare const ONBOARDING_FILE_NAME = "onboarding.json";
+/** Where a user creates a Cruxy gateway key (printed during onboarding). */
+export declare const CREATE_KEY_URL = "https://app.cruxy.in";
 /** Project-level config filenames, checked in order. */
 export declare const PROJECT_CONFIG_FILENAMES: string[];
 /** Project-instruction filenames, checked in order (first match wins). */

package/dist/constants.js

@@ -22,6 +22,12 @@ export const APP_DESCRIPTION = pkg.description ?? "an agentic coding CLI";
 /** Directory/file names cruxy looks for. */
 export const GLOBAL_DIR_NAME = ".cruxy";
 export const CONFIG_FILE_NAME = "config.json";
+/** Secret store under the global dir — `0600`, never holds non-secret config. */
+export const CREDENTIALS_FILE_NAME = "credentials.json";
+/** Onboarding state + completion marker under the global dir (U.6). */
+export const ONBOARDING_FILE_NAME = "onboarding.json";
+/** Where a user creates a Cruxy gateway key (printed during onboarding). */
+export const CREATE_KEY_URL = "https://app.cruxy.in";
 /** Project-level config filenames, checked in order. */
 export const PROJECT_CONFIG_FILENAMES = [
     "cruxy.config.json",

package/dist/errors/constructors.d.ts

@@ -18,6 +18,41 @@ 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;
+/** The agent's proposed plan was missing or malformed (plan mode, C.31). */
+export declare function planInvalid(reason: string): CruxyError;
+/** The plan was rejected too many times without converging (plan mode, C.31). */
+export declare function planRevisionLimit(limit: number): CruxyError;
+/**
+ * Plan mode needs interactive approval but cruxy is running non-interactively.
+ * Default-deny — a plan is never auto-approved. Distinct code (exit 10) so CI can
+ * tell it apart from a per-action approval requirement.
+ */
+export declare function planApprovalRequired(): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed