@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/exposure-catalog.js

@@ -0,0 +1,276 @@
+import path from "node:path";
+import { readJson } from "../fs-utils.js";
+import { getMcpLocalCapabilitiesPath, getMcpServersPath, getRepoRoot } from "../paths.js";
+import { validateRuntimeMcpPolicyFile } from "./mcp-policy.js";
+
+const advisoryCatalog = [
+  {
+    ecosystem: "npm",
+    packageName: "tar",
+    vulnerableBelow: "6.2.1",
+    severity: "critical",
+    confidence: "high",
+    diagnostic: "tar < 6.2.1 allows arbitrary file overwrite.",
+    recommendedAction: "Upgrade tar to 6.2.1 or newer in the lockfile and reverify.",
+    advisoryReference: "advisory-2026-0042",
+  },
+];
+
+function normalizePackageNameFromLockPath(lockPath) {
+  const marker = "node_modules/";
+  const markerIndex = lockPath.lastIndexOf(marker);
+  if (markerIndex === -1) {
+    return null;
+  }
+
+  return lockPath.slice(markerIndex + marker.length);
+}
+
+function compareSemver(a, b) {
+  const parse = (value) =>
+    `${value}`.split(".").map((part) => Number.parseInt(part.replace(/[^0-9].*$/, ""), 10) || 0);
+  const left = parse(a);
+  const right = parse(b);
+  const maxLength = Math.max(left.length, right.length);
+
+  for (let index = 0; index < maxLength; index += 1) {
+    const leftValue = left[index] ?? 0;
+    const rightValue = right[index] ?? 0;
+    if (leftValue > rightValue) {
+      return 1;
+    }
+    if (leftValue < rightValue) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+function normalizeManifestVersion(value) {
+  const match = `${value}`.match(/\d+(?:\.\d+){0,2}/);
+  return match ? match[0] : null;
+}
+
+export async function scanLockfilePackageExposure() {
+  const lockfilePath = path.join(getRepoRoot(), "package-lock.json");
+  let lockfile;
+  try {
+    lockfile = await readJson(lockfilePath);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
+  return scanPackageExposureFromLockfile(lockfile, {
+    sourcePath: lockfilePath,
+    catalog: advisoryCatalog,
+  });
+}
+
+export function scanPackageExposureFromLockfile(
+  lockfile,
+  { sourcePath = "package-lock.json", catalog = advisoryCatalog } = {},
+) {
+  const packages = lockfile?.packages ?? {};
+  const findings = [];
+
+  for (const [lockPath, entry] of Object.entries(packages)) {
+    if (!lockPath || lockPath === "" || !entry?.version) {
+      continue;
+    }
+
+    const packageName = normalizePackageNameFromLockPath(lockPath);
+    if (!packageName) {
+      continue;
+    }
+
+    for (const advisory of catalog) {
+      if (packageName !== advisory.packageName) {
+        continue;
+      }
+
+      if (compareSemver(entry.version, advisory.vulnerableBelow) >= 0) {
+        continue;
+      }
+
+      findings.push({
+        record_type: "finding:package_exposure",
+        severity: advisory.severity,
+        confidence: advisory.confidence,
+        ecosystem: advisory.ecosystem,
+        package_name: packageName,
+        package_version: entry.version,
+        source_path: sourcePath,
+        evidence_kind: "lockfile-version-match",
+        diagnostic: advisory.diagnostic,
+        recommended_action: advisory.recommendedAction,
+        advisory_reference: advisory.advisoryReference,
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function scanPackageExposureFromManifest(
+  manifest,
+  { sourcePath = "package.json", catalog = advisoryCatalog } = {},
+) {
+  const dependencyGroups = [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+  ];
+  const findings = [];
+
+  for (const group of dependencyGroups) {
+    for (const [packageName, versionRange] of Object.entries(manifest?.[group] ?? {})) {
+      const normalizedVersion = normalizeManifestVersion(versionRange);
+      if (!normalizedVersion) {
+        continue;
+      }
+
+      for (const advisory of catalog) {
+        if (packageName !== advisory.packageName) {
+          continue;
+        }
+        if (compareSemver(normalizedVersion, advisory.vulnerableBelow) >= 0) {
+          continue;
+        }
+
+        findings.push({
+          record_type: "finding:package_exposure",
+          severity: advisory.severity,
+          confidence: "medium",
+          ecosystem: advisory.ecosystem,
+          package_name: packageName,
+          package_version: versionRange,
+          normalized_version: normalizedVersion,
+          source_path: sourcePath,
+          evidence_kind: "manifest-version-range-match",
+          dependency_group: group,
+          diagnostic: advisory.diagnostic,
+          recommended_action: advisory.recommendedAction,
+          advisory_reference: advisory.advisoryReference,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export async function validateMcpPolicyExposure({ activeProfile = "project" } = {}) {
+  const findings = [];
+
+  try {
+    const localCapabilities = await readJson(getMcpLocalCapabilitiesPath());
+    for (const capability of localCapabilities.capabilities ?? []) {
+      if (
+        typeof capability.module === "string" &&
+        !capability.module.startsWith("./local/") &&
+        capability.kind === "local-capability"
+      ) {
+        findings.push({
+          record_type: "policy:mcp_validation",
+          severity: "warning",
+          confidence: "high",
+          diagnostic: `Local capability module '${capability.module}' escapes the expected ./local/ namespace.`,
+          source_path: getMcpLocalCapabilitiesPath(),
+          recommended_action:
+            "Keep packaged local capability modules inside the ./local/ namespace or document the exception explicitly.",
+        });
+      }
+    }
+  } catch (error) {
+    if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  try {
+    const servers = await readJson(getMcpServersPath());
+    for (const server of servers.servers ?? []) {
+      if (typeof server.endpoint === "string" && server.endpoint === "https://gitmcp.io/docs") {
+        findings.push({
+          record_type: "policy:mcp_validation",
+          severity: "warning",
+          confidence: "high",
+          diagnostic: "Fallback docs endpoint is configured as an approved evidence source.",
+          source_path: getMcpServersPath(),
+          recommended_action:
+            "Use exact repo-form GitMCP endpoints in mcp/servers.json instead of the docs fallback endpoint.",
+        });
+      }
+    }
+  } catch (error) {
+    if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  findings.push(...(await validateRuntimeMcpPolicyFile({ activeProfile })));
+
+  return findings;
+}
+
+export async function scanExposureProfile(profile = "baseline") {
+  const allowedProfiles = new Set(["baseline", "project", "deep"]);
+  if (!allowedProfiles.has(profile)) {
+    throw new Error(`Unsupported exposure scan profile: ${profile}`);
+  }
+
+  const lockfileFindings = await scanLockfilePackageExposure();
+  let manifestFindings = [];
+  if (profile !== "baseline") {
+    try {
+      const manifestPath = path.join(getRepoRoot(), "package.json");
+      manifestFindings = scanPackageExposureFromManifest(await readJson(manifestPath), {
+        sourcePath: manifestPath,
+        catalog: advisoryCatalog,
+      });
+    } catch (error) {
+      if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) {
+        throw error;
+      }
+    }
+  }
+  const policyFindings =
+    profile === "baseline" ? [] : await validateMcpPolicyExposure({ activeProfile: profile });
+  const findings = [...lockfileFindings, ...manifestFindings, ...policyFindings];
+
+  return {
+    record_type: "exposure_profile_report",
+    profile,
+    read_only: true,
+    mutates_release_state: false,
+    findings,
+    blocker_count: findings.filter((finding) =>
+      ["critical", "high"].includes(`${finding.severity}`.toLowerCase()),
+    ).length,
+    scanned_surfaces:
+      profile === "baseline"
+        ? ["package-lock.json"]
+        : profile === "project"
+          ? [
+              "package-lock.json",
+              "package.json",
+              "mcp/local-capabilities.json",
+              "mcp/servers.json",
+              ".ma/.mcp.json",
+            ]
+          : [
+              "package-lock.json",
+              "package.json",
+              "mcp/local-capabilities.json",
+              "mcp/servers.json",
+              ".ma/.mcp.json",
+              "policy",
+            ],
+  };
+}

package/src/runtime/graphify-core.js

@@ -0,0 +1,167 @@
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const graphifySchemaVersion = "0.1.0";
+
+export function getGraphifyRoot() {
+  return getRuntimeSubsystemPath("context", "graphify");
+}
+
+export function getGraphifyIndexPath() {
+  return getRuntimeSubsystemPath("context", "graphify", "index.json");
+}
+
+export function createDefaultGraphifyIndex() {
+  return {
+    schemaVersion: graphifySchemaVersion,
+    record_type: "derived_graph_index",
+    read_only: true,
+    nodes: [],
+    edges: [],
+    lastRebuiltAt: null,
+  };
+}
+
+export function validateGraphifyIndex(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("graphify index must be an object");
+  }
+  if (value.schemaVersion !== graphifySchemaVersion) {
+    throw new Error(`Unsupported graphify schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.record_type !== "derived_graph_index" || value.read_only !== true) {
+    throw new Error("graphify index must be a read-only derived_graph_index");
+  }
+  if (!Array.isArray(value.nodes) || !Array.isArray(value.edges)) {
+    throw new Error("graphify index requires nodes and edges arrays");
+  }
+  return value;
+}
+
+export async function seedGraphifyArtifacts() {
+  await ensureDir(getGraphifyRoot());
+  await writeFileIfMissing(
+    getGraphifyIndexPath(),
+    `${JSON.stringify(createDefaultGraphifyIndex(), null, 2)}\n`,
+  );
+}
+
+export async function loadGraphifyIndex() {
+  return validateGraphifyIndex(await readJson(getGraphifyIndexPath()));
+}
+
+function addNode(nodes, seen, id, kind, sourceSubsystem, label) {
+  if (!id || seen.has(id)) return;
+  seen.add(id);
+  nodes.push({ id, kind, sourceSubsystem, label: String(label ?? id) });
+}
+
+function addEdge(edges, seen, from, to, relation) {
+  if (!from || !to || from === to) return;
+  const key = `${from}\0${to}\0${relation}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  edges.push({ from, to, relation });
+}
+
+function addCollection(nodes, edges, nodeIds, edgeIds, sourceSubsystem, kind, entries, labelKey) {
+  for (const [index, entry] of (Array.isArray(entries) ? entries : []).entries()) {
+    if (!entry || typeof entry !== "object") continue;
+    const id = `${sourceSubsystem}:${kind}:${entry.id ?? entry.name ?? index}`;
+    addNode(
+      nodes,
+      nodeIds,
+      id,
+      kind,
+      sourceSubsystem,
+      entry[labelKey] ?? entry.name ?? entry.id ?? id,
+    );
+    if (entry.projectId) addEdge(edges, edgeIds, id, `project:${entry.projectId}`, "belongs_to");
+  }
+}
+
+export function rebuildGraphifyIndex(runtimeSnapshot = {}) {
+  const nodes = [];
+  const edges = [];
+  const nodeIds = new Set();
+  const edgeIds = new Set();
+  addNode(nodes, nodeIds, "project:root", "project", "project", "Project");
+
+  const continuity = runtimeSnapshot.continuityIndex;
+  if (continuity && typeof continuity === "object") {
+    addNode(nodes, nodeIds, "memory:continuity", "memory", "continuity", "Continuity memory");
+    addEdge(edges, edgeIds, "memory:continuity", "project:root", "supports");
+  }
+  const taskRegistry = runtimeSnapshot.taskRegistry ?? {};
+  addCollection(nodes, edges, nodeIds, edgeIds, "tasks", "task", taskRegistry.tasks, "title");
+  addCollection(nodes, edges, nodeIds, edgeIds, "tasks", "worker", taskRegistry.workers, "name");
+  for (const entry of runtimeSnapshot.mailboxEntries ?? []) {
+    if (typeof entry !== "string") continue;
+    const id = `tasks:mailbox:${entry}`;
+    addNode(nodes, nodeIds, id, "mailbox", "tasks", entry, entry);
+    addEdge(edges, edgeIds, id, "project:root", "supports");
+  }
+  addCollection(
+    nodes,
+    edges,
+    nodeIds,
+    edgeIds,
+    "workspaces",
+    "workspace",
+    runtimeSnapshot.workspaceIndex?.items,
+    "name",
+  );
+  addCollection(
+    nodes,
+    edges,
+    nodeIds,
+    edgeIds,
+    "manager",
+    "run",
+    runtimeSnapshot.managerRuns?.runs,
+    "state",
+  );
+  addCollection(
+    nodes,
+    edges,
+    nodeIds,
+    edgeIds,
+    "decisions",
+    "decision",
+    runtimeSnapshot.decisions?.decisions,
+    "title",
+  );
+
+  const vault = runtimeSnapshot.obsidianVaultIndex;
+  if (vault?.note_count > 0) {
+    addNode(
+      nodes,
+      nodeIds,
+      "obsidian:vault",
+      "vault",
+      "obsidian",
+      vault.vault_path || "Obsidian vault",
+    );
+    addEdge(edges, edgeIds, "obsidian:vault", "project:root", "context");
+  }
+
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  edges.sort((a, b) =>
+    `${a.from}:${a.to}:${a.relation}`.localeCompare(`${b.from}:${b.to}:${b.relation}`),
+  );
+  return {
+    schemaVersion: graphifySchemaVersion,
+    record_type: "derived_graph_index",
+    read_only: true,
+    nodes,
+    edges,
+    lastRebuiltAt: new Date().toISOString(),
+  };
+}
+
+export async function writeGraphifyIndex(runtimeSnapshot) {
+  const index = validateGraphifyIndex(rebuildGraphifyIndex(runtimeSnapshot));
+  await ensureDir(getGraphifyRoot());
+  await writeJson(getGraphifyIndexPath(), index);
+  return index;
+}

package/src/runtime/guidance-stack.js

@@ -20,8 +20,8 @@ export async function seedGuidanceStackArtifacts() {
     `${JSON.stringify(
       {
         schemaVersion: "0.1.0",
-        sources: [],
-        content: "",
+        sources: [ponytailGuidanceSource],
+        content: ponytailGuidanceSource.content,
       },
       null,
       2,
@@ -40,3 +40,10 @@ export async function seedGuidanceStackArtifacts() {
     )}\n`,
   );
 }
+
+export const ponytailGuidanceSource = {
+  id: "ponytail",
+  label: "Minimal-diff bias",
+  content:
+    "Apply a minimal-diff bias: prefer reuse over new abstractions, the smallest coherent diff, and deletion before addition. Preserve existing behavior and add complexity only when verification proves it is needed.",
+};

package/src/runtime/handoff-packets.js

@@ -0,0 +1,92 @@
+import path from "node:path";
+import { ensureDir, readJson, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const handoffPacketSchemaVersion = "0.1.0";
+
+export function getHandoffPacketRoot() {
+  return getRuntimeSubsystemPath("tasks", "handoffs");
+}
+
+function safePacketId(id) {
+  if (String(id ?? "").includes("/") || String(id ?? "").includes("\\"))
+    throw new Error("handoff packet id is required");
+  const safe = String(id ?? "")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, "-");
+  if (!safe || safe === "." || safe === "..") throw new Error("handoff packet id is required");
+  return safe;
+}
+
+export function createHandoffPacket({
+  goal,
+  currentState,
+  contextUsed = [],
+  decisions = [],
+  blockers = [],
+  risks = [],
+  changedFiles = [],
+  verification = [],
+  nextAction,
+  status = "active",
+}) {
+  if (!goal || !currentState || !nextAction)
+    throw new Error("handoff packet requires goal, currentState, and nextAction");
+  return validateHandoffPacket({
+    schemaVersion: handoffPacketSchemaVersion,
+    record_type: "handoff_packet",
+    goal,
+    current_state: currentState,
+    context_used: contextUsed,
+    decisions,
+    blockers,
+    risks,
+    changed_files: changedFiles,
+    verification,
+    next_action: nextAction,
+    status,
+    created_at: new Date().toISOString(),
+  });
+}
+
+export function validateHandoffPacket(packet) {
+  if (
+    !packet ||
+    packet.schemaVersion !== handoffPacketSchemaVersion ||
+    packet.record_type !== "handoff_packet"
+  )
+    throw new Error("invalid handoff packet schema");
+  for (const field of ["goal", "current_state", "next_action"]) {
+    if (typeof packet[field] !== "string" || packet[field].trim() === "")
+      throw new Error(`handoff packet requires ${field}`);
+  }
+  for (const field of [
+    "context_used",
+    "decisions",
+    "blockers",
+    "risks",
+    "changed_files",
+    "verification",
+  ]) {
+    if (!Array.isArray(packet[field]) || packet[field].some((value) => typeof value !== "string"))
+      throw new Error(`handoff packet requires string array: ${field}`);
+  }
+  if (!["active", "blocked", "verified"].includes(packet.status))
+    throw new Error(`Unsupported handoff packet status: ${packet.status}`);
+  return packet;
+}
+
+export async function writeHandoffPacket(id, packet) {
+  const packetId = safePacketId(id);
+  const validated = validateHandoffPacket(packet);
+  await ensureDir(getHandoffPacketRoot());
+  const packetPath = path.join(getHandoffPacketRoot(), `${packetId}.json`);
+  await writeJson(packetPath, validated);
+  return packetPath;
+}
+
+export async function loadHandoffPacket(id) {
+  return validateHandoffPacket(
+    await readJson(path.join(getHandoffPacketRoot(), `${safePacketId(id)}.json`)),
+  );
+}

package/src/runtime/headroom-core.js

@@ -0,0 +1,104 @@
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const headroomSchemaVersion = "0.1.0";
+
+const defaultBudgets = {
+  pendingMailboxCount: { warn: 3, critical: 8 },
+  taskCount: { warn: 10, critical: 25 },
+  activeManagerRunCount: { warn: 2, critical: 5 },
+  waitingReviewManagerRunCount: { warn: 1, critical: 3 },
+};
+
+export function getHeadroomRoot() {
+  return getRuntimeSubsystemPath("headroom");
+}
+
+export function getHeadroomBudgetsPath() {
+  return getRuntimeSubsystemPath("headroom", "budgets.json");
+}
+
+export function getHeadroomStatusPath() {
+  return getRuntimeSubsystemPath("headroom", "status.json");
+}
+
+export function createDefaultHeadroomBudgets() {
+  return { schemaVersion: headroomSchemaVersion, budgets: structuredClone(defaultBudgets) };
+}
+
+export function createDefaultHeadroomStatus() {
+  return { schemaVersion: headroomSchemaVersion, evaluatedAt: null, signals: [] };
+}
+
+export function validateHeadroomBudgets(value) {
+  if (!value || typeof value !== "object" || value.schemaVersion !== headroomSchemaVersion) {
+    throw new Error("headroom budgets require the current schemaVersion");
+  }
+  if (!value.budgets || typeof value.budgets !== "object" || Array.isArray(value.budgets)) {
+    throw new Error("headroom budgets require a budgets object");
+  }
+  for (const [counter, budget] of Object.entries(value.budgets)) {
+    if (
+      !budget ||
+      !Number.isFinite(budget.warn) ||
+      !Number.isFinite(budget.critical) ||
+      budget.warn < 0 ||
+      budget.critical < budget.warn
+    ) {
+      throw new Error(`Invalid headroom budget for ${counter}`);
+    }
+  }
+  return value;
+}
+
+export function validateHeadroomStatus(value) {
+  if (!value || typeof value !== "object" || value.schemaVersion !== headroomSchemaVersion) {
+    throw new Error("headroom status requires the current schemaVersion");
+  }
+  if (!Array.isArray(value.signals)) throw new Error("headroom status requires signals");
+  return value;
+}
+
+export async function seedHeadroomArtifacts() {
+  await ensureDir(getHeadroomRoot());
+  await writeFileIfMissing(
+    getHeadroomBudgetsPath(),
+    `${JSON.stringify(createDefaultHeadroomBudgets(), null, 2)}\n`,
+  );
+  await writeFileIfMissing(
+    getHeadroomStatusPath(),
+    `${JSON.stringify(createDefaultHeadroomStatus(), null, 2)}\n`,
+  );
+}
+
+export async function loadHeadroomBudgets() {
+  return validateHeadroomBudgets(await readJson(getHeadroomBudgetsPath()));
+}
+
+export async function loadHeadroomStatus() {
+  return validateHeadroomStatus(await readJson(getHeadroomStatusPath()));
+}
+
+export function evaluateHeadroom(
+  runtimeSummary = {},
+  budgetConfig = createDefaultHeadroomBudgets(),
+) {
+  const config = validateHeadroomBudgets(budgetConfig);
+  const signals = Object.entries(config.budgets).map(([counter, budget]) => {
+    const value = Number(runtimeSummary[counter] ?? 0);
+    const level = value >= budget.critical ? "critical" : value >= budget.warn ? "warn" : "ok";
+    return { counter, value, warn: budget.warn, critical: budget.critical, level };
+  });
+  return {
+    schemaVersion: headroomSchemaVersion,
+    evaluatedAt: new Date().toISOString(),
+    signals,
+  };
+}
+
+export async function writeHeadroomStatus(runtimeSummary, budgetConfig) {
+  const status = validateHeadroomStatus(evaluateHeadroom(runtimeSummary, budgetConfig));
+  await ensureDir(getHeadroomRoot());
+  await writeJson(getHeadroomStatusPath(), status);
+  return status;
+}