metergraph-cli 0.0.0-stage → 0.1.0

package/assets/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: metergraph
+description: Route Metergraph setup by client, execution runtime and deployment, then perform bounded evidence-backed investigation when already authenticated.
+---
+
+# Use Metergraph with your agent
+
+Public setup: https://www.metergraph.dev/docs/guides/agent-access/
+Connection and troubleshooting: https://www.metergraph.dev/docs/guides/agent-access/
+
+## Confirm setup before producing instructions
+
+Ask for or confirm these non-secret choices. Do not guess from the agent brand:
+
+1. Client: Claude Desktop, Claude Code, ChatGPT or Codex.
+2. Execution runtime: customer machine or cloud. Codex local app/CLI/IDE is distinct from cloud execution. Claude Desktop remote connectors execute in Anthropic's cloud; Desktop local MCP is a separate mechanism. ChatGPT MCP apps execute in the cloud.
+3. Deployment: Metergraph hosted cloud, the signed commercial customer-local bundle, a customer-owned AWS installation (`byoc-core`), or the open-source self-hosted server. These have different addresses, accounts and credentials. Staging is not a customer setup path.
+4. Fresh workspace/installation or connecting an existing workspace. Ask for the intended workspace name and deployment origin, never a token.
+
+Use the routing below with those four choices. Follow the matching credential and client configuration instructions in the connection guide.
+
+## Route honestly
+
+| Client and runtime | Hosted | Customer-local bundle | Customer AWS | Open source self-hosted |
+| --- | --- | --- | --- | --- |
+| Claude Code or Codex on the customer machine | Keyed HTTP at `https://app.metergraph.dev/v1/agent/mcp` | Keyed HTTP at the installed local address, normally `http://127.0.0.1:8080/v1/agent/mcp` | Keyed HTTP at the customer's reachable installation address | Static `MG_AGENT_TOKENS` bearer at the OSS server address, normally `http://localhost:8787/v1/agent/mcp` |
+| Claude Desktop remote connector on an individual account | Custom connector with a scoped bearer key if Request headers are available for the account; verify tools before claiming success | Cannot reach localhost from Anthropic's cloud | Default private installation is unreachable from Anthropic's cloud; no validated public route in this guide | Cannot reach localhost from Anthropic's cloud |
+| Claude Desktop local MCP | Separate local extension required; not supported by this guide | Docker does not install a host extension | Separate local extension required; not supported by this guide | Docker does not install a host extension |
+| ChatGPT MCP app or cloud execution | Separate cloud client configuration; not supported by this guide | Cannot reach localhost | Default private installation is unreachable | Cannot reach localhost |
+
+For hosted Claude Desktop on an individual account, guide the human through Customize → Connectors → Add custom connector with `https://app.metergraph.dev/v1/agent/mcp`. They create a coding-agent key in the intended hosted workspace. If Request headers are available, choose No sign-in and enter a required header named `Authorization` with value `Bearer <key>` in the connector's private settings, never in chat. Request headers are in beta and may be unavailable for the account; do not claim the route works without them. They must enable the connector in a conversation. Team and Enterprise connectors may share fixed credentials across users, so do not put one person's workspace key in a shared connector. Do not present OAuth server code, a tool listing, local CLI installation or a saved configuration as connection success. Do not invent a released plugin, extension, tunnel or signup path. If a route is blocked, name the blocker and offer the customer-machine Claude Code/Codex keyed HTTP route or hosted deployment as appropriate. Do not expose localhost publicly or disable authentication as a workaround.
+
+For a fresh hosted workspace, first ask whether the human already has a Metergraph account and workspace. Direct them to https://app.metergraph.dev/ and the signup, invitation or sign-in flow actually offered. The hosted UI can offer "Get a free API key" for self-service signup, but do not assume that button or a workspace invitation is available to everyone. If access is unavailable, direct them to their workspace owner or Metergraph. Confirm the workspace before creating a coding-agent key.
+
+For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands.
+
+For customer-owned AWS, direct them to https://www.metergraph.dev/docs/self-host/aws/. An operator provisions the installation, identity and membership. There is no public signup. Ask for the installation's actual reachable address and use a coding-agent key from its Keys page. Its default internal load balancer is private, and its Agent Access surface excludes trace content and replay.
+
+For the open-source self-hosted server, direct them to https://www.metergraph.dev/docs/self-host/local/#the-open-source-server. No Metergraph account, commercial release, registry credential or Keys page is needed. The operator configures static `MG_AGENT_TOKENS` separately from ingestion `MG_TOKENS`. Agent Access is content-blind and does not provide replay, incidents, ingestion health or pipeline reports. Use the actual local server address; do not ask them to mint a hosted coding-agent key.
+
+## Keep credentials outside chat
+
+Direct the human to the correct workspace's Keys page and private client configuration. Leave replay disabled unless separately authorized. Never ask for, quote, log or include raw keys in a prompt. Registry pull, ingestion, Agent Access and model/provider credentials are different credentials. Use the client's supported secure environment/settings input. Keep token-bearing configuration out of shell history and committed project files. Rotation/revocation happens in Keys; a revoked token must be rejected on the next request.
+
+## Answer capability and documentation questions
+
+Use https://www.metergraph.dev/docs/ for public product documentation and https://www.metergraph.dev/docs/guides/mcp-server/ for Agent Access tool details. Explain what the docs say about an edition, then use `metergraph_get_capabilities` to confirm what the connected workspace actually supports. Cite the public page you used and distinguish a missing capability from an empty workspace. Do not read retained content or run replay just to answer a documentation question.
+
+## When already connected: bounded investigation
+
+1. Call `metergraph_get_workspace_context` and `metergraph_get_capabilities` first. Verify the intended workspace, deployment profile, available tools, required scopes and privacy classes. Stop on wrong workspace, unavailable capabilities or failed authorization.
+2. Confirm the question, route and explicit time window. Choose the smallest available tool: bounded usage/route metadata for aggregate questions, incidents for known anomalies, or `metergraph_query_traces` with a small limit (start with 1) for a failed/anomalous trace. Follow cursors only within the agreed bound. Never request generic SQL or unbounded data.
+3. Start with metadata. Retained-content debugging and report evidence are separate content-bearing tools; confirm the user's content intent and capability before calling them. Replay is a separate scope and can send data to a provider and spend money. Obtain explicit bounded execution/data-egress authority before any replay. Read access grants no eval-write, analysis-run or production-mutation authority.
+4. Explain the failure or anomaly using only returned evidence. Cite workspace, time window, provenance, trace/report IDs, completeness/coverage, warnings and working app links when returned. Do not fabricate links. Distinguish no data, incomplete evidence, unavailable capability, classification pending, stale/mismatched identity, failed analysis and missing report. An empty result alone does not prove absence of traffic.
+5. An optional approved replay must be eligible, bounded and non-persistent. Do not claim that it changed production telemetry or fixed the application. Refuse autonomous dashboard mutations or production configuration changes.
+
+For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/ after confirming the ingestion destination and obtaining a separate ingest credential securely. Do not initiate provider calls or paid work merely to validate setup. Ingestion accepted, processed, retained content, classification readiness and analysis readiness are distinct states. Label synthetic/demo fixtures; they do not prove a first real application trace.

package/assets/skill/manifest.json

@@ -0,0 +1,9 @@
+{
+  "manifest_version": 1,
+  "name": "metergraph",
+  "file": "SKILL.md",
+  "source_url": "https://www.metergraph.dev/SKILL.md",
+  "sha256": "90f7d8d78a5b0b7a57436f194222f0c73310b0b04201c297c8fbf0b00ad6bb3f",
+  "size": 9149,
+  "revision": "sha256-90f7d8d78a5b"
+}

package/bin/metergraph.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+// A closed pipe on stdout (for example "metergraph --help | head -1") is not
+// a CLI failure.
+process.stdout.on("error", () => {});
+
+process.exitCode = await main(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+});

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "metergraph-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Preview Metergraph command line tool with a read-only connection probe and a project skill installer",
+  "type": "module",
+  "bin": {
+    "metergraph": "bin/metergraph.js"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/metergraph.js",
+    "src/*.js",
+    "assets/skill/SKILL.md",
+    "assets/skill/manifest.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:package": "node --test test/package/*.test.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "author": "Metergraph",
+  "homepage": "https://www.metergraph.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metergraph/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metergraph/cli/issues"
+  },
+  "keywords": [
+    "metergraph",
+    "cli",
+    "llm",
+    "cost-tracking"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.js

@@ -0,0 +1,180 @@
+import {
+  DEFAULT_ORIGIN,
+  DEFAULT_TIMEOUT_MS,
+  HANDOFF_SKILL_CLIENTS,
+  HANDOFF_SKILL_RUNTIMES,
+  MAX_TIMEOUT_MS,
+  MIN_TIMEOUT_MS,
+  SKILL_CLIENTS,
+  SKILL_RUNTIMES,
+} from "./constants.js";
+import { parseOrigin } from "./origin.js";
+
+const COMMANDS = new Set(["doctor", "help", "skill"]);
+const HELP_TOPICS = new Set(["doctor", "skill"]);
+const SKILL_ACTIONS = new Set(["install", "update"]);
+const OPTIONS = {
+  doctor: new Set(["--url", "--timeout-ms"]),
+  skill: new Set(["--client", "--runtime", "--project"]),
+};
+
+// 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 }
+// Error messages are fixed strings. They never contain an argument value,
+// because a mistyped argument can be a credential.
+export function parseArgs(argv) {
+  const json = argv.includes("--json");
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    const topic = argv.find((arg) => HELP_TOPICS.has(arg)) ?? null;
+    return { ok: true, command: "help", topic, json };
+  }
+
+  let command = null;
+  let action = null;
+  let topic = null;
+  let version = false;
+  const values = {};
+
+  const fail = (code, message) => ({
+    ok: false,
+    command: command === "skill" && action !== null ? `skill ${action}` : command ?? (version ? "version" : null),
+    json,
+    code,
+    message,
+  });
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const position = index + 1;
+
+    if (arg === "--json") continue;
+
+    if (command === null && !version && COMMANDS.has(arg)) {
+      command = arg;
+      continue;
+    }
+    if (command === null && arg === "--version") {
+      version = true;
+      continue;
+    }
+    if (command === "help" && topic === null && HELP_TOPICS.has(arg)) {
+      topic = arg;
+      continue;
+    }
+    if (command === "skill" && action === null && SKILL_ACTIONS.has(arg)) {
+      action = arg;
+      continue;
+    }
+
+    if (command === "doctor" || command === "skill") {
+      const equals = arg.indexOf("=");
+      const name = equals === -1 ? arg : arg.slice(0, equals);
+      if (OPTIONS[command].has(name)) {
+        let value;
+        if (equals === -1) {
+          index += 1;
+          value = argv[index];
+        } else {
+          value = arg.slice(equals + 1);
+        }
+        if (value === undefined) {
+          return fail("missing_value", `${name} requires a value.`);
+        }
+        if (values[name] !== undefined) {
+          return fail("duplicate_option", `${name} may be given only once.`);
+        }
+        values[name] = value;
+        continue;
+      }
+    }
+
+    if (command === null && !version && !arg.startsWith("-")) {
+      return fail(
+        "unknown_command",
+        `Unknown command at argument ${position}. Run "metergraph --help" for usage.`,
+      );
+    }
+    if (command === "skill" && action === null && !arg.startsWith("-")) {
+      return fail(
+        "unknown_subcommand",
+        `Unknown skill subcommand at argument ${position}. Use install or update.`,
+      );
+    }
+    return fail(
+      "unknown_argument",
+      `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
+    );
+  }
+
+  if (version) return { ok: true, command: "version", json };
+  if (command === null || command === "help") {
+    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.",
+    );
+  }
+
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs =
+    rawTimeout === undefined ? DEFAULT_TIMEOUT_MS : parseTimeout(rawTimeout);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${MIN_TIMEOUT_MS} to ${MAX_TIMEOUT_MS}.`,
+    );
+  }
+
+  return { ok: true, command: "doctor", origin, timeoutMs, 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.
+function parseSkill(action, values, json, fail) {
+  if (action === null) {
+    return fail(
+      "missing_subcommand",
+      'skill requires a subcommand: install or update. Run "metergraph help skill" for usage.',
+    );
+  }
+  const client = values["--client"];
+  if (client === undefined) {
+    return fail("missing_client", "--client is required. Use codex, claude or cursor.");
+  }
+  if (!Object.hasOwn(SKILL_CLIENTS, client) && !Object.hasOwn(HANDOFF_SKILL_CLIENTS, client)) {
+    return fail("invalid_client", "--client must be codex, claude or cursor.");
+  }
+  const runtime = values["--runtime"];
+  if (runtime === undefined) {
+    return fail("missing_runtime", "--runtime is required. Use local or cloud.");
+  }
+  if (!SKILL_RUNTIMES.includes(runtime) && !HANDOFF_SKILL_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local or cloud.");
+  }
+  const project = values["--project"];
+  if (project !== undefined && (project === "" || project.includes("\0"))) {
+    return fail("invalid_project", "--project must name an existing directory.");
+  }
+  return { ok: true, command: "skill", action, client, runtime, project: project ?? null, json };
+}
+
+function parseTimeout(raw) {
+  if (!/^[0-9]{1,6}$/.test(raw)) return null;
+  const value = Number(raw);
+  if (value < MIN_TIMEOUT_MS || value > MAX_TIMEOUT_MS) return null;
+  return value;
+}

package/src/cli.js

@@ -0,0 +1,90 @@
+import { parseArgs } from "./args.js";
+import { runDoctor } from "./doctor.js";
+import {
+  doctorMessage,
+  doctorText,
+  envelope,
+  helpData,
+  helpText,
+  skillText,
+  toJsonLine,
+  versionData,
+} from "./output.js";
+import { runSkill } from "./skill.js";
+import { VERSION } from "./constants.js";
+
+// Runs one command and resolves with the exit code. With --json, stdout gets
+// exactly one JSON line and stderr stays empty. Without it, results go to
+// stdout and usage or internal errors go to stderr. Never reads stdin.
+export async function main(argv, { stdout, stderr }) {
+  const json = argv.includes("--json");
+  let result;
+  try {
+    result = await run(argv, { stdout, stderr });
+  } catch {
+    result = envelope({
+      command: null,
+      outcome: "internal_error",
+      reason: "unexpected_failure",
+      message: "The CLI failed unexpectedly. No details are shown to avoid exposing sensitive input.",
+    });
+    if (json) stdout.write(toJsonLine(result));
+    else stderr.write(`Error: ${result.error.message}\n`);
+  }
+  return result.exit_code;
+}
+
+async function run(argv, { stdout, stderr }) {
+  const parsed = parseArgs(argv);
+
+  if (!parsed.ok) {
+    const result = envelope({
+      command: parsed.command,
+      outcome: "invalid_input",
+      reason: parsed.code,
+      message: parsed.message,
+    });
+    if (parsed.json) stdout.write(toJsonLine(result));
+    else stderr.write(`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));
+    return result;
+  }
+
+  if (parsed.command === "version") {
+    const result = envelope({ command: "version", outcome: "ok", data: versionData() });
+    stdout.write(parsed.json ? toJsonLine(result) : `${VERSION}\n`);
+    return result;
+  }
+
+  if (parsed.command === "skill") {
+    const { outcome, reason, message, data } = runSkill(parsed);
+    const result = envelope({
+      command: `skill ${parsed.action}`,
+      outcome,
+      reason,
+      data,
+      message: outcome === "ok" ? null : message,
+    });
+    stdout.write(parsed.json ? toJsonLine(result) : skillText(result, message));
+    return result;
+  }
+
+  const { outcome, reason, report } = await runDoctor({
+    origin: parsed.origin,
+    timeoutMs: parsed.timeoutMs,
+  });
+  const result = envelope({
+    command: "doctor",
+    outcome,
+    reason,
+    data: report,
+    message: doctorMessage(outcome, reason),
+  });
+  stdout.write(parsed.json ? toJsonLine(result) : doctorText(result));
+  return result;
+}

package/src/constants.js

@@ -0,0 +1,81 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export const PACKAGE_NAME = packageJson.name;
+export const VERSION = packageJson.version;
+
+export const SCHEMA_VERSION = 1;
+export const DEFAULT_ORIGIN = "https://app.metergraph.dev";
+
+export const DEFAULT_TIMEOUT_MS = 5000;
+export const MIN_TIMEOUT_MS = 100;
+export const MAX_TIMEOUT_MS = 30000;
+export const MAX_BODY_BYTES = 32 * 1024;
+
+// The public guide a person follows to connect an application to Metergraph.
+// The CLI cannot sign in yet, so this is the only next action it offers.
+export const CONNECTION_GUIDE_URL =
+  "https://www.metergraph.dev/docs/guides/agent-access/";
+
+// Deployment profiles recognized by the probe contract. Any other value,
+// including a well-formed one, is reported as unsupported and never echoed.
+export const SUPPORTED_PROFILES = Object.freeze([
+  "local",
+  "managed",
+  "byoc-core",
+]);
+
+// Clients that load project skills from a native directory, from each
+// client's own documentation. Every client has its own directory, so
+// installing for one never touches another client's files.
+export const SKILL_CLIENTS = Object.freeze({
+  codex: Object.freeze({ label: "Codex", dir: ".agents" }),
+  claude: Object.freeze({ label: "Claude Code", dir: ".claude" }),
+  cursor: Object.freeze({ label: "Cursor", dir: ".cursor" }),
+});
+export const SKILL_RUNTIMES = Object.freeze(["local", "cloud"]);
+
+// Recognized values that cannot load project skill files. They get a pointer
+// to the connection guide instead of a usage error, and nothing is written.
+export const HANDOFF_SKILL_CLIENTS = Object.freeze({
+  "claude-desktop": "Claude Desktop",
+  chatgpt: "ChatGPT",
+});
+export const HANDOFF_SKILL_RUNTIMES = Object.freeze(["cloud-no-shell"]);
+
+// One exit code per outcome. Documented in README.md; changing a value is a
+// breaking change for scripts. New outcomes are appended.
+export const EXIT_CODES = Object.freeze({
+  ok: 0,
+  internal_error: 1,
+  invalid_input: 2,
+  authentication_required: 3,
+  connection_failed: 4,
+  unhealthy: 5,
+  unsupported: 6,
+  redirect_rejected: 7,
+  conflict: 8,
+  filesystem_error: 9,
+});
+
+export const EXIT_CODE_MEANINGS = Object.freeze({
+  ok: "Command succeeded. Doctor does not return this in this preview.",
+  internal_error: "Unexpected internal failure in the CLI.",
+  invalid_input: "Unknown command or argument, or an invalid option value. No request was made.",
+  authentication_required:
+    "Service is reachable, healthy and supported, and requires authentication. No workspace is connected.",
+  connection_failed: "The origin could not be reached, the connection failed, or the probe timed out.",
+  unhealthy:
+    "The service answered but reported that it is not healthy, or answered with a server error.",
+  unsupported:
+    "The service answered with a response, deployment profile or status this CLI does not support, " +
+    "or the skill client or runtime cannot use project skill files. Nothing was written.",
+  redirect_rejected: "The service answered with a redirect. Redirects are never followed.",
+  conflict:
+    "The skill target is not owned by this CLI, was modified, is unsafe, is locked or needs an explicit update. Nothing was changed.",
+  filesystem_error:
+    "Project files could not be read or written. Partial changes were rolled back unless the message says otherwise.",
+});