metergraph-cli 0.2.0-preview.4 → 0.2.0-preview.5

package/src/output.js

@@ -84,6 +84,28 @@ const SKILL_USAGE = [
   "metergraph skill update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
 ];
 
+const SKILLS_USAGE = [
+  "metergraph skills install --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skills update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skills list [--project DIR] [--json]",
+];
+
+const SKILLS_LIST_OPTIONS = [
+  { name: "--project", value: "DIR", summary: "Existing project directory. Default: the current directory." },
+  { name: "--json", value: null, summary: "Print one JSON line on stdout." },
+];
+
+const SKILLS_STATE_LABELS = {
+  not_installed: "not installed",
+  installed: "installed",
+  outdated: "older revision; run skills update",
+  modified: "changed since install; left alone",
+  missing: "receipt only; run skills install",
+  not_owned: "not installed by this CLI; left alone",
+  receipt_invalid: "receipt not valid",
+  unsafe_path: "unsafe path",
+};
+
 const CONFIG_DIR_OPTION = {
   name: "--config-dir",
   value: "DIR",
@@ -257,6 +279,7 @@ export function helpData(topic) {
       "metergraph --version [--json]",
       "metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
       ...SKILL_USAGE,
+      ...SKILLS_USAGE,
       LOGIN_USAGE,
       LOGOUT_USAGE,
       SETUP_USAGE,
@@ -283,6 +306,25 @@ export function helpData(topic) {
           "Replace a skill this CLI installed, and that is unchanged since, with the bundled revision.",
         options: SKILL_OPTIONS,
       },
+      {
+        name: "skills install",
+        summary:
+          "Copy the Metergraph workflow skills bundled with this CLI, such as the model-swap loop, 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: "skills update",
+        summary:
+          "Replace workflow skills this CLI installed, and that are unchanged since, with the bundled revisions, " +
+          "and install skills added since.",
+        options: SKILL_OPTIONS,
+      },
+      {
+        name: "skills list",
+        summary: "List the bundled workflow skills and whether each is installed for each client. Writes nothing.",
+        options: SKILLS_LIST_OPTIONS,
+      },
       {
         name: "login",
         summary:
@@ -463,6 +505,40 @@ export function helpText(topic) {
       "",
       "Discovery stays pending until the client itself loads the skill.",
     );
+  } else if (topic === "skills") {
+    lines.push(
+      "Usage:",
+      ...SKILLS_USAGE.map((usage) => `  ${usage}`),
+      "",
+      "Copies the Metergraph workflow skills bundled with this CLI into one client's project",
+      "skill directory, one folder per skill, and records ownership of each in",
+      ".metergraph/skills/NAME.json. The skills come from https://github.com/metergraph/skills",
+      "at the commit this release pins. They cover investigation and the model-swap loop:",
+      "choose a workload, choose traces and models, define the eval, run the analysis,",
+      "summarize the report and rerun. The setup skill is installed by \"metergraph skill\".",
+      "",
+      "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 skills this CLI",
+      "installed and that are unchanged since, and installs skills added since. A conflict",
+      "on one skill leaves the others in place. There is no force option.",
+      "list takes only --project and reports every client. It never writes.",
+      "",
+      "Claude Desktop (--client claude-desktop) cannot load project skill files. It exits",
+      "with code 6, writes nothing and points to the metergraph/skills plugin marketplace.",
+      "ChatGPT and cloud runtimes without a shell get the connection guide instead.",
+      "",
+      "Discovery stays pending until the client itself loads the skills.",
+    );
   } else {
     lines.push(
       `metergraph ${VERSION} (preview)`,
@@ -472,6 +548,7 @@ export function helpText(topic) {
       "  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",
+      "  metergraph skills install|update|list  Workflow skills, such as the model-swap loop",
       "  metergraph login [options]       Sign in and bind a project to a workspace",
       "  metergraph logout [options]      Revoke and remove a project's sign in",
       "  metergraph setup [options]       Approve and write a private ingest key",
@@ -485,6 +562,7 @@ export function helpText(topic) {
       "",
       'Run "metergraph help doctor" for doctor options.',
       'Run "metergraph help skill" for skill options.',
+      'Run "metergraph help skills" for workflow skill options.',
       'Run "metergraph help login" or "metergraph help logout" for sign in options.',
       'Run "metergraph help verify" for exact-trace verification options.',
       'Run "metergraph help COMMAND" for status, context, capabilities, usage, routes or traces.',
@@ -521,6 +599,46 @@ export function skillText(result, message) {
   return `${lines.join("\n")}\n`;
 }
 
+export function skillsText(result, message) {
+  const report = result.data;
+  const lines = [];
+  if (result.command === "skills list") {
+    lines.push("Metergraph skills bundled with this CLI");
+    if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
+    if (!result.ok) {
+      lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+      return `${lines.join("\n")}\n`;
+    }
+    for (const skill of report.skills) {
+      lines.push("", `${skill.name} (${skill.revision})`);
+      for (const [client, state] of Object.entries(skill.installs)) {
+        lines.push(`  ${SKILL_CLIENTS[client].label.padEnd(12)}${SKILLS_STATE_LABELS[state] ?? state}`);
+      }
+    }
+    return `${lines.join("\n")}\n`;
+  }
+  const label = SKILL_CLIENTS[report.client]?.label ?? HANDOFF_SKILL_CLIENTS[report.client] ?? report.client;
+  lines.push(`Metergraph ${result.command}: ${label}, ${report.runtime} runtime`);
+  if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
+  for (const skill of report.skills) {
+    const status = skill.status === "failed" ? `failed (${skill.reason})` : skill.status;
+    lines.push(`  ${skill.name.padEnd(24)}${status.padEnd(12)}${skill.path}`);
+  }
+  if (result.ok) {
+    lines.push(
+      `Discovery: pending until ${label} loads the skills`,
+      "Authenticated: no",
+      "",
+      `Next: ${report.next_action.message}`,
+    );
+  } else {
+    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+    if (report.next_action?.kind === "plugin_marketplace") lines.push(`Next: ${report.next_action.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 };
 }

package/src/skill-bundle.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 // 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 = "8b81eb27b6159c4447a5c300409c4c64917238b7797f5ee37a35248cba50fcae";
+const PINNED_SHA256 = "92f7955f6f8761a20a1886ad81f22dfcee239afddf8e9f1e761c35eb8e70f218";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
@@ -51,3 +51,70 @@ export function loadBundledSkill() {
   if (!content.toString("utf8").startsWith(`---\nname: ${manifest.name}\ndescription: `)) return null;
   return { name: manifest.name, revision: manifest.revision, sha256, content };
 }
+
+// The workflow skills that "skills install" writes, vendored from the public
+// skills repository at one commit. The manifest's own hash is pinned here, and
+// the manifest pins each skill's hash, so changing any file alone is detected.
+const PINNED_PACK_SHA256 = "c8e4d9b0d90bd201e90758e16ab0827b8ea36e3620a28223a7e73e91c035d835";
+
+const PACK_DIR = new URL("../assets/skills/", import.meta.url);
+const PACK_KEYS = ["commit", "manifest_version", "repository", "skills"];
+const PACK_ENTRY_KEYS = ["name", "revision", "sha256", "size"];
+
+// Returns { repository, commit, skills: [{ name, revision, sha256, content }] }
+// sorted by name, or null when the manifest or any skill file is missing,
+// malformed or does not match its pinned hash. Never downloads anything.
+export function loadBundledPack() {
+  let manifestBytes;
+  let manifest;
+  try {
+    manifestBytes = readFileSync(new URL("manifest.json", PACK_DIR));
+    manifest = JSON.parse(manifestBytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (
+    sha256Hex(manifestBytes) !== PINNED_PACK_SHA256 ||
+    manifest === null ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    Object.keys(manifest).sort().join() !== PACK_KEYS.join() ||
+    manifest.manifest_version !== 1 ||
+    manifest.repository !== "metergraph/skills" ||
+    typeof manifest.commit !== "string" ||
+    !/^[0-9a-f]{40}$/.test(manifest.commit) ||
+    !Array.isArray(manifest.skills) ||
+    manifest.skills.length === 0
+  ) {
+    return null;
+  }
+  const skills = [];
+  const seen = new Set();
+  for (const entry of manifest.skills) {
+    if (
+      entry === null ||
+      typeof entry !== "object" ||
+      Object.keys(entry).sort().join() !== PACK_ENTRY_KEYS.join() ||
+      typeof entry.name !== "string" ||
+      !/^[a-z0-9-]{1,64}$/.test(entry.name) ||
+      entry.name === "metergraph" ||
+      seen.has(entry.name) ||
+      typeof entry.sha256 !== "string" ||
+      entry.revision !== revisionFor(entry.sha256)
+    ) {
+      return null;
+    }
+    seen.add(entry.name);
+    let content;
+    try {
+      content = readFileSync(new URL(`${entry.name}/SKILL.md`, PACK_DIR));
+    } catch {
+      return null;
+    }
+    if (content.length !== entry.size || sha256Hex(content) !== entry.sha256) return null;
+    if (!content.toString("utf8").startsWith(`---\nname: ${entry.name}\ndescription: `)) return null;
+    skills.push({ name: entry.name, revision: entry.revision, sha256: entry.sha256, content });
+  }
+  skills.sort((a, b) => (a.name < b.name ? -1 : 1));
+  return { repository: manifest.repository, commit: manifest.commit, skills };
+}

package/src/skill.js

@@ -2,11 +2,19 @@ import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-import { CONNECTION_GUIDE_URL, SKILL_CLIENTS, SKILL_RUNTIMES } from "./constants.js";
-import { loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
+import {
+  CONNECTION_GUIDE_URL,
+  SKILLS_REPOSITORY_URL,
+  SKILL_CLIENTS,
+  SKILL_RUNTIMES,
+} from "./constants.js";
+import { loadBundledPack, loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
 
-// Project-scoped skill installer. It writes exactly two things inside the
-// project: the client's SKILL.md and a secret-free ownership receipt. It never
+// Project-scoped skill installer. For each skill it writes exactly two things
+// inside the project: the client's SKILL.md and a secret-free ownership
+// receipt. "skill" installs the setup skill with the receipt below; "skills"
+// installs each skill of the workflow pack with its own receipt in
+// .metergraph/skills/. It never
 // touches client settings, AGENTS.md, CLAUDE.md or any other file, never
 // follows a symbolic link below the resolved project directory and makes no
 // network request. All file work is synchronous, so a signal cannot run
@@ -15,6 +23,8 @@ import { loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
 const RECEIPT_DIR = ".metergraph";
 const RECEIPT_FILE = "skill-installations.json";
 const LOCK_FILE = "skill-installations.lock";
+const PACK_RECEIPT_DIRS = [RECEIPT_DIR, "skills"];
+const CORE_RECEIPT = Object.freeze({ dirs: [RECEIPT_DIR], file: RECEIPT_FILE, lock: LOCK_FILE });
 const MAX_RECEIPT_BYTES = 64 * 1024;
 const MAX_SKILL_BYTES = 1024 * 1024;
 const ENTRY_KEYS = ["client", "path", "revision", "runtimes", "sha256", "skill"];
@@ -57,7 +67,7 @@ class Stop extends Error {
 // Returns { outcome, reason, message, data }. Every string comes from this
 // package. Paths in data are relative to the project.
 export function runSkill({ action, client, runtime, project }) {
-  const context = { action, client, runtime, target: null, bundle: null };
+  const context = { action, client, runtime, target: null, bundle: null, receipt: CORE_RECEIPT };
   if (!Object.hasOwn(SKILL_CLIENTS, client)) {
     return handoff(context, "client_not_supported");
   }
@@ -73,20 +83,25 @@ export function runSkill({ action, client, runtime, project }) {
 }
 
 function execute(context, project) {
-  const { action, client, runtime } = context;
   context.bundle = loadBundledSkill();
   if (context.bundle === null) throw new Stop("internal_error", "bundled_skill_invalid");
-  context.target = targetFor(client, context.bundle.name);
+  context.target = targetFor(context.client, context.bundle.name);
   const root = resolveProject(project);
+  return success(context, apply(root, context));
+}
+
+// Installs or updates one skill and returns its status, or throws a Stop.
+function apply(root, context) {
+  const { action, runtime, receipt } = context;
 
   // Decide from a read-only look first, so a matching rerun writes nothing.
   let state = inspect(root, context);
   let plan = decide(action, runtime, state, context.bundle);
-  if (plan.noop) return success(context, plan.status);
+  if (plan.noop) return plan.status;
 
   return deferSignals(() => {
-    const createdMeta = ensureDirs(root, [RECEIPT_DIR]);
-    const lockPath = path.join(root, RECEIPT_DIR, LOCK_FILE);
+    const createdMeta = ensureDirs(root, receipt.dirs);
+    const lockPath = path.join(root, ...receipt.dirs, receipt.lock);
     let done = false;
     try {
       acquireLock(lockPath);
@@ -96,7 +111,7 @@ function execute(context, project) {
         plan = decide(action, runtime, state, context.bundle);
         if (!plan.noop) commit(root, context, state, plan);
         done = true;
-        return success(context, plan.status);
+        return plan.status;
       } finally {
         try {
           fs.unlinkSync(lockPath);
@@ -129,8 +144,8 @@ function resolveProject(project) {
 // non-regular entry on either path stops the run.
 function inspect(root, context) {
   try {
-    checkDirs(root, [RECEIPT_DIR]);
-    const receiptFile = readRegular(path.join(root, RECEIPT_DIR, RECEIPT_FILE), MAX_RECEIPT_BYTES);
+    checkDirs(root, context.receipt.dirs);
+    const receiptFile = readRegular(path.join(root, ...context.receipt.dirs, context.receipt.file), MAX_RECEIPT_BYTES);
     let receipt = null;
     if (receiptFile !== null) {
       receipt = receiptFile.content === null ? null : parseReceipt(receiptFile.content, context.bundle.name);
@@ -181,7 +196,7 @@ function decide(action, runtime, state, bundle) {
 function commit(root, context, state, plan) {
   const { bundle, target } = context;
   const skillPath = path.join(root, ...target.dirs, "SKILL.md");
-  const receiptPath = path.join(root, RECEIPT_DIR, RECEIPT_FILE);
+  const receiptPath = path.join(root, ...context.receipt.dirs, context.receipt.file);
   const receipt = nextReceipt(state.receipt, context, target.relative);
   let createdDirs = [];
   let skillWritten = false;
@@ -447,3 +462,149 @@ function handoff(context, reason) {
 function failure(context, outcome, reason) {
   return { outcome, reason, message: MESSAGES[reason], data: data(context) };
 }
+
+// ---------------------------------------------------------------------------
+// The workflow skill pack ("metergraph skills"). Each skill runs through the
+// same engine as the setup skill, with its own receipt and lock in
+// .metergraph/skills/, so one skill's conflict never blocks or rolls back
+// another, and the setup skill's receipt is never touched.
+
+const PACK_HANDOFF_MESSAGE =
+  "In Claude Desktop, open Customize → Plugins → Add marketplace and enter metergraph/skills, " +
+  "or upload a skill zip from https://github.com/metergraph/skills/releases/latest under Customize → Skills.";
+
+function packReceipt(name) {
+  return { dirs: PACK_RECEIPT_DIRS, file: `${name}.json`, lock: `${name}.lock` };
+}
+
+function packMessage(name, reason) {
+  const receipt = `${PACK_RECEIPT_DIRS.join("/")}/${name}.json`;
+  const lock = `${PACK_RECEIPT_DIRS.join("/")}/${name}.lock`;
+  if (reason === "receipt_invalid") return `The receipt ${receipt} is not valid. Nothing was changed.`;
+  if (reason === "locked") return `Another skill install may be running. If none is, delete ${lock} and retry.`;
+  if (reason === "rollback_failed") {
+    return `The skill could not be written and the rollback did not finish. Check the skill path and ${receipt}.`;
+  }
+  return MESSAGES[reason];
+}
+
+// Returns { outcome, reason, message, data } like runSkill. data.skills has
+// one entry per bundled skill, in name order.
+export function runSkillPack({ action, client, runtime, project }) {
+  const base = { client, runtime, source: null, skills: [], discovery: null, authenticated: false, next_action: null };
+  if (client === "claude-desktop") {
+    return {
+      outcome: "unsupported",
+      reason: "client_not_supported",
+      message:
+        "Claude Desktop loads Metergraph skills from the plugin marketplace or an uploaded zip, not from project files. Nothing was written.",
+      data: { ...base, next_action: { kind: "plugin_marketplace", message: PACK_HANDOFF_MESSAGE, url: SKILLS_REPOSITORY_URL } },
+    };
+  }
+  if (!Object.hasOwn(SKILL_CLIENTS, client)) {
+    return { outcome: "unsupported", reason: "client_not_supported", message: MESSAGES.client_not_supported,
+      data: { ...base, next_action: { kind: "connection_guide", url: CONNECTION_GUIDE_URL } } };
+  }
+  if (!SKILL_RUNTIMES.includes(runtime)) {
+    return { outcome: "unsupported", reason: "runtime_not_supported", message: MESSAGES.runtime_not_supported,
+      data: { ...base, next_action: { kind: "connection_guide", url: CONNECTION_GUIDE_URL } } };
+  }
+  const pack = loadBundledPack();
+  if (pack === null) {
+    return { outcome: "internal_error", reason: "bundled_skill_invalid", message: MESSAGES.bundled_skill_invalid, data: base };
+  }
+  base.source = { repository: pack.repository, commit: pack.commit };
+  let root;
+  try {
+    root = resolveProject(project);
+  } catch (error) {
+    return { outcome: error.outcome, reason: error.reason, message: MESSAGES[error.reason], data: base };
+  }
+
+  let failed = null;
+  for (const bundle of pack.skills) {
+    const context = {
+      action,
+      client,
+      runtime,
+      bundle,
+      receipt: packReceipt(bundle.name),
+      target: targetFor(client, bundle.name),
+    };
+    const entry = { name: bundle.name, path: context.target.relative, status: null, revision: bundle.revision, reason: null };
+    try {
+      try {
+        entry.status = apply(root, context);
+      } catch (error) {
+        // A skill added to the pack since the last install is installed by update.
+        if (!(error instanceof Stop) || error.reason !== "not_installed") throw error;
+        entry.status = apply(root, { ...context, action: "install" });
+      }
+    } catch (error) {
+      const stop = error instanceof Stop ? error : new Stop("filesystem_error", "write_failed");
+      entry.status = "failed";
+      entry.reason = stop.reason;
+      failed ??= { outcome: stop.outcome, reason: stop.reason, message: packMessage(bundle.name, stop.reason) };
+    }
+    base.skills.push(entry);
+  }
+
+  const label = SKILL_CLIENTS[client].label;
+  if (failed !== null) {
+    return { ...failed, data: { ...base, discovery: "pending", next_action: null } };
+  }
+  const message =
+    runtime === "local"
+      ? `Start or restart ${label} in this project, then confirm that it lists the Metergraph skills.`
+      : `Make sure the cloud checkout includes ${SKILL_CLIENTS[client].dir}/skills (commit it if you installed it elsewhere), ` +
+        `then start a new ${label} cloud session and confirm that it lists the Metergraph skills.`;
+  return {
+    outcome: "ok",
+    reason: null,
+    message:
+      `Skills ready. Discovery is pending until ${label} loads them. ` +
+      "This does not sign in, connect a workspace or configure MCP.",
+    data: { ...base, discovery: "pending", next_action: { kind: "reload_client", message } },
+  };
+}
+
+// Read-only: what the pack bundles, and its state for every client in the
+// project. Never writes, never takes a lock.
+export function listSkillPack({ project }) {
+  const pack = loadBundledPack();
+  const data = { source: null, skills: [], clients: Object.keys(SKILL_CLIENTS) };
+  if (pack === null) {
+    return { outcome: "internal_error", reason: "bundled_skill_invalid", message: MESSAGES.bundled_skill_invalid, data };
+  }
+  data.source = { repository: pack.repository, commit: pack.commit };
+  let root;
+  try {
+    root = resolveProject(project);
+  } catch (error) {
+    return { outcome: error.outcome, reason: error.reason, message: MESSAGES[error.reason], data };
+  }
+  for (const bundle of pack.skills) {
+    const installs = {};
+    for (const client of Object.keys(SKILL_CLIENTS)) {
+      installs[client] = packState(root, { client, bundle, receipt: packReceipt(bundle.name), target: targetFor(client, bundle.name) });
+    }
+    data.skills.push({ name: bundle.name, revision: bundle.revision, sha256: bundle.sha256, installs });
+  }
+  return { outcome: "ok", reason: null, message: null, data };
+}
+
+// One of not_installed, installed, outdated, modified, missing, not_owned,
+// receipt_invalid or unsafe_path.
+function packState(root, context) {
+  let state;
+  try {
+    state = inspect(root, context);
+  } catch (error) {
+    return error instanceof Stop && error.reason === "receipt_invalid" ? "receipt_invalid" : "unsafe_path";
+  }
+  const { entry, file, skillDirExists } = state;
+  if (entry === null) return file !== null || skillDirExists ? "not_owned" : "not_installed";
+  if (file === null) return "missing";
+  if (file.content === null || sha256Hex(file.content) !== entry.sha256) return "modified";
+  return entry.revision === context.bundle.revision ? "installed" : "outdated";
+}