@cruxy/cli 0.1.0

package/dist/tools/file/write-file.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { Tool } from "../types.js";
+/**
+ * Create or overwrite a file within the project root. Gated on `ctx.approve`
+ * before anything is written.
+ */
+export declare const writeFileTool: Tool<z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}>>;

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

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { resolveInRoot } from "./paths.js";
+/** How many leading lines of new content the approval preview shows. */
+const PREVIEW_LINES = 20;
+/**
+ * Create or overwrite a file within the project root. Gated on `ctx.approve`
+ * before anything is written.
+ */
+export const writeFileTool = {
+    name: "write_file",
+    description: "Create or overwrite a file with the given content (creates parent directories). Use for new files or full rewrites; prefer edit_file for small changes.",
+    parameters: z.object({
+        path: z
+            .string()
+            .describe("Path to the file, relative to the project root."),
+        content: z.string().describe("Full UTF-8 contents to write."),
+    }),
+    async execute(input, ctx) {
+        let abs;
+        try {
+            abs = await resolveInRoot(ctx, input.path);
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+        // Does the target already exist? Drives create-vs-overwrite in the preview.
+        const exists = await fs
+            .access(abs)
+            .then(() => true)
+            .catch(() => false);
+        // First N lines of the new content, with a count of what's omitted.
+        const allLines = input.content.split("\n");
+        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({
+            kind: "write",
+            path: abs,
+            preview: { type: "write", exists, lines, omittedLines },
+        });
+        if (!approved) {
+            return { ok: false, error: `write to ${input.path} denied` };
+        }
+        try {
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            await fs.writeFile(abs, input.content, "utf8");
+            const bytes = Buffer.byteLength(input.content, "utf8");
+            return { ok: true, output: `wrote ${input.path} (${bytes} bytes)` };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};

package/dist/tools/git-status.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+/**
+ * Report the current git branch and working-tree status (`git status
+ * --porcelain`) for the project root. Read-only — no approval, like read_file
+ * and glob.
+ */
+export declare const gitStatusTool: Tool<z.ZodObject<Record<string, never>>>;

package/dist/tools/git-status.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { getGitStatus } from "../utils/git.js";
+/**
+ * Report the current git branch and working-tree status (`git status
+ * --porcelain`) for the project root. Read-only — no approval, like read_file
+ * and glob.
+ */
+export const gitStatusTool = {
+    name: "git_status",
+    description: "Show the current git branch and the working-tree status (porcelain format: ' M file' modified, '?? file' untracked, etc.). Read-only and requires no approval.",
+    parameters: z.object({}),
+    async execute(_input, ctx) {
+        const info = getGitStatus(ctx.cwd);
+        if (info === null) {
+            return {
+                ok: false,
+                error: "not a git repository (or git is unavailable)",
+            };
+        }
+        const body = info.status.trim();
+        return {
+            ok: true,
+            output: `branch ${info.branch}\n${body === "" ? "working tree clean" : body}`,
+        };
+    },
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./list-files.js";
+export * from "./git-status.js";
+export * from "./file/index.js";

package/dist/tools/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./list-files.js";
+export * from "./git-status.js";
+export * from "./file/index.js";

package/dist/tools/list-files.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+/**
+ * Proof-of-concept tool: list the entries of `ctx.cwd`, marking each as a
+ * directory or a file. Takes no arguments.
+ */
+export declare const listFilesTool: Tool<z.ZodObject<Record<string, never>>>;

package/dist/tools/list-files.js

@@ -0,0 +1,27 @@
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+/**
+ * Proof-of-concept tool: list the entries of `ctx.cwd`, marking each as a
+ * directory or a file. Takes no arguments.
+ */
+export const listFilesTool = {
+    name: "list_files",
+    description: "List the files and directories in the current working directory.",
+    parameters: z.object({}),
+    async execute(_input, ctx) {
+        try {
+            const entries = await fs.readdir(ctx.cwd, { withFileTypes: true });
+            if (entries.length === 0) {
+                return { ok: true, output: "(empty directory)" };
+            }
+            const lines = entries
+                .slice()
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((entry) => `${entry.isDirectory() ? "dir " : "file"}  ${entry.name}`);
+            return { ok: true, output: lines.join("\n") };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};

package/dist/tools/registry.d.ts

@@ -0,0 +1,23 @@
+import type { ToolSpec } from "@cruxy/sdk";
+import type { Tool } from "./types.js";
+/**
+ * In-memory catalogue of the tools available to the agent. Names are unique;
+ * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    /** Register a tool. Throws if a tool with the same name already exists. */
+    register(tool: Tool): void;
+    /** Look up a tool by name, or `undefined` if not registered. */
+    get(name: string): Tool | undefined;
+    /** All registered tools, in registration order. */
+    list(): Tool[];
+    /**
+     * Project every tool into a `ToolSpec` for the provider: name, description,
+     * and the zod schema rendered as JSON Schema (with the `$schema` / `definitions`
+     * cruft the wire format rejects stripped out).
+     */
+    toToolSpecs(): ToolSpec[];
+}
+/** Build the default registry with every built-in tool registered. */
+export declare function buildDefaultRegistry(): ToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,63 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { listFilesTool } from "./list-files.js";
+import { gitStatusTool } from "./git-status.js";
+import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
+import { runCommandTool } from "./shell/index.js";
+/**
+ * In-memory catalogue of the tools available to the agent. Names are unique;
+ * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    /** Register a tool. Throws if a tool with the same name already exists. */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`tool "${tool.name}" is already registered`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+    /** Look up a tool by name, or `undefined` if not registered. */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** All registered tools, in registration order. */
+    list() {
+        return [...this.tools.values()];
+    }
+    /**
+     * Project every tool into a `ToolSpec` for the provider: name, description,
+     * and the zod schema rendered as JSON Schema (with the `$schema` / `definitions`
+     * cruft the wire format rejects stripped out).
+     */
+    toToolSpecs() {
+        return this.list().map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: toInputSchema(tool.parameters),
+        }));
+    }
+}
+/** Render a zod schema to a wire-safe JSON Schema object. */
+function toInputSchema(schema) {
+    // `$refStrategy: "none"` inlines everything so no `$ref`/`definitions` block
+    // is emitted; we still strip both defensively along with `$schema`.
+    const json = zodToJsonSchema(schema, { $refStrategy: "none" });
+    delete json.$schema;
+    delete json.definitions;
+    delete json.$ref;
+    return json;
+}
+/** Build the default registry with every built-in tool registered. */
+export function buildDefaultRegistry() {
+    const registry = new ToolRegistry();
+    registry.register(listFilesTool);
+    registry.register(readFileTool);
+    registry.register(writeFileTool);
+    registry.register(editFileTool);
+    registry.register(applyPatchTool);
+    registry.register(globTool);
+    registry.register(grepFilesTool);
+    registry.register(gitStatusTool);
+    registry.register(runCommandTool);
+    return registry;
+}

package/dist/tools/shell/index.d.ts

@@ -0,0 +1 @@
+export * from "./run-command.js";

package/dist/tools/shell/index.js

@@ -0,0 +1 @@
+export * from "./run-command.js";

package/dist/tools/shell/run-command.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { Tool } from "../types.js";
+/**
+ * Run an arbitrary shell command in the project root. The highest-risk tool we
+ * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
+ * timeout that kills the whole process tree plus a cap on captured output.
+ */
+export declare const runCommandTool: Tool<z.ZodObject<{
+    command: z.ZodString;
+}>>;

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

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { z } from "zod";
+/**
+ * Run an arbitrary shell command in the project root. The highest-risk tool we
+ * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
+ * timeout that kills the whole process tree plus a cap on captured output.
+ */
+export const runCommandTool = {
+    name: "run_command",
+    description: "Run a shell command in the project root and return its exit code, stdout, and stderr. Use this for builds, tests, linters, and git. Prefer the dedicated file tools (read_file/write_file/edit_file) over shelling out to cat/sed/echo for inspecting or editing files. A non-zero exit is still returned so you can react to the failure output.",
+    parameters: z.object({
+        command: z
+            .string()
+            .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" };
+        }
+        return runBounded(input.command, ctx);
+    },
+};
+/** Spawn the command, capture bounded output, and enforce the timeout. */
+function runBounded(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return new Promise((resolve) => {
+        // `detached` makes the child its own process-group leader so the whole tree
+        // (the shell plus anything it spawns) can be killed on timeout.
+        const child = spawn(command, {
+            shell: true,
+            cwd: ctx.cwd,
+            detached: true,
+        });
+        const chunks = [];
+        let captured = 0;
+        let truncated = false;
+        const capture = (buf) => {
+            if (truncated)
+                return;
+            const room = maxOutputBytes - captured;
+            if (buf.length <= room) {
+                chunks.push(buf);
+                captured += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    chunks.push(buf.subarray(0, room));
+                    captured += room;
+                }
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        // A single guard so the timeout-kill and the natural close can't both fire.
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            killTree(child.pid);
+            resolve({ ok: false, error: `timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ ok: false, error: err.message });
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const exit = code ?? signal ?? "unknown";
+            let output = `exit code ${exit}\n${Buffer.concat(chunks).toString("utf8")}`;
+            if (truncated) {
+                output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
+            }
+            resolve({ ok: true, output });
+        });
+    });
+}
+/**
+ * Kill the command's entire process group. POSIX-specific (negative pid targets
+ * the group); fine on our darwin/linux targets. Swallows errors — the process
+ * may already be gone.
+ */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,113 @@
+import type { z, ZodTypeAny } from "zod";
+import type { CruxyConfig } from "../config/index.js";
+import type { logger } from "../utils/logger.js";
+/** The leveled logger instance shared across the CLI. */
+type Logger = typeof logger;
+/**
+ * The outcome of a tool run. Tools never throw across this boundary — failures
+ * are reported as `{ ok: false }` so the agent loop can feed the error back to
+ * the model instead of crashing.
+ */
+export type ToolResult = {
+    ok: true;
+    output: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * One file's worth of change inside an `apply_patch` preview. Paths are
+ * project-relative (the tool relativizes them for display).
+ */
+export type PatchFilePreview = {
+    op: "update";
+    path: string;
+    hunks: {
+        oldStr: string;
+        newStr: string;
+    }[];
+} | {
+    op: "create";
+    path: string;
+    lines: string[];
+    omittedLines: number;
+} | {
+    op: "delete";
+    path: string;
+};
+/**
+ * An optional preview of exactly what a mutating action will change, threaded
+ * from the tool into `ctx.approve` so the prompt can show it before the user
+ * decides. The tool fills this in from data it has already computed.
+ */
+export type ActionPreview = 
+/** The exact strings `edit_file` is about to swap. */
+{
+    type: "edit";
+    oldStr: string;
+    newStr: string;
+}
+/**
+ * What `write_file` will write: whether the path already exists (overwrite vs
+ * create) and the first lines of the new content, pre-capped by the tool.
+ */
+ | {
+    type: "write";
+    exists: boolean;
+    lines: string[];
+    omittedLines: number;
+}
+/** The full set of file changes `apply_patch` will make, for a combined diff. */
+ | {
+    type: "patch";
+    files: PatchFilePreview[];
+};
+/**
+ * A side-effecting action a tool wants to take, passed to `ctx.approve`. The
+ * `kind` set grows as more mutating tools land; it drives the permission prompt.
+ */
+export interface ApproveAction {
+    /** The category of side effect being requested. */
+    kind: "write" | "edit" | "shell" | "patch";
+    /** 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). */
+    preview?: ActionPreview;
+}
+/**
+ * Ambient capabilities handed to every tool at execution time. Tools run on the
+ * user's machine, so this is the only sanctioned door to the filesystem root
+ * (`cwd`), configuration, logging, and the permission gate.
+ */
+export interface ToolContext {
+    /** Absolute path the tool should treat as its working root. */
+    cwd: string;
+    /** Fully-resolved CLI configuration. */
+    config: CruxyConfig;
+    /** 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.
+     */
+    approve(action: ApproveAction): Promise<boolean>;
+}
+/**
+ * The one interface every tool implements. `parameters` is a zod schema; it both
+ * validates the model's arguments and (via the registry) becomes the wire-format
+ * JSON Schema advertised to the provider.
+ */
+export interface Tool<Schema extends ZodTypeAny = ZodTypeAny> {
+    /** Unique, snake_case identifier the model uses to call the tool. */
+    name: string;
+    /** One-line description shown to the model. */
+    description: string;
+    /** Zod schema for the tool's input arguments. */
+    parameters: Schema;
+    /** Run the tool against validated `input` and the ambient `ctx`. */
+    execute(input: z.infer<Schema>, ctx: ToolContext): Promise<ToolResult>;
+}
+export {};

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/git.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Branch name plus the raw `git status --porcelain` text for `cwd`, or `null`
+ * when it isn't a git repository (or git is unavailable). Backs the `git_status`
+ * tool, which surfaces the porcelain output to the model.
+ */
+export declare function getGitStatus(cwd: string): {
+    branch: string;
+    status: string;
+} | null;
+/**
+ * Compact git context for the system prompt: current branch and whether the
+ * working tree has uncommitted changes. `null` when not a repo / git missing.
+ */
+export declare function getGitInfo(cwd: string): {
+    branch: string;
+    dirty: boolean;
+} | null;

package/dist/utils/git.js

@@ -0,0 +1,43 @@
+import { spawnSync } from "node:child_process";
+/** Hard ceiling on a git invocation; a hung git must never stall startup. */
+const GIT_TIMEOUT_MS = 5000;
+/**
+ * Run `git <args>` in `cwd` and return trimmed stdout, or `null` on any failure
+ * — git missing (ENOENT), not a repo (non-zero exit), or a timeout. Never throws.
+ */
+function runGit(args, cwd) {
+    const res = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string") {
+        return null;
+    }
+    return res.stdout;
+}
+/**
+ * Branch name plus the raw `git status --porcelain` text for `cwd`, or `null`
+ * when it isn't a git repository (or git is unavailable). Backs the `git_status`
+ * tool, which surfaces the porcelain output to the model.
+ */
+export function getGitStatus(cwd) {
+    const branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    if (branch === null)
+        return null;
+    const status = runGit(["status", "--porcelain"], cwd);
+    if (status === null)
+        return null;
+    return { branch: branch.trim(), status };
+}
+/**
+ * Compact git context for the system prompt: current branch and whether the
+ * working tree has uncommitted changes. `null` when not a repo / git missing.
+ */
+export function getGitInfo(cwd) {
+    const info = getGitStatus(cwd);
+    if (info === null)
+        return null;
+    return { branch: info.branch, dirty: info.status.trim().length > 0 };
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,16 @@
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "silent"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+declare class Logger {
+    private level;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    private enabled;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /** Primary user-facing output — always written to stdout. */
+    print(...args: unknown[]): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,42 @@
+import pc from "picocolors";
+export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
+const WEIGHT = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 100,
+};
+class Logger {
+    level = "info";
+    setLevel(level) {
+        this.level = level;
+    }
+    getLevel() {
+        return this.level;
+    }
+    enabled(level) {
+        return WEIGHT[level] >= WEIGHT[this.level];
+    }
+    debug(...args) {
+        if (this.enabled("debug"))
+            console.error(pc.dim("debug"), ...args);
+    }
+    info(...args) {
+        if (this.enabled("info"))
+            console.error(...args);
+    }
+    warn(...args) {
+        if (this.enabled("warn"))
+            console.error(pc.yellow("warn"), ...args);
+    }
+    error(...args) {
+        if (this.enabled("error"))
+            console.error(pc.red("error"), ...args);
+    }
+    /** Primary user-facing output — always written to stdout. */
+    print(...args) {
+        console.log(...args);
+    }
+}
+export const logger = new Logger();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cruxy/cli",
+  "version": "0.1.0",
+  "description": "an agentic coding CLI",
+  "type": "module",
+  "bin": {
+    "cruxy": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cli",
+    "agent",
+    "coding",
+    "ai"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cruxy-ai/cli.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "tinyglobby": "^0.2.10",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5",
+    "@cruxy/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}