metergraph-cli 0.2.1 → 0.2.2

package/src/auth-login.js

@@ -1,4 +1,4 @@
-import { detectRemoteSession, openBrowser } from "./auth-browser.js";
+import { openBrowser } from "./auth-browser.js";
 import { startCallbackListener } from "./auth-callback.js";
 import {
   BINDING_PATH,
@@ -30,8 +30,9 @@ import {
   withSlotLock,
   writeCredential,
 } from "./auth-store.js";
-import { AUTH_HTTP_TIMEOUT_MS, CONNECTION_GUIDE_URL, METADATA_SCOPE } from "./constants.js";
+import { AUTH_HTTP_TIMEOUT_MS, METADATA_SCOPE } from "./constants.js";
 import { runDoctor } from "./doctor.js";
+import { agentKeyAction, classifyEnvironment } from "./environment.js";
 import { deadline, trapSignals } from "./transport.js";
 
 // login and logout. Each returns { outcome, reason, data }; every string in
@@ -44,6 +45,10 @@ import { deadline, trapSignals } from "./transport.js";
 // exists, while the listener keeps waiting. The caller prints it as the one
 // JSON line, so an agent can hand the URL to a person; approval-handoff.js
 // lets the agent's command exit then while this process keeps waiting.
+// options.ingestSetup, given only by setup, is { familyId, supported(origin,
+// profile, signal) }. When the service supports it, the sign-in consent also
+// approves the first ingest key for that family, and an ok result carries the
+// unredeemed receipt as result.ingestSetup (never in data).
 
 export async function runLogin(options, progress) {
   const ctx = {
@@ -55,14 +60,20 @@ export async function runLogin(options, progress) {
     configured: false,
     status: null,
     previousGrant: null,
+    environment: null,
   };
   const end = (outcome, reason, next = null) => ({ outcome, reason, data: loginData(ctx, next) });
 
   // Handoffs come first: no listener, request or file write happens for a
-  // session that cannot finish sign in.
-  if (options.runtime !== "local") return end("unsupported", "runtime_not_supported", GUIDE);
-  const remote = detectRemoteSession();
-  if (remote !== null) return end("unsupported", remote, GUIDE);
+  // session that cannot finish sign in. The next action tells the agent how
+  // a person hands it a Metadata key instead.
+  const environment = options.environment ?? classifyEnvironment();
+  ctx.environment = environment.kind;
+  if (options.runtime !== "local") {
+    ctx.environment = "declared_cloud";
+    return end("unsupported", "runtime_not_supported", agentKeyAction({ kind: "declared_cloud" }, options.origin));
+  }
+  if (environment.remote) return end("unsupported", environment.reason, agentKeyAction(environment, options.origin));
   const trap = trapSignals();
   try {
     const root = resolveProject(options.project);
@@ -153,7 +164,7 @@ export async function runLogin(options, progress) {
     if (bound !== null && bound.credential_slot !== slot) {
       ctx.previousGrant = await retireSlot(store, bound);
     }
-    return end("ok", null, CONNECTED);
+    return { ...end("ok", null, CONNECTED), ingestSetup: flow.ingestSetup };
   } catch (error) {
     if (error instanceof Stop) return end(error.outcome, error.reason);
     throw error;
@@ -182,6 +193,16 @@ async function authorize(options, ctx, cancel, progress, announce) {
   if (!discovered.ok) return httpFailure(discovered, cancel);
   const { endpoints, requireIss, offeredClientId } = discovered;
 
+  // Setup asks this consent to approve the first ingest key too, but only
+  // when the service says it can. Otherwise sign in is unchanged and setup
+  // asks for its own approval afterwards.
+  let setupPkce = null;
+  if (options.ingestSetup) {
+    limit = deadline(AUTH_HTTP_TIMEOUT_MS, cancel);
+    if (await options.ingestSetup.supported(ctx.origin, ctx.profile, limit.signal)) setupPkce = newPkce();
+    if (cancel.aborted) return fail("authorization_failed", "cancelled");
+  }
+
   const listener = await startCallbackListener();
   let callback;
   let clientId;
@@ -204,6 +225,7 @@ async function authorize(options, ctx, cancel, progress, announce) {
       requireIss,
       timeoutMs: options.timeoutMs,
       cancel,
+      acceptSetupCode: setupPkce !== null,
     });
     const url = authorizationUrl(endpoints, {
       clientId,
@@ -211,15 +233,18 @@ async function authorize(options, ctx, cancel, progress, announce) {
       state: pkce.state,
       challenge: pkce.challenge,
       signup: options.signup,
+      ingestSetup: setupPkce === null ? null : { familyId: options.ingestSetup.familyId, challenge: setupPkce.challenge },
     });
+    const purpose = setupPkce === null ? "sign in with Metadata access"
+      : "sign in with Metadata access and approve an ingest-only key for this project";
     const seconds = Math.round(options.timeoutMs / 1000);
     // A wait armed after Ctrl+C has already settled; do not show the URL.
     if (cancel.aborted) return fail("authorization_failed", "cancelled");
     if (options.noBrowser && announce) {
-      announce(openUrl(url, seconds, "sign in with Metadata access"));
+      announce(openUrl(url, seconds, purpose));
     } else if (options.noBrowser) {
       progress(
-        "Open this URL in a browser on this machine to sign in:\n" +
+        `Open this URL in a browser on this machine to ${purpose}:\n` +
           `${url}\n` +
           `Waiting up to ${seconds} seconds for the browser. Press Ctrl+C to cancel.`,
       );
@@ -228,15 +253,25 @@ async function authorize(options, ctx, cancel, progress, announce) {
         return fail("authorization_failed", "browser_unavailable", {
           kind: "no_browser",
           message: "Run login again with --no-browser, without --json, and open the URL it prints.",
+          // A local container's loopback callback is reachable only when its
+          // port is forwarded to the person's machine. A Metadata key avoids
+          // the callback altogether.
+          ...(ctx.environment === "local_container"
+            ? { alternative: agentKeyAction({ kind: "local_container", remote: false }, ctx.origin) }
+            : {}),
         });
       }
-      progress(`Opened your browser to sign in. Waiting up to ${seconds} seconds. Press Ctrl+C to cancel.`);
+      progress(setupPkce === null
+        ? `Opened your browser to sign in. Waiting up to ${seconds} seconds. Press Ctrl+C to cancel.`
+        : "Opened your browser to sign in and approve this project's ingest key in one step. " +
+          `Waiting up to ${seconds} seconds. Press Ctrl+C to cancel.`);
     }
     callback = await pending;
   } finally {
     await listener.close();
   }
 
+  if (callback.kind === "code" && setupPkce !== null && callback.setupCode) options.ingestSetup.onApproved?.();
   if (callback.kind === "denied") return fail("authorization_failed", "access_denied");
   if (callback.kind === "timeout") return fail("authorization_failed", "timeout");
   if (callback.kind === "cancelled") return fail("authorization_failed", "cancelled");
@@ -270,7 +305,15 @@ async function authorize(options, ctx, cancel, progress, announce) {
     return rejectGrant(verified.outcome, verified.reason);
   }
   ctx.workspaceId = grant.tenant;
-  return { ok: true, endpoints, clientId, grant };
+  // The receipt is a separate credential: setup redeems it with its own
+  // verifier, for the family it named, after binding this sign in. A service
+  // that showed only the sign in returns no receipt, and setup falls back to
+  // its own approval.
+  const ingestSetup = setupPkce !== null && callback.setupCode
+    ? { familyId: options.ingestSetup.familyId, code: callback.setupCode, verifier: setupPkce.verifier,
+        clientId, redirectUri: listener.redirectUri }
+    : null;
+  return { ok: true, endpoints, clientId, grant, ingestSetup };
 }
 
 export async function runLogout(options) {
@@ -389,7 +432,6 @@ export function openUrl(url, seconds, purpose) {
   };
 }
 
-const GUIDE = { kind: "connection_guide", url: CONNECTION_GUIDE_URL };
 const RECONNECT = {
   kind: "reconnect",
   message: "Run login again with --reconnect to switch this project, or run logout first.",
@@ -403,6 +445,7 @@ function loginData(ctx, next) {
   return {
     origin: ctx.origin,
     runtime: ctx.runtime,
+    environment: ctx.environment,
     deployment_profile: ctx.profile,
     workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId },
     scopes: ctx.authenticated ? [METADATA_SCOPE] : [],

package/src/auth-oauth.js

@@ -225,7 +225,11 @@ export function newPkce() {
 // The authorization URL the browser opens. With signup, the browser starts
 // at the service's own signup page, which returns to the same authorization
 // request on this origin after the account exists.
-export function authorizationUrl(endpoints, { clientId, redirectUri, state, challenge, signup }) {
+// ingestSetup, when given as { familyId, challenge }, asks this one consent to
+// also approve the first ingest key for a new setup family. The service
+// returns that receipt next to the code; it is redeemed separately with its
+// own PKCE verifier.
+export function authorizationUrl(endpoints, { clientId, redirectUri, state, challenge, signup, ingestSetup = null }) {
   const url = new URL(endpoints.authorization);
   url.search = new URLSearchParams({
     response_type: "code",
@@ -236,6 +240,11 @@ export function authorizationUrl(endpoints, { clientId, redirectUri, state, chal
     code_challenge: challenge,
     code_challenge_method: "S256",
     resource: endpoints.resource,
+    ...(ingestSetup === null ? {} : {
+      ingest_setup: "1",
+      ingest_setup_family_id: ingestSetup.familyId,
+      ingest_setup_code_challenge: ingestSetup.challenge,
+    }),
   }).toString();
   if (!signup) return url.href;
   const entry = new URL(`${endpoints.origin}${AUTH_PATHS.signup}`);
@@ -383,9 +392,17 @@ function decodeClaims(token) {
 // Nothing else is read: no telemetry, content or provider requests.
 // Returns { ok: true, workspaceId, documents } or { ok: false, outcome, reason, denied }
 // where denied means the service refused the token (401 or 403).
-export async function verifyContext(origin, accessToken, { profile, workspaceId }, signal) {
+// workspaceId is the workspace the credential must be for. Only an agent key
+// with nothing to pin it to passes anyWorkspace: true with workspaceId null,
+// and then the workspace the service reports is checked for consistency and
+// returned as the verified one.
+export async function verifyContext(origin, accessToken, { profile, workspaceId, anyWorkspace = false }, signal) {
   const workspace = await bearerJson(origin, AUTH_PATHS.workspace, accessToken, WORKSPACE_BYTES, signal, "workspace");
   if (!workspace.ok) return workspace;
+  if (workspaceId === null && anyWorkspace === true) {
+    workspaceId = normalizeUuid(workspace.body.workspace?.id);
+    if (workspaceId === null) return stop("verification_failed", "workspace_response_invalid");
+  }
   const checked = checkWorkspace(workspace.body, { profile, workspaceId });
   if (!checked.ok) return checked;
 
@@ -466,7 +483,7 @@ async function bearerJson(origin, path, accessToken, maxBytes, signal, document)
   const failure = failureOf(response);
   if (failure !== null) return { ok: false, ...failure };
   if (response.status === 401 || response.status === 403) {
-    return { ok: false, outcome: "verification_failed", reason: "access_rejected", denied: true };
+    return { ok: false, outcome: "verification_failed", reason: "access_rejected", denied: true, status: response.status };
   }
   if (response.status !== 200) return stop("unsupported", "unexpected_status");
   const body = parseJsonObject(response);

package/src/callback-page.js

@@ -0,0 +1,58 @@
+// The static pages the loopback callback listener answers with. They follow
+// the look of the server's consent page (green band with the Metergraph mark,
+// white card) so the hand-off from the browser back to the terminal reads as
+// one flow. Pages are fixed strings: nothing from a request is ever rendered.
+// The stylesheet is inline and allowed by its hash, so the policy stays
+// default-src 'none' with no script and no 'unsafe-inline'.
+import { createHash } from "node:crypto";
+
+const LOGO = `<svg class="logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 134 25" width="134" height="25" role="img" aria-label="Metergraph"><g fill="white" transform="scale(0.03681885)"><circle cx="105" cy="128" r="62"/><circle cx="105" cy="239" r="62"/><circle cx="105" cy="350" r="62"/><circle cx="105" cy="461" r="62"/><circle cx="105" cy="572" r="62"/><circle cx="578" cy="128" r="62"/><circle cx="578" cy="239" r="62"/><circle cx="578" cy="350" r="62"/><circle cx="578" cy="461" r="62"/><circle cx="578" cy="572" r="62"/><circle cx="221" cy="238" r="62"/><circle cx="282.5" cy="346" r="62"/><circle cx="341.5" cy="456" r="62"/><circle cx="400.5" cy="346" r="62"/><circle cx="462" cy="238" r="62"/></g><path d="M34.68 20V6H38.2L42.08 16.38L42.56 17.78C42.7 17.32 42.82 16.9 43.02 16.38L46.82 6H50.28V20H48.12V10.02L48.14 8.16L43.84 20H41.22L36.8 8.16L36.84 10.02V20H34.68ZM56.8091 20.32C53.9091 20.32 51.9691 18.48 51.9691 15.3C51.9691 12.1 53.9691 9.98 56.7091 9.98C59.6491 9.98 61.2891 12.02 61.2891 15.16V15.6H54.0891C54.1091 17.48 55.2491 18.7 56.8091 18.7C57.9291 18.7 58.9291 18.16 59.1291 16.92H61.2091C61.0091 18.76 59.4891 20.32 56.8091 20.32ZM59.1291 14.12C59.1091 12.6 58.2091 11.56 56.7091 11.56C55.2291 11.56 54.2291 12.68 54.1091 14.12H59.1291ZM66.6303 20.16C64.8703 20.16 63.6703 19.3 63.6703 17.14V11.98H61.6703V10.3H63.6703V6.94H65.7503V10.3H67.9503V11.98H65.7503V16.86C65.7503 17.94 66.2303 18.42 67.1903 18.42C67.4303 18.42 67.6503 18.4 67.9103 18.36V20.02C67.6103 20.1 67.1503 20.16 66.6303 20.16ZM73.4997 20.32C70.5997 20.32 68.6597 18.48 68.6597 15.3C68.6597 12.1 70.6597 9.98 73.3997 9.98C76.3397 9.98 77.9797 12.02 77.9797 15.16V15.6H70.7797C70.7997 17.48 71.9397 18.7 73.4997 18.7C74.6197 18.7 75.6197 18.16 75.8197 16.92H77.8997C77.6997 18.76 76.1797 20.32 73.4997 20.32ZM75.8197 14.12C75.7997 12.6 74.8997 11.56 73.3997 11.56C71.9197 11.56 70.9197 12.68 70.7997 14.12H75.8197ZM79.5581 20V10.3H81.6381V10.88L81.5981 11.98C82.0981 10.88 83.0581 9.98 84.5381 9.98C84.6981 9.98 84.8381 9.98 85.0181 10.02V12.04C84.8581 12.02 84.6781 11.98 84.3981 11.98C82.7181 11.98 81.6381 12.88 81.6381 15.02V20H79.5581ZM90.0131 24.44C87.3131 24.44 85.6531 22.96 85.6531 20.8H87.7531C87.7731 22.02 88.6131 22.82 90.0531 22.82C91.5931 22.82 92.6931 21.96 92.6931 20.2V19.08C92.6931 18.76 92.6931 18.46 92.7331 18.16C92.1931 19.08 91.0931 19.76 89.6331 19.76C87.0331 19.76 85.2531 17.92 85.2531 14.88C85.2531 11.88 87.2531 9.98 89.5931 9.98C91.2531 9.98 92.1931 10.74 92.7331 11.64C92.6931 11.36 92.6931 11.08 92.6931 10.78V10.3H94.7731V19.6C94.7731 22.86 92.9931 24.44 90.0131 24.44ZM90.1131 18.12C91.6931 18.12 92.8131 16.8 92.8131 14.88C92.8131 12.98 91.6931 11.62 90.1131 11.62C88.4931 11.62 87.3731 12.96 87.3731 14.88C87.3731 16.82 88.4931 18.12 90.1131 18.12ZM96.9128 20V10.3H98.9928V10.88L98.9528 11.98C99.4528 10.88 100.413 9.98 101.893 9.98C102.053 9.98 102.193 9.98 102.373 10.02V12.04C102.213 12.02 102.033 11.98 101.753 11.98C100.073 11.98 98.9928 12.88 98.9928 15.02V20H96.9128ZM105.929 20.32C104.169 20.32 102.589 19.2 102.589 17.34C102.589 15.3 104.189 14.48 106.089 14.22L107.829 13.96C108.589 13.86 108.849 13.58 108.849 13.04C108.849 12.18 108.169 11.56 107.089 11.56C105.769 11.56 105.029 12.28 104.969 13.38H102.849C102.949 11.5 104.469 9.98 106.949 9.98C109.629 9.98 110.909 11.48 110.909 13.96V20H108.969V19.56C108.969 19.26 108.969 19 109.009 18.68C108.509 19.66 107.489 20.32 105.929 20.32ZM106.389 18.76C107.809 18.76 108.889 17.76 108.889 16.28V15.04C108.729 15.22 108.369 15.36 107.789 15.46L106.689 15.68C105.549 15.9 104.729 16.34 104.729 17.28C104.729 18.22 105.469 18.76 106.389 18.76ZM112.92 24.12V10.3H115V10.86C115 11.12 114.98 11.36 114.96 11.66C115.54 10.7 116.66 9.98 118.14 9.98C120.82 9.98 122.5 12.14 122.5 15.16C122.5 18.28 120.64 20.32 118.08 20.32C116.56 20.32 115.58 19.64 114.96 18.66L115 19.52V24.12H112.92ZM117.64 18.7C119.28 18.7 120.36 17.24 120.36 15.14C120.36 13.08 119.32 11.62 117.64 11.62C116.04 11.62 114.9 12.98 114.9 15.14C114.9 17.26 116.02 18.7 117.64 18.7ZM124.058 20V6H126.138V10.76L126.098 11.64C126.618 10.7 127.658 9.98 129.078 9.98C131.258 9.98 132.578 11.44 132.578 13.88V20H130.498V14.16C130.498 12.54 129.838 11.62 128.478 11.62C127.058 11.62 126.138 12.8 126.138 14.24V20H124.058Z" fill="white"/></svg>`;
+
+const STYLE = `
+:root{color-scheme:light}
+*{box-sizing:border-box}
+body{margin:0;background:#edeee9;color:#151b17;font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.55}
+.shell{max-width:600px;margin:0 auto;padding:28px 12px 48px}
+.hero{background:linear-gradient(90deg,#0a6146,#0a5944 54%,#073d32);color:#fff;padding:26px 30px 34px}
+.logo{display:block;width:150px;height:auto;margin:0 0 36px}
+.eyebrow{margin:0 0 6px;color:#d7f68e;font-size:13px;font-weight:700;letter-spacing:.06em;text-transform:uppercase}
+h1{margin:0;font-size:30px;font-weight:400;letter-spacing:-.6px;line-height:1.2}
+.card{background:#fff;padding:30px}
+p{margin:0 0 18px}
+p:last-child{margin-bottom:0}
+.note{color:#505b53;font-size:14px}
+@media (max-width:520px){
+.shell{padding:0 0 32px}
+.hero{padding:22px 20px 28px}
+.logo{margin-bottom:28px}
+h1{font-size:25px}
+.card{padding:22px 20px}
+}
+`;
+
+export const PAGE_CSP = `default-src 'none'; style-src 'sha256-${createHash("sha256").update(STYLE).digest("base64")}'`;
+
+const page = (title, lead, note) =>
+  '<!doctype html><html lang="en"><head><meta charset="utf-8">' +
+  '<meta name="viewport" content="width=device-width, initial-scale=1">' +
+  `<title>${title} | Metergraph CLI</title><style>${STYLE}</style></head><body>` +
+  `<div class="shell"><header class="hero">${LOGO}<p class="eyebrow">Metergraph CLI</p><h1>${title}</h1></header>` +
+  `<main class="card"><p>${lead}</p><p class="note">${note}</p></main></div></body></html>\n`;
+
+export const PAGES = {
+  done: page(
+    "Authorization received",
+    "Return to the terminal. The command finishes signing in there and reports the result.",
+    "You can close this tab.",
+  ),
+  failed: page(
+    "Authorization did not complete",
+    "Return to the terminal for details and the next step.",
+    "You can close this tab.",
+  ),
+  invalid: page(
+    "Request not accepted",
+    "This page only accepts the browser hand-off for a command that is waiting in your terminal.",
+    "If you started a sign-in, return to the terminal and try again.",
+  ),
+};

package/src/cli.js

@@ -20,6 +20,7 @@ import { listSkillPack, runSkill, runSkillPack } from "./skill.js";
 import { runSetup } from "./setup.js";
 import { containsKnownCredential, preflightNonHostedSetup, prerequisiteGuide, resumeNonHostedRoute } from "./setup-deployment.js";
 import { VERSION } from "./constants.js";
+import { createStyle, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
 import { runVerify } from "./verify.js";
 import { verifyMessage, verifyText } from "./verify-output.js";
 
@@ -46,6 +47,7 @@ export async function main(argv, { stdout, stderr }) {
 
 async function run(argv, { stdout, stderr }) {
   const parsed = parseArgs(argv);
+  const style = createStyle(stdout);
 
   if (!parsed.ok) {
     const result = envelope({
@@ -55,13 +57,13 @@ async function run(argv, { stdout, stderr }) {
       message: parsed.message,
     });
     if (parsed.json) stdout.write(toJsonLine(result));
-    else stderr.write(`Error: ${parsed.message}\n`);
+    else stderr.write(`${createStyle(stderr).red("Error:")} ${parsed.message}\n`);
     return result;
   }
 
   if (parsed.command === "help") {
     const result = envelope({ command: "help", outcome: "ok", data: helpData(parsed.topic) });
-    stdout.write(parsed.json ? toJsonLine(result) : helpText(parsed.topic));
+    stdout.write(parsed.json ? toJsonLine(result) : helpText(parsed.topic, style));
     return result;
   }
 
@@ -87,7 +89,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : authText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : authText(result, message, style));
     return result;
   }
 
@@ -110,11 +112,7 @@ async function run(argv, { stdout, stderr }) {
     if (containsKnownCredential(result, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
     }
-    const receipt = result.data?.receipt;
-    const summary = receipt ? `Workspace: ${receipt.workspace_id}\nDeployment: ${receipt.deployment_profile} at ${receipt.origin}\nCompleted: ${receipt.completed_steps.join(", ")}\nPending: ${receipt.pending_steps.join(", ")}\n` : "";
-    const identity = repositoryLine(result.data?.repository);
-    const guide = handoffLines(result.data);
-    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}${guide}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
+    const human = setupText(result, style);
     if (containsKnownCredential(human, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
       stdout.write(parsed.json ? toJsonLine(result) : "Setup stopped.\n");
@@ -134,7 +132,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : readText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : readText(result, message, style));
     return result;
   }
 
@@ -142,7 +140,7 @@ async function run(argv, { stdout, stderr }) {
     const { outcome, reason, data } = await runVerify(parsed);
     const message = verifyMessage(outcome, reason);
     const result = envelope({ command: "verify", outcome, reason, data, message: outcome === "ok" ? null : message });
-    stdout.write(parsed.json ? toJsonLine(result) : verifyText(result));
+    stdout.write(parsed.json ? toJsonLine(result) : verifyText(result, style));
     return result;
   }
 
@@ -155,7 +153,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : skillText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : skillText(result, message, style));
     return result;
   }
 
@@ -169,7 +167,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message, style));
     return result;
   }
 
@@ -184,7 +182,7 @@ async function run(argv, { stdout, stderr }) {
     data: report,
     message: doctorMessage(outcome, reason),
   });
-  stdout.write(parsed.json ? toJsonLine(result) : doctorText(result));
+  stdout.write(parsed.json ? toJsonLine(result) : doctorText(result, style));
   return result;
 }
 
@@ -209,39 +207,98 @@ function announcer(parsed, stdout, screen) {
   return pending;
 }
 
-// What an operator handoff is waiting for, in fixed text: the route, each
-// unconfirmed prerequisite with its guidance, and the next action.
-function handoffLines(data) {
-  if (data?.status !== "operator_handoff") return "";
-  let text = data.origin ? `Deployment: ${data.deployment_profile} at ${data.origin}\n` : "";
-  if (data.workspace_id) text += `Workspace: ${data.workspace_id}\n`;
+const SETUP_TITLES = {
+  ready_for_instrumentation: "Setup complete, ready to instrument",
+  operator_handoff: "Setup is waiting on the operator",
+};
+
+function setupText(result, style) {
+  const data = result.data;
+  const status = data?.status ?? "not_ready";
+  const title = SETUP_TITLES[status] ?? (result.ok ? `Setup: ${status}` : "Setup did not complete");
+  const tone = status === "operator_handoff" ? "warn" : toneFor(result.outcome);
+  const lines = [headline(style, tone, title, result.outcome), ""];
+  const receipt = data?.receipt;
+  const rows = [];
+  if (receipt) {
+    rows.push(
+      ["Workspace", receipt.workspace_id],
+      ["Deployment", `${receipt.deployment_profile} at ${receipt.origin}`],
+      ["Completed", receipt.completed_steps.join(", ") || "none"],
+      ["Pending", receipt.pending_steps.join(", ") || "none"],
+    );
+  }
+  const repository = repositoryValue(data?.repository);
+  if (repository !== null) rows.push(["Repository", repository]);
+  if (status === "operator_handoff") {
+    if (data.origin) rows.push(["Deployment", `${data.deployment_profile} at ${data.origin}`]);
+    if (data.workspace_id) rows.push(["Workspace", data.workspace_id]);
+  }
+  rows.push(["Application traffic verified", "no"]);
+  lines.push(...fields(style, rows), "");
+  if (!result.ok) lines.push(...paragraph(style, result.error.message), `  ${style.dim(`Reason: ${result.error.reason}`)}`, "");
+  lines.push(...handoffLines(data, style));
+  lines.push(...remoteLines(data, style));
+  lines.push(...budgetLines(data, style));
+  if (result.ok) lines.push(...steps(style, [["", "Instrument your application and verify an exact trace."]]));
+  return render(lines);
+}
+
+// What an operator handoff is waiting for, in fixed text: each unconfirmed
+// prerequisite with its guidance, and the next action.
+function handoffLines(data, style) {
+  if (data?.status !== "operator_handoff" || data.next_action?.kind === "run_on_local_machine") return [];
+  const lines = [];
   if (data.pending_prerequisites.length > 0) {
-    text += "Confirm each prerequisite, then rerun with --confirm-prerequisites:\n";
+    lines.push("Confirm each prerequisite, then rerun with --confirm-prerequisites:");
     for (const name of data.pending_prerequisites) {
-      text += `  - ${name}: ${prerequisiteGuide(name, data.deployment_profile) ?? "see the guide"}\n`;
+      lines.push(`  ${style.yellow("•")} ${style.bold(name)}`,
+        ...paragraph(style, prerequisiteGuide(name, data.deployment_profile) ?? "See the guide.", "    "));
     }
+    lines.push("");
   }
   const next = data.next_action;
-  if (next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))) {
-    text += `Next: ${next.message}\n`;
-  }
-  if (next?.url) text += `Guide: ${next.url}\n`;
-  return text;
+  const message = next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))
+    ? next.message : null;
+  lines.push(...steps(style, [["", message], ["Guide", next?.url ?? null]]), "");
+  return lines;
+}
+
+// A refused key issuance: wait for the next window, or revoke unused keys.
+function budgetLines(data, style) {
+  const next = data?.next_action;
+  if (next?.kind !== "retry_later" && next?.kind !== "revoke_keys") return [];
+  return [...steps(style, [["", next.message], ["Keys page", next.url ?? null]]), ""];
+}
+
+// A remote session's handoff: where setup runs instead, and how this
+// environment can still make Metadata reads with a separate agent key.
+function remoteLines(data, style) {
+  const next = data?.next_action;
+  if (next?.kind !== "run_on_local_machine") return [];
+  const keys = next.metadata_reads?.person_steps.find((step) => step.action === "create_metadata_key")?.url ?? null;
+  return [...steps(style, [
+    ["", next.message],
+    ["On the person's own machine", style.bold(next.command)],
+    ["Metadata key for reads here", keys],
+    ["Then run here", next.metadata_reads ? style.bold(next.metadata_reads.then_run.join(", then ")) : null],
+    ["Guide", next.url],
+  ]), ""];
 }
 
-// One line on the repository identity setup found or recorded. The value is
-// owner/name only; a remote URL is never shown.
-function repositoryLine(repository) {
-  if (!repository) return "";
+// The repository identity setup found or recorded. The value is owner/name
+// only; a remote URL is never shown.
+function repositoryValue(repository) {
+  if (!repository) return null;
   const where = repository.path ? ` in ${repository.path}` : repository.source === "env_file" ? " in the env file" : "";
   switch (repository.status) {
-    case "written": return `Repository: ${repository.repository} (recorded${where}; commit it)\n`;
+    case "written": return `${repository.repository} (recorded${where}; commit it)`;
     case "existing": return repository.repository === null
-      ? `Repository: already set${where}\n` : `Repository: ${repository.repository} (already set${where})\n`;
-    case "mismatch": return `Repository: ${repository.repository} (already set${where}; differs from ${repository.expected}, left unchanged)\n`;
-    case "invalid_config": return `Repository: not recorded (${repository.path} is not a usable config; left unchanged)\n`;
-    case "skipped": return "Repository: not recorded (--no-repository)\n";
-    case "write_failed": return `Repository: not recorded (could not write ${repository.path})\n`;
-    default: return "Repository: not recorded (no owner/name git remote; pass --repository OWNER/NAME)\n";
+      ? `already set${where}` : `${repository.repository} (already set${where})`;
+    case "mismatch": return `${repository.repository} (already set${where}; differs from ${repository.expected}, left unchanged)`;
+    case "invalid_config": return `not recorded (${repository.path} is not a usable config; left unchanged)`;
+    case "skipped": return "not recorded (--no-repository)";
+    case "write_failed": return `not recorded (could not write ${repository.path})`;
+    default: return "not recorded (no owner/name git remote; pass --repository OWNER/NAME)";
   }
 }

package/src/constants.js

@@ -95,15 +95,35 @@ export const AUTH_PATHS = Object.freeze({
 // --limit locally.
 export const READ_PATHS = Object.freeze({
   usage: "/v1/agent/usage",
+  usageAggregates: "/v1/agent/usage/aggregates",
   routes: "/v1/agent/routes",
   traces: "/v1/agent/traces",
 });
 export const READ_QUERY_KEYS = Object.freeze({
-  "/v1/agent/usage": Object.freeze(["days", "limit"]),
-  "/v1/agent/traces": Object.freeze(["days", "limit", "route", "status", "cursor"]),
+  "/v1/agent/usage": Object.freeze(["days", "limit", "metadata"]),
+  "/v1/agent/usage/aggregates": Object.freeze([
+    "group_by", "days", "since", "until", "limit", "route", "provider", "model", "environment", "metadata",
+  ]),
+  "/v1/agent/traces": Object.freeze(["days", "limit", "route", "status", "cursor", "metadata"]),
   "/v1/cli/setup/credential": Object.freeze(["family_id"]),
 });
 
+// Query keys that may repeat on a path, one value each, as the service reads
+// list parameters. Every other key may appear at most once.
+export const READ_QUERY_REPEATABLE = Object.freeze({
+  // One group_by per dimension, so a metadata key is never split on a comma.
+  "/v1/agent/usage/aggregates": Object.freeze(["group_by", "route", "provider", "model", "environment"]),
+});
+
+// Grouped usage (GET /v1/agent/usage/aggregates). Dimensions the service can
+// group by (plus at most one "metadata.<key>"), the most values one filter may name, and how far apart the two
+// ends of an explicit window may be.
+export const USAGE_DIMENSIONS = Object.freeze(["provider", "model", "route", "day"]);
+export const USAGE_DEFAULT_GROUP_BY = Object.freeze(["provider", "model"]);
+export const USAGE_MAX_FILTER_VALUES = 20;
+export const USAGE_SORTS = Object.freeze(["cost", "cost-per-call", "calls", "errors", "avg-latency", "p95-latency", "day"]);
+export const USAGE_COMPARISONS = Object.freeze(["previous", "previous-same-time"]);
+
 // Read commands share one total deadline for every request they make,
 // including a token refresh. It is never reset per request or page.
 export const READ_DEFAULT_TIMEOUT_MS = 15000;
@@ -119,6 +139,15 @@ export const READ_DEFAULT_LIMIT = 50;
 export const TRACES_DEFAULT_LIMIT = 20;
 export const MAX_CURSOR_LENGTH = 512;
 export const MAX_FILTER_LENGTH = 256;
+// Exact customer-metadata filters, matching the service's bounds. The service
+// also refuses credential-like keys; the CLI checks the same rule first.
+export const MAX_METADATA_FILTERS = 5;
+export const MAX_METADATA_KEY_LENGTH = 200;
+export const MAX_METADATA_VALUE_LENGTH = 1000;
+// The longest query string the transport sends. Read arguments are checked
+// against the exact query they produce, so a long one is an input error
+// before any request rather than a failure after sign in.
+export const MAX_QUERY_LENGTH = 2048;
 
 // One exit code per outcome. Documented in README.md; changing a value is a
 // breaking change for scripts. New outcomes are appended.
@@ -175,7 +204,7 @@ export const EXIT_CODE_MEANINGS = Object.freeze({
     "The service does not make this read available to the project's Metadata grant. No data was read.",
   permission_denied:
     "The service refused this read for the signed in grant, for example for a missing scope or permission.",
-  rate_limited: "The service asked the CLI to slow down. Nothing was retried. Try again later.",
+  rate_limited: "The service asked the CLI to slow down. Try again later. Only setup retries, after a short Retry-After, to keep its approval.",
   cancelled:
     "A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry.",
   action_required: