@wanghuimvp/axon 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-> 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.
+> Foundation release (`0.0.x`). Non-interactive `axon -p` mode with read-only tools (always available) and write/edit/shell tools (enabled with `--yolo`). Interactive TUI is on the roadmap.
 
 ## Install
 
@@ -73,8 +73,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 });
@@ -632,9 +774,10 @@ function truncate(s, max = 500) {
 }
 
 // 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");
@@ -667,10 +810,12 @@ async function main(opts) {
   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.2.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": {