getclaros 0.0.0-stage → 0.1.0

package/dist/setup.js

@@ -0,0 +1,589 @@
+// getclaros init | test | undo | status (| export: a map's rules as markdown): puts the guard in front of the MCP servers an agent client already runs.
+// Edits only existing config files, backs each one up first (~/.config/getclaros/backups/<time>/, 0600), writes
+// atomically, and never prints the key.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir, hostname } from "node:os";
+import { basename, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { addClaros, argvOf, CLAROS, detect, launcher, load, removeEntry, sha, unwrapServer, wrapServer, writeAtomic, } from "./clients.js";
+import { cfgDir, loadConfig, relocate, resolve, saveConfig } from "./config.js";
+const NAME = launcher().at(-1) === "getclaros" ? "npx getclaros" : "getclaros";
+const say = (s = "") => process.stdout.write(s + "\n");
+const warn = (s) => process.stderr.write(s + "\n");
+const tilde = (p) => p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p;
+const keyId = (k) => k.split("_").slice(0, 2).join("_") + "_…"; // clr_<prefix>_… (the prefix is the lookup id, not the secret)
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+export const USAGE = `usage: ${NAME} init   [--key clr_… | env CLAROS_KEY | --paste] [--no-browser] [--url <claros server> | --web <claros web app>] [--yes] [--servers a,b] [--project <dir>] [--no-mcp]
+       ${NAME} test   [--app <server>]
+       ${NAME} status
+       ${NAME} undo   [--all]
+       ${NAME} export <workflow_id> [--format agents|design|skill] [> AGENTS.md]
+       ${NAME} override <check_id> --reason "…" [--rule <rule id>] [--verdict wrong_stop|wrong_nudge|missed|right]`;
+export async function run(argv) {
+    const [cmd, ...rest] = argv;
+    let v, pos;
+    try {
+        ({ values: v, positionals: pos } = parseArgs({ args: rest, allowPositionals: cmd === "export" || cmd === "override", options: {
+                url: { type: "string" }, web: { type: "string" }, key: { type: "string" }, yes: { type: "boolean", short: "y" }, servers: { type: "string" },
+                project: { type: "string" }, all: { type: "boolean" }, "no-mcp": { type: "boolean" }, app: { type: "string" },
+                paste: { type: "boolean" }, "no-browser": { type: "boolean" }, format: { type: "string" },
+                reason: { type: "string" }, rule: { type: "string" }, verdict: { type: "string" },
+            } }));
+    }
+    catch (e) {
+        warn(`${e.message}\n${USAGE}`);
+        return 2;
+    }
+    const project = v.project ?? process.cwd();
+    if (cmd === "init")
+        return init(v, project);
+    if (cmd === "test")
+        return test(v, project);
+    if (cmd === "status")
+        return status(v, project);
+    if (cmd === "undo")
+        return undo(v, project);
+    if (cmd === "export" && pos.length === 1 && ["agents", "design", "skill"].includes(v.format ?? "agents")) {
+        return exportMap(v, pos[0]);
+    }
+    if (cmd === "override" && pos.length === 1 && VERDICTS.includes(v.verdict ?? "wrong_stop"))
+        return override(v, pos[0]);
+    warn(USAGE);
+    return 2;
+}
+// ---- Claros API ----
+async function api(url, key, path, body) {
+    const r = await fetch(url + path, {
+        method: body === undefined ? "GET" : "POST", signal: AbortSignal.timeout(10_000),
+        headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    return { status: r.status, json: await r.json().catch(() => null) };
+}
+/** "valid" | why not. GET /v1/tools/kinds is the cheapest agent-scope read. */
+async function keyStatus(url, key) {
+    try {
+        const { status } = await api(url, key, "/v1/tools/kinds?app=getclaros");
+        return status === 200 ? "valid" : status === 401 ? "rejected (unknown or revoked key)"
+            : status === 403 ? "missing the agent scope" : status === 429 ? "rate limited, try again in a minute" : `HTTP ${status}`;
+    }
+    catch (e) {
+        return `unreachable (${e.message})`;
+    }
+}
+/** The server (resolve), asking the web app again once if it doesn't answer at all (it moved). null = no server. */
+async function locate(v) {
+    let r;
+    try {
+        r = await resolve(v);
+    }
+    catch (e) {
+        warn(e.message);
+        return null;
+    }
+    const answers = await fetch(r.url + "/healthz", { signal: AbortSignal.timeout(10_000) }).then(() => true, () => false);
+    if (!answers && await relocate(r))
+        warn(`Claros moved: now ${r.url}`);
+    return r;
+}
+// ---- browser sign-in (RFC 8628 device flow) ----
+const VERSION = "0.1.0";
+const sleep = (s) => new Promise((ok) => setTimeout(ok, s * Number(process.env.GETCLAROS_INTERVAL_MS ?? 1000)));
+function openBrowser(url) {
+    if (process.env.GETCLAROS_NO_BROWSER)
+        return;
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+    }
+    catch { /* no browser: the URL is printed */ }
+}
+/** Device flow → an agent key, or why not. "unsupported" = this Claros has no device sign-in (fall back to a key). */
+async function deviceSignIn(url, browser) {
+    let d;
+    try {
+        const r = await fetch(url + "/v1/device", { method: "POST", signal: AbortSignal.timeout(10_000),
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ client_name: `getclaros ${VERSION}`, device_name: hostname() }) });
+        if (!r.ok)
+            return "unsupported";
+        d = await r.json();
+    }
+    catch {
+        return "unsupported";
+    }
+    say(`Sign in to Claros in your browser:
+
+  ${d.verification_uri_complete ?? d.verification_uri}
+
+and check it shows the code ${d.user_code}. Waiting…`);
+    if (browser)
+        openBrowser(d.verification_uri_complete ?? d.verification_uri);
+    let interval = Number(d.interval) || 5;
+    const until = Date.now() + (Number(d.expires_in) || 600) * 1000;
+    while (Date.now() < until) {
+        await sleep(interval);
+        let r, j;
+        try {
+            r = await fetch(url + "/v1/device/token", { method: "POST", signal: AbortSignal.timeout(10_000),
+                headers: { "content-type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: d.device_code }) });
+            j = await r.json();
+        }
+        catch {
+            continue; // a network blip: keep polling until the code expires
+        }
+        if (r.ok && typeof j?.access_token === "string")
+            return { key: j.access_token, workspace: j.workspace };
+        if (j?.error === "authorization_pending")
+            continue;
+        if (j?.error === "slow_down") {
+            interval += 5;
+            continue;
+        }
+        if (j?.error === "access_denied")
+            return "the sign-in was denied in the browser";
+        if (j?.error === "expired_token")
+            return "the code expired before it was approved";
+        return `sign-in failed (${j?.error ?? `HTTP ${r.status}`})`;
+    }
+    return "the code expired before it was approved";
+}
+/** The key's workspace, from GET /v1/whoami (older servers: undefined). */
+async function whoami(url, key) {
+    try {
+        const r = await api(url, key, "/v1/whoami");
+        return r.status === 200 && r.json?.workspace?.id ? r.json.workspace : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- prompts ----
+async function ask(q) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(q);
+    }
+    finally {
+        rl.close();
+    }
+}
+function askHidden(q) {
+    return new Promise((ok) => {
+        const stdin = process.stdin;
+        process.stderr.write(q);
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        let s = "";
+        const on = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\u0003") {
+                    stdin.setRawMode(false);
+                    process.exit(130);
+                }
+                if (ch === "\r" || ch === "\n" || ch === "\u0004") {
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    stdin.off("data", on);
+                    process.stderr.write("\n");
+                    return ok(s);
+                }
+                s = ch === "\u007f" || ch === "\b" ? s.slice(0, -1) : s + ch;
+            }
+        };
+        stdin.on("data", on);
+    });
+}
+const backupsDir = () => join(cfgDir(), "backups");
+const newRun = (suffix = "") => ({ dir: join(backupsDir(), new Date().toISOString().replace(/[:.]/g, "-") + suffix), files: [] });
+/** Backs up `before`, writes `after` atomically, records both hashes. */
+function commit(run, path, before, after) {
+    if (!run.files.length) {
+        mkdirSync(cfgDir(), { recursive: true, mode: 0o700 });
+        mkdirSync(run.dir, { recursive: true, mode: 0o700 });
+    }
+    const backup = join(run.dir, `${run.files.length}-${basename(path)}`);
+    writeFileSync(backup, before, { mode: 0o600 });
+    writeAtomic(path, after);
+    run.files.push({ path, backup, before: sha(before), after: sha(after) });
+    writeFileSync(join(run.dir, "manifest.json"), JSON.stringify({ files: run.files }, null, 2), { mode: 0o600 });
+}
+function runs() {
+    if (!existsSync(backupsDir()))
+        return [];
+    return readdirSync(backupsDir()).filter((d) => !d.endsWith(".undone")).sort().flatMap((d) => {
+        try {
+            return [{ dir: join(backupsDir(), d), ...JSON.parse(readFileSync(join(backupsDir(), d, "manifest.json"), "utf8")) }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** A command line for the terminal: at most 3 parts, anything that looks like a secret masked. */
+function show(argv) {
+    const safe = argv.slice(0, 3).map((a, i) => i && (/^[A-Za-z0-9_\-+/=.]{24,}$/.test(a) || /(key|token|secret|pass)/i.test(a) &&
+        a.includes("=")) ? "***" : a);
+    return safe.join(" ") + (argv.length > 3 ? " …" : "");
+}
+/** A remote server's address for the terminal: no query string (it may carry a token). */
+const site = (u) => { try {
+    const x = new URL(u);
+    return x.origin + x.pathname;
+}
+catch {
+    return "(bad url)";
+} };
+const where = (s) => s.scope[0] === "projects" ? ` (project ${tilde(s.scope[1])})` : "";
+// ---- init ----
+async function init(v, project) {
+    const at = await locate(v);
+    if (!at)
+        return 3;
+    const { url } = at;
+    const web = at.source === "pinned" && !v.web && !process.env.CLAROS_WEB ? undefined : at.web; // --url alone: pinned
+    let { key } = at;
+    let workspace = key && key === loadConfig().key ? loadConfig().workspace : undefined;
+    if (!key && !v.paste) {
+        const d = await deviceSignIn(url, !v["no-browser"]);
+        if (typeof d === "object")
+            ({ key, workspace } = d);
+        else if (d !== "unsupported") {
+            warn(`Claros at ${url}: ${d}. Run ${NAME} init again.`);
+            return 3;
+        }
+    }
+    if (!key) {
+        if (!process.stdin.isTTY) {
+            warn(`No Claros key, and ${url} has no browser sign-in. Pass --key clr_… or set CLAROS_KEY (an \`agent\` key).`);
+            return 2;
+        }
+        key = (await askHidden("Paste your Claros key (clr_…, agent scope; input hidden): ")).trim();
+    }
+    const ks = await keyStatus(url, key);
+    if (ks !== "valid") {
+        warn(`Claros at ${url}: key ${keyId(key)} ${ks}.`);
+        return 3;
+    }
+    const saved = loadConfig();
+    workspace ??= await whoami(url, key);
+    const cfg = saved.url === url && saved.web === web && saved.key === key && saved.workspace?.name === workspace?.name
+        ? join(cfgDir(), "config.json") : saveConfig({ url, web, key, ...(workspace ? { workspace } : {}) });
+    say(`Signed in to ${url}${workspace?.name ? ` (workspace "${workspace.name}")` : ""} with key ${keyId(key)} (saved in ${tilde(cfg)}, readable only by you).`);
+    const files = detect(project);
+    if (!files.length) {
+        say(`\nSee a stop now: ${NAME} test`);
+        say("To guard an agent's tools: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), then run init again.");
+        return 1;
+    }
+    const maps = await api(url, key, "/api/workflows").then((r) => (Array.isArray(r.json) ? r.json : []), () => []);
+    const mapOf = (name) => maps.find((m) => (m.apps ?? []).some((a) => norm(a) && norm(name) && (norm(a).includes(norm(name)) || norm(name).includes(norm(a)))));
+    const cands = [];
+    say();
+    for (const f of files) {
+        say(`${f.client}  ${tilde(f.path)}`);
+        if (f.error)
+            say(`      couldn't read it (${f.error}); left alone`);
+        for (const s of f.servers) {
+            if (s.ours)
+                say(`      ${s.name}${where(s)}  Claros MCP server (agents read the Work Map with get_workflow)`);
+            else if (s.guarded)
+                say(`  [=] ${s.name}${where(s)}  already guarded`);
+            else if (s.gap)
+                say(`  [ ] ${s.name}${where(s)}  remote ${site(s.entry.url)}: ${s.gap}`);
+            else {
+                const m = mapOf(s.name);
+                cands.push(s);
+                say(`  ${String(cands.length).padStart(2)}. ${s.name}${where(s)}  ${s.remote ? `remote ${site(s.entry.url)}` : show(argvOf(s.entry))}` +
+                    (m ? `  ← Work Map "${m.name}"` : ""));
+            }
+        }
+    }
+    say();
+    const byName = (names) => cands.filter((s) => names.includes(s.name));
+    let picks = cands.filter((s) => mapOf(s.name));
+    if (v.servers !== undefined) {
+        const names = v.servers.split(",").map((s) => s.trim()).filter(Boolean);
+        const all = files.flatMap((f) => f.servers);
+        for (const n of names) {
+            const hit = all.filter((s) => s.name === n);
+            if (!hit.length) {
+                warn(`No MCP server named "${n}". Found: ${[...new Set(all.filter((s) => !s.ours).map((s) => s.name))].join(", ") || "none"}.`);
+                return 2;
+            }
+            if (hit.every((s) => s.gap))
+                say(`${n}: remote server, ${hit[0].gap}.`);
+            else if (hit.every((s) => s.guarded || s.gap))
+                say(`${n}: already guarded.`);
+        }
+        picks = byName(names);
+    }
+    else if (!v.yes) {
+        if (!process.stdin.isTTY) {
+            warn("Not a terminal: pass --yes (guard the servers that match a Work Map) or --servers a,b.");
+            return 2;
+        }
+        const def = picks.map((s) => cands.indexOf(s) + 1).join(",");
+        for (;;) {
+            const a = (await ask(`Guard which? Numbers (1,3), "all", "none"${def ? `, Enter = ${def}` : ""}: `)).trim().toLowerCase();
+            if (!a)
+                break;
+            if (a === "none") {
+                picks = [];
+                break;
+            }
+            if (a === "all") {
+                picks = cands;
+                break;
+            }
+            const ns = a.split(/[\s,]+/).map(Number);
+            if (ns.every((n) => n >= 1 && n <= cands.length)) {
+                picks = ns.map((n) => cands[n - 1]);
+                break;
+            }
+            warn(`Pick numbers between 1 and ${cands.length}.`);
+        }
+    }
+    else if (!picks.length && cands.length) {
+        say("None of these servers matches a Work Map yet, so none is guarded. Pick them with --servers a,b.");
+    }
+    const run = newRun();
+    const changed = [];
+    const userClients = new Set(files.filter((f) => f.user && !f.error).map((f) => f.client));
+    for (const f of files.filter((x) => !x.error)) {
+        const before = f.text, mine = picks.filter((s) => s.file === f);
+        try {
+            for (const s of mine) {
+                f.text = wrapServer(f, s);
+                load(f);
+                say(`guarded ${s.name}${where(s)} in ${f.client} (${tilde(f.path)})`);
+            }
+            // the Claros MCP server: in each client's user config, or its project file when the client has none
+            const top = f.servers.find((s) => s.name === CLAROS && s.scope.length === 1);
+            if (!v["no-mcp"] && (f.user || !userClients.has(f.client))) {
+                if (!top) {
+                    f.text = addClaros(f);
+                    load(f);
+                    say(`added the Claros MCP server to ${f.client} (${tilde(f.path)})`);
+                }
+                else if (!top.ours)
+                    say(`kept the existing "${CLAROS}" entry in ${tilde(f.path)} (not ours)`);
+            }
+        }
+        catch (e) {
+            warn(`${tilde(f.path)}: ${e.message}; left unchanged`);
+            f.text = before;
+            continue;
+        }
+        if (f.text !== before) {
+            commit(run, f.path, before, f.text);
+            changed.push(f.client);
+        }
+    }
+    if (!changed.length) {
+        say("Nothing to change.");
+        return 0;
+    }
+    say(`\nBacked up every file before changing it (${tilde(run.dir)}).`);
+    say(`Restart ${[...new Set(changed)].join(", ")} to load the change. Then: ${NAME} test   Undo: ${NAME} undo`);
+    return 0;
+}
+// ---- test ----
+async function test(v, project) {
+    const at = await locate(v);
+    if (!at)
+        return 3;
+    const { url, key } = at;
+    if (!key) {
+        warn(`Not signed in: run ${NAME} init first (or set CLAROS_KEY).`);
+        return 2;
+    }
+    const guarded = v.app ? [v.app] : [...new Set(detect(project).flatMap((f) => f.servers.filter((s) => s.guarded).map((s) => s.name)))];
+    try {
+        const q = guarded.map((a) => `app=${encodeURIComponent(a)}`).join("&");
+        const ex = await api(url, key, `/v1/check/example${q ? "?" + q : ""}`);
+        if (ex.status === 401 || ex.status === 403) {
+            warn(`Claros rejected key ${keyId(key)} (HTTP ${ex.status}). Run ${NAME} init with a valid agent key.`);
+            return 3;
+        }
+        if (ex.status === 404) {
+            say(`No approved Work Map with an exact rule to test yet. Paste a policy at ${at.web}/policy, approve the map, then run this again.`);
+            return 1;
+        }
+        if (ex.status !== 200)
+            throw new Error(`HTTP ${ex.status}`);
+        const e = ex.json, t0 = Date.now();
+        const r = await api(url, key, "/v1/check", { workflow_id: e.workflow_id, app: e.app ?? guarded[0] ?? undefined,
+            tool: "getclaros_test", actor: "getclaros test", state: e.state });
+        if (r.status !== 200)
+            throw new Error(`HTTP ${r.status}`);
+        const ms = Date.now() - t0;
+        if (e.demo)
+            say(`DEMO: ${guarded.length ? `none of your guarded servers (${guarded.join(", ")}) matches` : "no server is guarded yet, so nothing matches"} a Work Map, so this checks a made-up record against "${e.name}".`);
+        say(`Made-up test action for ${e.app ?? "a demo app"} (only checked, never run): ${Object.entries(e.state).map(([k, x]) => `${k} = ${x}`).join(", ")}`);
+        if (r.json.allowed) {
+            say(`\nClaros let it through (check ${r.json.check_id}). It should have been stopped by rule ${e.guardrail_id}; tell the Claros team.`);
+            return 1;
+        }
+        say(`\nClaros stopped it in ${ms} ms (Work Map "${e.name}", check ${r.json.check_id}):`);
+        for (const x of r.json.violations.filter((x) => x.action === "stop" || x.action === "ask")) {
+            say(`\n  Rule: ${x.rule}`);
+            if (x.quote)
+                say(`  In the expert's words${x.expert ? ` (${x.expert})` : ""}: "${x.quote}"`);
+            say(`  Who to ask: ${x.who_to_ask || x.owner || x.expert || "the process owner"}`);
+        }
+        say(`\nYour agent gets this as the tool's error instead of the call going through. Nothing was sent to ${e.app ?? "any app"}.`);
+        return 0;
+    }
+    catch (err) {
+        warn(`Couldn't reach Claros at ${url} (${err.message}).`);
+        return 3;
+    }
+}
+// ---- export ----
+/** A Work Map's rules as markdown on stdout (GET /v1/maps/<id>/export): redirect it into AGENTS.md, DESIGN.md or a
+ *  skill's SKILL.md. An advisory copy: Claros still enforces the rules when an agent acts. */
+async function exportMap(v, workflow) {
+    const at = await locate(v);
+    if (!at)
+        return 3;
+    if (!at.key) {
+        warn(`No key: run ${NAME} init, or set CLAROS_KEY.`);
+        return 2;
+    }
+    try {
+        const r = await fetch(`${at.url}/v1/maps/${encodeURIComponent(workflow)}/export?format=${v.format ?? "agents"}`, { headers: { authorization: `Bearer ${at.key}` }, signal: AbortSignal.timeout(10_000) });
+        if (r.status === 404) {
+            warn(`No Work Map "${workflow}" in this workspace.`);
+            return 1;
+        }
+        if (!r.ok) {
+            warn(`Claros answered HTTP ${r.status}${r.status === 401 || r.status === 403 ? ` for key ${keyId(at.key)}` : ""}.`);
+            return 3;
+        }
+        process.stdout.write(await r.text());
+        return 0;
+    }
+    catch (err) {
+        warn(`Couldn't reach Claros at ${at.url} (${err.message}).`);
+        return 3;
+    }
+}
+// ---- override: "this check got a rule wrong, because …" → the rule's expert (POST /v1/checks/{id}/override) ----
+const VERDICTS = ["wrong_stop", "wrong_nudge", "missed", "right"];
+async function override(v, checkId) {
+    const at = await locate(v);
+    if (!at)
+        return 3;
+    if (!at.key) {
+        warn(`No key: run ${NAME} init, or set CLAROS_KEY.`);
+        return 2;
+    }
+    try {
+        const { status, json } = await api(at.url, at.key, `/v1/checks/${encodeURIComponent(checkId)}/override`, { verdict: v.verdict ?? "wrong_stop", rule_id: v.rule ?? null, reason: v.reason ?? "" });
+        if (status === 200) {
+            say(`Sent to the rule's expert (${json.override.id}). The rule stays as it is until they confirm a change.`);
+            return 0;
+        }
+        const d = json?.detail;
+        warn(status === 404 ? `No check "${checkId}" in this workspace.`
+            : status === 422 ? `Not sent: ${Array.isArray(d?.invalid) ? d.invalid.join("; ") : "check the arguments"}.`
+                : `Claros answered HTTP ${status}${status === 401 || status === 403 ? ` for key ${keyId(at.key)}` : ""}.`);
+        return status === 422 || status === 404 ? 1 : 3;
+    }
+    catch (err) {
+        warn(`Couldn't reach Claros at ${at.url} (${err.message}).`);
+        return 3;
+    }
+}
+// ---- status ----
+async function status(v, project) {
+    const at = await locate(v);
+    if (!at)
+        return 3;
+    const { url, key } = at;
+    const up = await fetch(url + "/healthz", { signal: AbortSignal.timeout(10_000) }).then((r) => r.ok, () => false);
+    const ks = key ? await keyStatus(url, key) : "not set (run init)";
+    const ws = ks === "valid" ? (await whoami(url, key))?.name ?? (loadConfig().key === key ? loadConfig().workspace?.name : null) : null;
+    say(`Claros  ${url}  ${up ? "reachable" : "unreachable"}  key ${key ? keyId(key) + " " : ""}${ks}${ws ? `  workspace "${ws}"` : ""}`);
+    for (const f of detect(project)) {
+        say(`\n${f.client}  ${tilde(f.path)}${f.error ? `  couldn't read it (${f.error})` : ""}`);
+        for (const s of f.servers) {
+            say(`  ${(s.name + where(s)).padEnd(24)} ${s.ours ? "Claros MCP server" : s.guarded ? "guarded"
+                : s.gap ? `remote, ${s.gap}` : s.remote ? "remote, not guarded" : "not guarded"}`);
+        }
+    }
+    return !key ? 2 : up && ks === "valid" ? 0 : 3;
+}
+// ---- undo ----
+/** Unwraps every guarded server and removes our Claros entry in place; the rest of the file stays. */
+function unwrapAll(f) {
+    let n = 0;
+    for (const s of f.servers.filter((x) => x.guarded)) {
+        f.text = unwrapServer(f, s);
+        load(f);
+        n++;
+    }
+    for (const s of f.servers.filter((x) => x.ours)) {
+        f.text = removeEntry(f, s);
+        load(f);
+    }
+    return n;
+}
+async function undo(v, project) {
+    const scope = v.all ? runs() : runs().slice(-1);
+    if (!scope.length && !v.all) {
+        say(`Nothing to undo: no backups from ${NAME} init.`);
+        return 0;
+    }
+    const chains = new Map();
+    for (const r of scope)
+        for (const b of r.files)
+            chains.set(b.path, [...(chains.get(b.path) ?? []), { ...b, run: r.dir }]);
+    const safety = newRun("-undo.undone"); // what undo itself overwrites is backed up too
+    const byPath = new Map(detect(project).map((f) => [f.path, f]));
+    for (const [path, chain] of chains) {
+        if (!existsSync(path)) {
+            say(`${tilde(path)}: gone; nothing to undo`);
+            continue;
+        }
+        const cur = readFileSync(path, "utf8");
+        const same = sha(cur) === chain.at(-1).after && chain.every((b, i) => !i || b.before === chain[i - 1].after);
+        if (same) {
+            commit(safety, path, cur, readFileSync(chain[0].backup, "utf8"));
+            say(`${tilde(path)}: restored from the backup taken before init (unchanged since)`);
+        }
+        else {
+            const f = byPath.get(path) ?? detect(project).find((x) => x.path === path);
+            if (!f || f.error) {
+                warn(`${tilde(path)}: changed since init and couldn't be read (${f?.error ?? "unknown format"}); backup: ${chain[0].backup}`);
+                continue;
+            }
+            const n = unwrapAll(f);
+            if (f.text !== cur)
+                commit(safety, path, cur, f.text);
+            say(`${tilde(path)}: changed since init, so unwrapped ${n} server(s) in place and kept the other edits`);
+        }
+        byPath.delete(path);
+    }
+    if (v.all) {
+        for (const f of byPath.values()) {
+            if (f.error)
+                continue;
+            const cur = f.text, n = unwrapAll(f);
+            if (f.text !== cur) {
+                commit(safety, f.path, cur, f.text);
+                say(`${tilde(f.path)}: unwrapped ${n} server(s) in place`);
+            }
+        }
+    }
+    for (const r of scope)
+        renameSync(r.dir, r.dir + ".undone");
+    say(`Done. Restart your agent clients to load the change.${safety.files.length ? ` What undo replaced is in ${tilde(safety.dir)}.` : ""}`);
+    return 0;
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "getclaros",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Claros guard: checks an agent's MCP tool calls against your experts' rules before they run",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "getclaros": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test test/*.test.mjs",
+    "smoke": "tsc && node scripts/smoke.mjs && node scripts/smoke-init.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "jsonc-parser": "3.3.1"
+  }
+}