softwareobservatory 0.1.0

package/lib/core.mjs

@@ -0,0 +1,189 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const DATA_PATH = fileURLToPath(new URL("../data/sensors.json", import.meta.url));
+
+let cache = null;
+
+export function loadData() {
+  if (!cache) {
+    cache = JSON.parse(readFileSync(DATA_PATH, "utf8"));
+  }
+  return cache;
+}
+
+export function siteUrl(path = "") {
+  const base = loadData().site.replace(/\/$/, "");
+  return path ? `${base}/${path.replace(/^\//, "")}` : base;
+}
+
+export function listFamilies() {
+  return loadData().families;
+}
+
+export function getFamily(slug) {
+  const normalized = String(slug).toLowerCase();
+  return loadData().families.find((f) => f.slug === normalized) || null;
+}
+
+export function listSensors({ family } = {}) {
+  const { sensors } = loadData();
+  if (!family) return sensors;
+  const normalized = String(family).toLowerCase();
+  return sensors.filter((s) => s.family === normalized);
+}
+
+export function findSensor(query) {
+  const { sensors } = loadData();
+  const normalized = String(query).toLowerCase();
+  return (
+    sensors.find((s) => s.id.toLowerCase() === normalized) ||
+    sensors.find((s) => s.slug === normalized) ||
+    sensors.find((s) => s.title.toLowerCase() === normalized) ||
+    null
+  );
+}
+
+export function getRelated(sensor) {
+  const related = [];
+  for (const id of sensor.see_also_ids) {
+    const target = findSensor(id);
+    if (target) {
+      related.push({ kind: "sensor", id: target.id, slug: target.slug, title: target.title, family: target.family });
+    }
+  }
+  for (const slug of sensor.see_also_families) {
+    const family = getFamily(slug);
+    if (family) {
+      related.push({ kind: "family", slug: family.slug, name: family.name });
+    }
+  }
+  for (const page of sensor.see_also_pages) {
+    related.push({ kind: "page", ref: page });
+  }
+  return related;
+}
+
+export function listValues(field) {
+  const values = new Set();
+  for (const sensor of loadData().sensors) {
+    const value = sensor.frontmatter[field];
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) values.add(String(item));
+    } else {
+      values.add(String(value));
+    }
+  }
+  return [...values].sort();
+}
+
+const STOPWORDS = new Set([
+  "the", "and", "for", "are", "but", "not", "you", "your", "yours", "all", "any",
+  "can", "could", "should", "would", "will", "shall", "may", "might", "must",
+  "our", "ours", "their", "theirs", "his", "her", "hers", "its", "this", "that",
+  "these", "those", "there", "here", "what", "when", "where", "which", "who",
+  "whom", "why", "how", "has", "have", "had", "having", "does", "did", "doing",
+  "done", "was", "were", "been", "being", "with", "from", "into", "onto", "upon",
+  "about", "after", "before", "between", "through", "during", "without", "within",
+  "they", "them", "then", "than", "too", "very", "just", "still", "even", "also",
+  "know", "make", "made", "get", "got", "use", "used", "using", "want", "need",
+]);
+
+export function suggestSensors(question, { limit = 5 } = {}) {
+  const { sensors, families } = loadData();
+  const terms = String(question)
+    .toLowerCase()
+    .split(/[^\w]+/)
+    .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+  if (terms.length === 0) return [];
+
+  const scored = [];
+  for (const sensor of sensors) {
+    const title = sensor.title.toLowerCase();
+    const family = getFamily(sensor.family);
+    const familyText = family ? `${family.name} ${family.question} ${family.examples}`.toLowerCase() : "";
+    let score = 0;
+    for (const term of terms) {
+      if (title.includes(term)) score += 6;
+      if (familyText.includes(term)) score += 2;
+      if (sensor.body_text.includes(term)) score += 1;
+    }
+    if (score > 0) scored.push({ sensor, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.sensor.slug.localeCompare(b.sensor.slug));
+
+  const seenFamilies = new Set();
+  return scored.slice(0, limit).map(({ sensor, score }) => {
+    const matched = terms.filter(
+      (t) => sensor.title.toLowerCase().includes(t) || sensor.body_text.includes(t)
+    );
+    const firstOfFamily = !seenFamilies.has(sensor.family);
+    seenFamilies.add(sensor.family);
+    return {
+      id: sensor.id,
+      slug: sensor.slug,
+      title: sensor.title,
+      family: sensor.family,
+      score,
+      matched_terms: matched,
+      gap: firstOfFamily,
+      url: siteUrl(sensor.url_path),
+    };
+  });
+}
+
+export function stackCoverage(ids) {
+  const { sensors, families } = loadData();
+  const selected = [];
+  const unknown = [];
+  for (const id of ids) {
+    const sensor = findSensor(id);
+    if (sensor) selected.push(sensor);
+    else unknown.push(id);
+  }
+
+  const coveredFamilies = new Map();
+  const stackLevels = new Map();
+  const oracles = new Map();
+  const latencies = new Map();
+  const types = new Map();
+  for (const sensor of selected) {
+    coveredFamilies.set(sensor.family, (coveredFamilies.get(sensor.family) || 0) + 1);
+    const fm = sensor.frontmatter;
+    if (fm.stack_level) stackLevels.set(fm.stack_level, (stackLevels.get(fm.stack_level) || 0) + 1);
+    if (fm.oracle) oracles.set(fm.oracle, (oracles.get(fm.oracle) || 0) + 1);
+    if (fm.latency) latencies.set(fm.latency, (latencies.get(fm.latency) || 0) + 1);
+    if (fm.type) types.set(fm.type, (types.get(fm.type) || 0) + 1);
+  }
+
+  const missing = families.filter((f) => !coveredFamilies.has(f.slug));
+  const recommendations = [];
+  for (const family of missing.slice(0, 3)) {
+    const candidate = sensors.find((s) => s.family === family.slug);
+    if (candidate) {
+      recommendations.push({
+        id: candidate.id,
+        slug: candidate.slug,
+        title: candidate.title,
+        family: candidate.family,
+        reason: `covers the ${family.name} family ("${family.question}")`,
+      });
+    }
+  }
+
+  return {
+    selected: selected.map((s) => ({ id: s.id, slug: s.slug, title: s.title, family: s.family })),
+    unknown_ids: unknown,
+    coverage: {
+      families: Object.fromEntries(coveredFamilies),
+      stack_levels: Object.fromEntries(stackLevels),
+      oracle: Object.fromEntries(oracles),
+      latency: Object.fromEntries(latencies),
+      type: Object.fromEntries(types),
+    },
+    missing_families: missing.map((f) => ({ slug: f.slug, name: f.name, question: f.question })),
+    recommendations,
+  };
+}

package/lib/mcp.mjs

@@ -0,0 +1,190 @@
+import readline from "node:readline";
+import {
+  loadData,
+  siteUrl,
+  listFamilies,
+  getFamily,
+  listSensors,
+  findSensor,
+  getRelated,
+  suggestSensors,
+  stackCoverage,
+} from "./core.mjs";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_INFO = { name: "softwareobservatory", version: "0.1.0" };
+
+const TOOLS = [
+  {
+    name: "list_families",
+    description: "List the 11 sensor families of the Software Observatory catalog.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "list_sensors",
+    description: "List sensors, optionally filtered by family slug.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        family: { type: "string", description: "Family slug, e.g. 'structural' or 'adversarial'." },
+      },
+    },
+  },
+  {
+    name: "get_sensor",
+    description: "Get one sensor by id (SO-###), slug, or exact title, including its full entry text and related sensors.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Sensor id, slug, or exact title." },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "suggest_sensors",
+    description:
+      "Given a plain-language description of a project or concern, suggest sensors whose entries address it. Results flagged 'gap' are the first suggestion from a family not yet represented by a higher-scoring result.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        question: { type: "string", description: "The concern to match, e.g. 'our tests pass but bugs still ship'." },
+        limit: { type: "number", description: "Max results (default 5)." },
+      },
+      required: ["question"],
+    },
+  },
+  {
+    name: "stack_coverage",
+    description:
+      "Assess a set of sensors (by id or slug) for family and confidence-stack coverage, and recommend sensors for uncovered families.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: { type: "array", items: { type: "string" }, description: "Sensor ids or slugs." },
+      },
+      required: ["ids"],
+    },
+  },
+];
+
+function sensorSummary(sensor) {
+  return {
+    id: sensor.id,
+    slug: sensor.slug,
+    title: sensor.title,
+    family: sensor.family,
+    url: siteUrl(sensor.url_path),
+  };
+}
+
+function callTool(name, args = {}) {
+  switch (name) {
+    case "list_families":
+      return listFamilies();
+    case "list_sensors":
+      return listSensors({ family: args.family }).map((s) => ({
+        ...sensorSummary(s),
+        oracle: s.frontmatter.oracle,
+        latency: s.frontmatter.latency,
+        type: s.frontmatter.type,
+      }));
+    case "get_sensor": {
+      const sensor = findSensor(args.query || "");
+      if (!sensor) return { error: `no sensor matches '${args.query}'` };
+      return { ...sensorSummary(sensor), frontmatter: sensor.frontmatter, body_text: sensor.body_text, related: getRelated(sensor) };
+    }
+    case "suggest_sensors":
+      return suggestSensors(args.question || "", { limit: args.limit });
+    case "stack_coverage":
+      return stackCoverage(args.ids || []);
+    default:
+      throw Object.assign(new Error(`unknown tool '${name}'`), { code: -32602 });
+  }
+}
+
+function resources() {
+  return [
+    { uri: "softwareobservatory://families", name: "Sensor families", mimeType: "application/json" },
+    ...loadData().sensors.map((s) => ({
+      uri: `softwareobservatory://sensor/${s.slug}`,
+      name: s.title,
+      description: `${s.id} (${s.family})`,
+      mimeType: "application/json",
+    })),
+  ];
+}
+
+function readResource(uri) {
+  const data = loadData();
+  if (uri === "softwareobservatory://families") {
+    return JSON.stringify(data.families, null, 2);
+  }
+  const match = uri.match(/^softwareobservatory:\/\/sensor\/(.+)$/);
+  if (match) {
+    const sensor = findSensor(match[1]);
+    if (sensor) return JSON.stringify({ ...sensor, url: siteUrl(sensor.url_path) }, null, 2);
+  }
+  throw Object.assign(new Error(`unknown resource '${uri}'`), { code: -32602 });
+}
+
+function respond(id, result, error) {
+  const message = { jsonrpc: "2.0", id };
+  if (error) message.error = { code: error.code || -32603, message: error.message };
+  else message.result = result;
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+function handleMessage(message) {
+  const { id, method, params = {} } = message;
+  try {
+    switch (method) {
+      case "initialize":
+        respond(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {}, resources: {} }, serverInfo: SERVER_INFO });
+        break;
+      case "ping":
+        respond(id, {});
+        break;
+      case "notifications/initialized":
+        break;
+      case "tools/list":
+        respond(id, { tools: TOOLS });
+        break;
+      case "tools/call": {
+        const result = callTool(params.name, params.arguments);
+        respond(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+        break;
+      }
+      case "resources/list":
+        respond(id, { resources: resources() });
+        break;
+      case "resources/read": {
+        const text = readResource(params.uri);
+        respond(id, { contents: [{ uri: params.uri, mimeType: "application/json", text }] });
+        break;
+      }
+      default:
+        if (id !== undefined && id !== null) {
+          respond(id, null, { code: -32601, message: `method not found: ${method}` });
+        }
+    }
+  } catch (error) {
+    respond(id ?? null, null, { code: error.code || -32603, message: error.message });
+  }
+}
+
+export function startMcpServer() {
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch {
+      respond(null, null, { code: -32700, message: "parse error" });
+      return;
+    }
+    handleMessage(message);
+  });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "softwareobservatory",
+  "version": "0.1.0",
+  "description": "Query the Software Observatory catalog of epistemic sensors for software correctness. Built for humans and agents: every command emits JSON with --json.",
+  "keywords": [
+    "observability",
+    "testing",
+    "correctness",
+    "sensors",
+    "software-quality",
+    "agents",
+    "mcp"
+  ],
+  "homepage": "https://softwareobservatory.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justinabrahms/software-observatory.git",
+    "directory": "cli"
+  },
+  "license": "CC-BY-NC-SA-4.0",
+  "type": "module",
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "bin": {
+    "softwareobservatory": "bin/softwareobservatory.mjs",
+    "sensors": "bin/softwareobservatory.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "data/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}