metergraph-cli 0.2.0-preview.1 → 0.2.0-preview.2

package/README.md

@@ -1,6 +1,6 @@
 # metergraph-cli
 
-The Metergraph command line tool. Version `0.2.0-preview.1` is published on the
+The Metergraph command line tool. Version `0.2.0-preview.2` is published on the
 `next` npm tag. The `latest` tag remains on `0.1.0`.
 
 Install the released preview channel with npm or run it directly:
@@ -11,7 +11,7 @@ npx --yes metergraph-cli@next doctor --json
 npm install -g metergraph-cli@next
 ```
 
-The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.1`
+The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.2`
 when you need this exact preview rather than whichever version `next` names later.
 
 **Availability:**
@@ -24,6 +24,10 @@ when you need this exact preview rather than whichever version `next` names late
   `METERGRAPH_INGEST_URL` and repairs the full ingest endpoint that
   `0.2.0-preview.0` wrote, after checking the saved key. It also keeps validated,
   workspace-bound trace links in Metadata reads.
+- `metergraph-cli@0.2.0-preview.2` makes `verify` exit 11 `verification_failed`
+  when its deadline expires after the service reported the trace as pending, lets
+  `login` and `setup` reruns that need no approval succeed with `--json
+  --no-browser`, and reports why `verify --open` did not launch a browser.
 - Sign in needs a Metergraph service that offers Metadata-only CLI grants and grant
   revocation. A service without them is reported as unsupported, and the CLI never
   falls back to broader access.
@@ -100,7 +104,16 @@ sends a test event.
 `--open` launches only a server-provided link carrying the exact trace and the
 verified workspace ID. The dashboard must check that ID against its signed-in
 workspace before displaying traces. Older links without a workspace remain a
-manual handoff; a conflicting workspace or unsafe link is refused.
+manual handoff; a conflicting workspace or unsafe link is refused. The result's
+`browser` field is `launcher_started`, `launcher_unavailable`, `not_requested`
+(no `--open`), or `suppressed_by_json` / `suppressed_by_no_browser` when `--open`
+was given but that flag returned the link instead of launching it.
+
+If `--timeout-ms` expires after the service has answered at least once with a
+pending result, `verify` exits 11 `verification_failed` with reason
+`verification_timeout`: the origin is reachable and the trace is not visible yet.
+Exit 4 `connection_failed` with that reason means no valid answer arrived before
+the deadline.
 
 ### doctor
 
@@ -225,7 +238,7 @@ metergraph logout
 | `--config-dir DIR` | see below | Private per-user directory for the saved grant. |
 | `--timeout-ms N` | `300000` | How long to wait for the browser, 1000 to 900000. |
 | `--signup` | off | Start at the hosted sign up page, which returns to the same authorization request. Managed service only; other profiles exit 6. |
-| `--no-browser` | off | Print the authorization URL on stderr for you to open on this machine, then wait. Not with `--json`. |
+| `--no-browser` | off | Print the authorization URL on stderr for you to open on this machine, then wait. With `--json`, a rerun that needs no approval succeeds; one that needs approval exits 6 `no_browser_requires_terminal`. |
 | `--reconnect` | off | Allow replacing a binding to a different origin or workspace. |
 | `--json` | off | Print exactly one JSON line on stdout and nothing on stderr. |
 
@@ -763,7 +776,7 @@ To try a packed artifact without publishing:
 
 ```sh
 npm pack --pack-destination "$(mktemp -d)"
-npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.1.tgz -- metergraph --version
+npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.2.tgz -- metergraph --version
 ```
 
 Do not commit tarballs or other generated files.
@@ -772,7 +785,7 @@ Do not commit tarballs or other generated files.
 
 The source of truth is the public repository
 [github.com/metergraph/cli](https://github.com/metergraph/cli), licensed Apache-2.0.
-`0.2.0-preview.1` is published on the `next` npm tag; `latest` remains on
+`0.2.0-preview.2` is published on the `next` npm tag; `latest` remains on
 `0.1.0`. The hosted service supports sign in, Metadata reads and ingest bootstrap.
 Subsequent releases must pass the checks below before publication.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.1",
+  "version": "0.2.0-preview.2",
   "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": {

package/src/auth-login.js

@@ -58,12 +58,13 @@ export async function runLogin(options, progress) {
   if (options.runtime !== "local") return end("unsupported", "runtime_not_supported", GUIDE);
   const remote = detectRemoteSession();
   if (remote !== null) return end("unsupported", remote, GUIDE);
-  if (options.json && options.noBrowser) {
-    return end("unsupported", "no_browser_requires_terminal", {
-      kind: "run_in_terminal",
-      message: "Run the same login command in a terminal without --json to see the sign in URL.",
-    });
-  }
+  // --json cannot show a person the --no-browser URL. A rerun with a saved,
+  // working grant needs no URL, so only refuse once approval is required.
+  const noBrowserHandoff = () => end("unsupported", "no_browser_requires_terminal", {
+    kind: "run_in_terminal",
+    message: "Run the same login command in a terminal without --json to see the sign in URL.",
+  });
+  const urlUnshowable = options.json && options.noBrowser;
 
   const trap = trapSignals();
   try {
@@ -71,6 +72,7 @@ export async function runLogin(options, progress) {
     const configDir = resolveConfigDir(options.configDir);
     const existing = readBinding(root);
     const bound = existing?.binding ?? null;
+    if (urlUnshowable && (bound === null || options.reconnect)) return noBrowserHandoff();
     // Setup pins a deployment model before sign in. A stale binding for a
     // different profile must never be silently reused or reconnected.
     if (options.expectedProfile && bound !== null && !options.reconnect &&
@@ -100,6 +102,7 @@ export async function runLogin(options, progress) {
       }
       if (session.outcome !== "login_required") return end(session.outcome, session.reason);
     }
+    if (urlUnshowable) return noBrowserHandoff();
 
     const flow = await authorize(options, ctx, trap.signal, progress);
     if (!flow.ok) return end(flow.outcome, flow.reason, flow.next ?? null);

package/src/output.js

@@ -599,8 +599,8 @@ const AUTH_MESSAGES = {
   ci_environment:
     "This is a CI environment, where no person can approve sign in in a browser. Nothing was written.",
   no_browser_requires_terminal:
-    "--no-browser prints the sign in URL for a person to open, which --json cannot do. " +
-    "Run login without --json in a terminal. Nothing was done.",
+    "Approval is needed, and --no-browser prints its URL for a person to open, which --json cannot do. " +
+    "Run the same command without --json in a terminal. Nothing was done.",
   bound_to_other_origin:
     "This project is bound to a different origin. Nothing was changed. Use --reconnect to switch it.",
   bound_to_other_workspace:

package/src/setup.js

@@ -31,7 +31,6 @@ const fail = (outcome, reason, status = "not_ready", receipt = null) => ({ outco
 // response can supply it. Every returned string is fixed and non-secret.
 export async function runSetup(options, progress = () => {}) {
   if (options.runtime !== "local" || detectRemoteSession() !== null) return fail("unsupported", "run_on_local_machine");
-  if (options.json && options.noBrowser) return fail("unsupported", "no_browser_requires_terminal");
   const trap = trapSignals();
   let receipt = null;
   let loginVerified = false;
@@ -138,6 +137,9 @@ export async function runSetup(options, progress = () => {}) {
       return stop("conflict", "repair_requires_saved_key");
     }
 
+    // A verified rerun returned above without approval. From here a person
+    // must open an approval URL, which --json cannot show with --no-browser.
+    if (options.json && options.noBrowser) return stop("unsupported", "no_browser_requires_terminal");
     const setup = await discoverSetup(origin, profile, trap.signal);
     if (!setup.ok) return stop(setup.outcome, setup.reason);
 

package/src/trace-open.js

@@ -4,7 +4,8 @@ import { normalizeUuid } from "./auth-oauth.js";
 import { parseOrigin } from "./origin.js";
 
 // Operates only on an already verified, provenance-bound receipt. JSON and
-// no-browser mode return its URL without starting a launcher. "opened" means
+// no-browser mode return its URL without starting a launcher, and say which
+// one suppressed an --open request. "opened" means
 // the OS launcher started; it does not assert a browser rendered the page.
 export async function openTrace(receipt, options = {}, launch = openBrowser) {
   if (receipt?.readiness?.metadata_available !== true || receipt?.readiness?.processed !== true ||
@@ -20,7 +21,11 @@ export async function openTrace(receipt, options = {}, launch = openBrowser) {
   if (link.workspaceBound !== true || receipt.link_workspace_bound !== true || receipt.link_status !== "available") {
     return { outcome: "unsupported", reason: "link_workspace_binding_unavailable", data: { ...receipt, browser: "not_requested" } };
   }
-  if (options.json || options.noBrowser || !options.open) return { outcome: "ok", reason: null, data: { ...receipt, browser: "not_requested" } };
+  if (!options.open) return { outcome: "ok", reason: null, data: { ...receipt, browser: "not_requested" } };
+  if (options.json || options.noBrowser) {
+    const browser = options.json ? "suppressed_by_json" : "suppressed_by_no_browser";
+    return { outcome: "ok", reason: null, data: { ...receipt, browser } };
+  }
   if (options.signal?.aborted) return { outcome: "cancelled", reason: "cancelled", data: receipt };
   const launched = await launchWithinSignal(link.value, launch, options.signal);
   if (options.signal?.aborted) return { outcome: "cancelled", reason: "cancelled", data: receipt };

package/src/verify.js

@@ -33,7 +33,10 @@ export async function runVerify(options, dependencies = {}) {
     if (holdsKnown(data, known)) return { outcome: "verification_failed", reason: "credential_in_metadata_response", data: null };
     return { outcome, reason, data: data === null ? null : { ...data, attempts } };
   };
-  const interrupted = () => limit.timedOut() ? end("connection_failed", "verification_timeout") : end("cancelled", "cancelled");
+  // Once the origin has answered with a valid pending receipt, a deadline
+  // means the trace is not visible yet, not that the origin is unreachable.
+  const interrupted = () => !limit.timedOut() ? end("cancelled", "cancelled")
+    : end(receipt === null ? "connection_failed" : "verification_failed", "verification_timeout");
   try {
     const sessionResult = await (dependencies.session ?? verifiedSession)({ project: options.project, configDir: options.configDir, cancel: limit.signal });
     if (limit.signal.aborted) return interrupted();