@inetafrica/open-claudia 2.6.59 → 2.7.1

package/core/tool-repo.js

@@ -0,0 +1,270 @@
+// Git-backed tool repository: every tool is a directory (executable + TOOL.md +
+// state.json) inside a git-initialised TOOLS_DIR, so `git log` IS the upgrade
+// history and any change is one revert from undone.
+//
+// Split from core/tools.js so the registry (read/parse/match) stays pure fs;
+// this module owns everything that shells out to git, plus the scaffold and
+// legacy-migration machinery that writes whole tool directories. Requires
+// between the two modules are lazy to tolerate the natural circularity.
+//
+// state.json is deliberately gitignored: it is runtime telemetry stamped on
+// every run — committing it would bury real code/doc changes in noise. The
+// curated, human-readable condition of a tool lives in TOOL.md's State section.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const GIT_IDENT = ["-c", "user.name=open-claudia", "-c", "user.email=tools@open-claudia.local"];
+const GITIGNORE = ["*/state.json", ".usage.json", "__pycache__/", ".DS_Store", ""].join("\n");
+
+function toolsDir() {
+  return require("./tools").TOOLS_DIR;
+}
+
+function git(args, { ident = false } = {}) {
+  try {
+    const full = ["-C", toolsDir(), ...(ident ? GIT_IDENT : []), ...args];
+    const r = spawnSync("git", full, { encoding: "utf-8" });
+    if (r.error) return { ok: false, status: -1, stdout: "", stderr: String(r.error.message || r.error) };
+    return { ok: r.status === 0, status: r.status, stdout: (r.stdout || "").trim(), stderr: (r.stderr || "").trim() };
+  } catch (e) {
+    return { ok: false, status: -1, stdout: "", stderr: String(e.message || e) };
+  }
+}
+
+function gitAvailable() {
+  try { return !spawnSync("git", ["--version"], { encoding: "utf-8" }).error; }
+  catch (e) { return false; }
+}
+
+// Initialise the tools dir as a git repo (idempotent). Best-effort: on a box
+// without git everything else still works, there's just no history.
+function ensureRepo() {
+  const dir = toolsDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const ignoreFile = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignoreFile)) { try { fs.writeFileSync(ignoreFile, GITIGNORE, { mode: 0o600 }); } catch (e) {} }
+  if (fs.existsSync(path.join(dir, ".git"))) return true;
+  if (!gitAvailable()) return false;
+  if (!git(["init", "-q"]).ok) return false;
+  git(["add", "-A"]);
+  git(["commit", "-q", "-m", "init tool repository"], { ident: true });
+  return true;
+}
+
+// Stage + commit one tool's paths (or everything with "."). No-op when the tree
+// is clean or git is unavailable. Every add/change/remove funnels through here.
+function commitTool(name, message) {
+  if (!ensureRepo()) return false;
+  const target = name ? require("./tools").sanitizeName(name) : ".";
+  if (!git(["add", "-A", "--", target || "."]).ok) return false;
+  const staged = git(["diff", "--cached", "--quiet"]);
+  if (staged.status === 0) return false; // nothing to commit
+  return git(["commit", "-q", "-m", message], { ident: true }).ok;
+}
+
+// Recent history for one tool — surfaced by `tool show` as the upgrade log.
+function toolLog(name, limit = 5) {
+  const n = require("./tools").sanitizeName(name);
+  if (!n || !fs.existsSync(path.join(toolsDir(), ".git"))) return [];
+  const r = git(["log", "--date=short", `--pretty=%ad %s`, "-n", String(limit), "--", n]);
+  return r.ok && r.stdout ? r.stdout.split("\n").filter(Boolean) : [];
+}
+
+// ── Scaffold ─────────────────────────────────────────────────────────────────
+
+function today() { return new Date().toISOString().slice(0, 10); }
+
+function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateLine, journalLine }) {
+  return [
+    `# ${name}`,
+    "",
+    "## Interface",
+    description || "(describe what system this tool fronts)",
+    "",
+    `Usage: \`open-claudia tool run ${name}${usage ? " " + usage.replace(new RegExp("^" + name + "\\s*"), "") : " <verb> [args]"}\``,
+    `Risk: ${risk || "write"}${requires && requires.length ? ` · Requires: ${requires.join(", ")}` : ""}${pack ? ` · Pack: ${pack}` : ""}`,
+    "",
+    "## Known issues",
+    "(none yet)",
+    "",
+    "## State",
+    stateLine || `Scaffolded ${today()} — not yet proven against the live system.`,
+    "",
+    "## Journal",
+    `- [${today()}] ${journalLine || "Scaffolded."}`,
+    "",
+  ].join("\n");
+}
+
+function nodeStub({ name, description, pack, risk, requires, usage }) {
+  const req = requires && requires.length ? `// requires: ${requires.join(", ")}\n` : "";
+  return `#!/usr/bin/env node
+// open-claudia-tool: ${name}
+// description: ${description || ""}
+${pack ? `// pack: ${pack}\n` : ""}// risk: ${risk}
+${req}// usage: ${usage || `${name} <verb> [args]`}
+//
+// One CLI per system, verbs as subcommands. Add a function per verb below.
+// Confirmation flags (--yes / --yes-destructive) are enforced by the tool
+// runner and may appear in argv — ignore them unless you need them.
+
+const args = process.argv.slice(2).filter((a) => a !== "--yes" && a !== "--yes-destructive");
+const verb = args[0] || "help";
+
+const HANDLERS = {
+  help() {
+    console.log("${name} — ${(description || "").replace(/"/g, '\\"')}");
+    console.log("verbs: " + Object.keys(HANDLERS).join(", "));
+  },
+  // example(rest) { ... },
+};
+
+const fn = HANDLERS[verb] || (verb === "--help" ? HANDLERS.help : null);
+if (!fn) { console.error("unknown verb: " + verb); HANDLERS.help(); process.exit(1); }
+Promise.resolve(fn(args.slice(1))).catch((e) => { console.error(e.message || e); process.exit(1); });
+`;
+}
+
+function bashStub({ name, description, pack, risk, requires, usage }) {
+  const req = requires && requires.length ? `# requires: ${requires.join(", ")}\n` : "";
+  return `#!/usr/bin/env bash
+# open-claudia-tool: ${name}
+# description: ${description || ""}
+${pack ? `# pack: ${pack}\n` : ""}# risk: ${risk}
+${req}# usage: ${usage || `${name} <verb> [args]`}
+#
+# One CLI per system, verbs as subcommands: add a case per verb below.
+# Confirmation flags (--yes / --yes-destructive) are enforced by the tool
+# runner and may appear in "$@" — ignore them unless you need them.
+set -euo pipefail
+
+verb="\${1:-help}"; shift || true
+
+case "$verb" in
+  help|--help)
+    echo "${name} — ${description || ""}"
+    echo "verbs: help" ;;
+  *)
+    echo "unknown verb: $verb" >&2; exit 1 ;;
+esac
+`;
+}
+
+// Create a new tool directory with an executable stub, TOOL.md skeleton, and
+// initial state.json — then commit. The generated stub already carries the full
+// header (name, desc, pack, risk, requires, usage) so the tool is registered
+// and runnable the moment it exists.
+function scaffoldTool(name, opts = {}) {
+  const tools = require("./tools");
+  const n = tools.sanitizeName(name);
+  if (!n) throw new Error("scaffold needs a tool name");
+  if (tools.findTool(n)) throw new Error(`tool "${n}" already exists — extend it (tool edit ${n}) instead of re-scaffolding`);
+  const risk = tools.normalizeRisk(opts.risk) || "write";
+  const requires = [].concat(opts.requires || []).filter(Boolean);
+  const spec = { name: n, description: opts.description || "", pack: opts.pack || "", risk, requires, usage: opts.usage || "" };
+
+  ensureRepo();
+  const dir = path.join(toolsDir(), n);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stub = (opts.lang === "bash" || opts.lang === "sh") ? bashStub(spec) : nodeStub(spec);
+  fs.writeFileSync(path.join(dir, "tool"), stub, { mode: 0o700 });
+  try { fs.chmodSync(path.join(dir, "tool"), 0o700); } catch (e) {}
+  fs.writeFileSync(path.join(dir, "TOOL.md"), toolMdSkeleton(spec), { mode: 0o600 });
+  tools.writeState(n, { createdAt: new Date().toISOString(), runCount: 0 });
+  commitTool(n, `scaffold ${n}`);
+  return tools.findTool(n);
+}
+
+// ── Legacy migration ─────────────────────────────────────────────────────────
+// Convert flat-file tools (pre-2.7 layout) into directories, one commit each.
+// Seeds each tool's state.json from the old .usage.json sidecar and generates a
+// TOOL.md so every migrated tool arrives with its memory intact. Files in the
+// tools dir that don't parse as tools are left untouched.
+function migrateLegacyTools() {
+  const tools = require("./tools");
+  const dir = toolsDir();
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (e) { return { migrated: [], skipped: [] }; }
+
+  const legacy = [];
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    const p = path.join(dir, name);
+    try { if (!fs.statSync(p).isFile()) continue; } catch (e) { continue; }
+    legacy.push(name);
+  }
+  if (!legacy.length) return { migrated: [], skipped: [] };
+
+  ensureRepo();
+  const usage = tools.readUsage();
+  const migrated = [], skipped = [];
+
+  for (const fileName of legacy) {
+    const src = path.join(dir, fileName);
+    let content;
+    try { content = fs.readFileSync(src, "utf-8"); } catch (e) { skipped.push(fileName); continue; }
+    const header = tools.parseHeader(content);
+    if (!header) { skipped.push(fileName); continue; } // not a registered tool — leave it alone
+
+    const n = header.name || tools.sanitizeName(fileName);
+    const tmp = path.join(dir, `.migrating-${n}`);
+    try {
+      fs.renameSync(src, tmp);
+      const toolDir = path.join(dir, n);
+      fs.mkdirSync(toolDir, { recursive: true, mode: 0o700 });
+      fs.renameSync(tmp, path.join(toolDir, "tool"));
+      try { fs.chmodSync(path.join(toolDir, "tool"), 0o700); } catch (e) {}
+
+      const u = usage[n] || {};
+      tools.writeState(n, {
+        createdAt: u.createdAt || new Date().toISOString(),
+        lastUsed: u.lastUsed || "",
+        runCount: u.runCount || 0,
+      });
+      if (!fs.existsSync(path.join(toolDir, "TOOL.md"))) {
+        fs.writeFileSync(path.join(toolDir, "TOOL.md"), toolMdSkeleton({
+          ...header,
+          risk: header.risk || "",
+          stateLine: `Migrated from flat layout ${today()}. Risk tier ${header.risk ? `"${header.risk}"` : "not yet classified — treated as write (fail-safe) until set"}.`,
+          journalLine: "Migrated from flat file layout; telemetry carried over from .usage.json.",
+        }), { mode: 0o600 });
+      }
+      delete usage[n];
+      commitTool(n, `migrate ${n} to directory layout`);
+      migrated.push(n);
+    } catch (e) {
+      // Roll the file back if anything failed mid-move.
+      try { if (fs.existsSync(tmp)) fs.renameSync(tmp, src); } catch (e2) {}
+      skipped.push(fileName);
+    }
+  }
+
+  if (migrated.length) {
+    try {
+      if (Object.keys(usage).length) fs.writeFileSync(tools.USAGE_FILE, JSON.stringify(usage), { mode: 0o600 });
+      else fs.rmSync(tools.USAGE_FILE, { force: true });
+    } catch (e) {}
+  }
+  return { migrated, skipped };
+}
+
+// True when flat-file tools still exist (cheap check used to auto-trigger
+// migration from the CLI entry point).
+function hasLegacyTools() {
+  const tools = require("./tools");
+  let entries;
+  try { entries = fs.readdirSync(toolsDir()); } catch (e) { return false; }
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    const p = path.join(toolsDir(), name);
+    try {
+      if (!fs.statSync(p).isFile()) continue;
+      if (tools.parseHeader(fs.readFileSync(p, "utf-8"))) return true;
+    } catch (e) {}
+  }
+  return false;
+}
+
+module.exports = { ensureRepo, commitTool, toolLog, scaffoldTool, migrateLegacyTools, hasLegacyTools, toolMdSkeleton };