metergraph-cli 0.2.2 → 0.2.4

package/src/read.js

@@ -2,12 +2,22 @@ import { agentKeySource, keySession, keyTarget, readAgentKey } from "./agent-key
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { checkDeployment } from "./doctor.js";
 import { sessionFor } from "./auth-session.js";
-import { Stop, openStore, readCredential, resolveConfigDir } from "./auth-store.js";
-import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE, READ_MAX_BYTES, READ_MAX_LIMIT, READ_PATHS } from "./constants.js";
+import { Stop, openStore, readProjectCredential, resolveConfigDir } from "./auth-store.js";
+import {
+  DEFAULT_ORIGIN,
+  MAX_BODY_BYTES,
+  READ_MAX_BYTES,
+  READ_MAX_LIMIT,
+  READ_PATHS,
+  WORKFLOW_DEPLOYMENT_CAPABILITY,
+  WORKFLOW_PERMISSIONS,
+} from "./constants.js";
 import { parseJsonObject } from "./http.js";
 import {
   readQuery,
   groupedRequest,
+  workspaceLabel,
+  workspacePinned,
   READ_ENVIRONMENTS,
   CAPABILITY_NAMES,
   capabilitySummary,
@@ -19,6 +29,8 @@ import {
 } from "./read-contract.js";
 import { compareReports, priorWindow, rankReport } from "./usage-aggregates.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
+import { experimentNextAction, experimentRead } from "./experiments.js";
+import { readArguments, toolsNextAction, toolsRead } from "./tools.js";
 import { agentKeyAction, classifyEnvironment, handoffPages } from "./environment.js";
 
 // The read commands: status, context, capabilities, usage, routes and traces.
@@ -60,6 +72,11 @@ export async function runRead(options) {
     healthy: null,
     profileVerified: null,
     authenticated: false,
+    // The credential's access ("metadata" or "debug") and scopes, once verified.
+    access: null,
+    scopes: [],
+    // The verified workspace's slug and name, for output. Never its ID.
+    workspaceLabel: { slug: null, name: null },
     verifiedWorkspace: null,
     capabilities: null,
   };
@@ -81,13 +98,16 @@ export async function runRead(options) {
     if (holdsKnown(data, known)) {
       notices.clear();
       ctx.reason = "credential_in_metadata_response";
+      // The workspace's name or slug may be what echoed the credential.
+      ctx.workspaceLabel = { slug: null, name: null };
       return {
         outcome: "verification_failed",
         reason: "credential_in_metadata_response",
         data: build("verification_failed", null),
+        validateOutput: (text) => !outputHoldsKnown(text, known),
       };
     }
-    return { outcome, reason, data };
+    return { outcome, reason, data, validateOutput: (text) => !outputHoldsKnown(text, known) };
   };
   // A deadline or Ctrl+C reported by a lower layer as a timeout or
   // cancellation is reported here by what actually happened.
@@ -101,6 +121,11 @@ export async function runRead(options) {
   };
 
   try {
+    if (options.command === "tools" && options.action === "call") {
+      const args = readArguments(options.tool);
+      if (!args.ok) return end(args.outcome, args.reason);
+      options = { ...options, toolArguments: args };
+    }
     const root = resolveProject(options.project);
     const configDir = resolveConfigDir(options.configDir);
     const found = readBinding(root);
@@ -115,7 +140,7 @@ export async function runRead(options) {
     if (binding !== null) {
       try {
         store = openStore(configDir, { create: false });
-        const record = store === null ? null : readCredential(store, binding.credential_slot);
+        const record = store === null ? null : readProjectCredential(store, binding.credential_slot, root);
         grantSaved = record !== null;
         originConfirmed = record !== null && record.origin === binding.origin;
       } catch (error) {
@@ -178,18 +203,26 @@ export async function runRead(options) {
     }
 
     const session = useKey
-      ? await keySession({ target, source, env, signal: limit.signal, verifiedProfile })
-      : await sessionFor(binding, store, limit.signal);
+      ? await keySession({ target, source, env, signal: limit.signal, verifiedProfile, access: "read" })
+      : await sessionFor(binding, store, limit.signal, root);
     if (!session.ok) {
       const settled = settle(session);
       return end(settled.outcome, settled.reason);
     }
     ctx.profile = session.session.profile;
+    ctx.access = session.session.access;
+    ctx.scopes = session.session.scopes;
+    known = session.knownCredentials;
+    ctx.workspaceLabel = workspaceLabel(session.documents.workspace?.workspace);
+    // A workspace named by slug or name is checked against the verified one.
+    if (target.workspaceText !== null && !workspacePinned(session.documents.workspace?.workspace, target.workspaceText)) {
+      return end("verification_failed", "workspace_context_mismatch");
+    }
     if (ctx.workspaceId === null) {
       ctx.workspaceId = session.session.workspaceId;
-      notices.add("workspace_not_pinned");
+      if (target.workspaceText === null) notices.add("workspace_not_pinned");
+      else ctx.intendedWorkspace = ctx.workspaceId;
     }
-    known = session.knownCredentials;
     ctx.authenticated = true;
     const { documents } = session;
 
@@ -211,6 +244,25 @@ export async function runRead(options) {
       return end("ok", null, context.value);
     }
     if (options.command === "capabilities") return end("ok", null, capabilities.value);
+    if (options.command === "tools") {
+      const tools = await toolsRead(session.session, options, limit.signal);
+      if (!tools.ok) {
+        if (ctx.credential === "agent_key" && tools.reason === "access_revoked") tools.reason = "agent_key_rejected";
+        const settled = ["refused", "unconfirmed", "action_required"].includes(tools.outcome) ? tools : settle(tools);
+        return end(settled.outcome, settled.reason, tools.report);
+      }
+      return end("ok", null, tools.value);
+    }
+    if (options.command === "experiments") {
+      const read = await experimentRead(session.session, options, ctx, documents, limit.signal, notices);
+      if (!read.ok) {
+        const settled = read.outcome === "refused" ? read : settle(read);
+        const report = read.refusal ? { refusal: read.refusal }
+          : read.retryAfter !== undefined ? { retry_after_seconds: read.retryAfter } : null;
+        return end(settled.outcome, settled.reason, report);
+      }
+      return end("ok", null, read.value);
+    }
 
     const read = grouped ? GROUPED_USAGE : READS[options.command];
     const entry = capabilities.value.agent[read.capability];
@@ -328,7 +380,7 @@ const INSUFFICIENT_SCOPE = /(?:^|[\s,])error\s*=\s*"?insufficient_scope"?(?:$|[\
 // True when any string in value (keys included) contains one of the known
 // credential values. An exact containment check against values this run
 // holds, not a guess at what looks secret.
-function holdsKnown(value, known) {
+export function holdsKnown(value, known) {
   if (known.length === 0) return false;
   if (typeof value === "string") return known.some((secret) => value.includes(secret));
   if (value === null || typeof value !== "object") return false;
@@ -340,7 +392,7 @@ function holdsKnown(value, known) {
 
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
-function retryAfterOf(response) {
+export function retryAfterOf(response) {
   const header = response.headers["retry-after"];
   const seconds = typeof header === "string" && RETRY_AFTER.test(header.trim()) ? Number(header.trim()) : null;
   return seconds !== null && seconds <= 86400 ? seconds : null;
@@ -394,15 +446,18 @@ async function fetchRead(session, path, query, signal) {
 function readData(ctx, report, notices, outcome, options, extra = {}) {
   return {
     origin: ctx.origin,
-    workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId },
+    workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId, ...ctx.workspaceLabel },
     deployment_profile: ctx.profile,
     environment: ctx.environment.kind,
     credential: ctx.credential,
     authenticated: ctx.authenticated,
-    scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
+    scopes: ctx.authenticated ? ctx.scopes : [],
     result: outcome === "ok" ? report : null,
     retry_after_seconds: outcome === "rate_limited" || report?.retry_after_seconds !== undefined
       ? report?.retry_after_seconds ?? null : null,
+    ...(options.command === "experiments" ? { refusal: outcome === "refused" ? report?.refusal ?? null : null } : {}),
+    // A tool's own error document, as the service returned it.
+    ...(options.command === "tools" ? { tool_error: outcome === "refused" ? report?.tool_error ?? null : null } : {}),
     notices: [...notices].sort(),
     next_action: nextAction(outcome, ctx, options, extra),
   };
@@ -434,17 +489,38 @@ function statusData(ctx, notices, outcome, options) {
         ctx.verifiedWorkspace === null || ctx.intendedWorkspace === null
           ? null
           : ctx.verifiedWorkspace === ctx.intendedWorkspace,
+      // The verified workspace's slug and name, which output shows instead
+      // of either ID.
+      ...ctx.workspaceLabel,
     },
-    scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
+    scopes: ctx.authenticated ? ctx.scopes : [],
     capabilities:
       agent === null ? null : Object.fromEntries(CAPABILITY_NAMES.map((name) => [name, agent[name]?.available ?? null])),
-    content_access: false,
+    // Whether this credential may read content through Agent Access. The
+    // read commands never do, whatever it allows.
+    content_access: agent !== null && Object.values(agent).some((entry) => entry?.available === true && entry.content === true),
+    access: accessFor(ctx),
     application_traffic_verified: false,
     notices: [...notices].sort(),
     next_action: nextAction(outcome, ctx, options),
   };
 }
 
+// The credential's role and workflow permissions, by the names the Keys page
+// uses. Either role reads. Writing and testing evaluations and starting
+// analyses need Debug with all three permissions, on a deployment that offers
+// managed evaluations: permissions_offered is false where it does not, and
+// null when the capabilities were not read.
+export function accessFor(ctx) {
+  if (!ctx.authenticated) return null;
+  const deployment = ctx.capabilities?.deployment_capabilities ?? null;
+  return {
+    role: ctx.access,
+    permissions: Object.fromEntries(WORKFLOW_PERMISSIONS.map(({ field, scope }) => [field, ctx.scopes.includes(scope)])),
+    permissions_offered: deployment === null ? null : deployment.includes(WORKFLOW_DEPLOYMENT_CAPABILITY),
+  };
+}
+
 const NARROW =
   "Narrow the read: a shorter --days or --since/--until window, exact --route, --provider or --model filters, " +
   "fewer --group-by dimensions or a lower --limit.";
@@ -460,6 +536,10 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
   const reason = ctx.reason;
   const capabilities = ctx.capabilities;
   if (outcome === "rate_limited") return { kind: "retry_later", message: "Wait, then run the same command again." };
+  const experiment = experimentNextAction(outcome, ctx, options, report);
+  if (experiment !== undefined) return experiment;
+  const tool = toolsNextAction(ctx, options);
+  if (tool !== undefined) return tool;
   if (reason === "usage_aggregates_unavailable" || (grouped && reason === "endpoint_unavailable")) {
     // Offer the route-by-day read only when this grant actually has it.
     if (capabilities?.agent?.usage?.available !== true) return null;
@@ -513,8 +593,8 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
       kind: "use_metadata_only_key",
       url: handoffPages(origin).keys_url,
       message:
-        "This key grants more than Metadata access, so the CLI does not use it. Ask the person for a " +
-        "coding-agent key limited to Metadata access.",
+        "This key has Replay access or another scope the CLI does not use. Ask the person for a coding-agent " +
+        "key with the Metadata or Debug role, and to replace the secret.",
     };
   }
   if (keyed && reason === "workspace_context_mismatch") {
@@ -561,3 +641,12 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
   }
   return null;
 }
+
+// The final renderer may join independent service fields or insert styling.
+// Check exact emitted bytes and their terminal-visible equivalent.
+export function outputHoldsKnown(text, known) {
+  const visible = (value) => value.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/[\x00-\x1f\x7f-\x9f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").normalize("NFKC");
+  return holdsKnown(text, known) || known.some((secret) => visible(text).includes(visible(secret)));
+}

package/src/repository-identity.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
+import fs, { withRollback } from "./anchored-fs.js";
 import path from "node:path";
 
 // Repository identity for the SDKs: `.metergraph/config.json` with
@@ -157,7 +157,7 @@ function writeNewConfig(root, repository) {
     try { fs.writeFileSync(fd, content); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
     fs.linkSync(temp, dest);
   } finally {
-    try { fs.unlinkSync(temp); } catch { /* already gone */ }
+    try { withRollback(() => fs.unlinkSync(temp)); } catch { /* already gone */ }
   }
 }
 

package/src/setup-deployment.js

@@ -64,6 +64,13 @@ const ACTION_GUIDE = Object.freeze({
   retry: "Rerun the same command.",
 });
 
+// Each prerequisite a non-hosted route asserts, with its guidance, for a
+// person confirming them at a terminal.
+export function prerequisitesFor(deployment) {
+  const profile = EXPECTED_PROFILE[deployment];
+  return (PREREQUISITES[deployment] ?? []).map((name) => ({ name, guide: prerequisiteGuide(name, profile) }));
+}
+
 export function prerequisiteGuide(name, profile) {
   if (name === "metadata_agent_credential") return METADATA_CREDENTIAL_GUIDE[profile] ?? null;
   return PREREQUISITE_GUIDE[name] ?? null;

package/src/setup-env-git.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
+import fs from "./anchored-fs.js";
 import path from "node:path";
 
 import { Stop } from "./auth-store.js";

package/src/setup-env.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import fs from "node:fs";
+import fs, { validatePath, withRollback } from "./anchored-fs.js";
 import path from "node:path";
 
 import { resolveProject } from "./auth-binding.js";
@@ -62,6 +62,8 @@ const PLANS = new WeakMap();
 const HANDLES = new WeakMap();
 
 export const ENV_MESSAGES = Object.freeze({
+  secure_writes_unavailable:
+    "Secure automatic file writes are unavailable on this platform or the bundled filesystem helper failed verification. Nothing was written.",
   invalid_project: "--project must name an existing directory.",
   env_path_invalid:
     "The env file path is not allowed. Use a project-relative path with forward slashes to a file named .env, .env.<name> or <name>.env.",
@@ -193,12 +195,12 @@ export async function rollbackEnv(handle, { signal = null, waitMs = DEFAULT_WAIT
   if (state === undefined) throw new Stop("internal_error", "invalid_plan");
   checkCancel(signal);
   if (state.journal.length > 0) {
-    const lock = await takeLock(state.lockDir, waitMs, signal);
+    const lock = await takeLock(state.lockDir, waitMs, signal, true);
     try {
       checkCancel(signal);
       deferSignals(() => {
         try {
-          undo(state.journal);
+          withRollback(() => undo(state.journal));
         } catch (error) {
           if (error instanceof Stop && error.outcome === "conflict") throw new Stop("conflict", "rollback_conflict");
           throw new Stop("filesystem_error", "rollback_incomplete");
@@ -352,6 +354,8 @@ function apply(state, updates) {
       }
     }
 
+    validatePath(target.dir);
+    if (ignore !== null) validatePath(state.root);
     const receipt = freeze({
       path: target.rel,
       location: target.location,
@@ -363,7 +367,7 @@ function apply(state, updates) {
     return { receipt, journal };
   } catch (error) {
     try {
-      undo(journal);
+      withRollback(() => undo(journal));
     } catch {
       throw new Stop("filesystem_error", "rollback_incomplete");
     }
@@ -575,7 +579,7 @@ function replaceFile(file, content, { before, mode, protect, reasons, changed })
   } catch (error) {
     if (created) {
       try {
-        fs.unlinkSync(temp);
+        withRollback(() => fs.unlinkSync(temp));
       } catch {
         // Reported by the caller's failure; nothing else to do.
       }
@@ -602,7 +606,7 @@ function syncDir(dir) {
 // An exclusive lock file in the project (or, outside a project, in the env
 // file's directory). A held lock is waited on for at most waitMs, then
 // reported; it is never taken over or removed, even if it looks stale.
-async function takeLock(dir, waitMs, signal) {
+async function takeLock(dir, waitMs, signal, rollback = false) {
   const file = path.join(dir, LOCK);
   const wait = Number.isFinite(waitMs) ? Math.min(Math.max(waitMs, 0), MAX_WAIT_MS) : DEFAULT_WAIT_MS;
   const until = Date.now() + wait;
@@ -610,7 +614,7 @@ async function takeLock(dir, waitMs, signal) {
     checkCancel(signal);
     let fd;
     try {
-      fd = fs.openSync(file, "wx", 0o600);
+      fd = rollback ? withRollback(() => fs.openSync(file, "wx", 0o600)) : fs.openSync(file, "wx", 0o600);
     } catch (error) {
       if (error.code !== "EEXIST") throw fixed(error, "env_write_failed");
       if (Date.now() >= until) throw new Stop("conflict", "env_locked");
@@ -629,8 +633,10 @@ async function takeLock(dir, waitMs, signal) {
 // Removes the lock only if it is still the file this process created.
 function dropLock(lock) {
   try {
-    const stat = fs.lstatSync(lock.file);
-    if (IS_WINDOWS || (stat.dev === lock.dev && stat.ino === lock.ino)) fs.unlinkSync(lock.file);
+    withRollback(() => {
+      const stat = fs.lstatSync(lock.file);
+      if (stat.dev === lock.dev && stat.ino === lock.ino) fs.unlinkSync(lock.file);
+    });
   } catch {
     // Reported by the next run as a held lock.
   }
@@ -670,6 +676,7 @@ function deferSignals(work) {
 // error, which can hold a path, is never passed on.
 function fixed(error, reason) {
   if (error instanceof Stop) return error;
+  if (error?.code === "ENOTSUP") return new Stop("unsupported", "secure_writes_unavailable");
   if (DENIED.has(error?.code)) {
     return new Stop("filesystem_error", reason === "env_read_failed" ? "env_read_denied" : "env_write_denied");
   }