@inetafrica/open-claudia 2.6.58 → 2.7.0

package/test-tools.js

@@ -1,6 +1,7 @@
 // Reusable tools: a script the agent crystallises must register with a parseable
-// header, run with the keyring merged into its env (preauth), and be findable by
-// the always-on tool index. This exercises the core/tools.js library end to end
+// header, live in the git-tracked directory layout (tool + TOOL.md + state.json),
+// run with the keyring merged into its env (preauth), be risk-gated, and be
+// findable by the always-on tool index. Exercises core/tools.js + core/tool-repo.js
 // in an isolated TOOLS_DIR so nothing touches the real ~/.open-claudia/tools.
 const assert = require("assert");
 const fs = require("fs");
@@ -11,9 +12,11 @@ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tools-test-"));
 process.env.TOOLS_DIR = path.join(tmp, "tools");
 
 const tools = require("./core/tools");
+const repo = require("./core/tool-repo");
 
 // ── add a bare script (no header): a header is synthesised from opts, shebang
-//    is preserved on line 1, and the file is made executable ──
+//    is preserved on line 1, the tool lands in the directory layout, and the
+//    undeclared risk tier defaults to write (fail-safe) ──
 const srcA = path.join(tmp, "hello.sh");
 fs.writeFileSync(srcA, "#!/usr/bin/env bash\necho \"hi $1\"\n");
 const a = tools.addTool(srcA, {
@@ -31,6 +34,20 @@ assert.strictEqual(a.usage, "hello <name>", "usage parsed back");
 assert.ok(a.executable, "stored tool is chmod +x");
 assert.ok(a.content.startsWith("#!/usr/bin/env bash\n"), "shebang stays on line 1");
 assert.ok(/# open-claudia-tool: hello/.test(a.content), "marker line injected with '#' prefix for a shell script");
+assert.strictEqual(a.risk, "write", "undeclared risk defaults to write");
+assert.strictEqual(a.defaultedRisk, true, "defaulted risk is flagged for the CLI warning");
+assert.strictEqual(a.layout, "dir", "new tools land in the directory layout");
+assert.strictEqual(a.file, path.join(process.env.TOOLS_DIR, "hello", "tool"), "executable lives at <name>/tool");
+assert.ok(fs.existsSync(path.join(process.env.TOOLS_DIR, "hello", "TOOL.md")), "TOOL.md skeleton generated");
+assert.ok(fs.existsSync(path.join(process.env.TOOLS_DIR, "hello", "state.json")), "state.json created");
+assert.ok(/## Known issues/.test(tools.readToolDoc("hello")), "TOOL.md carries the four sections");
+
+// ── explicit risk is honoured and normalised ──
+const srcRo = path.join(tmp, "peek.sh");
+fs.writeFileSync(srcRo, "#!/usr/bin/env bash\necho peek\n");
+const ro = tools.addTool(srcRo, { name: "peek", description: "look at things", risk: "READONLY" });
+assert.strictEqual(ro.risk, "read-only", "risk value is normalised (READONLY → read-only)");
+assert.ok(!ro.defaultedRisk, "explicit risk is not flagged as defaulted");
 
 // ── findTool / listTools see it ──
 assert.strictEqual(tools.findTool("hello").name, "hello", "findTool resolves by name");
@@ -45,7 +62,8 @@ assert.ok(/\/\/ open-claudia-tool: fetch/.test(b.content), "JS script gets '//'
 assert.strictEqual(b.requires.length, 0, "no requires when none supplied");
 
 // ── a source that already declares its own header is respected; a --pack passed
-//    in is grafted on without clobbering the existing marker ──
+//    in is grafted on without clobbering the existing marker; missing risk is
+//    grafted as write ──
 const srcC = path.join(tmp, "self-doc.sh");
 fs.writeFileSync(
   srcC,
@@ -55,6 +73,24 @@ const c = tools.addTool(srcC, { pack: "linked-pack" });
 assert.strictEqual(c.name, "selfdoc", "existing marker name wins");
 assert.strictEqual(c.description, "pre-documented", "existing description preserved");
 assert.strictEqual(c.pack, "linked-pack", "--pack grafted onto a self-documented script");
+assert.strictEqual(c.risk, "write", "missing risk grafted as write on a self-documented script");
+assert.strictEqual((c.content.match(/open-claudia-tool: selfdoc/g) || []).length, 1, "marker survives exactly once");
+
+// ── a source declaring its own risk keeps it ──
+const srcD = path.join(tmp, "declared.sh");
+fs.writeFileSync(
+  srcD,
+  "#!/usr/bin/env bash\n# open-claudia-tool: declared\n# risk: destructive\necho boom\n"
+);
+const d = tools.addTool(srcD, {});
+assert.strictEqual(d.risk, "destructive", "declared risk tier survives add");
+assert.ok(!d.defaultedRisk, "declared risk is not flagged as defaulted");
+
+// ── addTool REFUSES a hardcoded secret (the tools repo history is forever) ──
+const srcSecret = path.join(tmp, "leaky.sh");
+fs.writeFileSync(srcSecret, "#!/usr/bin/env bash\ncurl -H 'x: sk-ant-abcdefgh12345678'\n");
+assert.throws(() => tools.addTool(srcSecret, { name: "leaky" }), /secret/i, "hardcoded secret blocks the save");
+assert.strictEqual(tools.findTool("leaky"), null, "refused tool is not registered");
 
 // ── missingRequires: keys absent from keyring AND env are reported; present env
 //    keys are not ──
@@ -69,17 +105,33 @@ delete process.env.api_key;
 const env = tools.runEnv();
 assert.ok(env && typeof env === "object" && env.PATH, "runEnv yields an env object carrying PATH");
 
-// ── toolNameFromPath only recognises a direct child of TOOLS_DIR ──
+// ── toolNameFromPath recognises legacy flat files and the directory layout's
+//    agent-editable members; state.json and outside paths do not resolve ──
 assert.strictEqual(
-  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "hello")),
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "hello", "tool")),
   "hello",
-  "a file directly in TOOLS_DIR resolves to its tool name"
+  "<name>/tool resolves to the tool name"
+);
+assert.strictEqual(
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "hello", "TOOL.md")),
+  "hello",
+  "<name>/TOOL.md resolves to the tool name"
+);
+assert.strictEqual(
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "hello", "state.json")),
+  null,
+  "state.json is machine telemetry — not a tool edit"
+);
+assert.strictEqual(
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "legacy-flat")),
+  "legacy-flat",
+  "a direct child of TOOLS_DIR still resolves (legacy layout)"
 );
 assert.strictEqual(tools.toolNameFromPath("/etc/passwd"), null, "a path outside TOOLS_DIR → null");
 assert.strictEqual(
-  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "sub", "deep")),
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "sub", "deep", "deeper")),
   null,
-  "a nested path under TOOLS_DIR → null"
+  "a 3-deep path under TOOLS_DIR → null"
 );
 
 // ── parseHeader returns null for a script with no marker line ──
@@ -95,15 +147,53 @@ assert.ok(!mFetch.some((m) => m.name === "hello"), "an unrelated tool does not m
 assert.deepStrictEqual(tools.matchTools("zzzznomatchatall"), [], "no terms hit → empty match");
 assert.deepStrictEqual(tools.matchTools(""), [], "empty query → empty match");
 
-// ── recordRun telemetry: bumps runCount + stamps lastUsed, visible via readUsage
-//    and surfaced on the tool record itself ──
+// ── recordRunResult telemetry: stamps state.json with run counts, exit codes,
+//    per-verb health, and a capped history ──
 assert.strictEqual(tools.findTool("hello").runCount, 0, "fresh tool has runCount 0");
-tools.recordRun("hello");
-assert.strictEqual(tools.readUsage().hello.runCount, 1, "recordRun bumps the usage sidecar");
-assert.ok(tools.readUsage().hello.lastUsed, "recordRun stamps lastUsed");
+tools.recordRunResult("hello", { args: ["greet", "world"], exit: 0, ms: 42 });
+let hState = tools.readState("hello");
+assert.strictEqual(hState.runCount, 1, "recordRunResult bumps runCount in state.json");
+assert.ok(hState.lastUsed, "recordRunResult stamps lastUsed");
+assert.strictEqual(hState.lastExit, 0, "recordRunResult records the exit code");
+assert.ok(hState.lastSuccess, "a zero exit stamps lastSuccess");
+assert.strictEqual(hState.verbs.greet.runs, 1, "per-verb run count tracked (verb = first non-flag arg)");
+assert.ok(hState.verbs.greet.lastSuccess, "per-verb lastSuccess tracked");
+assert.strictEqual(hState.history[0].args, "greet world", "history records the arg line");
 assert.strictEqual(tools.findTool("hello").runCount, 1, "runCount surfaces on the tool record");
+
+tools.recordRunResult("hello", { args: ["--yes", "assign"], exit: 2, ms: 10 });
+hState = tools.readState("hello");
+assert.strictEqual(hState.runCount, 2, "a second run increments again");
+assert.strictEqual(hState.lastExit, 2, "failure exit recorded");
+assert.ok(hState.lastFailure, "a non-zero exit stamps lastFailure");
+assert.strictEqual(hState.verbs.assign.lastExit, 2, "flags are skipped when picking the verb");
+
+for (let i = 0; i < 25; i++) tools.recordRunResult("hello", { args: ["spam"], exit: 0, ms: 1 });
+assert.ok(tools.readState("hello").history.length <= 20, "run history is capped");
+
+// ── recordRun (end-of-turn transcript parse) is a no-op for directory tools —
+//    the CLI already stamped the authoritative result; double-counting would lie ──
+const beforeNoop = tools.readState("hello").runCount;
 tools.recordRun("hello");
-assert.strictEqual(tools.findTool("hello").runCount, 2, "a second run increments again");
+assert.strictEqual(tools.readState("hello").runCount, beforeNoop, "recordRun no-ops on a dir-layout tool");
+
+// ── legacy flat tools: recordRun still feeds the sidecar until migration ──
+const legacyFile = path.join(process.env.TOOLS_DIR, "oldy");
+fs.writeFileSync(legacyFile, "#!/usr/bin/env bash\n# open-claudia-tool: oldy\n# description: legacy widget probe\necho old\n", { mode: 0o700 });
+assert.strictEqual(tools.findTool("oldy").layout, "file", "flat file reads as legacy layout");
+tools.recordRun("oldy");
+assert.strictEqual(tools.readUsage().oldy.runCount, 1, "recordRun bumps the legacy sidecar");
+assert.strictEqual(tools.findTool("oldy").runCount, 1, "legacy runCount surfaces on the tool record");
+
+// ── migration: flat file → directory, telemetry carried over, sidecar cleaned ──
+const mig = repo.migrateLegacyTools();
+assert.ok(mig.migrated.includes("oldy"), "legacy tool is migrated");
+const oldy = tools.findTool("oldy");
+assert.strictEqual(oldy.layout, "dir", "migrated tool now uses the directory layout");
+assert.strictEqual(oldy.runCount, 1, "telemetry carried over from the sidecar");
+assert.ok(fs.existsSync(path.join(process.env.TOOLS_DIR, "oldy", "TOOL.md")), "migration generates TOOL.md");
+assert.ok(!tools.readUsage().oldy, "sidecar entry cleaned after migration");
+assert.ok(!repo.hasLegacyTools(), "no legacy tools remain after migration");
 
 // ── matchTools tie-break: equal score → more-run tool ranks first ──
 for (const n of ["alpha", "beta"]) {
@@ -111,7 +201,7 @@ for (const n of ["alpha", "beta"]) {
   fs.writeFileSync(s, "#!/usr/bin/env bash\necho x\n");
   tools.addTool(s, { name: n, description: "common widget gadget" });
 }
-tools.recordRun("beta");
+tools.recordRunResult("beta", { args: [], exit: 0, ms: 1 });
 const ranked = tools.matchTools("common widget gadget").map((m) => m.name);
 assert.ok(ranked.indexOf("beta") < ranked.indexOf("alpha"), "on equal score, the more-run tool ranks first");
 
@@ -123,6 +213,25 @@ const bornHello = tools.findTool("hello").createdAt;
 tools.recordCreate("hello"); // a second create-record must NOT move the stamp
 assert.strictEqual(tools.findTool("hello").createdAt, bornHello, "createdAt is immutable once set");
 
+// ── runGate: read-only runs freely; write demands --yes; destructive demands
+//    --yes-destructive (a plain --yes must NOT unlock it); undeclared → write ──
+assert.ok(tools.runGate({ name: "t", risk: "read-only" }, []).ok, "read-only runs without flags");
+assert.ok(!tools.runGate({ name: "t", risk: "write" }, []).ok, "write without --yes is refused");
+assert.ok(tools.runGate({ name: "t", risk: "write" }, ["--yes"]).ok, "write with --yes runs");
+assert.ok(!tools.runGate({ name: "t", risk: "destructive" }, ["--yes"]).ok, "plain --yes does not unlock destructive");
+assert.ok(tools.runGate({ name: "t", risk: "destructive" }, ["--yes-destructive"]).ok, "destructive with --yes-destructive runs");
+const undeclared = tools.runGate({ name: "t", risk: "" }, []);
+assert.ok(!undeclared.ok && undeclared.tier === "write", "undeclared tier is treated as write (fail-safe)");
+assert.ok(/destructive/i.test(tools.runGate({ name: "t", risk: "destructive" }, []).message), "destructive refusal spells out the warning");
+
+// ── scaffold: creates dir + stub + TOOL.md, registered and runnable ──
+const sc = repo.scaffoldTool("kwidget", { description: "widget system CLI", risk: "read-only", pack: "widgets", usage: "kwidget <verb>" });
+assert.strictEqual(sc.name, "kwidget", "scaffold registers the tool");
+assert.strictEqual(sc.risk, "read-only", "scaffold honours the risk tier");
+assert.ok(sc.executable, "scaffolded stub is executable");
+assert.ok(/## Journal/.test(tools.readToolDoc("kwidget")), "scaffolded TOOL.md has the sections");
+assert.throws(() => repo.scaffoldTool("kwidget", {}), /already exists/, "re-scaffolding an existing tool is refused");
+
 // ── envRefsIn: pulls every shape of env read out of a script ──
 const refs = tools.envRefsIn('echo $FOO ${BAR}\nx=process.env.BAZ\ny=process.env["QUX"]\n');
 for (const k of ["FOO", "BAR", "BAZ", "QUX"]) assert.ok(refs.has(k), `envRefsIn finds ${k}`);
@@ -152,7 +261,7 @@ assert.strictEqual(tools.checkSyntax("/tmp/x.txt", "plain text, no shebang\n"),
 
 // ── updateToolHeader (the 'fix' verb): refreshes recognised field lines in place,
 //    preserves the marker (exactly once), hand-written comments, and createdAt;
-//    leaves the body untouched ──
+//    leaves the body untouched; sets risk; refuses an invalid tier ──
 const fixSrc = path.join(tmp, "fixme.sh");
 fs.writeFileSync(
   fixSrc,
@@ -160,22 +269,33 @@ fs.writeFileSync(
 );
 const fixed0 = tools.addTool(fixSrc, {});
 const bornFix = fixed0.createdAt;
-const fixed = tools.updateToolHeader("fixme", { description: "new desc", requires: ["WIDGET_KEY"], usage: "fixme <x>" });
+const fixed = tools.updateToolHeader("fixme", { description: "new desc", requires: ["WIDGET_KEY"], usage: "fixme <x>", risk: "read-only" });
 assert.strictEqual(fixed.description, "new desc", "updateToolHeader rewrites the description");
 assert.deepStrictEqual(fixed.requires, ["WIDGET_KEY"], "updateToolHeader sets requires");
 assert.strictEqual(fixed.usage, "fixme <x>", "updateToolHeader sets usage");
+assert.strictEqual(fixed.risk, "read-only", "updateToolHeader sets the risk tier");
 assert.strictEqual(fixed.createdAt, bornFix, "updateToolHeader preserves createdAt");
 assert.ok(/a hand note worth keeping/.test(fixed.content), "updateToolHeader keeps hand-written comments");
 assert.strictEqual((fixed.content.match(/open-claudia-tool: fixme/g) || []).length, 1, "marker survives exactly once");
 assert.ok(/echo "\$WIDGET_KEY"/.test(fixed.content), "updateToolHeader leaves the body untouched");
+assert.throws(() => tools.updateToolHeader("fixme", { risk: "yolo" }), /invalid risk/i, "an invalid tier is refused");
 // requires-string form is normalised to a list
 const fixed2 = tools.updateToolHeader("fixme", { requires: "WIDGET_KEY, OTHER_KEY" });
 assert.deepStrictEqual(fixed2.requires, ["WIDGET_KEY", "OTHER_KEY"], "string requires split into a list");
-// a body that now reads OTHER_KEY would no longer be 'unused' — lint stays in sync
 assert.strictEqual(tools.updateToolHeader("does-not-exist", { description: "x" }), null, "updateToolHeader on a missing tool → null");
 
+// ── git history: the tools dir is a repo and changes commit (skipped without git) ──
+try {
+  require("child_process").execFileSync("git", ["--version"], { stdio: "pipe" });
+  assert.ok(fs.existsSync(path.join(process.env.TOOLS_DIR, ".git")), "tools dir is git-initialised");
+  const log = repo.toolLog("hello", 10);
+  assert.ok(log.length >= 1, "tool changes are committed (git log has entries)");
+  assert.ok(fs.readFileSync(path.join(process.env.TOOLS_DIR, ".gitignore"), "utf-8").includes("state.json"), "state.json is gitignored");
+} catch (e) { console.log("  (git not available — history assertions skipped)"); }
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");
+assert.ok(!fs.existsSync(path.join(process.env.TOOLS_DIR, "hello")), "removed tool's directory is gone");
 
 console.log("tools OK");