metergraph-cli 0.2.1 → 0.2.3

package/src/setup-interactive.js

@@ -0,0 +1,341 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+import { resolveProject } from "./auth-binding.js";
+import { runDoctor } from "./doctor.js";
+import { classifyEnvironment, handoffPages, shellArg } from "./environment.js";
+import { prerequisitesFor } from "./setup-deployment.js";
+import { readSetupState } from "./setup-state.js";
+
+// Setup asks for what it is missing only when a person is at a terminal: no
+// --json, stdin and stdout both terminals, and not CI. An agent or a script
+// never gets a question, so nothing waits on input that will never come; it
+// keeps the flag errors and the next_action contract. The answers become the
+// same flags a script would pass, and the full command is printed so it can
+// be rerun without questions.
+
+// The setup parse failures a question can answer. Any other failure, such as
+// an invalid value or two conflicting flags, is reported as it is.
+export const ASKABLE = new Set([
+  "missing_runtime", "non_hosted_origin_required", "non_hosted_workspace_required", "client_required",
+]);
+
+export const LOCAL_BUNDLE_ORIGIN = "http://localhost:8080";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PROBE_TIMEOUT_MS = 1500;
+
+const DEPLOYMENTS = [
+  ["managed", "Metergraph cloud (app.metergraph.dev)"],
+  ["customer-local", "The Metergraph bundle running on this machine"],
+  ["byoc", "Your company's Metergraph installation on AWS"],
+  ["oss", "The open source Metergraph server"],
+];
+const CLIENTS = [
+  ["claude", "Claude Code"],
+  ["codex", "Codex"],
+  ["cursor", "Cursor"],
+  [null, "None (skip installing the skill)"],
+];
+const URL_QUESTIONS = {
+  "customer-local": "Address of the bundle",
+  byoc: "HTTPS address of the installation",
+  oss: "Address of the server",
+};
+const WORKSPACE_QUESTIONS = {
+  "customer-local": "Workspace ID (./bin/status in the bundle directory prints it)",
+  byoc: "Workspace ID (shown on the installation's Settings page)",
+  oss: "Workspace ID",
+};
+
+export function canAsk(argv, { stdin, stdout, env = process.env }) {
+  return !argv.includes("--json") && Boolean(stdin?.isTTY) && Boolean(stdout?.isTTY) && !env.CI;
+}
+
+// Questions on the terminal. ask resolves with the trimmed answer, or null
+// once the person presses Ctrl-C or Ctrl-D, after which every ask is null.
+export function terminalPrompter(stdin, stdout) {
+  const lines = createInterface({ input: stdin, output: stdout, terminal: true });
+  const stop = new AbortController();
+  let closed = false;
+  lines.on("SIGINT", () => stop.abort());
+  lines.on("close", () => {
+    closed = true;
+    stop.abort();
+  });
+  return {
+    async ask(question) {
+      if (stop.signal.aborted) return null;
+      try {
+        return (await lines.question(question, { signal: stop.signal })).trim();
+      } catch {
+        return null;
+      }
+    },
+    close() {
+      if (!closed) lines.close();
+    },
+  };
+}
+
+// Resolves with argv plus the flags the answers stand for, or null when the
+// person cancelled. Flags already given are never asked for or changed.
+export async function fillSetupArgv(argv, {
+  ask, say, probe = probeLocalBundle, savedProfile = savedSetupProfile, remote = classifyEnvironment().remote,
+}) {
+  const has = (flag) => argv.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+  const added = [];
+  // A person at a terminal runs setup for a coding agent on this machine.
+  // Over SSH or in a cloud workspace, setup itself still hands off.
+  if (!has("--runtime")) added.push("--runtime", "local");
+
+  let deployment = valueOf(argv, "--deployment");
+  // A rerun in a project set up before resumes that route without asking.
+  if (deployment === undefined && savedProfile(valueOf(argv, "--project")) === null) {
+    // A remote shell sends no request before setup hands it off to the
+    // person's own machine, and its localhost is not that machine anyway.
+    const found = remote ? false : await probe(LOCAL_BUNDLE_ORIGIN);
+    if (found) say(`Found a Metergraph bundle at ${LOCAL_BUNDLE_ORIGIN}.`);
+    deployment = await choose(ask, say, "Where is Metergraph running?", DEPLOYMENTS,
+      found ? "customer-local" : "managed");
+    if (deployment === undefined) return null;
+    if (deployment !== "managed") added.push("--deployment", deployment);
+  }
+
+  if (deployment !== undefined && deployment !== "managed") {
+    if (!has("--url")) {
+      const url = await askFor(ask, say, URL_QUESTIONS[deployment], {
+        fallback: deployment === "customer-local" ? LOCAL_BUNDLE_ORIGIN : null,
+        valid: (value) => /^https?:\/\/\S+$/.test(value),
+        retry: "Enter an address that starts with http:// or https://.",
+      });
+      if (url === null) return null;
+      added.push("--url", url);
+    }
+    if (!has("--workspace")) {
+      const workspace = await askFor(ask, say, WORKSPACE_QUESTIONS[deployment], {
+        valid: (value) => UUID.test(value),
+        retry: "A workspace ID looks like 11111111-1111-4111-8111-111111111111.",
+      });
+      if (workspace === null) return null;
+      added.push("--workspace", workspace.toLowerCase());
+    }
+    if (deployment === "oss" && !has("--agent-token-file")) {
+      const file = await askFor(ask, say, "Absolute path to a private file holding one MG_AGENT_TOKENS value", {
+        valid: (value) => path.isAbsolute(value),
+        retry: "Enter an absolute path, for example /home/me/.config/metergraph/oss-agent-token.",
+      });
+      if (file === null) return null;
+      added.push("--agent-token-file", file);
+    }
+    if (!has("--confirm-prerequisites")) {
+      say("", "Setup connects to an installation that is already running. It needs these done first:");
+      // Except on the open source server, setup signs in for its own
+      // Metadata access, so that one is not the person's to confirm.
+      for (const { name, guide } of prerequisitesFor(deployment)) {
+        if (name !== "metadata_agent_credential" || deployment === "oss") say(`  - ${guide}`);
+      }
+      const done = await yesNo(ask, "Are they all done? [y/N] ");
+      if (done === null) return null;
+      // Without it, setup reports the first pending prerequisite.
+      if (done) added.push("--confirm-prerequisites");
+    }
+  }
+
+  if (!has("--client") && !has("--skip-skill")) {
+    const client = await choose(ask, say, "Install the Metergraph skill for which coding agent?", CLIENTS, "claude");
+    if (client === undefined) return null;
+    if (client === null) added.push("--skip-skill");
+    else added.push("--client", client);
+  }
+  return [...argv, ...added];
+}
+
+export function commandLine(argv) {
+  return ["metergraph", ...argv.map(shellArg)].join(" ");
+}
+
+function valueOf(argv, flag) {
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === flag) return argv[index + 1];
+    if (argv[index].startsWith(`${flag}=`)) return argv[index].slice(flag.length + 1);
+  }
+  return undefined;
+}
+
+// A numbered menu. Resolves with the chosen value, or undefined on cancel
+// (null is a valid choice: no client).
+async function choose(ask, say, question, options, fallback) {
+  say("", question);
+  options.forEach(([, label], index) => say(`  ${index + 1}) ${label}`));
+  const fallbackIndex = options.findIndex(([value]) => value === fallback) + 1;
+  for (;;) {
+    const answer = await ask(`Choose 1-${options.length} [${fallbackIndex}]: `);
+    if (answer === null) return undefined;
+    const index = answer === "" ? fallbackIndex : Number(answer);
+    if (Number.isInteger(index) && index >= 1 && index <= options.length) return options[index - 1][0];
+    say(`Enter a number from 1 to ${options.length}.`);
+  }
+}
+
+async function askFor(ask, say, question, { fallback = null, valid, retry }) {
+  for (;;) {
+    const answer = await ask(fallback === null ? `${question}: ` : `${question} [${fallback}]: `);
+    if (answer === null) return null;
+    const value = answer === "" ? fallback : answer;
+    if (value !== null && valid(value)) return value;
+    say(retry);
+  }
+}
+
+async function yesNo(ask, question) {
+  const answer = await ask(question);
+  if (answer === null) return null;
+  return ["y", "yes"].includes(answer.toLowerCase());
+}
+
+async function probeLocalBundle(origin) {
+  try {
+    const { report } = await runDoctor({ origin, timeoutMs: PROBE_TIMEOUT_MS });
+    return report?.deployment_profile === "local";
+  } catch {
+    return false;
+  }
+}
+
+function savedSetupProfile(project) {
+  try {
+    return readSetupState(resolveProject(project))?.value.deployment_profile ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// --- Access for the coding agent on the customer-local bundle ---------------
+
+// Setup signs the agent in with Metadata access only. On the customer-local
+// bundle, bin/agent-key issues a broader key without a sign in and writes it
+// to a private file, never printing it. The command text is fixed here, not
+// taken from the service, so an origin cannot choose what a person is asked
+// to run.
+export const AGENT_KEY_FILE = "~/.config/metergraph/agent.env";
+const AGENT_KEY_GRANTS = [
+  "--role", "debug", "--allow-evaluation-writes", "--allow-evaluation-previews", "--allow-analysis-starts",
+];
+export const AGENT_KEY_COMMAND = ["./bin/agent-key", "create", "--write-to", AGENT_KEY_FILE, ...AGENT_KEY_GRANTS].join(" ");
+
+export function agentAccessOffer(origin) {
+  return {
+    role: "metadata",
+    offer: {
+      kind: "bundle_agent_key",
+      run_in: "bundle_directory",
+      command: AGENT_KEY_COMMAND,
+      requires_person_approval: true,
+      keys_page_url: handoffPages(origin).keys_url,
+      message: "The agent has Metadata access. To let it write evaluations and start analyses, " +
+        "ask the person which access they want, then they run this command in the bundle directory, " +
+        "or the agent runs it with --yes after they agree. The Debug role reads captured prompts and " +
+        "responses, and analysis starts send captured content to the person's model provider and spend " +
+        "money. The command writes the key to the named private file and never prints it. A bundle " +
+        "without bin/agent-key uses the Keys page instead.",
+    },
+  };
+}
+
+// After a customer-local setup at a terminal: offer to run bin/agent-key
+// now. It shows what it grants and asks for its own confirmation. Setup runs
+// in the person's project, which may be a repository they did not write, so
+// nothing there is ever a default: the person types the bundle directory, it
+// must look like a started bundle, and setup names the exact program and asks
+// before running it.
+const BUNDLE_MARKERS = [["bin", "start"], ["docker-compose.yml"], ["metergraph-byoc-release.json"]];
+
+export async function offerAgentAccess({ client, origin, prompter, say, run = runInherited, platform = process.platform }) {
+  say("", "Your coding agent has Metadata access. It can also write evaluations and start analyses.",
+    "That reads captured prompts and responses, and an analysis sends captured content to your model",
+    "provider and spends money on your account.");
+  if (platform === "win32") {
+    // The bundle's commands are shell scripts that run inside WSL, and
+    // Windows has no owner-only file mode to check, so say what to run there.
+    say(`To allow it, run this in the bundle directory inside WSL: ${AGENT_KEY_COMMAND}`);
+    return;
+  }
+  const wanted = await yesNo(prompter.ask, "Give it that access now? [y/N] ");
+  if (!wanted) {
+    say(`Later, run this in the bundle directory: ${AGENT_KEY_COMMAND}`);
+    return;
+  }
+  const answer = await askFor(prompter.ask, say, "Bundle directory (the one you ran bin/start in)", {
+    valid: (value) => BUNDLE_MARKERS.every((parts) => fs.existsSync(path.join(expandHome(value), ...parts))),
+    retry: "That is not a started bundle (it needs bin/start, docker-compose.yml and the release manifest).",
+  });
+  if (answer === null) return;
+  const bundle = fs.realpathSync(expandHome(answer));
+  const command = path.join(bundle, "bin", "agent-key");
+  if (!fs.existsSync(command)) {
+    say("This bundle has no bin/agent-key. Create the key on the Keys page instead:",
+      `  ${handoffPages(origin).keys_url}`);
+    return;
+  }
+  const problem = untrustedProgram(command);
+  if (problem !== null) {
+    say(`Not running ${command}: ${problem}.`);
+    return;
+  }
+  const confirmed = await yesNo(prompter.ask, `Run ${command}? [y/N] `);
+  if (!confirmed) {
+    say(`Later, run this in the bundle directory: ${AGENT_KEY_COMMAND}`);
+    return;
+  }
+  prompter.close();
+  const file = path.join(os.homedir(), ".config", "metergraph", "agent.env");
+  const code = await run(command, ["create", "--write-to", file, ...AGENT_KEY_GRANTS], bundle);
+  if (code !== 0) {
+    say(`bin/agent-key did not finish. Run it again from ${bundle}: ${AGENT_KEY_COMMAND}`);
+    return;
+  }
+  say("", ...connectSteps(client, origin, file));
+}
+
+// Only a regular file the person owns and nobody else can change is run.
+function untrustedProgram(command) {
+  const info = fs.lstatSync(command);
+  if (!info.isFile()) return "it is not a regular file";
+  if (typeof process.getuid === "function" && info.uid !== process.getuid()) return "it is owned by another user";
+  if (info.mode & 0o022) return "other users can change it";
+  return null;
+}
+
+// How the person connects their agent to the key: load the file where the
+// agent starts, and name the variable (never the token) in its MCP settings.
+export function connectSteps(client, origin, file) {
+  const mcp = `${origin}/v1/agent/mcp`;
+  const steps = [`Load the key in the shell that starts your agent: . ${shellArg(file)}`];
+  if (client === "claude") {
+    steps.push("Add the MCP server to Claude Code (it saves the variable name, not the token):",
+      `  claude mcp add-json --scope user metergraph '${JSON.stringify({
+        type: "http", url: mcp, headers: { Authorization: "Bearer ${METERGRAPH_AGENT_TOKEN}" } })}'`);
+  } else if (client === "codex") {
+    steps.push("Add the MCP server to Codex (it saves the variable name, not the token):",
+      `  codex mcp add metergraph --url ${mcp} --bearer-token-env-var METERGRAPH_AGENT_TOKEN`);
+  } else {
+    steps.push("Add the MCP server as the bundle README's 'Let your coding agent run analyses' section shows.");
+  }
+  steps.push("Then restart the agent.");
+  return steps;
+}
+
+function expandHome(value) {
+  return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(1)) : value;
+}
+
+function runInherited(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}

package/src/setup-refusal.js

@@ -0,0 +1,172 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// What the --json --no-browser background waiter is doing with an approval
+// it received, so the agent's rerun can report it instead of asking the
+// person for another approval. The waiter is the only writer: a foreground
+// run reports a refusal directly and never records one.
+//
+//   redeeming  the waiter holds an approval and is redeeming it (possibly
+//              waiting out a short Retry-After). A rerun waits for it.
+//   refused    the service refused the redemption: the rate budget until
+//              retry_at, or the workspace's key cap. A rerun reports it.
+//
+// The record names the setup family, the waiter's process and the approval
+// it came from. It holds no credential. It is a separate file, not a field of
+// setup.json, so an older CLI that validates setup.json strictly keeps
+// reading the project. Any read problem is treated as no record.
+//
+// The file lives in the project, so its content is untrusted: a record can
+// only delay setup for as long as this CLI would ever write it for. A
+// redeeming record expiring, or a refusal retrying, further out than that is
+// ignored and removed, so a crafted or committed record cannot block setup.
+const FILE = "setup-refusal.json";
+const MAX_BYTES = 1024;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const KEYS = "approval_id,expires_at,family_id,pid,reason,retry_at,schema_version,state";
+export const REFUSAL_REASONS = Object.freeze(["setup_rate_limited", "setup_key_limit"]);
+// A redeeming record outlives no waiter: redemption plus two Retry-After
+// waits takes well under this. A rate refusal is reported for at most this.
+const MAX_RECORD_MS = 10 * 60 * 1000;
+const MAX_RATE_WAIT_MS = 5 * 60 * 1000;
+
+const fileFor = (root) => path.join(root, ".metergraph", FILE);
+const isTime = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+
+function valid(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) ||
+      Object.keys(value).sort().join() !== KEYS || value.schema_version !== 2 ||
+      !UUID.test(value.family_id) || !UUID.test(value.approval_id) ||
+      !Number.isInteger(value.pid) || value.pid < 1 || !isTime(value.expires_at)) return false;
+  if (value.state === "redeeming") return value.reason === null && value.retry_at === null;
+  if (value.state === "refused") {
+    return REFUSAL_REASONS.includes(value.reason) &&
+      (value.reason === "setup_key_limit" ? value.retry_at === null : isTime(value.retry_at));
+  }
+  return false;
+}
+
+function read(root) {
+  const file = fileFor(root);
+  let fd;
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES) return null;
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    const opened = fs.fstatSync(fd);
+    if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size > MAX_BYTES) return null;
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fs.readFileSync(fd)));
+    return valid(value) ? value : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// Best effort: a record that cannot be written only means a rerun asks for a
+// new approval, as it did before records existed.
+function write(root, value) {
+  if (!valid(value)) return false;
+  const dir = path.join(root, ".metergraph");
+  const temp = path.join(dir, `.refusal.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return false;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try { fs.writeFileSync(fd, `${JSON.stringify(value)}\n`); }
+    finally { fs.closeSync(fd); }
+    fs.renameSync(temp, fileFor(root));
+    return true;
+  } catch {
+    try { fs.unlinkSync(temp); } catch { /* no temp */ }
+    return false;
+  }
+}
+
+export function clearSetupRefusal(root) {
+  try {
+    const stat = fs.lstatSync(fileFor(root));
+    if (stat.isFile() || stat.isSymbolicLink()) fs.unlinkSync(fileFor(root));
+  } catch { /* nothing to clear */ }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+// The waiter's handle on one approval it received. Every method is best
+// effort and only ever touches this approval's own record.
+export function waiterRecord(root, familyId, now = Date.now) {
+  const approvalId = randomUUID();
+  const base = () => ({ schema_version: 2, family_id: familyId, approval_id: approvalId, pid: process.pid,
+    expires_at: new Date(now() + MAX_RECORD_MS).toISOString() });
+  return {
+    // Early, as soon as an approval arrives: never replaces another waiter
+    // that is still alive. With force, once this waiter has won the setup
+    // state for its redemption, it takes the record over.
+    redeeming: ({ force = false } = {}) => {
+      const current = read(root);
+      if (!force && current?.state === "redeeming" && current.approval_id !== approvalId &&
+          current.pid !== process.pid && alive(current.pid) && Date.parse(current.expires_at) > now()) return false;
+      return write(root, { ...base(), state: "redeeming", reason: null, retry_at: null });
+    },
+    refused: (reason, retryAfterSeconds = null) => write(root, { ...base(), state: "refused", reason,
+      retry_at: reason === "setup_rate_limited"
+        ? new Date(now() + Math.min((retryAfterSeconds ?? 60) * 1000, MAX_RATE_WAIT_MS)).toISOString()
+        : null }),
+    // Any other outcome: drop a redeeming record this waiter left behind.
+    settle: () => {
+      const record = read(root);
+      if (record?.approval_id === approvalId && record.state === "redeeming") clearSetupRefusal(root);
+    },
+  };
+}
+
+// What a run should report before asking for an approval, or null to
+// proceed. familyId and delivered describe the saved setup state; a refusal
+// for another family, or for one already delivered, no longer applies.
+export function pendingRefusal(root, { familyId, delivered }, now = Date.now()) {
+  const record = read(root);
+  if (record === null) return null;
+  const expires = Date.parse(record.expires_at);
+  const retry = record.retry_at === null ? null : Date.parse(record.retry_at);
+  if (expires <= now || expires > now + MAX_RECORD_MS || (retry !== null && retry > now + MAX_RATE_WAIT_MS)) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  // A delivered family has nothing pending, whatever the record says.
+  if (delivered) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  if (record.state === "redeeming") {
+    if (record.pid === process.pid || !alive(record.pid)) {
+      clearSetupRefusal(root);
+      return null;
+    }
+    // A live waiter matters only for the saved family, or before any state
+    // is saved (a combined sign in writes it after the approval). A record
+    // for another family does not block this setup.
+    if (familyId !== null && record.family_id !== familyId) return null;
+    return { reason: "setup_in_progress", retryAfter: 5 };
+  }
+  if (record.family_id !== familyId) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  if (record.reason === "setup_rate_limited") {
+    const remaining = Math.ceil((Date.parse(record.retry_at) - now) / 1000);
+    if (remaining > 0) return { reason: record.reason, retryAfter: remaining };
+    clearSetupRefusal(root);
+    return null;
+  }
+  clearSetupRefusal(root);
+  return { reason: record.reason, retryAfter: null };
+}

package/src/setup-state.js

@@ -101,10 +101,12 @@ export function readSetupState(root) {
   }
 }
 
-export function newSetupState(origin, workspaceId, profile, client) {
+// familyId is given when the family was already named in an approval, as a
+// combined sign-in and ingest approval does; otherwise a new one is chosen.
+export function newSetupState(origin, workspaceId, profile, client, familyId = randomUUID()) {
   return withSetupState({ schema_version: 1, origin, workspace_id: workspaceId,
     deployment_profile: profile, selected_client: client, skill_status: client === null ? "skipped" : "pending",
-    family_id: randomUUID(), key_id: null, phase: "unsubmitted" });
+    family_id: familyId, key_id: null, phase: "unsubmitted" });
 }
 
 // Compare-and-swap under a project-local exclusive lock. A concurrent setup