@jstn-sdk/ma 0.1.13 → 0.14.1

package/src/bootstrap.js

@@ -1,16 +1,28 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { detectInstalled, getAgent } from "./agents.js";
 import { loadDecisionLog } from "./decision-log.js";
+import { inspectRuntimeStateHealth } from "./fs-utils.js";
 import {
   runLocalCapabilityReadinessChecks,
   validateLocalCapabilities,
   validateMcpServers,
 } from "./mcp-config.js";
+import { getMcpBridgeConfiguration, mcpClientVersion } from "./mcp-live-client.js";
 import { getMcpRootPath, getRepoRoot, getRuntimeWritePath, packageRoot } from "./paths.js";
+import { safeSpawnSync } from "./process-utils.js";
+import { resolveReleaseIssueGates } from "./release-issue-gates.js";
 import { loadReleaseState } from "./release-state.js";
+import { validateAgentIntegrations } from "./runtime/agent-compat.js";
+import { getArchitectReviewConfiguration } from "./runtime/architect-review.js";
+import { printDoctorStatuses, summarizeDoctorStatuses } from "./runtime/doctor-report.js";
+import { mcpWriteCapabilityStatus } from "./runtime/mcp-authority.js";
+import { loadObsidianVaultConfig } from "./runtime/obsidian-integration-core.js";
+import { inspectRedactionVault } from "./runtime/redaction-gateway.js";
 import { loadLeaderAuthority, loadRuntimeSnapshot } from "./runtime/runtime-state.js";
+import { findOutdatedSchemas } from "./runtime/schema-migrations.js";
+import { inspectSetupDrift } from "./setup-lifecycle.js";
 import {
   areSkillsInstalled,
   ensureSkillsInstalled,
@@ -18,49 +30,216 @@ import {
   getSkillInstallRoot,
   getSupportBundleRoot,
   isSupportBundleInstalled,
+  readInstallReceipt,
 } from "./skill-installer.js";
 import { runInit } from "./skills.js";
+import { renderCheckGrid } from "./tui/status-grid.js";
 
 function makeStatus(kind, label, detail = "") {
   return { kind, label, detail };
 }
 
-function resolveCodexCommand() {
-  return process.env.MA_CODEX_BIN ?? "codex";
+function inspectMcpBridge() {
+  const template = process.env.MA_MCP_REMOTE_BRIDGE_CMD?.trim();
+  if (!template) return makeStatus("OK", "MCP remote bridge", "not configured");
+  const command = template.split(/\s+/, 1)[0].replace(/^['"]|['"]$/g, "");
+  const policy = getMcpBridgeConfiguration();
+  const allowed = policy.allowedCommands.some(
+    (entry) => entry === command || path.basename(entry) === path.basename(command),
+  );
+  return makeStatus(
+    allowed ? "OK" : "WARN",
+    "MCP remote bridge",
+    allowed
+      ? `${command} is explicitly allowlisted (${policy.source})`
+      : `${command} is not allowlisted; configure MA_MCP_REMOTE_BRIDGE_ALLOWLIST or mcp/bridge.json`,
+  );
 }
 
-function runCommand(command, args) {
-  const isNodeScript = [".js", ".mjs", ".cjs"].includes(path.extname(command));
-  const finalCommand = isNodeScript ? process.execPath : command;
-  const finalArgs = isNodeScript ? [command, ...args] : args;
-  return spawnSync(finalCommand, finalArgs, { encoding: "utf8" });
+function inspectArchitectReview() {
+  const template = process.env.MA_ARCHITECT_REVIEW_CMD?.trim();
+  if (!template) return makeStatus("OK", "external architect review", "not configured");
+  const command = template.split(/\s+/, 1)[0].replace(/^['"]|['"]$/g, "");
+  const policy = getArchitectReviewConfiguration();
+  const allowed = policy.allowedCommands.some(
+    (entry) => entry === command || path.basename(entry) === path.basename(command),
+  );
+  return makeStatus(
+    allowed ? "OK" : "WARN",
+    "external architect review",
+    allowed
+      ? `${command} is explicitly allowlisted (${policy.source})`
+      : `${command} is not allowlisted; configure MA_ARCHITECT_REVIEW_ALLOWLIST or .ma/architect-review-policy.json`,
+  );
 }
 
-function inspectCodex() {
-  const command = resolveCodexCommand();
-  const result = runCommand(command, ["--version"]);
-  const version = result.stdout.trim();
-  if (result.status === 0) {
-    return {
-      ok: true,
-      command,
-      detail: result.error?.message ?? "",
-      version,
+export async function inspectWorkspaceNpmrc() {
+  const npmrcPath = path.join(getRepoRoot(), ".npmrc");
+  try {
+    const content = await fs.readFile(npmrcPath, "utf8");
+    const hasAuthMaterial = /(?:_authToken|_auth|_password|username)\s*=|token\s*=/i.test(content);
+    return makeStatus(
+      hasAuthMaterial ? "WARN" : "OK",
+      "workspace npm auth",
+      hasAuthMaterial
+        ? "token-bearing .npmrc detected; use NODE_AUTH_TOKEN or a temporary config outside the workspace"
+        : "no token-bearing .npmrc detected",
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return makeStatus("OK", "workspace npm auth", "no workspace .npmrc");
+    return makeStatus("WARN", "workspace npm auth", `unable to inspect .npmrc: ${error.message}`);
+  }
+}
+
+async function inspectPluginInjectionState() {
+  const root = path.join(os.homedir(), ".ma", "backups", "plugins");
+  try {
+    const plugins = await fs.readdir(root, { withFileTypes: true });
+    const receipts = [];
+    for (const plugin of plugins) {
+      if (!plugin.isDirectory()) continue;
+      const runs = await fs.readdir(path.join(root, plugin.name), { withFileTypes: true });
+      for (const run of runs.filter((entry) => entry.isDirectory())) {
+        const receiptPath = path.join(root, plugin.name, run.name, "receipt.json");
+        try {
+          receipts.push(JSON.parse(await fs.readFile(receiptPath, "utf8")));
+        } catch {
+          // Ignore incomplete backup directories.
+        }
+      }
+    }
+    const latest = receipts.sort((a, b) => `${b.backupRoot}`.localeCompare(`${a.backupRoot}`))[0];
+    const hosts = latest?.vendorInjection?.configured_hosts ?? [];
+    return makeStatus(
+      "OK",
+      "plugin MCP injection state",
+      hosts.length > 0 ? `configured hosts: ${hosts.join(", ")}` : "no recorded vendor mutations",
+    );
+  } catch {
+    return makeStatus("OK", "plugin MCP injection state", "no recorded vendor mutations");
+  }
+}
+
+async function inspectContextHealth() {
+  const contextPath = getRuntimeWritePath("context", "project-index.json");
+  const briefPath = getRuntimeWritePath("context", "agent-brief.md");
+  const hookPath = path.join(getRepoRoot(), ".codex", "hooks.json");
+  try {
+    const project = JSON.parse(await fs.readFile(contextPath, "utf8"));
+    const brief = await fs.readFile(briefPath, "utf8");
+    const hooks = JSON.parse(await fs.readFile(hookPath, "utf8"));
+    const hookText = JSON.stringify(hooks);
+    const hydrated =
+      hookText.includes("context-hydration-hook.mjs") ||
+      hookText.includes("ma hook context-hydration");
+    const hookFiles = [];
+    const collectHookCommands = (value) => {
+      if (Array.isArray(value)) return value.forEach(collectHookCommands);
+      if (!value || typeof value !== "object") return;
+      if (typeof value.command === "string") hookFiles.push(value.command);
+      Object.values(value).forEach(collectHookCommands);
     };
+    collectHookCommands(hooks);
+    const brokenHookCommands = [];
+    for (const command of hookFiles) {
+      const relative = command.match(/^node\s+([^\s]+)/)?.[1];
+      if (!relative) continue;
+      try {
+        await fs.access(path.resolve(getRepoRoot(), relative));
+      } catch {
+        brokenHookCommands.push(relative);
+      }
+    }
+    const freshness = project.freshness?.status ?? "unknown";
+    const outdated = await findOutdatedSchemas(getRepoRoot());
+    const runtimeFindings = await inspectRuntimeStateHealth(getRepoRoot());
+    const setupDrift = await inspectSetupDrift(getRepoRoot());
+    const mcpWriteStatus = mcpWriteCapabilityStatus();
+    return [
+      makeStatus(
+        setupDrift.length ? "WARN" : "OK",
+        "seeded artifact drift",
+        setupDrift.length
+          ? setupDrift.map((entry) => `${entry.status}: ${entry.path}`).join(", ")
+          : "no managed template drift",
+      ),
+      makeStatus(
+        runtimeFindings.length ? "WARN" : "OK",
+        "runtime state integrity",
+        runtimeFindings.length
+          ? runtimeFindings.map((finding) => `${finding.type}: ${finding.path}`).join(", ")
+          : "atomic writes and locks healthy",
+      ),
+      makeStatus(
+        freshness === "stale" ? "WARN" : "OK",
+        "project context freshness",
+        `${freshness}; ${project.quality?.confidence ?? "unknown"} confidence`,
+      ),
+      makeStatus(brief.trim() ? "OK" : "WARN", "agent context brief", briefPath),
+      makeStatus(
+        hydrated ? "OK" : "WARN",
+        "startup/prompt context hydration",
+        hydrated ? hookPath : "run `ma setup`",
+      ),
+      makeStatus(
+        brokenHookCommands.length ? "WARN" : "OK",
+        "hook command portability",
+        brokenHookCommands.length
+          ? `missing: ${brokenHookCommands.join(", ")}`
+          : "all local hook scripts are present",
+      ),
+      makeStatus(
+        "OK",
+        "Obsidian integration",
+        (await loadObsidianVaultConfig())?.vaultPath || process.env.MA_OBSIDIAN_VAULT
+          ? "configured"
+          : "not configured (explicitly disabled)",
+      ),
+      await inspectRedactionVault().then((vault) =>
+        makeStatus(
+          vault.status === "warning" ? "WARN" : "OK",
+          "redaction vault policy",
+          vault.issues.length > 0
+            ? vault.issues.join(", ")
+            : `${vault.policy.retentionDays}d retention, ${vault.policy.maxEntries} max entries`,
+        ),
+      ),
+      await inspectWorkspaceNpmrc(),
+      makeStatus("OK", "MCP context resources", "local read-only context capability available"),
+      makeStatus(
+        mcpWriteStatus.readOnly ? "WARN" : "OK",
+        "MCP write authority",
+        mcpWriteStatus.detail,
+      ),
+      makeStatus(
+        outdated.length ? "WARN" : "OK",
+        "runtime schema versions",
+        outdated.length ? `${outdated.length} outdated artifact(s); run ma migrate` : "current",
+      ),
+    ];
+  } catch (_error) {
+    return [
+      makeStatus(
+        "WARN",
+        "project context health",
+        "Run `ma setup` to generate bounded context artifacts",
+      ),
+    ];
   }
+}
 
+function inspectAgent(type = process.env.MA_AGENT || "codex") {
+  const result = detectInstalled(type);
   return {
-    ok: false,
-    command,
-    detail:
-      (result.error?.message ?? result.stderr.trim() ?? result.stdout.trim()) ||
-      "Codex command failed",
-    version: "",
+    ok: result.installed,
+    detail: result.error || `${getAgent(type).displayName} command failed`,
+    version: result.version,
   };
 }
 
 function listCodexPaths() {
-  const result = spawnSync("which", ["-a", "codex"], { encoding: "utf8" });
+  const result = safeSpawnSync("which", ["-a", "codex"], { encoding: "utf8" });
   if (result.error || result.status !== 0) {
     return [];
   }
@@ -157,6 +336,7 @@ async function inspectLocalScaffold() {
     getRuntimeWritePath("context", "code-graph-rehearse.json"),
     getRuntimeWritePath("context", "core-source-ingest.json"),
     getRuntimeWritePath("context", "learning-loop-core.json"),
+    getRuntimeWritePath("context", "project-index.json"),
     getRuntimeWritePath("context", "obsidian-bridge.json"),
     getRuntimeWritePath("context", "obsidian-vault-index.json"),
     getRuntimeWritePath("context", "obsidian-vault-operations.json"),
@@ -177,7 +357,8 @@ async function inspectLocalScaffold() {
     getRuntimeWritePath("state", "manager-runs.json"),
     getRuntimeWritePath("state", "maestro-state.json"),
     getRuntimeWritePath("evidence", "semantic-receipts.json"),
-    path.join(getRepoRoot(), "docs", "qa", "release-issue-gates-0.1.13.json"),
+    resolveReleaseIssueGates(getRepoRoot())?.path ??
+      path.join(getRepoRoot(), "docs", "qa", "release-issue-gates-missing.json"),
     path.join(getMcpRootPath(), "servers.json"),
     path.join(getMcpRootPath(), "local-capabilities.json"),
   ];
@@ -319,48 +500,59 @@ async function inspectLocalCapabilityState({ fix }) {
 }
 
 async function runEnvironmentFlow({ fix, initMcp }) {
-  const statuses = [];
+  const statuses = [makeStatus("OK", "MCP client version", mcpClientVersion)];
+  statuses.push(inspectMcpBridge());
+  statuses.push(inspectArchitectReview());
 
-  const codexResolution = await inspectCodexResolution({ fix });
+  const agentType = process.env.MA_AGENT?.trim() || "codex";
+  const agent = getAgent(agentType);
+  const codexResolution = agentType === "codex" ? await inspectCodexResolution({ fix }) : null;
   if (codexResolution) {
     statuses.push(codexResolution);
   }
 
-  const codex = inspectCodex();
-  if (codex.ok) {
-    statuses.push(makeStatus("OK", "codex command is available", codex.version));
+  const installed = inspectAgent(agentType);
+  if (installed.ok) {
+    statuses.push(makeStatus("OK", `${agent.displayName} command is available`, installed.version));
   } else {
     statuses.push(
       makeStatus(
         "BLOCKED",
-        "codex command is not usable",
-        "Install or repair Codex with: npm install -g @openai/codex@latest",
+        `${agent.displayName} command is not usable`,
+        installed.detail || "Install or repair the selected agent command.",
       ),
     );
   }
 
-  const skillInstallRoot = getSkillInstallRoot();
+  const skillInstallRoot = getSkillInstallRoot(agent.id);
   if (fix) {
     const result = await ensureSkillsInstalled();
     statuses.push(
       makeStatus(
         result.installed.length > 0 ? "FIXED" : "OK",
-        "Codex skills are installed",
+        `${agent.displayName} skills are installed`,
         skillInstallRoot,
       ),
     );
   } else {
+    const receipt = await readInstallReceipt(skillInstallRoot, "skills");
     statuses.push(
       makeStatus(
         (await areSkillsInstalled()) ? "OK" : "WARN",
-        "Codex skills install state",
-        skillInstallRoot,
+        `${agent.displayName} skills install state`,
+        receipt
+          ? `${skillInstallRoot} (v${receipt.packageVersion}, receipt present)`
+          : `${skillInstallRoot} (receipt missing)`,
       ),
     );
   }
 
   const supportBundleRoot = getSupportBundleRoot();
-  if (fix) {
+  if (agent.id !== "codex") {
+    statuses.push(
+      makeStatus("OK", "Codex support bundle", "not applicable to the selected agent surface"),
+    );
+  } else if (fix) {
     const result = await ensureSupportBundleInstalled();
     statuses.push(
       makeStatus(
@@ -370,11 +562,14 @@ async function runEnvironmentFlow({ fix, initMcp }) {
       ),
     );
   } else {
+    const receipt = await readInstallReceipt(supportBundleRoot, "support");
     statuses.push(
       makeStatus(
         (await isSupportBundleInstalled()) ? "OK" : "WARN",
         "support bundle install state",
-        supportBundleRoot,
+        receipt
+          ? `${supportBundleRoot} (v${receipt.bundleVersion}, receipt present)`
+          : `${supportBundleRoot} (receipt missing)`,
       ),
     );
   }
@@ -403,35 +598,43 @@ async function runEnvironmentFlow({ fix, initMcp }) {
 
   statuses.push(await inspectGitMcpState({ fix, initMcp }));
   statuses.push(await inspectLocalCapabilityState({ fix }));
-  return statuses;
-}
-
-function summarizeStatuses(statuses) {
-  const hasBlocked = statuses.some((status) => status.kind === "BLOCKED");
-  const hasWarn = statuses.some((status) => status.kind === "WARN");
-  if (hasBlocked) {
-    return "BLOCKED";
-  }
-  if (hasWarn) {
-    return "READY_WITH_WARNINGS";
+  statuses.push(...(await inspectContextHealth()));
+  statuses.push(await inspectPluginInjectionState());
+  if (agent.id === "cursor") {
+    try {
+      const validation = await validateAgentIntegrations(getRepoRoot(), { targets: ["cursor"] });
+      const cursorResult = validation.results.cursor;
+      statuses.push(
+        makeStatus(
+          cursorResult?.status === "valid" ? "OK" : "WARN",
+          "Cursor native project rules",
+          cursorResult?.status === "valid"
+            ? ".cursor/rules/agents.mdc validated"
+            : cursorResult?.issues?.map((issue) => issue.message).join(", ") || "run `ma setup`",
+        ),
+      );
+    } catch (error) {
+      statuses.push(makeStatus("WARN", "Cursor native project rules", error.message));
+    }
   }
-  return "READY";
+  return statuses;
 }
 
 function printStatuses(title, statuses) {
-  console.log(title);
-  console.log("=".repeat(title.length));
-  for (const status of statuses) {
-    const label = status.kind.padEnd(7, " ");
-    if (status.detail) {
-      console.log(`${label} ${status.label}: ${status.detail}`);
-    } else {
-      console.log(`${label} ${status.label}`);
-    }
+  if (process.stdout.isTTY) {
+    const result = summarizeDoctorStatuses(statuses);
+    console.log(title);
+    console.log("=".repeat(title.length));
+    console.log(renderCheckGrid(statuses));
+    console.log(`\nResult: ${result}`);
+    console.log(
+      result === "BLOCKED"
+        ? "Next: install or repair blocked prerequisites, then rerun `ma bootstrap`."
+        : "Next: start Codex or run `ma run '$maestro'`.",
+    );
+    return result;
   }
-  const result = summarizeStatuses(statuses);
-  console.log();
-  console.log(`Result: ${result}`);
+  const result = printDoctorStatuses(title, statuses);
   if (result === "BLOCKED") {
     console.log("Next: install or repair blocked prerequisites, then rerun `ma bootstrap`.");
   } else if (result === "READY_WITH_WARNINGS") {
@@ -442,16 +645,20 @@ function printStatuses(title, statuses) {
   return result;
 }
 
-export async function runDoctor() {
+export async function runDoctor({ json = false } = {}) {
   const statuses = await runEnvironmentFlow({ fix: false, initMcp: false });
+  const result = summarizeDoctorStatuses(statuses);
+  if (json) return { schemaVersion: "0.1.0", scope: "environment", result, statuses };
   return {
     statuses,
     result: printStatuses("Meta-Architect Doctor", statuses),
   };
 }
 
-export async function runBootstrap({ initMcp = false } = {}) {
+export async function runBootstrap({ initMcp = false, json = false } = {}) {
   const statuses = await runEnvironmentFlow({ fix: true, initMcp });
+  const result = summarizeDoctorStatuses(statuses);
+  if (json) return { schemaVersion: "0.1.0", scope: "bootstrap", result, statuses };
   return {
     statuses,
     result: printStatuses("Meta-Architect Bootstrap", statuses),