@polygraphso/litmus 0.8.0 → 0.9.0

package/README.md

@@ -61,9 +61,9 @@ MCP-capable client. It exposes two tools:
 It also registers two **prompts** that show up as slash commands — in Claude Code,
 `/mcp__polygraph-litmus__grade <server_ref>` (run a fresh grade) and
 `/mcp__polygraph-litmus__check <server_ref>` (read a published grade); other
-clients surface the same prompts in their own UI. (Want a bare `/polygraph` in
-Claude Code? Drop a `.claude/commands/polygraph.md` that calls `run_litmus` — a
-Claude-Code-only convenience, not shipped here.)
+clients surface the same prompts in their own UI. For a cleaner pair of commands
+in Claude Code — `/polygraph:grade` and `/polygraph:check` — install the plugin
+(below), which wires up this server and both commands in one step.
 
 **Prerequisites:** Node ≥ 18. Docker is optional (without it, C-02 egress is
 skipped and the grade caps at B). Set `POLYGRAPH_API_URL=https://polygraph.so` so
@@ -73,7 +73,20 @@ skipped and the grade caps at B). Set `POLYGRAPH_API_URL=https://polygraph.so` s
 > commonly returns `not_available` today — that means *unevaluated*, not a failing
 > grade. To grade a server right now, use `run_litmus`.
 
-Add the server once, then just talk to your agent.
+### Claude Code: one-click plugin (recommended)
+
+The plugin bundles this MCP server **and** adds the `/polygraph:grade` and
+`/polygraph:check` commands — one install does everything:
+
+```
+/plugin marketplace add polygraphso/litmus
+/plugin install polygraph@polygraphso
+```
+
+Then just run `/polygraph:grade npm/@modelcontextprotocol/server-filesystem`.
+
+Prefer to wire the server up by hand, or using another client? Add it once, then
+just talk to your agent.
 
 **Claude Code** — one command:
 
@@ -138,6 +151,54 @@ machine.
 - **`verify_attestation` says `lookup_failed`:** the grade index or RPC was
   unreachable — that's *unknown*, not *no grade*. Retry; check `POLYGRAPH_API_URL`.
 
+## Grade a skill
+
+Claude Code / Agent **Skills** (a `SKILL.md` plus an optional bundle) are graded by a
+separate static litmus (`litmus-skill-v1`). It scans the skill's bytes — **S-01**
+prompt injection in the body, **S-03** data-exfiltration instructions, **S-04**
+dangerous commands in bundled executable scripts — and content-hashes the whole
+directory. The letter is **A/B/D/F**.
+
+This is a **static** scan: it does not execute the skill or its scripts, so an `A`
+means the static checks were clean, not that the skill is behaviorally safe. A
+command the skill builds or fetches at runtime is not visible to it.
+
+### CLI
+
+```bash
+polygraphso-litmus-skill <path-to-skill-dir>          # grade a local skill folder (must contain SKILL.md)
+polygraphso-litmus-skill --json <path-to-skill-dir>   # machine-readable safety + quality bundles
+```
+
+It also prints a separate, advisory **quality** signal (`well-formed` / `issues` /
+`malformed`) — never an A–F letter, never minted. Its deterministic checks
+(frontmatter + bundled-link resolution) always run; the optional LLM-judged axes
+(honesty, coherence) run only when a judge is available:
+
+- **Inside an agent** (the MCP tool below): the host agent's own model judges via MCP
+  sampling — no key, any provider.
+- **Standalone:** bring your own key for any OpenAI-compatible endpoint:
+
+  ```bash
+  export LITMUS_LLM_API_KEY=…                            # your key
+  export LITMUS_LLM_MODEL=gpt-4o                         # any model the endpoint serves
+  export LITMUS_LLM_BASE_URL=https://api.openai.com/v1   # optional; defaults to OpenAI
+  ```
+
+- With neither, the judged axes are skipped — the grade and deterministic quality
+  still run. The core never needs a key.
+
+### From an AI agent (MCP)
+
+The same `polygraphso-litmus-mcp` server exposes two skill tools (plus `grade-skill` /
+`check-skill` prompts):
+
+- **`run_skill_litmus`** — grade a local skill directory now (static; uses the host
+  model via sampling for the quality axes, no key).
+- **`verify_skill_attestation`** — read a skill's *already-published* grade. It returns
+  the attested `contentHash`; recompute the skill's hash and require equality before
+  installing — the content hash, not the version, is the trust anchor.
+
 ## Library
 
 ```ts
@@ -145,6 +206,12 @@ import { runLitmus, gateDecision, liveFingerprint, readAttestation } from "@poly
 
 const bundle = await runLitmus("npm/@modelcontextprotocol/server-filesystem");
 console.log(bundle.grade, bundle.gradeRationale);
+
+// Skills: static safety grade + a separate advisory quality bundle.
+import { runSkillLitmus, runSkillQuality } from "@polygraphso/litmus";
+
+const skill = runSkillLitmus("./skills/my-skill");
+console.log(skill.grade, skill.contentHash);
 ```
 
 ## License

package/dist/{chunk-ZR6XRGMQ.js → chunk-44R4ZYOE.js}

@@ -82,6 +82,69 @@ function serverKey(parts) {
   return parts.owner ? `${parts.registry}/${parts.owner}/${parts.name}` : `${parts.registry}/${parts.name}`;
 }
 
+// ../core/src/skill-identity.ts
+var SOURCES = /* @__PURE__ */ new Set(["github", "marketplace", "npm"]);
+var OWNER_RE2 = /^@?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var NAME_RE2 = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var REF_RE = /^[A-Za-z0-9][A-Za-z0-9.+_-]*$/;
+var PATH_SEG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var SkillRefParseError = class extends Error {
+  constructor(ref, reason) {
+    super(`Invalid skill ref "${ref}": ${reason}`);
+    this.name = "SkillRefParseError";
+  }
+};
+function parseSkillRef(ref) {
+  const firstSlash = ref.indexOf("/");
+  if (firstSlash === -1) throw new SkillRefParseError(ref, "expected `{source}/...`");
+  const source = ref.slice(0, firstSlash);
+  if (!SOURCES.has(source)) {
+    throw new SkillRefParseError(ref, `unknown source "${source}" (expected one of: ${[...SOURCES].join(", ")})`);
+  }
+  let rest = ref.slice(firstSlash + 1);
+  let pin = null;
+  const at = rest.lastIndexOf("@");
+  if (at > 0) {
+    pin = rest.slice(at + 1);
+    rest = rest.slice(0, at);
+    if (!pin) throw new SkillRefParseError(ref, "empty ref after `@`");
+    if (!REF_RE.test(pin)) throw new SkillRefParseError(ref, "ref contains disallowed characters");
+  }
+  let path = null;
+  const hash = rest.indexOf("#");
+  if (hash >= 0) {
+    path = rest.slice(hash + 1);
+    rest = rest.slice(0, hash);
+    if (!path) throw new SkillRefParseError(ref, "empty path after `#`");
+    for (const seg of path.split("/")) {
+      if (!PATH_SEG_RE.test(seg)) throw new SkillRefParseError(ref, "path contains disallowed characters");
+    }
+  }
+  const lastSlash = rest.lastIndexOf("/");
+  let owner;
+  let name;
+  if (lastSlash === -1) {
+    owner = null;
+    name = rest;
+  } else {
+    owner = rest.slice(0, lastSlash);
+    name = rest.slice(lastSlash + 1);
+  }
+  if (!name) throw new SkillRefParseError(ref, "empty name segment");
+  if (owner !== null && !OWNER_RE2.test(owner)) throw new SkillRefParseError(ref, "owner contains disallowed characters");
+  if (!NAME_RE2.test(name)) throw new SkillRefParseError(ref, "name contains disallowed characters");
+  return { source, owner, name, path, ref: pin };
+}
+function formatSkillRef(p) {
+  let base = p.owner ? `${p.source}/${p.owner}/${p.name}` : `${p.source}/${p.name}`;
+  if (p.path) base += `#${p.path}`;
+  return p.ref ? `${base}@${p.ref}` : base;
+}
+function skillKey(p) {
+  const base = p.owner ? `${p.source}/${p.owner}/${p.name}` : `${p.source}/${p.name}`;
+  return p.path ? `${base}#${p.path}` : base;
+}
+
 // ../core/src/canonical.ts
 function canonicalStringify(value) {
   return JSON.stringify(sortDeep(value));
@@ -116,5 +179,9 @@ export {
   parseServerRef,
   formatServerRef,
   serverKey,
+  SkillRefParseError,
+  parseSkillRef,
+  formatSkillRef,
+  skillKey,
   canonicalStringify
 };