@wanghuimvp/axon 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # Axon
 
-An agentic coding CLI. Axon streams from Anthropic and runs a multi-step tool loop over your codebase — it reads, searches, and reasons across your files to answer a prompt.
+A multi-provider agentic coding CLI. Axon runs a multi-step tool loop over your codebase — it reads, searches, edits, and runs commands to carry out a request — with an interactive chat or a one-shot non-interactive mode.
 
-> Foundation release (`0.0.x`). Non-interactive `axon -p` mode with read-only tools. Interactive TUI and write/edit/shell tools are on the roadmap.
+> `0.x` — interactive TUI (`axon`) and non-interactive (`axon -p`), multi-provider (Anthropic / OpenAI + OpenAI-compatible / Gemini), read + write/edit/shell tools.
 
 ## Install
 
@@ -10,6 +10,25 @@ An agentic coding CLI. Axon streams from Anthropic and runs a multi-step tool lo
 npm install -g @wanghuimvp/axon
 ```
 
+## Interactive mode
+
+Run `axon` with no arguments to open the interactive chat:
+
+```bash
+axon
+```
+
+Type a request and press Enter. Axon streams its reasoning and tool calls. When it wants to write a file or run a command, you get an inline prompt:
+
+```
+🔒 write_file({"path":"NOTES.md", …})
+[a] allow once / [A] always this session / [d] deny
+```
+
+Press `a` to allow once, `A` to allow that tool for the rest of the session, or `d` to deny (the model is told and adapts). `Ctrl+C` quits. Pass `--yolo` to skip all prompts.
+
+For one-shot, non-interactive use, see [Usage](#usage) (`axon -p`).
+
 ## Providers
 
 Axon speaks to three backends. The OpenAI-compatible provider also drives any
@@ -73,8 +92,19 @@ Axon will stream the model's reasoning, run read-only tools as needed (`read_fil
 - `-p, --print <prompt>` — run one prompt non-interactively and stream the result.
 - `--provider <name>` — select a provider (anthropic, openai, gemini) for this run.
 - `--model <name>` — select a model for this run.
+- `--yolo` — enable the `write_file`/`edit_file`/`shell` tools without prompting (non-interactive). Off by default: these tools are not even offered to the model, so it sticks to read-only inspection.
 - `--version` — print the version.
 
+### Changing files
+
+Axon can modify your workspace with `write_file`, `edit_file`, and run commands with `shell`. In non-interactive (`-p`) mode these tools are **only available with `--yolo`** — without the flag they are not offered to the model at all (and a permission gate denies them as defense-in-depth).
+
+```bash
+axon --yolo -p "add a CHANGELOG.md with an initial entry, then run the tests"
+```
+
+Read/search tools (`read_file`, `list_dir`, `glob`, `grep`) always run without a prompt. `write_file` and `edit_file` are confined to the project root (path-escape and symlink-escape protected). `shell` is **not** sandboxed — under `--yolo` it runs arbitrary commands and can affect anything your shell can. Only pass `--yolo` to runs you trust.
+
 ## Configuration
 
 Optional config file at `~/.axon/config.json`:

package/dist/cli.js

@@ -383,7 +383,8 @@ import { join as join3, resolve as resolve2 } from "node:path";
 import fg from "fast-glob";
 
 // src/tools/paths.ts
-import { resolve, relative, isAbsolute, sep } from "node:path";
+import { resolve, relative, isAbsolute, sep, dirname as dirname2 } from "node:path";
+import { realpathSync, existsSync } from "node:fs";
 function resolveInside(cwd, p) {
   const root = resolve(cwd);
   const full = isAbsolute(p) ? resolve(p) : resolve(root, p);
@@ -399,6 +400,20 @@ function assertSafeGlob(pattern) {
     throw new Error(`glob pattern escapes project root: ${pattern}`);
   }
 }
+function assertRealInside(cwd, full) {
+  const root = realpathSync(resolve(cwd));
+  let p = full;
+  while (!existsSync(p)) {
+    const parent = dirname2(p);
+    if (parent === p) throw new Error(`cannot resolve path: ${full}`);
+    p = parent;
+  }
+  const real = realpathSync(p);
+  const rel = relative(root, real);
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+    throw new Error(`path escapes project root via symlink: ${full}`);
+  }
+}
 
 // src/tools/fs.ts
 function fail(err) {
@@ -496,11 +511,129 @@ var grepTool = {
   }
 };
 
+// src/tools/edit.ts
+import { readFile as readFile2, writeFile, mkdir } from "node:fs/promises";
+import { dirname as dirname3 } from "node:path";
+function fail2(err) {
+  return { ok: false, output: err instanceof Error ? err.message : String(err) };
+}
+var writeFileTool = {
+  name: "write_file",
+  dangerous: true,
+  schema: {
+    name: "write_file",
+    description: "Create or overwrite a file (relative to the project root). Creates parent directories as needed.",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string" }, content: { type: "string" } },
+      required: ["path", "content"]
+    }
+  },
+  async run(args, ctx) {
+    try {
+      const { path, content } = args;
+      const full = resolveInside(ctx.cwd, path);
+      assertRealInside(ctx.cwd, full);
+      await mkdir(dirname3(full), { recursive: true });
+      await writeFile(full, content, "utf8");
+      return { ok: true, output: `wrote ${Buffer.byteLength(content, "utf8")} bytes to ${path}` };
+    } catch (err) {
+      return fail2(err);
+    }
+  }
+};
+var editFileTool = {
+  name: "edit_file",
+  dangerous: true,
+  schema: {
+    name: "edit_file",
+    description: "Replace an exact, unique occurrence of old_string with new_string in a file.",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string" }, old_string: { type: "string" }, new_string: { type: "string" } },
+      required: ["path", "old_string", "new_string"]
+    }
+  },
+  async run(args, ctx) {
+    try {
+      const { path, old_string, new_string } = args;
+      const full = resolveInside(ctx.cwd, path);
+      assertRealInside(ctx.cwd, full);
+      if (old_string === "") return { ok: false, output: "old_string must not be empty" };
+      const text = await readFile2(full, "utf8");
+      const count = text.split(old_string).length - 1;
+      if (count === 0) return { ok: false, output: `old_string not found in ${path}` };
+      if (count > 1) return { ok: false, output: `old_string matches ${count} occurrences in ${path}; make it unique` };
+      const updated = text.split(old_string).join(new_string);
+      await writeFile(full, updated, "utf8");
+      return { ok: true, output: `edited ${path}` };
+    } catch (err) {
+      return fail2(err);
+    }
+  }
+};
+
+// src/tools/shell.ts
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+var pexec = promisify(exec);
+function combine(stdout, stderr) {
+  return [stdout, stderr].filter((s) => s.trim()).join("\n").trim();
+}
+var shellTool = {
+  name: "shell",
+  dangerous: true,
+  schema: {
+    name: "shell",
+    description: "Run a shell command in the project root. Returns combined stdout+stderr; ok is false on a nonzero exit or timeout.",
+    parameters: {
+      type: "object",
+      properties: { command: { type: "string" } },
+      required: ["command"]
+    }
+  },
+  async run(args, ctx) {
+    const { command } = args;
+    try {
+      const { stdout, stderr } = await pexec(command, {
+        cwd: ctx.cwd,
+        timeout: 12e4,
+        maxBuffer: 10 * 1024 * 1024,
+        windowsHide: true
+      });
+      return { ok: true, output: combine(stdout, stderr) || "(no output)" };
+    } catch (err) {
+      const e = err;
+      const body = combine(e.stdout ?? "", e.stderr ?? "");
+      const status = e.killed && e.code == null ? "timed out" : e.killed ? "killed by signal" : `exit ${e.code ?? "?"}`;
+      return { ok: false, output: `[${status}] ${body || e.message}`.trim() };
+    }
+  }
+};
+
 // src/tools/registry.ts
-function buildReadOnlyTools() {
-  const tools = [readFileTool, listDirTool, globTool, grepTool];
+function toMap(tools) {
   return new Map(tools.map((t) => [t.name, t]));
 }
+function buildReadOnlyTools() {
+  return toMap([readFileTool, listDirTool, globTool, grepTool]);
+}
+function buildMutatingTools() {
+  return toMap([writeFileTool, editFileTool, shellTool]);
+}
+function buildAllTools() {
+  return toMap([...buildReadOnlyTools().values(), ...buildMutatingTools().values()]);
+}
+
+// src/permission/gate.ts
+var denyGate = async (req) => ({
+  allow: false,
+  reason: `permission denied: "${req.name}" is a write/exec action and non-interactive mode blocks it. Re-run with --yolo to allow.`
+});
+var allowAllGate = async () => ({
+  allow: true,
+  reason: "allowed (--yolo)"
+});
 
 // src/core/conversation.ts
 var Conversation = class {
@@ -579,6 +712,15 @@ var Engine = class {
           this.convo.pushToolResult(call.id, `unknown tool: ${call.name}`);
           continue;
         }
+        if (tool.dangerous) {
+          const gate = this.deps.gate ?? denyGate;
+          const verdict = await gate({ id: call.id, name: call.name, args: call.args });
+          if (!verdict.allow) {
+            this.emit({ type: "tool_end", id: call.id, ok: false, output: verdict.reason });
+            this.convo.pushToolResult(call.id, verdict.reason);
+            continue;
+          }
+        }
         let result;
         try {
           result = await tool.run(call.args, { cwd: this.deps.cwd });
@@ -631,10 +773,250 @@ function truncate(s, max = 500) {
   return s.length > max ? `${s.slice(0, max)}\u2026` : s;
 }
 
+// src/ui/runTui.tsx
+import { render } from "ink";
+
+// src/ui/permissionController.ts
+function createPermissionController() {
+  const sessionAllow = /* @__PURE__ */ new Set();
+  const subscribers = /* @__PURE__ */ new Set();
+  const queue = [];
+  let active = null;
+  let currentPending = null;
+  const notify = (p) => {
+    currentPending = p;
+    for (const fn of subscribers) fn(p);
+  };
+  const pump = () => {
+    if (active || queue.length === 0) return;
+    active = queue.shift();
+    notify({ req: active.req });
+  };
+  const gate = (req) => {
+    if (sessionAllow.has(req.name)) {
+      return Promise.resolve({ allow: true, reason: "allowed (remembered this session)" });
+    }
+    return new Promise((res) => {
+      queue.push({ req, settle: res });
+      pump();
+    });
+  };
+  const resolve3 = (decision) => {
+    if (!active) return;
+    const { req, settle } = active;
+    active = null;
+    if (decision === "always") sessionAllow.add(req.name);
+    settle({
+      allow: decision !== "deny",
+      reason: decision === "deny" ? `permission denied by user: ${req.name}` : `allowed (${decision})`
+    });
+    pump();
+    if (!active) notify(null);
+  };
+  const subscribe = (fn) => {
+    subscribers.add(fn);
+    return () => {
+      subscribers.delete(fn);
+    };
+  };
+  const getPending = () => currentPending;
+  return { gate, subscribe, getPending, resolve: resolve3 };
+}
+
+// src/ui/app.tsx
+import { useEffect, useState, useSyncExternalStore, useCallback } from "react";
+import { Box as Box4, Text as Text4, useInput as useInput2 } from "ink";
+import TextInput from "ink-text-input";
+
+// src/ui/components/MessageView.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function toolIcon(status) {
+  if (status === "running") return "\u23F3";
+  return status === "ok" ? "\u2705" : "\u274C";
+}
+function truncate2(s, max = 300) {
+  return s.length > max ? `${s.slice(0, max)}\u2026` : s;
+}
+function MessageView({ items }) {
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: items.map((it, i) => {
+    if (it.kind === "user") {
+      return /* @__PURE__ */ jsxs(Text, { children: [
+        /* @__PURE__ */ jsxs(Text, { color: "cyan", bold: true, children: [
+          "You",
+          "  "
+        ] }),
+        it.text
+      ] }, i);
+    }
+    if (it.kind === "assistant") {
+      return /* @__PURE__ */ jsxs(Text, { children: [
+        /* @__PURE__ */ jsxs(Text, { color: "green", bold: true, children: [
+          "Axon",
+          " "
+        ] }),
+        it.text
+      ] }, i);
+    }
+    if (it.kind === "error") {
+      return /* @__PURE__ */ jsxs(Text, { color: "red", children: [
+        "\u{1F4A5} ",
+        it.text
+      ] }, i);
+    }
+    if (it.kind === "tool") {
+      return /* @__PURE__ */ jsxs(Text, { color: "gray", children: [
+        toolIcon(it.status),
+        " ",
+        it.name,
+        "(",
+        truncate2(JSON.stringify(it.args ?? {}), 60),
+        ")",
+        it.output ? ` \u2014 ${truncate2(it.output)}` : ""
+      ] }, i);
+    }
+    return null;
+  }) });
+}
+
+// src/ui/components/PermissionPrompt.tsx
+import { Box as Box2, Text as Text2, useInput } from "ink";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function summarize(args) {
+  const s = JSON.stringify(args ?? {});
+  return s.length > 80 ? `${s.slice(0, 80)}\u2026` : s;
+}
+function decisionForKey(input) {
+  if (input === "a") return "once";
+  if (input === "A") return "always";
+  if (input === "d") return "deny";
+  return null;
+}
+function PermissionPrompt({ req, onDecide }) {
+  useInput((input) => {
+    const d = decisionForKey(input);
+    if (d) onDecide(d);
+  });
+  return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs2(Text2, { color: "yellow", children: [
+      "\u{1F512} ",
+      req.name,
+      "(",
+      summarize(req.args),
+      ")"
+    ] }),
+    /* @__PURE__ */ jsx2(Text2, { color: "yellow", children: "[a] allow once / [A] always this session / [d] deny" })
+  ] });
+}
+
+// src/ui/components/StatusBar.tsx
+import { Box as Box3, Text as Text3 } from "ink";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function StatusBar({ provider, model, running, yolo }) {
+  return /* @__PURE__ */ jsx3(Box3, { children: /* @__PURE__ */ jsxs3(Text3, { color: "gray", children: [
+    "[axon: ",
+    provider,
+    "/",
+    model,
+    yolo ? " \xB7 yolo" : "",
+    " \xB7 ",
+    running ? "working\u2026" : "ready",
+    " \xB7 ^C quit]"
+  ] }) });
+}
+
+// src/ui/app.tsx
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function reduceEvent(items, e) {
+  switch (e.type) {
+    case "text_delta": {
+      const last = items[items.length - 1];
+      if (last && last.kind === "assistant") {
+        return [...items.slice(0, -1), { kind: "assistant", text: last.text + e.text }];
+      }
+      return [...items, { kind: "assistant", text: e.text }];
+    }
+    case "tool_start":
+      return [...items, { kind: "tool", id: e.id, name: e.name, args: e.args, status: "running" }];
+    case "tool_end":
+      return items.map(
+        (it) => it.kind === "tool" && it.id === e.id ? { ...it, status: e.ok ? "ok" : "fail", output: e.output } : it
+      );
+    default:
+      return items;
+  }
+}
+function usePendingPermission(controller) {
+  const subscribe = useCallback((onChange) => controller.subscribe(() => onChange()), [controller]);
+  const getSnapshot = useCallback(() => controller.getPending(), [controller]);
+  const pending = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return pending ? pending.req : null;
+}
+function App({ engine, controller, provider, model, yolo }) {
+  const [items, setItems] = useState([]);
+  const [input, setInput] = useState("");
+  const [running, setRunning] = useState(false);
+  const pending = usePendingPermission(controller);
+  useEffect(() => {
+    engine.on((e) => setItems((prev) => reduceEvent(prev, e)));
+  }, [engine]);
+  useInput2(
+    (_input, key) => {
+      if (key.escape && !running) setInput("");
+    },
+    { isActive: !pending }
+  );
+  const handleSubmit = (text) => {
+    if (!text.trim() || running) return;
+    setItems((prev) => [...prev, { kind: "user", text }]);
+    setInput("");
+    setRunning(true);
+    engine.submit(text).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      setItems((prev) => [...prev, { kind: "error", text: msg }]);
+    }).finally(() => setRunning(false));
+  };
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx4(MessageView, { items }),
+    pending ? /* @__PURE__ */ jsx4(PermissionPrompt, { req: pending, onDecide: (d) => controller.resolve(d) }) : running ? /* @__PURE__ */ jsx4(Text4, { color: "gray", children: "\u2026 working (Ctrl+C to quit)" }) : /* @__PURE__ */ jsxs4(Box4, { children: [
+      /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "\u203A " }),
+      /* @__PURE__ */ jsx4(TextInput, { value: input, onChange: setInput, onSubmit: handleSubmit })
+    ] }),
+    /* @__PURE__ */ jsx4(StatusBar, { provider, model, running, yolo })
+  ] });
+}
+
+// src/ui/runTui.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+var TUI_SYSTEM = `You are Axon, an interactive agentic coding assistant. Use the tools to inspect and modify the project: read_file, list_dir, glob, grep (read-only) and write_file, edit_file, shell (these change the workspace; the user is prompted to approve each). Prefer edit_file for surgical changes. Explain briefly what you are doing.`;
+function runTui(opts) {
+  const cfg = loadConfig();
+  if (opts.provider) cfg.provider = opts.provider;
+  if (opts.model) cfg.model = opts.model;
+  const provider = createProvider(cfg);
+  const tools = buildAllTools();
+  const controller = createPermissionController();
+  const gate = opts.yolo ? allowAllGate : controller.gate;
+  const engine = new Engine({ provider, tools, system: TUI_SYSTEM, cwd: process.cwd(), gate });
+  render(
+    /* @__PURE__ */ jsx5(
+      App,
+      {
+        engine,
+        controller,
+        provider: cfg.provider,
+        model: resolveModel(cfg),
+        yolo: Boolean(opts.yolo)
+      }
+    )
+  );
+}
+
 // src/cli.ts
-var SYSTEM = `You are Axon, an agentic coding assistant. Use the provided tools to inspect the project and answer precisely. When done, stop calling tools.`;
+var READONLY_SYSTEM = `You are Axon, an agentic coding assistant. Use the read-only tools \u2014 read_file, list_dir, glob, grep \u2014 to inspect the project and answer precisely. When done, stop calling tools.`;
+var YOLO_SYSTEM = `You are Axon, an agentic coding assistant. Use the provided tools to inspect AND modify the project: read_file, list_dir, glob, grep (read-only), and write_file, edit_file, shell (these change the workspace). Prefer edit_file for surgical changes. When done, stop calling tools.`;
 var program = new Command();
-program.name("axon").version(VERSION).option("-p, --print <prompt>", "run one prompt non-interactively and stream the result").option("--provider <name>", "override the provider for this run (anthropic | openai | gemini)").option("--model <name>", "override the model for this run");
+program.name("axon").version(VERSION).option("-p, --print <prompt>", "run one prompt non-interactively and stream the result").option("--provider <name>", "override the provider for this run (anthropic | openai | gemini)").option("--model <name>", "override the model for this run").option("--yolo", "allow write/edit/shell tools without prompting (non-interactive)");
 program.command("config").argument("<action>", "get | set").argument("[key]", "config key (provider | model | <provider>.<baseUrl|model>)").argument("[value]", "value to set").action((action, key, value) => {
   if (action === "get") {
     process.stdout.write(JSON.stringify(readConfigFile(), null, 2) + "\n");
@@ -660,17 +1042,19 @@ program.action(() => {
 program.parse();
 async function main(opts) {
   if (!opts.print) {
-    process.stdout.write('Interactive TUI not built yet \u2014 use: axon -p "your prompt"\n');
+    runTui({ provider: opts.provider, model: opts.model, yolo: opts.yolo });
     return;
   }
   const cfg = loadConfig();
   if (opts.provider) cfg.provider = opts.provider;
   if (opts.model) cfg.model = opts.model;
   const provider = createProvider(cfg);
-  const tools = buildReadOnlyTools();
-  const engine = new Engine({ provider, tools, system: SYSTEM, cwd: process.cwd() });
+  const tools = opts.yolo ? buildAllTools() : buildReadOnlyTools();
+  const gate = opts.yolo ? allowAllGate : denyGate;
+  const system = opts.yolo ? YOLO_SYSTEM : READONLY_SYSTEM;
+  const engine = new Engine({ provider, tools, system, cwd: process.cwd(), gate });
   printRunner(engine, (s) => process.stdout.write(s));
-  process.stderr.write(`[axon: ${cfg.provider} / ${resolveModel(cfg)}]
+  process.stderr.write(`[axon: ${cfg.provider} / ${resolveModel(cfg)}${opts.yolo ? " / yolo" : ""}]
 `);
   await engine.submit(opts.print);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wanghuimvp/axon",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Axon — a multi-provider agentic coding CLI (Anthropic, OpenAI + OpenAI-compatible endpoints, Gemini). Runs a multi-step tool loop over your codebase.",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=dist/cli.js --packages=external",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=dist/cli.js --packages=external --jsx=automatic",
     "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {
@@ -46,11 +46,16 @@
     "@google/genai": "^1.52.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.0",
-    "openai": "^4.104.0"
+    "ink": "^5.2.1",
+    "ink-text-input": "^6.0.0",
+    "openai": "^4.104.0",
+    "react": "^18.3.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/react": "^18.3.31",
     "esbuild": "^0.23.0",
+    "ink-testing-library": "^4.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"