@cruxy/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cruxy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @cruxy/cli
+
+An agentic coding CLI. **Phase C.0 — CLI scaffolding + config.**
+
+This is the foundation pass: a working command-line skeleton with a layered
+configuration system. The agent loop, tools, indexing, and everything else in
+the C-series slot into the directory structure laid out here.
+
+## Requirements
+
+- Node.js >= 20
+
+## Setup
+
+```bash
+npm install
+npm run build      # compile TypeScript -> dist/
+npm link           # optional: expose the `cruxy` command globally
+```
+
+During development you can skip the build step:
+
+```bash
+npm run dev -- --help
+npm run dev -- config path
+```
+
+## Usage
+
+```bash
+cruxy                       # entrypoint (interactive REPL stub — lands in C.3)
+cruxy run "fix the bug"     # one-shot prompt (agent loop stub — lands in C.4)
+cruxy config init           # write a default global config
+cruxy config list           # print the fully-resolved config
+cruxy config get model.temperature
+cruxy config set model.model claude-opus-4-8
+cruxy config path           # show where config files live
+cruxy --help
+```
+
+Global flags: `--config <path>`, `--log-level <level>`, `--verbose`, `--version`.
+
+## Configuration
+
+Config is resolved in layers, where later sources override earlier ones:
+
+1. Built-in schema defaults
+2. Global config — `~/.cruxy/config.json`
+3. Project config — `cruxy.config.json` or `.cruxy/config.json` (discovered by
+   walking up from the current directory), or an explicit `--config <path>`
+4. Environment variables — `CRUXY_MODEL`, `CRUXY_PROVIDER`, `CRUXY_LOG_LEVEL`
+
+The merged result is validated against a [zod](https://zod.dev) schema
+(`src/config/schema.ts`); invalid configs are rejected with a readable error.
+
+**API keys are never stored in config files.** They are read from the
+environment only (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `CRUXY_API_KEY`).
+Copy `.env.example` to `.env` to set them locally.
+
+## Project structure
+
+```
+src/
+  index.ts            # bin entry (shebang) + top-level error handling
+  constants.ts        # app name/version, config file names
+  cli/
+    program.ts        # commander program + global options
+    commands/
+      run.ts          # `cruxy run` (agent loop stub)
+      config.ts       # `cruxy config` subcommands
+  config/
+    schema.ts         # zod config schema + types
+    paths.ts          # global/project config path resolution
+    manager.ts        # layered load/merge/validate, get/set/init
+    index.ts          # barrel
+  utils/
+    logger.ts         # leveled logger
+```
+
+Folders for `agent/`, `tools/`, and `providers/` are introduced as their phases
+land, so this layout grows without restructuring.
+
+## Roadmap (C-series)
+
+| Phase    | Description                                                                                                                |
+| -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| C.0      | CLI scaffolding + config                                                                                                   |
+| C.1–C.10 | Provider client, tool system, agent loop, file tools, **permissions** ← you are here, terminal UI, shell, git, IDE plugins |
+| C.11     | Codebase indexing (vector store)                                                                                           |
+| C.12     | Per-language LSP integration                                                                                               |
+| C.13     | Test execution + iteration loop                                                                                            |
+| C.14     | Subagent orchestration                                                                                                     |
+| C.15     | PR generation                                                                                                              |
+| C.16     | Sandbox / Docker execution                                                                                                 |
+| C.17     | Web-search subtool                                                                                                         |
+| C.18     | Custom skills (SKILL.md system)                                                                                            |
+| C.19     | Hooks + slash commands                                                                                                     |
+| C.20     | Headless / CI mode                                                                                                         |
+| C.21     | Multi-repo agents                                                                                                          |
+| C.22     | Telemetry + cost tracking                                                                                                  |
+| C.23     | Streaming UI improvements                                                                                                  |
+
+## License
+
+MIT

package/dist/agent/approval.d.ts

@@ -0,0 +1,41 @@
+import type { ApproveAction } from "../tools/index.js";
+import { logger as defaultLogger } from "../utils/logger.js";
+type Logger = typeof defaultLogger;
+/** Reads a single keypress from the user. Returns "" on EOF. */
+export type KeypressReader = () => Promise<string>;
+export interface ApproverConfig {
+    /** "prompt" asks interactively; "auto" approves everything unattended. */
+    mode: "prompt" | "auto";
+    /** Project root, used to render action paths relative for the prompt. */
+    cwd: string;
+    /** Whether stdin is an interactive TTY. */
+    isInteractive: boolean;
+    /** Explicit unattended opt-in (e.g. --yes / --dangerously-approve). */
+    autoApprove?: boolean;
+    /** Keypress source (injectable for tests). Defaults to a raw-mode stdin read. */
+    readKey?: KeypressReader;
+    /** Where the prompt text is written (injectable). Defaults to stderr. */
+    write?: (text: string) => void;
+    /** Logger for unattended / denial diagnostics. */
+    logger?: Logger;
+}
+/**
+ * Decides whether a side-effecting tool action may proceed. The single gate every
+ * mutating tool funnels through (write/edit today, run_command later).
+ *
+ * Interactive: prints the action (plus a change preview when the tool supplied
+ * one) and reads one key — `y` allow once, `a` allow-all for this run, anything
+ * else (including EOF) denies. **Fails closed.**
+ * Non-interactive: denies by default unless an explicit opt-in (`mode:"auto"` or
+ * `autoApprove`) is set, in which case it auto-approves and warns it's unattended.
+ */
+export declare class Approver {
+    /** Session allow-all — scoped to this instance, never persisted. */
+    private allowAll;
+    private warnedUnattended;
+    private readonly cfg;
+    constructor(cfg: ApproverConfig);
+    approve(action: ApproveAction): Promise<boolean>;
+}
+export declare function createApprover(cfg: ApproverConfig): Approver;
+export {};

package/dist/agent/approval.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import pc from "picocolors";
+import { logger as defaultLogger } from "../utils/logger.js";
+/** Cap on rendered preview lines before collapsing the rest into "...N more". */
+const PREVIEW_MAX_LINES = 40;
+/** Human-readable verb + detail for a pending action. */
+function renderAction(cwd, action) {
+    switch (action.kind) {
+        case "write":
+            return `write  ${path.relative(cwd, action.path ?? "") || action.path}`;
+        case "edit":
+            return `edit  ${path.relative(cwd, action.path ?? "") || action.path}`;
+        case "shell":
+            return `run  ${action.command ?? ""}`;
+        case "patch": {
+            const n = action.preview?.type === "patch" ? action.preview.files.length : 0;
+            return `apply patch (${n} file${n === 1 ? "" : "s"})`;
+        }
+    }
+}
+/**
+ * A minimal unified-style diff for one hunk: the removed block (red `-`) then the
+ * added block (green `+`). The `-`/`+` prefixes keep it readable without color.
+ * Shared by the `edit` and `patch` previews (the C.6 renderer).
+ */
+function diffLines(oldStr, newStr) {
+    const removed = oldStr.split("\n").map((l) => pc.red(`- ${l}`));
+    const added = newStr.split("\n").map((l) => pc.green(`+ ${l}`));
+    return [...removed, ...added];
+}
+/**
+ * Render every file in an `apply_patch` preview as a combined diff: a per-file
+ * header (op + path) followed by its hunk diffs (update), created content
+ * (create), or nothing (delete).
+ */
+function renderPatchFiles(files) {
+    const out = [];
+    for (const file of files) {
+        if (file.op === "delete") {
+            out.push(pc.red(`delete ${file.path}`));
+        }
+        else if (file.op === "create") {
+            out.push(pc.green(`create ${file.path}`));
+            out.push(...file.lines.map((l) => pc.green(`+ ${l}`)));
+            if (file.omittedLines > 0) {
+                out.push(pc.dim(`  ...${file.omittedLines} more lines`));
+            }
+        }
+        else {
+            out.push(pc.yellow(`update ${file.path}`));
+            for (const hunk of file.hunks) {
+                out.push(...diffLines(hunk.oldStr, hunk.newStr));
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Render the exact-change preview for a write/edit action as indented lines, so
+ * the user sees what they're approving. Caps the output at `PREVIEW_MAX_LINES`
+ * and collapses the overflow into a "...N more" notice. Returns "" when there's
+ * nothing to preview. Colors are decorative — the `-`/`+`/header prefixes keep
+ * it readable without them.
+ */
+function renderPreview(preview) {
+    if (!preview)
+        return "";
+    let lines;
+    if (preview.type === "edit") {
+        lines = diffLines(preview.oldStr, preview.newStr);
+    }
+    else if (preview.type === "patch") {
+        lines = renderPatchFiles(preview.files);
+    }
+    else {
+        const header = preview.exists
+            ? pc.yellow("OVERWRITE existing")
+            : pc.green("create");
+        const body = preview.lines.map((l) => `  ${l}`);
+        if (preview.omittedLines > 0) {
+            body.push(pc.dim(`  ...${preview.omittedLines} more lines`));
+        }
+        lines = [header, ...body];
+    }
+    // Cap the rendered block; collapse the rest into a count.
+    if (lines.length > PREVIEW_MAX_LINES) {
+        const hidden = lines.length - PREVIEW_MAX_LINES;
+        lines = [...lines.slice(0, PREVIEW_MAX_LINES), pc.dim(`...${hidden} more`)];
+    }
+    return lines.map((l) => `  ${l}\n`).join("");
+}
+/**
+ * Decides whether a side-effecting tool action may proceed. The single gate every
+ * mutating tool funnels through (write/edit today, run_command later).
+ *
+ * Interactive: prints the action (plus a change preview when the tool supplied
+ * one) and reads one key — `y` allow once, `a` allow-all for this run, anything
+ * else (including EOF) denies. **Fails closed.**
+ * Non-interactive: denies by default unless an explicit opt-in (`mode:"auto"` or
+ * `autoApprove`) is set, in which case it auto-approves and warns it's unattended.
+ */
+export class Approver {
+    /** Session allow-all — scoped to this instance, never persisted. */
+    allowAll = false;
+    warnedUnattended = false;
+    cfg;
+    constructor(cfg) {
+        this.cfg = {
+            ...cfg,
+            readKey: cfg.readKey ?? readKeyFromStdin,
+            write: cfg.write ?? ((t) => process.stderr.write(t)),
+            logger: cfg.logger ?? defaultLogger,
+        };
+    }
+    async approve(action) {
+        const log = this.cfg.logger ?? defaultLogger;
+        if (this.allowAll)
+            return true;
+        // Explicit unattended opt-in — approve everywhere, warn once.
+        if (this.cfg.mode === "auto" || this.cfg.autoApprove) {
+            if (!this.warnedUnattended) {
+                log.warn("running unattended — auto-approving all tool actions");
+                this.warnedUnattended = true;
+            }
+            return true;
+        }
+        // No way to ask → fail closed.
+        if (!this.cfg.isInteractive) {
+            log.warn(`denied (${renderAction(this.cfg.cwd, action)}): non-interactive — pass --yes or set approval.mode=auto`);
+            return false;
+        }
+        const write = this.cfg.write ?? ((t) => process.stderr.write(t));
+        write(`${pc.yellow("?")} cruxy wants to ${renderAction(this.cfg.cwd, action)}\n` +
+            renderPreview(action.preview) +
+            `  ${pc.dim("[y] allow once · [n] deny · [a] allow all:")} `);
+        const key = (await (this.cfg.readKey ?? readKeyFromStdin)()).toLowerCase();
+        write("\n");
+        if (key === "y")
+            return true;
+        if (key === "a") {
+            this.allowAll = true;
+            return true;
+        }
+        // n, EOF (""), Ctrl-C, or any other key → deny.
+        return false;
+    }
+}
+export function createApprover(cfg) {
+    return new Approver(cfg);
+}
+/**
+ * Read a single keypress from stdin in raw mode. Resolves to the first character
+ * of the chunk, or "" on EOF. Always restores cooked mode and pauses stdin.
+ */
+function readKeyFromStdin() {
+    const stdin = process.stdin;
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const onData = (buf) => {
+            cleanup();
+            resolve(buf.toString("utf8").slice(0, 1));
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve("");
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.once("data", onData);
+        stdin.once("end", onEnd);
+    });
+}

package/dist/agent/index.d.ts

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

package/dist/agent/index.js

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

package/dist/agent/loop.d.ts

@@ -0,0 +1,53 @@
+import type { Message, Provider, Usage } from "@cruxy/sdk";
+import type { CruxyConfig } from "../config/index.js";
+import type { ToolContext } from "../tools/index.js";
+import { ToolRegistry } from "../tools/index.js";
+export interface RunAgentArgs {
+    /**
+     * The full running conversation. The caller owns history and must append the
+     * user turn before calling; `runAgent` does not fabricate the initial array.
+     */
+    messages: Message[];
+    /** A constructed provider to stream from. */
+    provider: Provider;
+    /** The tool catalogue advertised to the model and dispatched against. */
+    registry: ToolRegistry;
+    /** Resolved CLI configuration (turn ceiling, etc.). */
+    config: CruxyConfig;
+    /** Ambient capabilities handed to each tool. */
+    ctx: ToolContext;
+    /**
+     * Optional sink for assistant text as it streams: called per text delta, then
+     * once with a lone "\n" to close each non-empty text segment on its own line.
+     * When set, `runAgent` streams live and does not buffer-print the turn (the
+     * caller renders); when omitted, behavior is unchanged (one buffered print).
+     */
+    onText?: (delta: string) => void;
+    /** Git context (branch + dirty) for the system prompt's Environment section. */
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
+    projectInstructions?: string | null;
+}
+export interface AgentResult {
+    /** The full conversation, including assistant tool calls and tool results. */
+    messages: Message[];
+    /** Number of model turns consumed. */
+    iterations: number;
+    /** Why the loop ended. */
+    stop: "completed" | "max_iterations";
+    /** Accumulated token usage (stashed for cost tracking in C.22). */
+    usage: Usage;
+}
+/**
+ * Drive the model/tool loop over an existing conversation. Streams each turn,
+ * renders assistant text, reassembles tool calls, executes them, feeds the
+ * results back, and repeats until the model stops calling tools or the turn
+ * ceiling is hit.
+ *
+ * Requires a tool-capable provider — it throws up front otherwise rather than
+ * silently running tool-less.
+ */
+export declare function runAgent(args: RunAgentArgs): Promise<AgentResult>;

package/dist/agent/loop.js

@@ -0,0 +1,148 @@
+import { buildSystemPrompt } from "./prompts.js";
+/**
+ * Drive the model/tool loop over an existing conversation. Streams each turn,
+ * renders assistant text, reassembles tool calls, executes them, feeds the
+ * results back, and repeats until the model stops calling tools or the turn
+ * ceiling is hit.
+ *
+ * Requires a tool-capable provider — it throws up front otherwise rather than
+ * silently running tool-less.
+ */
+export async function runAgent(args) {
+    const { provider, registry, config, ctx } = args;
+    if (!provider.supportsTools) {
+        throw new Error(`provider ${config.model.provider} does not support tool use; cruxy run requires a tool-capable provider`);
+    }
+    const { logger } = ctx;
+    // Work on a copy so we never mutate the caller's array as a side effect; the
+    // extended history is returned for the caller to adopt.
+    const messages = [...args.messages];
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    const maxIterations = config.agent.maxIterations;
+    // The tool catalogue and environment are stable across the loop, so build the
+    // system prompt once. The builder degrades gracefully when git is null.
+    const system = buildSystemPrompt({
+        cwd: ctx.cwd,
+        platform: process.platform,
+        date: new Date().toISOString().slice(0, 10),
+        model: `${config.model.provider}/${config.model.model}`,
+        tools: registry
+            .list()
+            .map((tool) => ({ name: tool.name, description: tool.description })),
+        autoApprove: config.approval.mode === "auto",
+        git: args.git ?? null,
+        projectInstructions: args.projectInstructions ?? null,
+    });
+    let iterations = 0;
+    for (let i = 0; i < maxIterations; i++) {
+        iterations = i + 1;
+        const tools = registry.toToolSpecs();
+        // ── Consume one model turn ──────────────────────────────────────────────
+        let turnText = "";
+        const pending = new Map();
+        const toolUses = [];
+        for await (const ev of provider.stream({
+            system,
+            messages,
+            tools,
+        })) {
+            switch (ev.type) {
+                case "text_delta":
+                    turnText += ev.text;
+                    args.onText?.(ev.text);
+                    break;
+                case "tool_use_start":
+                    pending.set(ev.index, { id: ev.id, name: ev.name });
+                    break;
+                case "tool_use_stop": {
+                    // tool_use_stop carries the fully-assembled, parsed input; `pending`
+                    // is only a fallback for id/name if a start arrived without a stop.
+                    const started = pending.get(ev.index);
+                    pending.delete(ev.index);
+                    toolUses.push({
+                        type: "tool_use",
+                        id: ev.id || started?.id || "",
+                        name: ev.name || started?.name || "",
+                        input: ev.input,
+                    });
+                    break;
+                }
+                case "usage":
+                    usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
+                    usage.output_tokens += ev.usage.output_tokens;
+                    break;
+                case "message_stop":
+                    // Turn complete; the stream ends after this.
+                    break;
+                case "error":
+                    throw ev.error;
+                default:
+                    break;
+            }
+        }
+        // ── Record the assistant turn ───────────────────────────────────────────
+        if (turnText) {
+            // Streaming (onText set): the text already reached the user delta by delta,
+            // so close the segment with a single newline through the *same* sink — no
+            // separate buffered print racing the stream — so tool output, the next
+            // turn, or an approval prompt starts on its own line. Otherwise render the
+            // whole buffered block (no-callback path, unchanged).
+            if (args.onText)
+                args.onText("\n");
+            else
+                logger.print(turnText);
+        }
+        const assistantBlocks = [];
+        if (turnText)
+            assistantBlocks.push({ type: "text", text: turnText });
+        assistantBlocks.push(...toolUses);
+        messages.push({ role: "assistant", content: assistantBlocks });
+        // No tool calls → the model is done.
+        if (toolUses.length === 0) {
+            return { messages, iterations, stop: "completed", usage };
+        }
+        // ── Execute each tool call, collecting one tool_result per call ──────────
+        const toolResults = [];
+        for (const call of toolUses) {
+            toolResults.push(await runToolCall(call, registry, ctx));
+        }
+        messages.push({ role: "user", content: toolResults });
+    }
+    logger.warn(`reached maxIterations (${maxIterations}) without completing`);
+    return { messages, iterations, stop: "max_iterations", usage };
+}
+/**
+ * Dispatch a single reassembled tool call to its tool and shape the outcome as
+ * a `tool_result` block. Unknown tools and invalid arguments become `is_error`
+ * results rather than thrown exceptions, so the model can read the error and
+ * self-correct on the next turn.
+ */
+async function runToolCall(call, registry, ctx) {
+    const tool = registry.get(call.name);
+    if (!tool) {
+        return {
+            type: "tool_result",
+            tool_use_id: call.id,
+            content: `unknown tool "${call.name}"`,
+            is_error: true,
+        };
+    }
+    const parsed = tool.parameters.safeParse(call.input);
+    if (!parsed.success) {
+        return {
+            type: "tool_result",
+            tool_use_id: call.id,
+            content: `invalid arguments for "${call.name}": ${parsed.error.message}`,
+            is_error: true,
+        };
+    }
+    const result = await tool.execute(parsed.data, ctx);
+    return result.ok
+        ? { type: "tool_result", tool_use_id: call.id, content: result.output }
+        : {
+            type: "tool_result",
+            tool_use_id: call.id,
+            content: result.error,
+            is_error: true,
+        };
+}

package/dist/agent/prompts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * cruxy-code agent prompts.
+ *
+ * These are ORIGINAL prompts written for cruxy — not copied from any other
+ * tool. The system prompt is assembled at runtime from a static core plus a
+ * dynamic environment block, so the model always knows where it is, what it
+ * can do, and how it's expected to behave.
+ */
+export interface ToolSummary {
+    name: string;
+    description: string;
+}
+export interface PromptContext {
+    /** Absolute working directory the agent is rooted in. */
+    cwd: string;
+    /** node `process.platform`, e.g. "linux", "darwin", "win32". */
+    platform: string;
+    /** Provider/model string, for the model's self-awareness. */
+    model: string;
+    /** Current ISO date (so the model isn't guessing). */
+    date: string;
+    /** Tools available this session (from the tool registry). */
+    tools: ToolSummary[];
+    /** Optional git context, when the cwd is a repo. */
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    /** When true, the agent may act without per-step confirmation. */
+    autoApprove: boolean;
+    /** Optional extra instructions (e.g. from a project CRUXY.md). */
+    projectInstructions?: string | null;
+}
+/** Assemble the full system prompt for a session. */
+export declare function buildSystemPrompt(ctx: PromptContext): string;
+/**
+ * Compact reminder injected after tool results when the loop has run long, to
+ * keep the model anchored to the original objective and the verify step.
+ */
+export declare const PROGRESS_REMINDER = "Reminder: stay focused on the original task. Before declaring done, verify your change actually works (build/tests/lint), then summarize what changed.";
+/**
+ * System prompt for the side conversation that compacts an over-long history
+ * (see Session.compact). It runs as a standalone, tool-less completion over a
+ * rendered transcript — the goal is a synopsis dense enough that the main loop
+ * can continue without the verbatim prefix.
+ */
+export declare const SUMMARY_SYSTEM = "You are compacting a coding assistant's conversation to fit within its context window. Summarize the conversation so far into a compact synopsis that preserves: decisions made and their rationale, concrete file paths and identifiers touched, the current state of the work, and any open or pending tasks. Be specific and terse \u2014 omit pleasantries and restated instructions. Output only the synopsis.";
+/**
+ * Marker embedded in the synthetic messages that replace a compacted prefix, so
+ * they're recognizable in the history (and fold cleanly into a later
+ * re-summarization rather than being mistaken for live conversation).
+ */
+export declare const COMPACTION_MARKER = "[conversation compacted]";