metergraph-cli 0.1.0 → 0.2.0-preview.0

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "90f7d8d78a5b0b7a57436f194222f0c73310b0b04201c297c8fbf0b00ad6bb3f",
-  "size": 9149,
-  "revision": "sha256-90f7d8d78a5b"
+  "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891",
+  "size": 10426,
+  "revision": "sha256-57b920677adf"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "metergraph-cli",
-  "version": "0.1.0",
-  "description": "Preview Metergraph command line tool with a read-only connection probe and a project skill installer",
+  "version": "0.2.0-preview.0",
+  "description": "Preview Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {
     "metergraph": "bin/metergraph.js"

package/src/args.js

@@ -3,27 +3,96 @@ import {
   DEFAULT_TIMEOUT_MS,
   HANDOFF_SKILL_CLIENTS,
   HANDOFF_SKILL_RUNTIMES,
+  HANDOFF_LOGIN_RUNTIMES,
+  LOGIN_DEFAULT_TIMEOUT_MS,
+  LOGIN_MAX_TIMEOUT_MS,
+  LOGIN_MIN_TIMEOUT_MS,
+  LOGIN_RUNTIMES,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
+  READ_DEFAULT_DAYS,
+  READ_DEFAULT_LIMIT,
+  READ_DEFAULT_TIMEOUT_MS,
+  READ_MAX_DAYS,
+  READ_MAX_LIMIT,
+  READ_MAX_TIMEOUT_MS,
+  READ_MIN_TIMEOUT_MS,
   SKILL_CLIENTS,
   SKILL_RUNTIMES,
+  TRACES_DEFAULT_LIMIT,
 } from "./constants.js";
 import { parseOrigin } from "./origin.js";
+import { isCursor, isSafeFilter } from "./read-contract.js";
 
-const COMMANDS = new Set(["doctor", "help", "skill"]);
-const HELP_TOPICS = new Set(["doctor", "skill"]);
+export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
+const COMMANDS = new Set(["doctor", "help", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["doctor", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
 const SKILL_ACTIONS = new Set(["install", "update"]);
+const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
 const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
+  login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
+  setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file"]),
+  logout: new Set(["--project", "--config-dir"]),
+  status: new Set(READ_BASE),
+  context: new Set(READ_BASE),
+  capabilities: new Set(READ_BASE),
+  usage: new Set([...READ_BASE, "--days", "--limit"]),
+  routes: new Set([...READ_BASE, "--limit"]),
+  traces: new Set([...READ_BASE, "--days", "--limit", "--route", "--status", "--cursor"]),
+  verify: new Set([...READ_BASE, "--trace-id", "--request-id", "--since", "--until", "--source", "--days", "--poll-ms", "--max-attempts"]),
 };
+// Requests the read commands recognize and refuse, so a script gets an
+// explicit unsupported result instead of an unknown argument or, worse, a
+// broader query than it asked for. Nothing is sent for them.
+const REFUSED = {
+  "--environment": { value: true, reason: "environment_selector_unsupported" },
+  "--workload": { value: true, reason: "workload_filter_unsupported" },
+  "--since": { value: true, reason: "time_range_unsupported" },
+  "--until": { value: true, reason: "time_range_unsupported" },
+  "--sql": { value: true, reason: "query_unsupported" },
+  "--query": { value: true, reason: "query_unsupported" },
+  "--content": { value: false, reason: "content_access_unsupported" },
+  "--include-content": { value: false, reason: "content_access_unsupported" },
+  "--debug": { value: false, reason: "content_access_unsupported" },
+  "--replay": { value: false, reason: "content_access_unsupported" },
+};
+const REFUSED_MESSAGES = {
+  environment_selector_unsupported:
+    "--environment is not supported: the service's agent access contract has no environment selector, " +
+    "so the CLI never sends one. Results cover the bound workspace. No request was made.",
+  workload_filter_unsupported:
+    "--workload is not supported by this CLI version: it cannot verify from the returned traces that a " +
+    "workload filter was applied, so it never sends one. No request was made.",
+  time_range_unsupported:
+    "--since and --until are not supported. Use --days N (1 to 90) for a window relative to now. No request was made.",
+  query_unsupported:
+    "Free-form queries are not supported. Use the fixed options of this command. No request was made.",
+  content_access_unsupported:
+    "Read commands return Metadata only. They never read retained content, debug data or replays. No request was made.",
+};
+// Options that take no value.
+const FLAGS = {
+  login: new Set(["--signup", "--no-browser", "--reconnect"]),
+  setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites"]),
+  verify: new Set(["--open", "--no-browser"]),
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // Parses argv into one of:
 //   { ok: true, command: "help", topic, json }
 //   { ok: true, command: "version", json }
 //   { ok: true, command: "doctor", origin, timeoutMs, json }
 //   { ok: true, command: "skill", action, client, runtime, project, json }
-//   { ok: false, command, json, code, message }
+//   { ok: true, command: "login", runtime, origin, workspace, project,
+//     configDir, timeoutMs, signup, noBrowser, reconnect, json }
+//   { ok: true, command: "logout", project, configDir, json }
+//   { ok: true, command: one of READ_COMMANDS, project, configDir, timeoutMs,
+//     days, limit, route, status, cursor, json }
+//   { ok: false, command, json, code, message, outcome }
+// outcome is invalid_input, or unsupported for a recognized request the read
+// commands refuse (such as --environment).
 // Error messages are fixed strings. They never contain an argument value,
 // because a mistyped argument can be a credential.
 export function parseArgs(argv) {
@@ -39,13 +108,15 @@ export function parseArgs(argv) {
   let topic = null;
   let version = false;
   const values = {};
+  const flags = new Set();
 
-  const fail = (code, message) => ({
+  const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
     command: command === "skill" && action !== null ? `skill ${action}` : command ?? (version ? "version" : null),
     json,
     code,
     message,
+    outcome,
   });
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -71,9 +142,24 @@ export function parseArgs(argv) {
       continue;
     }
 
-    if (command === "doctor" || command === "skill") {
+    if (READ_COMMANDS.includes(command)) {
+      const equals = arg.indexOf("=");
+      const name = equals === -1 ? arg : arg.slice(0, equals);
+      if (Object.hasOwn(REFUSED, name)) {
+        const { reason } = REFUSED[name];
+        return fail(reason, REFUSED_MESSAGES[reason], "unsupported");
+      }
+    }
+
+    if (Object.hasOwn(OPTIONS, command ?? "")) {
       const equals = arg.indexOf("=");
       const name = equals === -1 ? arg : arg.slice(0, equals);
+      if (FLAGS[command]?.has(name)) {
+        if (equals !== -1) return fail("unexpected_value", `${name} does not take a value.`);
+        if (flags.has(name)) return fail("duplicate_option", `${name} may be given only once.`);
+        flags.add(name);
+        continue;
+      }
       if (OPTIONS[command].has(name)) {
         let value;
         if (equals === -1) {
@@ -116,18 +202,19 @@ export function parseArgs(argv) {
     return { ok: true, command: "help", topic, json };
   }
   if (command === "skill") return parseSkill(action, values, json, fail);
-
-  const rawUrl = values["--url"];
-  const origin = rawUrl === undefined ? DEFAULT_ORIGIN : parseOrigin(rawUrl);
-  if (origin === null) {
-    return fail(
-      "invalid_url",
-      "--url must be a bare https origin such as https://metergraph.example.com, " +
-        "or an http origin on localhost, 127.0.0.1 or [::1]. " +
-        "Credentials, paths, queries and fragments are not accepted.",
-    );
+  if (command === "login") return parseLogin(values, flags, json, fail);
+  if (command === "setup") return parseSetup(values, flags, json, fail);
+  if (command === "verify") return parseVerify(values, flags, json, fail);
+  if (READ_COMMANDS.includes(command)) return parseRead(command, values, json, fail);
+  if (command === "logout") {
+    const paths = parsePaths(values, fail);
+    if (!paths.ok) return paths;
+    return { ok: true, command: "logout", project: paths.project, configDir: paths.configDir, json };
   }
 
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+
   const rawTimeout = values["--timeout-ms"];
   const timeoutMs =
     rawTimeout === undefined ? DEFAULT_TIMEOUT_MS : parseTimeout(rawTimeout);
@@ -141,6 +228,39 @@ export function parseArgs(argv) {
   return { ok: true, command: "doctor", origin, timeoutMs, json };
 }
 
+function parseVerify(values, flags, json, fail) {
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const traceId = values["--trace-id"] ?? null;
+  const requestId = values["--request-id"] ?? null;
+  if ((traceId === null) === (requestId === null) ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(traceId ?? requestId)) {
+    return fail("invalid_trace_identity", "Provide exactly one --trace-id or --request-id (1 to 200 safe characters).");
+  }
+  const since = values["--since"];
+  const until = values["--until"];
+  const validTime = (value) => typeof value === "string" && value.length <= 40 &&
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value));
+  if (!validTime(since) || !validTime(until) || Date.parse(since) > Date.parse(until) || Date.parse(until) > Date.now()) {
+    return fail("invalid_invocation_window", "--since and --until must bound a past invocation using ISO 8601 timestamps.");
+  }
+  const source = values["--source"] ?? "unspecified";
+  if (!["application", "synthetic", "demo", "import", "unspecified"].includes(source)) {
+    return fail("invalid_source", "--source must be application, synthetic, demo, import or unspecified.");
+  }
+  const days = values["--days"] === undefined ? undefined : parseBounded(values["--days"], 1, 90);
+  if (days === null) return fail("invalid_days", "--days must be a whole number from 1 to 90.");
+  const timeoutMs = values["--timeout-ms"] === undefined ? 30000 : parseTimeout(values["--timeout-ms"], 100, 60000);
+  if (timeoutMs === null) return fail("invalid_timeout", "--timeout-ms must be a whole number from 100 to 60000.");
+  const pollIntervalMs = values["--poll-ms"] === undefined ? 1000 : parseTimeout(values["--poll-ms"], 100, 10000);
+  if (pollIntervalMs === null) return fail("invalid_poll_interval", "--poll-ms must be a whole number from 100 to 10000.");
+  const maxAttempts = values["--max-attempts"] === undefined ? 30 : parseBounded(values["--max-attempts"], 1, 60);
+  if (maxAttempts === null) return fail("invalid_max_attempts", "--max-attempts must be a whole number from 1 to 60.");
+  return { ok: true, command: "verify", project: paths.project, configDir: paths.configDir,
+    traceId, requestId, since, until, source, days, timeoutMs, pollIntervalMs, maxAttempts,
+    open: flags.has("--open"), noBrowser: flags.has("--no-browser"), json };
+}
+
 // Client and runtime are required, so a script states where the skill is
 // used instead of the CLI guessing. Values for clients and runtimes that
 // cannot use project skill files are accepted here and handed off later.
@@ -172,9 +292,195 @@ function parseSkill(action, values, json, fail) {
   return { ok: true, command: "skill", action, client, runtime, project: project ?? null, json };
 }
 
-function parseTimeout(raw) {
+const INVALID_URL =
+  "--url must be a bare https origin such as https://metergraph.example.com, " +
+  "or an http origin on localhost, 127.0.0.1 or [::1]. " +
+  "Credentials, paths, queries and fragments are not accepted.";
+
+function parseUrlOption(values) {
+  const raw = values["--url"];
+  return raw === undefined ? DEFAULT_ORIGIN : parseOrigin(raw);
+}
+
+// The runtime is required so a script states where the browser is. Cloud
+// runtimes are accepted here and handed off later, before any request.
+function parseLogin(values, flags, json, fail) {
+  const runtime = values["--runtime"];
+  if (runtime === undefined) return fail("missing_runtime", "--runtime is required. Use local.");
+  if (!LOGIN_RUNTIMES.includes(runtime) && !HANDOFF_LOGIN_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local, cloud or cloud-no-shell.");
+  }
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs =
+    rawTimeout === undefined
+      ? LOGIN_DEFAULT_TIMEOUT_MS
+      : parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`,
+    );
+  }
+  return {
+    ok: true,
+    command: "login",
+    runtime,
+    origin,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    project: paths.project,
+    configDir: paths.configDir,
+    timeoutMs,
+    signup: flags.has("--signup"),
+    noBrowser: flags.has("--no-browser"),
+    reconnect: flags.has("--reconnect"),
+    json,
+  };
+}
+
+function parseSetup(values, flags, json, fail) {
+  const runtime = values["--runtime"];
+  if (runtime === undefined) return fail("missing_runtime", "--runtime is required. Use local.");
+  if (!LOGIN_RUNTIMES.includes(runtime) && !HANDOFF_LOGIN_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local, cloud or cloud-no-shell.");
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+  const deployment = values["--deployment"] ?? "managed";
+  if (!["managed", "customer-local", "byoc", "oss"].includes(deployment)) {
+    return fail("invalid_deployment", "--deployment must be managed, customer-local, byoc or oss.");
+  }
+  if (deployment === "managed" && (flags.has("--confirm-prerequisites") || values["--agent-token-file"] !== undefined)) {
+    return fail("managed_route_conflict", "Operator prerequisites and agent token files are only for non-hosted deployments.");
+  }
+  if (deployment !== "managed" && values["--url"] === undefined) {
+    return fail("non_hosted_origin_required", "Non-hosted setup requires an explicit --url for the installed service.");
+  }
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  if (deployment !== "managed" && rawWorkspace === undefined) {
+    return fail("non_hosted_workspace_required", "Non-hosted setup requires an explicit --workspace UUID.");
+  }
+  const agentTokenFile = values["--agent-token-file"] ?? null;
+  if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
+    return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
+  }
+  const client = values["--client"] ?? null;
+  if (client === null && !flags.has("--skip-skill")) {
+    return fail("client_required", "Choose --client codex, claude or cursor, or explicitly use --skip-skill.");
+  }
+  if (client !== null && !Object.hasOwn(SKILL_CLIENTS, client)) {
+    return fail("invalid_client", "--client must be codex, claude or cursor.");
+  }
+  if (client !== null && flags.has("--skip-skill")) {
+    return fail("client_conflict", "Use either --client or --skip-skill, not both.");
+  }
+  const envFile = values["--env-file"] ?? ".env";
+  if (envFile === "" || envFile.includes("\0")) return fail("invalid_env_file", "--env-file must name a project-relative env file.");
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs = rawTimeout === undefined ? LOGIN_DEFAULT_TIMEOUT_MS :
+    parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) return fail("invalid_timeout", `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`);
+  return { ok: true, command: "setup", runtime, origin, originExplicit: values["--url"] !== undefined,
+    deployment, confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    project: paths.project, configDir: paths.configDir, envFile, client, skipSkill: flags.has("--skip-skill"),
+    timeoutMs, noBrowser: flags.has("--no-browser"), repair: flags.has("--repair"),
+    signup: flags.has("--signup"), reconnect: flags.has("--reconnect"), json };
+}
+
+// Read commands take the project and config directory, one total timeout and,
+// where the endpoint supports them, bounded days, limit and trace filters.
+// Out of range values fail here; nothing is clamped.
+function parseRead(command, values, json, fail) {
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs =
+    rawTimeout === undefined
+      ? READ_DEFAULT_TIMEOUT_MS
+      : parseTimeout(rawTimeout, READ_MIN_TIMEOUT_MS, READ_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${READ_MIN_TIMEOUT_MS} to ${READ_MAX_TIMEOUT_MS}.`,
+    );
+  }
+  const takesDays = command === "usage" || command === "traces";
+  const takesLimit = takesDays || command === "routes";
+  let days = null;
+  if (takesDays) {
+    days = values["--days"] === undefined ? READ_DEFAULT_DAYS : parseBounded(values["--days"], 1, READ_MAX_DAYS);
+    if (days === null) return fail("invalid_days", `--days must be a whole number from 1 to ${READ_MAX_DAYS}.`);
+  }
+  let limit = null;
+  if (takesLimit) {
+    const fallback = command === "traces" ? TRACES_DEFAULT_LIMIT : READ_DEFAULT_LIMIT;
+    limit = values["--limit"] === undefined ? fallback : parseBounded(values["--limit"], 1, READ_MAX_LIMIT);
+    if (limit === null) return fail("invalid_limit", `--limit must be a whole number from 1 to ${READ_MAX_LIMIT}.`);
+  }
+  const route = values["--route"] ?? null;
+  if (route !== null && !isSafeFilter(route)) {
+    return fail("invalid_route", "--route must be 1 to 256 characters without control characters.");
+  }
+  const status = values["--status"] ?? null;
+  if (status !== null && status !== "success" && status !== "error") {
+    return fail("invalid_status", "--status must be success or error.");
+  }
+  const cursor = values["--cursor"] ?? null;
+  if (cursor !== null && !isCursor(cursor)) {
+    return fail(
+      "invalid_cursor",
+      "--cursor must be the next_cursor value from an earlier traces result, at most 512 printable characters.",
+    );
+  }
+  return {
+    ok: true,
+    command,
+    project: paths.project,
+    configDir: paths.configDir,
+    timeoutMs,
+    days,
+    limit,
+    route,
+    status,
+    cursor,
+    json,
+  };
+}
+
+function parseBounded(raw, min, max) {
+  if (!/^[0-9]{1,3}$/.test(raw)) return null;
+  const value = Number(raw);
+  return value < min || value > max ? null : value;
+}
+
+function parsePaths(values, fail) {
+  const project = values["--project"];
+  if (project !== undefined && (project === "" || project.includes("\0"))) {
+    return fail("invalid_project", "--project must name an existing directory.");
+  }
+  const configDir = values["--config-dir"];
+  if (configDir !== undefined && (configDir === "" || configDir.includes("\0"))) {
+    return fail("invalid_config_dir", "--config-dir must name a directory path.");
+  }
+  return { ok: true, project: project ?? null, configDir: configDir ?? null };
+}
+
+function parseTimeout(raw, min = MIN_TIMEOUT_MS, max = MAX_TIMEOUT_MS) {
   if (!/^[0-9]{1,6}$/.test(raw)) return null;
   const value = Number(raw);
-  if (value < MIN_TIMEOUT_MS || value > MAX_TIMEOUT_MS) return null;
+  if (value < min || value > max) return null;
   return value;
 }

package/src/auth-binding.js

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { Stop, isSlot } from "./auth-store.js";
+import { SUPPORTED_PROFILES } from "./constants.js";
+import { parseOrigin } from "./origin.js";
+
+// The project binding, .metergraph/project.json, names which origin,
+// workspace and profile a project is signed in to and which credential slot
+// in the user's private store holds the grant. It holds no credential, user
+// name or absolute path, so it is safe to commit. Other files in .metergraph,
+// such as skill receipts, are never touched.
+
+export const BINDING_PATH = ".metergraph/project.json";
+const DIR = ".metergraph";
+const FILE = "project.json";
+const LOCK = "project.lock";
+const MAX_BYTES = 16 * 1024;
+const KEYS = ["credential_slot", "deployment_profile", "origin", "schema_version", "workspace_id"].join();
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+
+export function resolveProject(project) {
+  try {
+    const real = fs.realpathSync(path.resolve(project ?? process.cwd()));
+    if (fs.statSync(real).isDirectory()) return real;
+  } catch {
+    // Fall through to the fixed error.
+  }
+  throw new Stop("invalid_input", "invalid_project");
+}
+
+// Returns { binding, content } or null when the project is not bound.
+export function readBinding(root) {
+  try {
+    const dir = lstatOrNull(path.join(root, DIR));
+    if (dir === null) return null;
+    if (!dir.isDirectory()) throw new Stop("conflict", "unsafe_path");
+    const content = readRegular(path.join(root, DIR, FILE));
+    if (content === null) return null;
+    const binding = parse(content);
+    if (binding === null) throw new Stop("conflict", "binding_invalid");
+    return { binding, content };
+  } catch (error) {
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "read_failed");
+  }
+}
+
+export function bindingFor({ origin, workspaceId, profile, slot }) {
+  return {
+    schema_version: 1,
+    origin,
+    workspace_id: workspaceId,
+    deployment_profile: profile,
+    credential_slot: slot,
+  };
+}
+
+// Writes binding in place of previous (the { content } readBinding saw, or
+// null). Under the project lock, the file must still be exactly previous, so
+// a concurrent change is never overwritten. A failed write leaves the
+// previous file and removes a .metergraph directory this call created.
+export function writeBinding(root, binding, previous) {
+  const content = Buffer.from(`${JSON.stringify(binding, null, 2)}\n`);
+  if (parse(content) === null) throw new Error("binding is not valid");
+  const dir = path.join(root, DIR);
+  let created = false;
+  try {
+    try {
+      fs.mkdirSync(dir);
+      created = true;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!fs.lstatSync(dir).isDirectory()) throw new Stop("conflict", "unsafe_path");
+    }
+    withProjectLock(dir, () => {
+      expectUnchanged(dir, previous);
+      replace(dir, content);
+    });
+  } catch (error) {
+    if (created) {
+      try {
+        fs.rmdirSync(dir);
+      } catch {
+        // Not empty. An empty directory is harmless.
+      }
+    }
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "binding_write_failed");
+  }
+}
+
+// Removes the binding if it is still exactly previous.
+export function removeBinding(root, previous) {
+  const dir = path.join(root, DIR);
+  try {
+    withProjectLock(dir, () => {
+      expectUnchanged(dir, previous);
+      fs.unlinkSync(path.join(dir, FILE));
+    });
+  } catch (error) {
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "binding_write_failed");
+  }
+}
+
+function withProjectLock(dir, work) {
+  const lock = path.join(dir, LOCK);
+  try {
+    fs.closeSync(fs.openSync(lock, "wx"));
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Stop("conflict", "binding_locked");
+    throw error;
+  }
+  try {
+    return work();
+  } finally {
+    try {
+      fs.unlinkSync(lock);
+    } catch {
+      // Reported by the next run as a held lock.
+    }
+  }
+}
+
+function expectUnchanged(dir, previous) {
+  const now = readRegular(path.join(dir, FILE));
+  const same = previous === null ? now === null : now !== null && now.equals(previous.content);
+  if (!same) throw new Stop("conflict", "binding_changed");
+}
+
+function replace(dir, content) {
+  const dest = path.join(dir, FILE);
+  const temp = path.join(dir, `.${FILE}.${randomBytes(6).toString("hex")}.tmp`);
+  const fd = fs.openSync(temp, "wx", 0o666);
+  try {
+    try {
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temp, dest);
+  } catch (error) {
+    try {
+      fs.unlinkSync(temp);
+    } catch {
+      // Already renamed or never created.
+    }
+    throw error;
+  }
+}
+
+// Accepts only the exact shape this CLI writes.
+function parse(content) {
+  let value;
+  try {
+    value = JSON.parse(content.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  if (Object.keys(value).sort().join() !== KEYS) return null;
+  if (value.schema_version !== 1) return null;
+  if (typeof value.origin !== "string" || parseOrigin(value.origin) !== value.origin) return null;
+  if (typeof value.workspace_id !== "string" || !UUID.test(value.workspace_id)) return null;
+  if (!SUPPORTED_PROFILES.includes(value.deployment_profile)) return null;
+  if (!isSlot(value.credential_slot)) return null;
+  return value;
+}
+
+function lstatOrNull(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function readRegular(file) {
+  const stat = lstatOrNull(file);
+  if (stat === null) return null;
+  if (!stat.isFile()) throw new Stop("conflict", "unsafe_path");
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ELOOP") throw new Stop("conflict", "unsafe_path");
+    throw error;
+  }
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile()) throw new Stop("conflict", "unsafe_path");
+    if (opened.size > MAX_BYTES) throw new Stop("conflict", "binding_invalid");
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}