@jstn-sdk/ma 0.1.10 → 0.1.12

package/src/mcp-config.js

@@ -1,7 +1,26 @@
 import fs from "node:fs/promises";
-import { getMcpServersPath } from "./paths.js";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getBundledMcpPath, getMcpLocalCapabilitiesPath, getMcpServersPath } from "./paths.js";
 
 const gitMcpRepoPattern = /^https:\/\/gitmcp\.io\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const localCapabilityNames = ["_state", "memory", "trace", "team_run", "code_intel", "playbooks"];
+const localCapabilityNameSet = new Set(localCapabilityNames);
+
+function validateObjectWithArray(parsed, arrayField, label) {
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed[arrayField])) {
+    throw new Error(`${label} must be an object with a ${arrayField} array`);
+  }
+
+  return parsed;
+}
+
+function normalizeGitMcpDescriptor(server) {
+  return {
+    ...server,
+    kind: server.kind ?? "gitmcp-evidence",
+  };
+}
 
 export function isValidGitMcpEndpoint(url) {
   return gitMcpRepoPattern.test(url);
@@ -9,18 +28,25 @@ export function isValidGitMcpEndpoint(url) {
 
 export async function loadMcpServers() {
   const raw = await fs.readFile(getMcpServersPath(), "utf8");
-  const parsed = JSON.parse(raw);
-
-  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.servers)) {
-    throw new Error("mcp/servers.json must be an object with a servers array");
-  }
-
-  return parsed;
+  const parsed = validateObjectWithArray(JSON.parse(raw), "servers", "mcp/servers.json");
+  return {
+    ...parsed,
+    servers: parsed.servers.map(normalizeGitMcpDescriptor),
+  };
 }
 
 export async function validateMcpServers() {
   const parsed = await loadMcpServers();
   for (const server of parsed.servers) {
+    if (server.kind !== "gitmcp-evidence") {
+      throw new Error(`Invalid GitMCP descriptor kind: ${server.kind ?? "(missing)"}`);
+    }
+    if (typeof server.category !== "string" || server.category.trim() === "") {
+      throw new Error("GitMCP descriptors require a category");
+    }
+    if (typeof server.repo !== "string" || server.repo.trim() === "") {
+      throw new Error("GitMCP descriptors require a repo");
+    }
     if (!isValidGitMcpEndpoint(server.endpoint)) {
       throw new Error(`Invalid GitMCP endpoint: ${server.endpoint}`);
     }
@@ -28,3 +54,99 @@ export async function validateMcpServers() {
 
   return parsed;
 }
+
+export async function loadLocalCapabilities() {
+  const raw = await fs.readFile(getMcpLocalCapabilitiesPath(), "utf8");
+  return validateObjectWithArray(JSON.parse(raw), "capabilities", "mcp/local-capabilities.json");
+}
+
+export function getSupportedLocalCapabilities() {
+  return [...localCapabilityNames];
+}
+
+export async function validateLocalCapabilities() {
+  const parsed = await loadLocalCapabilities();
+  const seen = new Set();
+
+  for (const descriptor of parsed.capabilities) {
+    if (descriptor.kind !== "local-capability") {
+      throw new Error(`Invalid local capability kind: ${descriptor.kind ?? "(missing)"}`);
+    }
+    if (!localCapabilityNameSet.has(descriptor.capability)) {
+      throw new Error(`Unsupported local capability: ${descriptor.capability}`);
+    }
+    if (seen.has(descriptor.capability)) {
+      throw new Error(`Duplicate local capability: ${descriptor.capability}`);
+    }
+    if (descriptor.transport !== "inproc") {
+      throw new Error(
+        `Local capability ${descriptor.capability} must use inproc transport, received ${descriptor.transport}`,
+      );
+    }
+    if (typeof descriptor.module !== "string" || descriptor.module.trim() === "") {
+      throw new Error(`Local capability ${descriptor.capability} requires a module`);
+    }
+    if (typeof descriptor.readinessCheck !== "string" || descriptor.readinessCheck.trim() === "") {
+      throw new Error(`Local capability ${descriptor.capability} requires a readinessCheck`);
+    }
+    if (descriptor.seededByBootstrap !== true) {
+      throw new Error(
+        `Local capability ${descriptor.capability} must declare seededByBootstrap: true`,
+      );
+    }
+    seen.add(descriptor.capability);
+  }
+
+  for (const capability of localCapabilityNames) {
+    if (!seen.has(capability)) {
+      throw new Error(`Missing local capability descriptor: ${capability}`);
+    }
+  }
+
+  return parsed;
+}
+
+export function resolveLocalCapabilityModulePath(descriptor) {
+  if (path.isAbsolute(descriptor.module)) {
+    throw new Error(`Local capability ${descriptor.capability} cannot use an absolute module path`);
+  }
+
+  const bundledLocalRoot = path.resolve(getBundledMcpPath("local"));
+  const resolvedModulePath = path.resolve(getBundledMcpPath(descriptor.module));
+  if (!resolvedModulePath.startsWith(`${bundledLocalRoot}${path.sep}`)) {
+    throw new Error(
+      `Local capability ${descriptor.capability} must resolve inside bundled mcp/local`,
+    );
+  }
+
+  return resolvedModulePath;
+}
+
+export async function loadLocalCapabilityModule(descriptor) {
+  const modulePath = resolveLocalCapabilityModulePath(descriptor);
+  return import(pathToFileURL(modulePath).href);
+}
+
+export async function runLocalCapabilityReadinessChecks() {
+  const parsed = await validateLocalCapabilities();
+  const results = [];
+
+  for (const descriptor of parsed.capabilities) {
+    const moduleExports = await loadLocalCapabilityModule(descriptor);
+    const readinessCheck = moduleExports[descriptor.readinessCheck];
+    if (typeof readinessCheck !== "function") {
+      throw new Error(
+        `Local capability ${descriptor.capability} is missing readiness export ${descriptor.readinessCheck}`,
+      );
+    }
+
+    const outcome = await readinessCheck();
+    results.push({
+      capability: descriptor.capability,
+      ready: outcome?.ready !== false,
+      detail: outcome?.detail ?? "",
+    });
+  }
+
+  return results;
+}

package/src/mcp-live-client.js

@@ -38,7 +38,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.10",
+        version: "0.1.12-dev",
       },
     });
 

package/src/paths.js

@@ -13,6 +13,14 @@ export function getRuntimeRoot() {
   return path.join(getRepoRoot(), ".ma");
 }
 
+export function getRuntimeSubsystemPath(subsystem, ...parts) {
+  return path.join(getRuntimeRoot(), subsystem, ...parts);
+}
+
+export function getRuntimeStatePath(...parts) {
+  return getRuntimeSubsystemPath("state", ...parts);
+}
+
 export function getRuntimeWritePath(...parts) {
   return path.join(getRuntimeRoot(), ...parts);
 }
@@ -21,6 +29,30 @@ export function getRuntimeReadPath(...parts) {
   return path.join(getRuntimeRoot(), ...parts);
 }
 
+export function getMcpRootPath() {
+  return path.join(getRepoRoot(), "mcp");
+}
+
+export function getBundledMcpPath(...parts) {
+  return path.join(packageRoot, "mcp", ...parts);
+}
+
 export function getMcpServersPath() {
-  return path.join(getRepoRoot(), "mcp", "servers.json");
+  return path.join(getMcpRootPath(), "servers.json");
+}
+
+export function getMcpLocalCapabilitiesPath() {
+  return path.join(getMcpRootPath(), "local-capabilities.json");
+}
+
+export function getBundledNativePlaybooksPath() {
+  return getBundledMcpPath("native-playbooks.json");
+}
+
+export function getBundledDocsPath(...parts) {
+  return path.join(packageRoot, "docs", ...parts);
+}
+
+export function getBundledSkillsPath(...parts) {
+  return path.join(packageRoot, "skills", ...parts);
 }

package/src/release-state.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import { writeJson } from "./fs-utils.js";
 import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
 
-const allowedStatuses = {
+export const allowedStatuses = {
   idea_status: ["DRAFT", "CLEAR", "BLOCKED"],
   architecture_status: ["DRAFT", "REVIEWED", "APPROVED"],
   evidence_status: ["MISSING", "PARTIAL", "VERIFIED"],
@@ -27,6 +27,23 @@ function validateWaiver(state) {
   }
 }
 
+export function createDefaultReleaseState() {
+  return {
+    schemaVersion: "0.1.0",
+    idea_status: "DRAFT",
+    architecture_status: "DRAFT",
+    evidence_status: "MISSING",
+    logic_status: "PENDING",
+    security_status: "PENDING",
+    experience_status: "PENDING",
+    build_status: "LOCKED",
+    merge_status: "LOCKED",
+    release_status: "LOCKED",
+    waiver: null,
+    updatedAt: null,
+  };
+}
+
 export function validateReleaseState(state) {
   if (!state || typeof state !== "object" || Array.isArray(state)) {
     throw new Error("Release state must be an object");
@@ -48,6 +65,18 @@ export async function loadReleaseState() {
   return validateReleaseState(parsed);
 }
 
+export async function loadReleaseStateOrDefault() {
+  try {
+    return await loadReleaseState();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultReleaseState();
+    }
+
+    throw error;
+  }
+}
+
 export async function saveReleaseState(state) {
   validateReleaseState(state);
   const next = {

package/src/runtime/build-readiness.js

@@ -0,0 +1,38 @@
+import {
+  evaluateBuildGate,
+  formatBuildBlockers,
+  formatNextAllowedTriggers,
+} from "../build-gate.js";
+
+export function evaluateRuntimeBuildReadiness(releaseState, runtimeSummary) {
+  const releaseEvaluation = evaluateBuildGate(releaseState);
+  const controlPlaneBlockers = [
+    ...runtimeSummary.invalidArtifacts.filter((artifact) =>
+      ["runtime.release", "runtime.decisions"].includes(artifact),
+    ),
+    ...runtimeSummary.missingArtifacts.filter(
+      (artifact) => artifact === "runtime.release" || artifact === "runtime.decisions",
+    ),
+  ];
+  const runtimeBlockers = [
+    ...runtimeSummary.invalidArtifacts.map((artifact) => `runtime artifact ${artifact} is invalid`),
+    ...runtimeSummary.missingArtifacts.map((artifact) => `runtime artifact ${artifact} is missing`),
+    ...(runtimeSummary.pendingMailboxCount > 0
+      ? ["pending mailbox proposals require leader review"]
+      : []),
+  ];
+  const releaseBlockers = formatBuildBlockers(releaseEvaluation);
+  const nextTriggers =
+    releaseEvaluation.allowed && runtimeBlockers.length > 0
+      ? ["repair runtime artifacts"]
+      : formatNextAllowedTriggers(releaseEvaluation);
+
+  return {
+    allowed: releaseEvaluation.allowed && runtimeBlockers.length === 0,
+    controlPlaneBlockers,
+    runtimeBlockers,
+    releaseBlockers,
+    blockers: [...releaseBlockers, ...runtimeBlockers],
+    nextTriggers,
+  };
+}

package/src/runtime/continuity-notes.js

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+import { guardLeaderMutation } from "./runtime-state.js";
+
+export function getContinuityRoot() {
+  return getRuntimeSubsystemPath("memory");
+}
+
+export function getContinuityNotesPath() {
+  return getRuntimeSubsystemPath("memory", "notes.md");
+}
+
+export function getContinuityIndexPath() {
+  return getRuntimeSubsystemPath("memory", "index.json");
+}
+
+export async function seedContinuityArtifacts() {
+  await ensureDir(getContinuityRoot());
+  await writeFileIfMissing(
+    getContinuityNotesPath(),
+    "# Continuity Notes\n\nNo continuity notes captured yet.\n",
+  );
+  await writeFileIfMissing(
+    getContinuityIndexPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        sessionCount: 0,
+        lastUpdatedAt: null,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+export async function loadContinuityNotes() {
+  return fs.readFile(getContinuityNotesPath(), "utf8");
+}
+
+export async function loadContinuityIndex() {
+  return readJson(getContinuityIndexPath());
+}
+
+export async function storeContinuityNote(content, options = {}) {
+  const guard = await guardLeaderMutation({
+    actor: options.actor,
+    kind: "memory-note-write",
+    payload: { content },
+  });
+  if (!guard.allowed) {
+    return { proposed: true, proposalPath: guard.proposalPath };
+  }
+
+  const note = content.trim();
+  if (!note) {
+    throw new Error("memory.store_note requires non-empty content");
+  }
+
+  const [existingNotes, existingIndex] = await Promise.all([
+    loadContinuityNotes(),
+    loadContinuityIndex(),
+  ]);
+  const timestamp = new Date().toISOString();
+  const nextNotes = `${existingNotes.trimEnd()}\n\n## ${timestamp}\n\n${note}\n`;
+  const nextIndex = {
+    ...existingIndex,
+    sessionCount: existingIndex.sessionCount + 1,
+    lastUpdatedAt: timestamp,
+  };
+
+  await Promise.all([
+    fs.writeFile(getContinuityNotesPath(), nextNotes),
+    writeJson(getContinuityIndexPath(), nextIndex),
+  ]);
+
+  return { proposed: false, proposalPath: null, index: nextIndex };
+}

package/src/runtime/guidance-stack.js

@@ -0,0 +1,42 @@
+import { ensureDir, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export function getGuidanceRoot() {
+  return getRuntimeSubsystemPath("guidance");
+}
+
+export function getMergedGuidancePath() {
+  return getRuntimeSubsystemPath("guidance", "merged.json");
+}
+
+export function getGuidanceIncludeGraphPath() {
+  return getRuntimeSubsystemPath("guidance", "include-graph.json");
+}
+
+export async function seedGuidanceStackArtifacts() {
+  await ensureDir(getGuidanceRoot());
+  await writeFileIfMissing(
+    getMergedGuidancePath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        sources: [],
+        content: "",
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  await writeFileIfMissing(
+    getGuidanceIncludeGraphPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        roots: [],
+        edges: [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}