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

package/README.md

@@ -1,7 +1,7 @@
 # metergraph-cli
 
-The Metergraph command line tool. This checkout is a **development preview**, version
-`0.2.0-preview.0`, which has not been published.
+The Metergraph command line tool. Version `0.2.0-preview.1` 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,42 +11,41 @@ npx --yes metergraph-cli@next doctor --json
 npm install -g metergraph-cli@next
 ```
 
-The installed command is `metergraph`. Pin `metergraph-cli@0.1.0` for that exact preview.
+The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.1`
+when you need this exact preview rather than whichever version `next` names later.
 
 **Availability:**
 
-- The published package, `metergraph-cli@0.1.0`, contains only `doctor` and
-  `skill install` / `skill update`. It has no sign in commands.
-- `login` and `logout`, described below, exist only in this checkout. They are an
-  upcoming preview: run them from a checkout or a locally packed tarball (see
-  [Development](#development)). Do not expect them from `npx metergraph-cli` until a
-  release that includes them is announced.
-- They also need a Metergraph service that offers Metadata-only CLI sign in and grant
+- `metergraph-cli@0.1.0` contains only `doctor` and `skill install` /
+  `skill update`. It has no sign in commands.
+- `metergraph-cli@0.2.0-preview.0` adds `login`, `logout`, `setup`, `verify`,
+  `status`, `context`, `capabilities`, `usage`, `routes` and `traces`.
+- `metergraph-cli@0.2.0-preview.1` makes `setup` write the SDK service root as
+  `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.
+- 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.
-- The read commands `status`, `context`, `capabilities`, `usage`, `routes` and `traces`
-  also exist only in this checkout and are part of the same unpublished upcoming preview.
-  They need a project signed in with `login`.
-- `setup` also exists only in this checkout. It guides sign in and workspace choice,
-  then requires the deployment's separate ingest bootstrap API and browser approval
-  by a member of that workspace.
-- `verify` also exists only in this checkout. It checks one exact trace identity in an
-  explicit invocation window using Metadata access. It never sends application data.
+- The read commands need a project signed in with `login`. `setup` also needs the
+  deployment's ingest bootstrap API and browser approval by a workspace member.
+  `verify` checks one exact trace identity in an explicit invocation window using
+  Metadata access. It never sends application data.
 
-This checkout includes:
+The preview includes:
 
 - `doctor` checks whether a Metergraph service is reachable, healthy and supported.
 - `skill install` and `skill update` copy the Metergraph agent skill bundled with the
   CLI into one coding agent's project skill directory.
-- `login` and `logout` (checkout only) sign a project in to one workspace through your
+- `login` and `logout` sign a project in to one workspace through your
   browser with a delegated, Metadata-only grant, and sign it out again.
-- The read commands (checkout only) use that grant to read bounded workspace Metadata:
+- The read commands use that grant to read bounded workspace Metadata:
   connection status, workspace context, capabilities, daily usage, routes and one page
   of trace metadata.
-- `setup` (checkout only) guides browser sign in and workspace choice, asks for
+- `setup` guides browser sign in and workspace choice, asks for
   ingest-only approval, writes a private project env file, confirms delivery, and
   installs the selected client skill.
-- `verify` (checkout only) polls for one exact processed trace in a bounded window.
+- `verify` polls for one exact processed trace in a bounded window.
   It does not infer application provenance from a Metadata match.
 
 It does not read retained content, replay traces, call model providers or send
@@ -205,7 +204,7 @@ does not match. It never downloads the skill or runs a remote script. A new skil
 revision ships only in a new CLI release; `skill update` then upgrades projects that
 hold an unchanged earlier revision.
 
-### login and logout (checkout only, unreleased)
+### login and logout
 
 `login` binds a project directory to one Metergraph workspace. Your browser does the
 sign in, sign up, invitation and workspace consent on the service's own pages and
@@ -296,7 +295,7 @@ revocation request. If it does not answer `200`, local sign out still happens an
 command exits 13 with `revocation: "unconfirmed"`. A project that is not signed in
 exits 0 without any request.
 
-### setup (checkout only, unreleased)
+### setup
 
 Run setup once from a project directory, choosing the coding client that will use
 the skill:
@@ -343,6 +342,11 @@ page shows the workspace and the consequence of approval. A signed-in browser
 on another workspace must switch in Metergraph and rerun; the CLI does not
 switch it automatically.
 
+`METERGRAPH_INGEST_URL` is the deployment's service root. The Python SDK
+appends `/v1/ingest` itself. A setup rerun with a verified
+key repairs the endpoint value written by the first preview without minting a
+new key.
+
 The env file must be a project-relative `.env`, `.env.<name>` or `<name>.env`
 (`--env-file` selects another). The writer refuses tracked files, links,
 ambiguous dotenv syntax and unsafe paths. It adds a project `.gitignore` rule
@@ -367,11 +371,11 @@ conflict leaves the delivered key in place and reports `credential_ready_skill_p
 resolve the skill file conflict and rerun setup without another approval.
 Success means the key was delivered and the project is ready to instrument.
 It does **not** mean application traffic has arrived. Run your application and
-verify one exact trace afterward. This checkout and the matching server slice
-are development work; neither their availability on a deployed service nor a
-published package has been established by these local tests.
+verify one exact trace afterward. The hosted service advertises the setup
+contract, but each non-hosted deployment must be checked at its own origin.
+Local protocol tests do not prove browser approval or real application traffic.
 
-### Read commands (checkout only, unreleased)
+### Read commands
 
 The read commands use the grant `login` saved for this project. They never open a
 browser, never sign in on their own and never request another scope. Each one:
@@ -512,8 +516,8 @@ before the failure, and `notices` lists fixed tokens such as `rows_truncated`,
 
 ## Exit codes
 
-Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 exist only in
-this checkout.
+Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 were
+added in `0.2.0-preview.0` and are unavailable in `0.1.0`.
 
 | Code | Outcome | Meaning |
 | --- | --- | --- |
@@ -618,7 +622,7 @@ A successful `skill install`:
   `receipt_invalid`, `locked`, `invalid_project`, `client_not_supported`,
   `write_failed` or `bundled_skill_invalid`.
 
-A successful `login` (checkout only):
+A successful `login`:
 
 ```json
 {
@@ -759,7 +763,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.0.tgz -- metergraph --version
+npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.1.tgz -- metergraph --version
 ```
 
 Do not commit tarballs or other generated files.
@@ -768,10 +772,9 @@ 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.
-The first preview uses the `next` npm tag. `0.1.0` is the only published version.
-This checkout's `0.2.0-preview.0` is not published and must not be published until
-the service side of sign in and the Metadata read endpoints are released. Subsequent releases must pass the checks
-below before publication.
+`0.2.0-preview.1` 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.
 
 Releases are manual. The `Release CLI` workflow (`.github/workflows/release.yml`) runs
 only when a maintainer starts it from `main`. It does not run on tags, pushes or a
@@ -803,12 +806,12 @@ commit:
 - If `main` moves after you copy the SHA, the run fails. Start a new run with the new
   head. To release an older state, land it on `main` first.
 
-### First package bootstrap
+### First package bootstrap (completed for 0.1.0)
 
 npm trusted publishing is configured on a package that already exists, so the very
-first version cannot come from this workflow. Creating the package is a one time,
-human step that a Metergraph maintainer must approve and perform. Nothing in this
-repository automates it, and no npm token or secret is stored here.
+first version could not come from this workflow. The steps below describe the
+completed bootstrap of `0.1.0`; they are not part of subsequent releases. No npm
+token or secret is stored here.
 
 1. Confirm the intended npm maintainer accounts and that `metergraph-cli` is
    available. The first approved publish establishes package ownership.
@@ -837,15 +840,13 @@ Trusted publishing requires npm 11.5.1 or newer. The publish job checks this bef
 publishes. After the trusted publisher works, consider restricting the package to
 trusted publishing so that long lived tokens cannot publish it.
 
-### Remaining maintainer setup
+### Release configuration
 
-The source repository and license are settled. Before any automated release, a
-maintainer still has to:
+Before an automated publish, confirm the following settings are still in place:
 
-- complete the [first package bootstrap](#first-package-bootstrap);
-- configure the [trusted publisher](#trusted-publishing);
-- create the `npm-release` environment with required reviewers;
-- set the repository variable `METERGRAPH_CLI_PUBLISH_ENABLED` to `true`.
+- the [trusted publisher](#trusted-publishing) matches this repository and workflow;
+- the `npm-release` environment has required reviewers;
+- the repository variable `METERGRAPH_CLI_PUBLISH_ENABLED` is `true`.
 
 Until all of these are done, leave `publish` false.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.0",
+  "version": "0.2.0-preview.1",
   "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/read-contract.js

@@ -1,5 +1,6 @@
 import { normalizeUuid } from "./auth-oauth.js";
 import { AGENT_CONTRACT_VERSION, MAX_CURSOR_LENGTH, METADATA_SCOPE } from "./constants.js";
+import { traceLink } from "./trace-contract.js";
 
 // Validators for the service's Metadata read documents. Each one checks the
 // document against the agent access contract, the bound workspace and the
@@ -530,6 +531,8 @@ export function tracesReport(body, ctx, request, notices) {
       ) {
         throw new Invalid("verification_failed", reason);
       }
+      const link = traceLink(row.metergraph_links?.trace ?? null, ctx.origin, row, ctx.workspaceId);
+      if (!link.ok) throw new Invalid(link.outcome, link.reason);
       return {
         id: row.id,
         trace_id: row.trace_id,
@@ -546,12 +549,16 @@ export function tracesReport(body, ctx, request, notices) {
         routes: nameList(row.routes, notices, reason),
         providers: nameList(row.providers, notices, reason),
         models: nameList(row.models, notices, reason),
-        link: null,
+        link: link.value,
+        link_workspace_bound: link.workspaceBound === true,
       };
     });
     if (!proof.complete) notices.add("evidence_incomplete");
     if (page.truncated) notices.add("more_pages");
-    notices.add("trace_links_unavailable");
+    const missingLinks = traces.length === 0 || traces.some((trace) => trace.link === null);
+    if (missingLinks) notices.add("trace_links_unavailable");
+    const unboundLinks = traces.some((trace) => trace.link !== null && !trace.link_workspace_bound);
+    if (unboundLinks) notices.add("trace_workspace_binding_unavailable");
     return {
       provenance: origin,
       window: span,
@@ -570,7 +577,8 @@ export function tracesReport(body, ctx, request, notices) {
       next_cursor: page.next_cursor,
       complete: proof.complete && !page.truncated,
       empty: traces.length === 0,
-      link_status: "server_link_unavailable",
+      link_status: missingLinks ? "server_link_unavailable" :
+        unboundLinks ? "workspace_binding_unavailable" : "available",
       traces,
     };
   });

package/src/setup-env-parse.js

@@ -13,14 +13,14 @@ export const ENV_NAMES = Object.freeze({
 });
 const NAMES = Object.values(ENV_NAMES);
 
-// Ingest paths the service accepts on an origin. A URL with any other path,
-// a query, a fragment or user information is refused.
-export const INGEST_PATHS = Object.freeze(["/v1/ingest"]);
+// The SDK expects a service root and appends /v1/ingest itself. Accept the
+// endpoint form only while reading setup files written by the first preview.
+export const INGEST_PATHS = Object.freeze(["", "/v1/ingest"]);
 
 // Server-generated application tokens are RFC 3986 unreserved characters
 // only, so a value can never carry a quote, newline, comment or space.
 const TOKEN = /^[A-Za-z0-9._~-]{16,1024}$/;
-const URL_TEXT = /^(https?:\/\/[^/?#@\\]+)(\/[A-Za-z0-9/_.-]*)$/i;
+const URL_TEXT = /^(https?:\/\/[^/?#@\\]+)(\/[A-Za-z0-9/_.-]*)?$/i;
 const SAFE_URL = /^[A-Za-z0-9.:/[\]_-]+$/;
 
 const ASSIGNMENT = /^([ \t]*)(export[ \t]+)?([A-Za-z_][A-Za-z0-9_.-]*)([ \t]*=[ \t]*)(.*)$/;
@@ -35,15 +35,15 @@ export function isAppToken(value) {
   return typeof value === "string" && TOKEN.test(value);
 }
 
-// Returns the normalized ingest URL (origin plus a supported path) or null.
+// Returns the normalized service root or legacy ingest endpoint, or null.
 // The caller must not echo the raw input when this returns null.
 export function parseIngestUrl(raw) {
   if (typeof raw !== "string" || raw.length > 2048) return null;
   const match = URL_TEXT.exec(raw);
-  if (match === null || !INGEST_PATHS.includes(match[2])) return null;
+  if (match === null || !INGEST_PATHS.includes(match[2] ?? "")) return null;
   const origin = parseOrigin(match[1]);
   if (origin === null) return null;
-  const url = `${origin}${match[2]}`;
+  const url = `${origin}${match[2] ?? ""}`;
   return SAFE_URL.test(url) ? url : null;
 }
 

package/src/setup.js

@@ -111,7 +111,9 @@ export async function runSetup(options, progress = () => {}) {
     if (previous && existing.token !== null) {
       const checked = await checkCredential(origin, existing.token, previous.value, profile, trap.signal);
       if (checked.ok) {
-        if (existing.ingestUrl !== `${origin}/v1/ingest`) return stop("conflict", "ingest_url_mismatch");
+        if (existing.ingestUrl !== origin && existing.ingestUrl !== `${origin}/v1/ingest`) {
+          return stop("conflict", "ingest_url_mismatch");
+        }
         if (previous.value.key_id !== null && previous.value.key_id !== checked.keyId) {
           return stop("conflict", "setup_key_changed");
         }
@@ -121,6 +123,13 @@ export async function runSetup(options, progress = () => {}) {
         if (previous.value.phase !== "delivered" || previous.value.key_id === null) {
           writeSetupState(root, withSetupState(previous.value, { key_id: checked.keyId, phase: "delivered" }), previous);
         }
+        // The first preview wrote the endpoint, which the SDK appends again.
+        // Repair only after verifying this family's saved key, without issuing
+        // another key or changing the workspace binding.
+        if (existing.ingestUrl !== origin) {
+          const repaired = await commitEnv(plan, { ingestUrl: origin, signal: trap.signal });
+          return finishSkill(root, options, repaired.receipt.file);
+        }
         return finishSkill(root, options, "unchanged");
       }
       if (!options.repair && previous.value.phase !== "redeem_attempted") return stop("verification_failed", "saved_key_unverified");
@@ -188,7 +197,7 @@ export async function runSetup(options, progress = () => {}) {
       redirect_uri: listener.redirectUri, code_verifier: pkce.verifier,
       family_id: state.family_id, workspace_id: workspaceId }, profile, trap.signal);
     if (!redeemed.ok) return stop(redeemed.outcome, redeemed.reason, "delivery_pending");
-    const written = await commitEnv(plan, { token: redeemed.token, ingestUrl: `${origin}/v1/ingest`, signal: trap.signal });
+    const written = await commitEnv(plan, { token: redeemed.token, ingestUrl: origin, signal: trap.signal });
     const checked = await checkCredential(origin, redeemed.token, state, profile, trap.signal);
     if (!checked.ok || checked.keyId !== redeemed.keyId) return stop("verification_failed", "issued_key_unverified", "delivery_pending");
     const ack = await acknowledge(origin, redeemed.token, state, profile, redeemed.keyId, trap.signal);