metergraph-cli 0.0.0-stage → 0.1.0

package/src/doctor.js

@@ -0,0 +1,198 @@
+import { CONNECTION_GUIDE_URL, SUPPORTED_PROFILES } from "./constants.js";
+import { get, parseJsonObject } from "./http.js";
+
+const CHECKS = Object.freeze([
+  { name: "health", path: "/healthz", readBody: true },
+  { name: "deployment", path: "/v1/deployment", readBody: true },
+  { name: "capabilities", path: "/v1/agent/capabilities", readBody: false },
+]);
+
+// Runs the read-only connection probe against an already validated origin.
+// Every request shares one deadline of timeoutMs. The result contains only
+// fixed tokens, numeric HTTP statuses, the validated origin and a profile from
+// SUPPORTED_PROFILES. Nothing from a response body or header is copied.
+export async function runDoctor({ origin, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await probe(origin, controller.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function probe(origin, signal) {
+  const report = {
+    origin,
+    reachable: null,
+    healthy: null,
+    deployment_profile: null,
+    profile_status: "unknown",
+    authentication_required: null,
+    authenticated: false,
+    workspace: null,
+    checks: CHECKS.map(({ name, path }) => ({
+      name,
+      path,
+      result: "skipped",
+      http_status: null,
+      reason: null,
+    })),
+    next_action: null,
+  };
+
+  for (const [index, check] of CHECKS.entries()) {
+    const response = await get(new URL(check.path, origin), {
+      signal,
+      readBody: check.readBody,
+    });
+    const entry = report.checks[index];
+    const verdict = evaluate(check.name, response, report);
+    entry.result = verdict.outcome === null || verdict.pass ? "pass" : "fail";
+    entry.http_status = response.status ?? null;
+    entry.reason = verdict.reason;
+    if (verdict.outcome !== null) {
+      return { outcome: verdict.outcome, reason: verdict.reason, report };
+    }
+  }
+
+  // Unreachable in this preview: the capabilities check always ends the probe.
+  return { outcome: "internal_error", reason: "probe_incomplete", report };
+}
+
+// Returns { outcome, reason } where outcome is null when the probe should
+// continue to the next check.
+function evaluate(name, response, report) {
+  if (response.kind === "error") {
+    // Headers that arrived before a body failure still prove the server
+    // answered over HTTP. They prove nothing about health or authentication.
+    if (name === "health") report.reachable = response.status !== null;
+    return { outcome: "connection_failed", reason: response.reason };
+  }
+
+  report.reachable = true;
+  const { status } = response;
+
+  if (status >= 300 && status < 400) {
+    return { outcome: "redirect_rejected", reason: "redirect" };
+  }
+  if (status === 503) {
+    report.healthy = false;
+    return { outcome: "unhealthy", reason: "service_unavailable" };
+  }
+  if (status >= 500) {
+    report.healthy = false;
+    return { outcome: "unhealthy", reason: "server_error" };
+  }
+
+  if (name === "health") return evaluateHealth(response, report);
+  if (name === "deployment") return evaluateDeployment(response, report);
+  return evaluateCapabilities(response, report);
+}
+
+function evaluateHealth(response, report) {
+  if (response.status !== 200) {
+    return { outcome: "unsupported", reason: "unexpected_status" };
+  }
+  if (response.tooLarge) {
+    return { outcome: "unsupported", reason: "response_too_large" };
+  }
+  const body = parseJsonObject(response);
+  if (body === null || typeof body.ok !== "boolean") {
+    return { outcome: "unsupported", reason: "invalid_response" };
+  }
+  if (body.ok !== true) {
+    report.healthy = false;
+    return { outcome: "unhealthy", reason: "reported_unhealthy" };
+  }
+  report.healthy = true;
+  return { outcome: null, reason: null };
+}
+
+function evaluateDeployment(response, report) {
+  if (response.status === 404) {
+    // Servers without this endpoint, such as a self-hosted open source
+    // server, have no profile adapter yet. Never assume they are hosted.
+    report.profile_status = "unavailable";
+    return { outcome: "unsupported", reason: "deployment_endpoint_missing" };
+  }
+  if (response.status !== 200) {
+    return { outcome: "unsupported", reason: "unexpected_status" };
+  }
+  if (response.tooLarge) {
+    return { outcome: "unsupported", reason: "response_too_large" };
+  }
+  const body = parseJsonObject(response);
+  if (body === null || typeof body.deployment_profile !== "string") {
+    return { outcome: "unsupported", reason: "invalid_response" };
+  }
+  if (!SUPPORTED_PROFILES.includes(body.deployment_profile)) {
+    report.profile_status = "unrecognized";
+    return { outcome: "unsupported", reason: "unrecognized_profile" };
+  }
+  report.deployment_profile = body.deployment_profile;
+  report.profile_status = "supported";
+  return { outcome: null, reason: null };
+}
+
+function evaluateCapabilities(response, report) {
+  if (response.status === 401) {
+    if (!hasBearerChallenge(response.headers["www-authenticate"])) {
+      return { outcome: "unsupported", reason: "unexpected_auth_challenge" };
+    }
+    report.authentication_required = true;
+    report.next_action = { kind: "connection_guide", url: CONNECTION_GUIDE_URL };
+    // The check passed: the server behaved as expected. The outcome is still
+    // not a connection, because this CLI holds no credentials.
+    return { outcome: "authentication_required", reason: "bearer_token_required", pass: true };
+  }
+  if (response.status === 200) {
+    report.authentication_required = false;
+    return { outcome: "unsupported", reason: "unexpected_unauthenticated_access" };
+  }
+  return { outcome: "unsupported", reason: "unexpected_status" };
+}
+
+// RFC 9110 challenge grammar, applied to one comma-separated list element:
+//   auth-scheme [ 1*SP ( token68 / auth-param ) ]  or a further auth-param.
+// Only the first form names a scheme, so "Bearer=x" or "Bearer = x" is a
+// parameter, never a challenge.
+const TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+";
+const QUOTED = '"(?:[^"\\\\]|\\\\.)*"';
+const PARAM = `${TOKEN}[ \\t]*=[ \\t]*(?:${TOKEN}|${QUOTED})`;
+const TOKEN68 = "[A-Za-z0-9._~+/-]+=*";
+const ELEMENT = new RegExp(`^(?:(${TOKEN})(?:[ \\t]+(?:${TOKEN68}|${PARAM}))?|${PARAM})$`);
+
+// True when the header holds a Bearer challenge. Commas inside quoted strings
+// (with backslash escapes) do not split elements. Any malformed element,
+// including unbalanced quoting, makes the whole header unacceptable.
+function hasBearerChallenge(value) {
+  if (typeof value !== "string") return false;
+  const elements = [];
+  let start = 0;
+  let quoted = false;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quoted) {
+      if (char === "\\") i += 1;
+      else if (char === '"') quoted = false;
+    } else if (char === '"') {
+      quoted = true;
+    } else if (char === ",") {
+      elements.push(value.slice(start, i));
+      start = i + 1;
+    }
+  }
+  if (quoted) return false;
+  elements.push(value.slice(start));
+
+  let bearer = false;
+  for (const element of elements) {
+    const trimmed = element.trim();
+    if (trimmed === "") continue;
+    const match = ELEMENT.exec(trimmed);
+    if (match === null) return false;
+    if (match[1] !== undefined && match[1].toLowerCase() === "bearer") bearer = true;
+  }
+  return bearer;
+}

package/src/http.js

@@ -0,0 +1,129 @@
+import http from "node:http";
+import https from "node:https";
+
+import { MAX_BODY_BYTES, PACKAGE_NAME, VERSION } from "./constants.js";
+
+const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;
+
+const DNS_ERRORS = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_FAIL", "EAI_NONAME"]);
+const REFUSED_ERRORS = new Set(["ECONNREFUSED"]);
+const RESET_ERRORS = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED"]);
+const UNREACHABLE_ERRORS = new Set(["EHOSTUNREACH", "ENETUNREACH", "ETIMEDOUT"]);
+
+// Sends one unauthenticated GET and resolves (never rejects) with either
+//   { kind: "response", status, headers, body, tooLarge }
+//   { kind: "error", reason, status }
+// where reason is a fixed token from classifyError, and status is the HTTP
+// status when the headers arrived before the failure (a body timeout, reset or
+// truncation), otherwise null. Redirects are returned as ordinary responses
+// and never followed. Only fixed headers are sent: no cookies, no
+// authorization and nothing taken from the environment.
+// The body is read only when readBody is true and the status is 200. Any
+// other response is settled as soon as its headers arrive and its body is
+// discarded, so a slow body cannot hide a status that is already known.
+export function get(url, { signal, readBody }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let status = null;
+    const finish = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const fail = (error) =>
+      finish({ kind: "error", reason: classifyError(error, signal), status });
+
+    const transport = url.protocol === "https:" ? https : http;
+    let request;
+    try {
+      request = transport.request(url, {
+        method: "GET",
+        agent: false,
+        signal,
+        headers: {
+          accept: "application/json",
+          "accept-encoding": "identity",
+          "user-agent": USER_AGENT,
+        },
+      });
+    } catch (error) {
+      fail(error);
+      return;
+    }
+
+    request.on("error", fail);
+    request.on("response", (response) => {
+      response.on("error", fail);
+      status = response.statusCode;
+      const headers = response.headers;
+      const respond = (body, tooLarge) =>
+        finish({ kind: "response", status, headers, body, tooLarge });
+
+      if (!readBody || status !== 200) {
+        respond(null, false);
+        response.destroy();
+        return;
+      }
+
+      const declared = headers["content-length"];
+      if (declared !== undefined && Number(declared) > MAX_BODY_BYTES) {
+        respond(null, true);
+        response.destroy();
+        return;
+      }
+
+      const chunks = [];
+      let size = 0;
+      response.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+          respond(null, true);
+          response.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => respond(Buffer.concat(chunks), false));
+      // A close without end means the body was cut off.
+      response.on("close", () => fail(null));
+    });
+    request.end();
+  });
+}
+
+function classifyError(error, signal) {
+  if (signal?.aborted) return "timeout";
+  const code = typeof error?.code === "string" ? error.code : "";
+  if (DNS_ERRORS.has(code)) return "dns_lookup_failed";
+  if (REFUSED_ERRORS.has(code)) return "connection_refused";
+  if (RESET_ERRORS.has(code)) return "connection_reset";
+  if (UNREACHABLE_ERRORS.has(code)) return "host_unreachable";
+  if (code.startsWith("HPE_")) return "invalid_http_response";
+  if (code.startsWith("ERR_TLS") || code.startsWith("ERR_SSL") || code.includes("CERT")) {
+    return "tls_error";
+  }
+  return "network_error";
+}
+
+// Decodes a bounded body as a JSON object. Returns the object, or null when
+// the content type, encoding, text or top-level shape is not acceptable.
+export function parseJsonObject(response) {
+  if (response.body === null || response.tooLarge) return null;
+  const encoding = response.headers["content-encoding"];
+  if (encoding !== undefined && encoding.trim().toLowerCase() !== "identity") return null;
+  const contentType = response.headers["content-type"];
+  if (typeof contentType !== "string") return null;
+  const mediaType = contentType.split(";")[0].trim().toLowerCase();
+  if (mediaType !== "application/json") return null;
+
+  let value;
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(response.body);
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}

package/src/origin.js

@@ -0,0 +1,37 @@
+const MAX_INPUT_LENGTH = 2048;
+
+// A bare authority with an optional trailing slash: no userinfo, path, query,
+// fragment or backslash. Checked on the raw text because the URL parser
+// silently normalizes some of these away.
+const HTTPS_ORIGIN = /^https:\/\/[^/?#@\\]+\/?$/i;
+
+// Plaintext HTTP is only for these exact loopback spellings. Alternate forms
+// such as 127.1 or 0x7f000001 are rejected even though they resolve locally.
+const HTTP_LOOPBACK_ORIGIN = /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]{1,5})?\/?$/i;
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+// Returns the normalized origin (for example "https://example.com") or null.
+// The caller must not echo the raw input when this returns null.
+export function parseOrigin(raw) {
+  if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_INPUT_LENGTH) {
+    return null;
+  }
+  // Printable ASCII only. Hosts with non-ASCII labels use their xn-- form.
+  if (/[^\x21-\x7e]/.test(raw)) return null;
+  if (!HTTPS_ORIGIN.test(raw) && !HTTP_LOOPBACK_ORIGIN.test(raw)) return null;
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  if (url.username !== "" || url.password !== "") return null;
+  if (url.pathname !== "/" || url.search !== "" || url.hash !== "") return null;
+  if (url.hostname === "" || url.port === "0") return null;
+  if (url.protocol === "http:" && !LOOPBACK_HOSTNAMES.has(url.hostname)) return null;
+
+  return url.origin;
+}

package/src/output.js

@@ -0,0 +1,274 @@
+import {
+  CONNECTION_GUIDE_URL,
+  DEFAULT_ORIGIN,
+  DEFAULT_TIMEOUT_MS,
+  EXIT_CODE_MEANINGS,
+  EXIT_CODES,
+  HANDOFF_SKILL_CLIENTS,
+  MAX_TIMEOUT_MS,
+  MIN_TIMEOUT_MS,
+  PACKAGE_NAME,
+  SCHEMA_VERSION,
+  SKILL_CLIENTS,
+  SKILL_RUNTIMES,
+  SUPPORTED_PROFILES,
+  VERSION,
+} from "./constants.js";
+
+// Every JSON result, success or failure, has the same top-level keys:
+//   schema_version, command, ok, outcome, exit_code, data, error
+// error is null when ok is true, otherwise { code, reason, message } where
+// code equals outcome. All strings come from this package, never from input
+// or from a server.
+export function envelope({ command, outcome, data = null, reason = null, message = null }) {
+  const ok = outcome === "ok";
+  return {
+    schema_version: SCHEMA_VERSION,
+    command,
+    ok,
+    outcome,
+    exit_code: EXIT_CODES[outcome],
+    data,
+    error: ok ? null : { code: outcome, reason, message },
+  };
+}
+
+export function toJsonLine(result) {
+  return `${JSON.stringify(result)}\n`;
+}
+
+const DOCTOR_OPTIONS = [
+  {
+    name: "--url",
+    value: "ORIGIN",
+    summary: `Origin to probe. Default ${DEFAULT_ORIGIN}.`,
+  },
+  {
+    name: "--timeout-ms",
+    value: "N",
+    summary: `Total time allowed for the whole probe, ${MIN_TIMEOUT_MS} to ${MAX_TIMEOUT_MS}. Default ${DEFAULT_TIMEOUT_MS}.`,
+  },
+  { name: "--json", value: null, summary: "Print one JSON line on stdout." },
+];
+
+const SKILL_OPTIONS = [
+  {
+    name: "--client",
+    value: "CLIENT",
+    summary: "Required. codex (.agents/skills), claude (.claude/skills) or cursor (.cursor/skills).",
+  },
+  {
+    name: "--runtime",
+    value: "RUNTIME",
+    summary: "Required. local or cloud: where the client runs. Recorded, not detected.",
+  },
+  { name: "--project", value: "DIR", summary: "Existing project directory. Default: the current directory." },
+  { name: "--json", value: null, summary: "Print one JSON line on stdout." },
+];
+
+const SKILL_USAGE = [
+  "metergraph skill install --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skill update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+];
+
+export function helpData(topic) {
+  return {
+    topic,
+    usage: [
+      "metergraph --help [--json]",
+      "metergraph --version [--json]",
+      "metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
+      ...SKILL_USAGE,
+    ],
+    commands: [
+      {
+        name: "doctor",
+        summary:
+          "Check that a Metergraph service is reachable, healthy and supported. Read only, sends no credentials.",
+        options: DOCTOR_OPTIONS,
+      },
+      {
+        name: "skill install",
+        summary:
+          "Copy the Metergraph skill bundled with this CLI into one client's project skill directory. " +
+          "Never replaces a skill it did not install. No network requests, no sign in.",
+        options: SKILL_OPTIONS,
+      },
+      {
+        name: "skill update",
+        summary:
+          "Replace a skill this CLI installed, and that is unchanged since, with the bundled revision.",
+        options: SKILL_OPTIONS,
+      },
+    ],
+    skill_clients: Object.keys(SKILL_CLIENTS),
+    skill_runtimes: [...SKILL_RUNTIMES],
+    supported_profiles: [...SUPPORTED_PROFILES],
+    exit_codes: Object.entries(EXIT_CODES).map(([outcome, code]) => ({
+      code,
+      outcome,
+      meaning: EXIT_CODE_MEANINGS[outcome],
+    })),
+  };
+}
+
+export function helpText(topic) {
+  const lines = [];
+  if (topic === "doctor") {
+    lines.push(
+      "Usage: metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
+      "",
+      "Makes unauthenticated, read-only GET requests to /healthz, /v1/deployment and",
+      "/v1/agent/capabilities on one origin. Sends no credentials and follows no redirects.",
+      "",
+      "Options:",
+    );
+    for (const option of DOCTOR_OPTIONS) {
+      const flag = option.value ? `${option.name} ${option.value}` : option.name;
+      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
+    }
+    lines.push(
+      "",
+      "ORIGIN must be a bare https origin such as https://metergraph.example.com.",
+      "Plain http is accepted only for localhost, 127.0.0.1 and [::1].",
+      "",
+      "A healthy, supported service that requires sign in exits with code 3.",
+      "This preview cannot sign in, so it never reports a connected workspace.",
+    );
+  } else if (topic === "skill") {
+    lines.push(
+      "Usage:",
+      ...SKILL_USAGE.map((usage) => `  ${usage}`),
+      "",
+      "Copies the Metergraph skill bundled with this CLI into one client's project skill",
+      "directory and records ownership in .metergraph/skill-installations.json. Writes",
+      "nothing else. Makes no network requests, does not sign in and does not configure",
+      "MCP, client settings, AGENTS.md or CLAUDE.md.",
+      "",
+      "Options:",
+    );
+    for (const option of SKILL_OPTIONS) {
+      const flag = option.value ? `${option.name} ${option.value}` : option.name;
+      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
+    }
+    lines.push(
+      "",
+      "install never replaces an existing skill. update replaces only a skill this CLI",
+      "installed and that is unchanged since. There is no force option.",
+      "",
+      "Claude Desktop (--client claude-desktop), ChatGPT (--client chatgpt) and cloud",
+      "runtimes without a shell (--runtime cloud-no-shell) cannot load project skill files.",
+      "They exit with code 6, point to the connection guide and write nothing.",
+      "",
+      "Discovery stays pending until the client itself loads the skill.",
+    );
+  } else {
+    lines.push(
+      `metergraph ${VERSION} (preview)`,
+      "",
+      "Usage:",
+      "  metergraph --help [--json]       Show this help",
+      "  metergraph --version [--json]    Show the CLI version",
+      "  metergraph doctor [options]      Check a Metergraph service, read only",
+      "  metergraph skill install|update  Install or update the agent skill in a project",
+      "",
+      'Run "metergraph help doctor" for doctor options.',
+      'Run "metergraph help skill" for skill options.',
+    );
+  }
+  lines.push("", "Exit codes:");
+  for (const [outcome, code] of Object.entries(EXIT_CODES)) {
+    lines.push(`  ${String(code).padEnd(3)}${outcome.padEnd(25)}${EXIT_CODE_MEANINGS[outcome]}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function skillText(result, message) {
+  const report = result.data;
+  const label = SKILL_CLIENTS[report.client]?.label ?? HANDOFF_SKILL_CLIENTS[report.client];
+  const lines = [`Metergraph ${result.command}: ${label}, ${report.runtime} runtime`];
+  if (report.path !== null) lines.push(`Path: ${report.path}`);
+  if (result.ok) {
+    lines.push(
+      `Status: ${report.status}`,
+      `Source revision: ${report.source.revision} (sha256 ${report.source.sha256})`,
+      `Discovery: pending until ${label} loads the skill`,
+      "Authenticated: no",
+      "",
+      message,
+      `Next: ${report.next_action.message}`,
+    );
+  } else {
+    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+    if (report.next_action?.kind === "connection_guide") {
+      lines.push(`Connection guide: ${report.next_action.url}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function versionData() {
+  return { name: PACKAGE_NAME, version: VERSION };
+}
+
+const CHECK_LABELS = {
+  health: "Health",
+  deployment: "Deployment profile",
+  capabilities: "Agent capabilities",
+};
+
+const REASON_TEXT = {
+  timeout: "the probe did not finish within the time limit",
+  dns_lookup_failed: "the host name could not be resolved",
+  connection_refused: "the connection was refused",
+  connection_reset: "the connection was closed unexpectedly",
+  host_unreachable: "the host could not be reached",
+  invalid_http_response: "the server did not send a valid HTTP response",
+  tls_error: "the TLS connection could not be verified",
+  network_error: "a network error occurred",
+  redirect: "the server answered with a redirect, which is never followed",
+  service_unavailable: "the service reported that it is unavailable",
+  server_error: "the service answered with a server error",
+  reported_unhealthy: "the service reported that it is not healthy",
+  unexpected_status: "the service answered with an unexpected status",
+  response_too_large: "the response was larger than the allowed limit",
+  invalid_response: "the response was not the expected JSON",
+  deployment_endpoint_missing:
+    "the service does not report a deployment profile; this preview supports only services that do",
+  unrecognized_profile: "the service reported a deployment profile this CLI does not support",
+  unexpected_auth_challenge: "the service did not ask for a bearer token",
+  unexpected_unauthenticated_access: "the service answered without asking for authentication",
+  bearer_token_required: "authentication required",
+  probe_incomplete: "the probe did not complete",
+};
+
+export function doctorMessage(outcome, reason) {
+  if (outcome === "authentication_required") {
+    return "The service is reachable and supported, and it requires authentication. No workspace is connected.";
+  }
+  const detail = REASON_TEXT[reason] ?? "the probe failed";
+  return `${detail.charAt(0).toUpperCase()}${detail.slice(1)}.`;
+}
+
+export function doctorText(result) {
+  const report = result.data;
+  const lines = ["Metergraph doctor (read only, no credentials sent)", `Origin: ${report.origin}`, ""];
+  for (const check of report.checks) {
+    let line = `  ${check.result.padEnd(8)}${CHECK_LABELS[check.name]} (${check.path})`;
+    if (check.name === "deployment" && report.deployment_profile !== null) {
+      line += `: ${report.deployment_profile}`;
+    } else if (check.reason !== null) {
+      line += `: ${REASON_TEXT[check.reason] ?? check.reason}`;
+    }
+    lines.push(line);
+  }
+  lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`);
+  if (result.error !== null) lines.push(result.error.message);
+  if (result.outcome === "authentication_required") {
+    lines.push(
+      "This preview cannot sign in. To connect an application, follow the connection guide:",
+      CONNECTION_GUIDE_URL,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/skill-bundle.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+// The skill file shipped in assets/skill/ is a byte-for-byte copy of the
+// public skill at the manifest's source_url. The source has no version of its
+// own, so the revision is derived from the content hash. The hash is pinned
+// here as well as in the manifest, so editing either file alone is detected.
+const PINNED_SHA256 = "90f7d8d78a5b0b7a57436f194222f0c73310b0b04201c297c8fbf0b00ad6bb3f";
+
+const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
+const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
+
+export function sha256Hex(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function revisionFor(sha256) {
+  return `sha256-${sha256.slice(0, 12)}`;
+}
+
+// Returns { name, revision, sha256, content } for the bundled skill, or null
+// when the manifest or the skill file is missing, malformed or does not match
+// the pinned hash. Never downloads anything.
+export function loadBundledSkill() {
+  let manifest;
+  let content;
+  try {
+    manifest = JSON.parse(readFileSync(new URL("manifest.json", ASSET_DIR), "utf8"));
+    content = readFileSync(new URL("SKILL.md", ASSET_DIR));
+  } catch {
+    return null;
+  }
+  if (
+    manifest === null ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    Object.keys(manifest).sort().join() !== MANIFEST_KEYS.join() ||
+    manifest.manifest_version !== 1 ||
+    manifest.file !== "SKILL.md" ||
+    manifest.source_url !== "https://www.metergraph.dev/SKILL.md" ||
+    typeof manifest.name !== "string" ||
+    !/^[a-z0-9-]{1,64}$/.test(manifest.name) ||
+    manifest.sha256 !== PINNED_SHA256 ||
+    manifest.revision !== revisionFor(PINNED_SHA256) ||
+    manifest.size !== content.length
+  ) {
+    return null;
+  }
+  const sha256 = sha256Hex(content);
+  if (sha256 !== PINNED_SHA256) return null;
+  if (!content.toString("utf8").startsWith(`---\nname: ${manifest.name}\ndescription: `)) return null;
+  return { name: manifest.name, revision: manifest.revision, sha256, content };
+}