@jstn-sdk/ma 0.1.0

package/sprint/04-security.md

@@ -0,0 +1,25 @@
+# Sprint 4: Security
+
+## Goal
+
+Record a baseline security pass and keep the workflow blocked if prerequisites are not satisfied.
+
+## Inputs
+
+- `logic_status = GREEN`
+
+## Expected outputs
+
+- `.ma/evidence/audits.json`
+- `.ma/evidence/cves.json`
+- `security_status = GREEN | RED`
+
+## Exit criteria
+
+- baseline security findings are recorded
+- blockers are explicit when the lane remains red
+
+## Failure conditions
+
+- logic not green
+- missing evidence output

package/sprint/05-dx-ux.md

@@ -0,0 +1,24 @@
+# Sprint 5: DX/UX
+
+## Goal
+
+Record a baseline developer and user experience pass before build unlock.
+
+## Inputs
+
+- `security_status = GREEN`
+
+## Expected outputs
+
+- `.ma/evidence/outcomes.json`
+- `experience_status = GREEN | RED | WAIVED`
+
+## Exit criteria
+
+- baseline experience notes are recorded
+- waiver path is explicit when used
+
+## Failure conditions
+
+- security not green
+- no operator-facing or user-facing review output

package/sprint/06-build-plan.md

@@ -0,0 +1,26 @@
+# Sprint 6: Build Plan
+
+## Goal
+
+Evaluate all required gates and prepare bounded implementation work.
+
+## Inputs
+
+- required upstream gates green or waived per release policy
+
+## Expected outputs
+
+- blocked or ready decision entry
+- `build_status = READY` on success
+- suggested `feature/*` branches
+- optional `git worktree add` commands
+
+## Exit criteria
+
+- build is either clearly blocked or clearly ready
+- branch/worktree guidance is explicit when ready
+
+## Failure conditions
+
+- missing or red gates
+- invalid release-state file

package/sprint/07-release.md

@@ -0,0 +1,26 @@
+# Sprint 7: Release
+
+## Goal
+
+Move from completed bounded implementation to a controlled merge and release path.
+
+## Inputs
+
+- `build_status = READY | RUNNING`
+- valid branch origin
+
+## Expected outputs
+
+- `merge_status = MERGED_TO_DEVELOPMENT`
+- `release_status = SHIPPED_TO_PROD`
+
+## Exit criteria
+
+- merge follows `feature/* -> development`
+- release follows `development|release/* -> prod`
+
+## Failure conditions
+
+- invalid merge target
+- invalid release origin
+- attempt to bypass protected release flow

package/src/build-gate.js

@@ -0,0 +1,52 @@
+const gateChecks = [
+  ["idea_status", "CLEAR", "ma idea"],
+  ["architecture_status", "APPROVED", "$arch"],
+  ["evidence_status", "VERIFIED", "$sage"],
+  ["logic_status", "GREEN", "$flow"],
+  ["security_status", "GREEN", "$vet"],
+];
+
+export function evaluateBuildGate(releaseState) {
+  const blockers = [];
+
+  for (const [field, expected, trigger] of gateChecks) {
+    if (releaseState[field] !== expected) {
+      blockers.push({ field, expected, actual: releaseState[field], trigger });
+    }
+  }
+
+  const experienceAllowed =
+    releaseState.experience_status === "GREEN" || releaseState.experience_status === "WAIVED";
+  if (!experienceAllowed) {
+    blockers.push({
+      field: "experience_status",
+      expected: "GREEN or WAIVED",
+      actual: releaseState.experience_status,
+      trigger: "$vibe",
+    });
+  }
+
+  if (!["LOCKED", "READY"].includes(releaseState.build_status)) {
+    blockers.push({
+      field: "build_status",
+      expected: "LOCKED or READY",
+      actual: releaseState.build_status,
+      trigger: "$build",
+    });
+  }
+
+  return {
+    allowed: blockers.length === 0,
+    blockers,
+  };
+}
+
+export function formatBuildBlockers(evaluation) {
+  return evaluation.blockers.map(
+    (blocker) => `${blocker.field} must be ${blocker.expected}; current value is ${blocker.actual}`,
+  );
+}
+
+export function formatNextAllowedTriggers(evaluation) {
+  return [...new Set(evaluation.blockers.map((blocker) => blocker.trigger))];
+}

package/src/decision-log.js

@@ -0,0 +1,40 @@
+import { readJson, writeJson } from "./fs-utils.js";
+import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
+
+function validateDecisionShape(entry) {
+  const required = ["decision", "status", "evidence", "blockers", "next_allowed_triggers"];
+  for (const field of required) {
+    if (!(field in entry)) {
+      throw new Error(`Decision entry missing field: ${field}`);
+    }
+  }
+}
+
+export async function loadDecisionLog() {
+  const parsed = await readJson(getRuntimeReadPath("decisions.json"));
+
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.decisions)) {
+    throw new Error("Decision log must be an object with a decisions array");
+  }
+
+  return parsed;
+}
+
+export async function appendDecision(entry) {
+  validateDecisionShape(entry);
+  const log = await loadDecisionLog();
+  log.decisions.push({
+    ...entry,
+    timestamp: new Date().toISOString(),
+  });
+
+  await writeJson(getRuntimeWritePath("decisions.json"), log);
+}
+
+export async function updateDecisionStatuses(statusUpdates) {
+  const log = await loadDecisionLog();
+  for (const [field, value] of Object.entries(statusUpdates)) {
+    log[field] = value;
+  }
+  await writeJson(getRuntimeWritePath("decisions.json"), log);
+}

package/src/fs-utils.js

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readJson(filePath) {
+  const raw = await fs.readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+export async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function writeFileIfMissing(filePath, content) {
+  try {
+    await fs.access(filePath);
+  } catch {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content);
+  }
+}

package/src/launcher.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const nativeCommands = new Set([
+  "setup",
+  "init",
+  "idea",
+  "skills",
+  "status",
+  "merge",
+  "release",
+  "run",
+]);
+
+export function shouldDelegateToCodex(args) {
+  if (args.length === 0) {
+    return true;
+  }
+
+  return !nativeCommands.has(args[0]);
+}
+
+function normalizeCodexArgs(args) {
+  return args.filter((arg) => arg !== "--madmax" && arg !== "--high");
+}
+
+function resolveCodexCommand() {
+  if (process.env.MA_CODEX_BIN) {
+    return process.env.MA_CODEX_BIN;
+  }
+
+  return "codex";
+}
+
+export function runCodex(args) {
+  const codexCommand = resolveCodexCommand();
+  const codexArgs = normalizeCodexArgs(args);
+  const commandArgs =
+    path.extname(codexCommand) === ".js" || path.extname(codexCommand) === ".mjs"
+      ? [codexCommand, ...codexArgs]
+      : codexArgs;
+  const command = commandArgs[0] === codexCommand ? process.execPath : codexCommand;
+  const finalArgs = command === process.execPath ? commandArgs : codexArgs;
+  const result = spawnSync(command, finalArgs, { stdio: "inherit" });
+
+  if (result.error) {
+    if (result.error.code === "ENOENT") {
+      throw new Error("Codex CLI not found. Install it with: npm install -g @openai/codex");
+    }
+
+    throw new Error(`Failed to start Codex CLI: ${result.error.message}`);
+  }
+
+  return typeof result.status === "number" ? result.status : 1;
+}

package/src/mcp-config.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import { getMcpServersPath } from "./paths.js";
+
+const gitMcpRepoPattern = /^https:\/\/gitmcp\.io\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+export function isValidGitMcpEndpoint(url) {
+  return gitMcpRepoPattern.test(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;
+}
+
+export async function validateMcpServers() {
+  const parsed = await loadMcpServers();
+  for (const server of parsed.servers) {
+    if (!isValidGitMcpEndpoint(server.endpoint)) {
+      throw new Error(`Invalid GitMCP endpoint: ${server.endpoint}`);
+    }
+  }
+
+  return parsed;
+}

package/src/mcp-live-client.js

@@ -0,0 +1,186 @@
+export class McpSseClient {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+    this.controller = new AbortController();
+    this.reader = null;
+    this.buffer = "";
+    this.pending = new Map();
+    this.postUrl = null;
+    this.nextId = 1;
+    this.readLoopPromise = null;
+  }
+
+  async connect() {
+    const response = await fetch(this.baseUrl, {
+      headers: { accept: "text/event-stream" },
+      signal: this.controller.signal,
+    });
+
+    if (!response.ok || !response.body) {
+      throw new Error(`Failed to open MCP SSE stream: ${response.status}`);
+    }
+
+    this.reader = response.body.getReader();
+    const endpointEvent = await this.#withTimeout(
+      this.#readNextEvent(),
+      5000,
+      "Timed out waiting for MCP endpoint event",
+    );
+    if (!endpointEvent || endpointEvent.event !== "endpoint") {
+      throw new Error("MCP server did not provide an endpoint event");
+    }
+
+    this.postUrl = `${this.baseUrl}${endpointEvent.data}`;
+    this.readLoopPromise = this.#startReadLoop();
+
+    const initResult = await this.request("initialize", {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: {
+        name: "meta-architect",
+        version: "0.1.0",
+      },
+    });
+
+    await this.notify("notifications/initialized");
+    return initResult;
+  }
+
+  async request(method, params = {}) {
+    const id = this.nextId++;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for MCP response to ${method}`));
+      }, 15000);
+
+      this.pending.set(id, {
+        resolve: (payload) => {
+          clearTimeout(timeout);
+          resolve(payload);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+
+    await this.#post({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    });
+
+    return responsePromise;
+  }
+
+  async notify(method, params = {}) {
+    await this.#post({
+      jsonrpc: "2.0",
+      method,
+      params,
+    });
+  }
+
+  async close() {
+    this.controller.abort();
+    if (this.readLoopPromise) {
+      try {
+        await this.readLoopPromise;
+      } catch {
+        // Ignore abort-related shutdown failures.
+      }
+    }
+  }
+
+  async #post(message) {
+    const response = await fetch(this.postUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(message),
+      signal: this.controller.signal,
+    });
+
+    if (!response.ok && response.status !== 202) {
+      throw new Error(`MCP POST failed: ${response.status}`);
+    }
+  }
+
+  async #startReadLoop() {
+    try {
+      while (true) {
+        const event = await this.#readNextEvent();
+        if (!event) {
+          break;
+        }
+
+        if (event.event !== "message") {
+          continue;
+        }
+
+        const payload = JSON.parse(event.data);
+        if (typeof payload.id === "number" && this.pending.has(payload.id)) {
+          const handlers = this.pending.get(payload.id);
+          this.pending.delete(payload.id);
+          if (payload.error) {
+            handlers.reject(new Error(payload.error.message ?? "Unknown MCP error"));
+          } else {
+            handlers.resolve(payload.result);
+          }
+        }
+      }
+    } finally {
+      for (const [, handlers] of this.pending) {
+        handlers.reject(new Error("MCP stream closed"));
+      }
+      this.pending.clear();
+    }
+  }
+
+  async #readNextEvent() {
+    while (true) {
+      const result = await this.reader.read();
+      if (result.done) {
+        return null;
+      }
+
+      this.buffer += Buffer.from(result.value).toString("utf8");
+      const index = this.buffer.indexOf("\n\n");
+      if (index === -1) {
+        continue;
+      }
+
+      const rawEvent = this.buffer.slice(0, index);
+      this.buffer = this.buffer.slice(index + 2);
+      return parseSseEvent(rawEvent);
+    }
+  }
+
+  async #withTimeout(promise, timeoutMs, message) {
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        const timeout = setTimeout(() => {
+          clearTimeout(timeout);
+          reject(new Error(message));
+        }, timeoutMs);
+      }),
+    ]);
+  }
+}
+
+export function parseSseEvent(rawEvent) {
+  const event = { event: "message", data: "" };
+  for (const line of rawEvent.split("\n")) {
+    if (line.startsWith("event:")) {
+      event.event = line.slice("event:".length).trim();
+    } else if (line.startsWith("data:")) {
+      event.data += `${line.slice("data:".length).trim()}\n`;
+    }
+  }
+
+  event.data = event.data.trimEnd();
+  return event;
+}

package/src/paths.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const packageRoot = path.resolve(__dirname, "..");
+export function getRepoRoot() {
+  return process.env.MA_ROOT ? path.resolve(process.env.MA_ROOT) : process.cwd();
+}
+
+export function getRuntimeRoot() {
+  return path.join(getRepoRoot(), ".ma");
+}
+
+export function getRuntimeWritePath(...parts) {
+  return path.join(getRuntimeRoot(), ...parts);
+}
+
+export function getRuntimeReadPath(...parts) {
+  return path.join(getRuntimeRoot(), ...parts);
+}
+
+export function getMcpServersPath() {
+  return path.join(getRepoRoot(), "mcp", "servers.json");
+}

package/src/policy.js

@@ -0,0 +1,23 @@
+export function validateReleaseOrigin(originBranch) {
+  if (originBranch === "development") {
+    return true;
+  }
+
+  if (originBranch.startsWith("release/")) {
+    return true;
+  }
+
+  return false;
+}
+
+export function rejectsDirectProdPromotion(originBranch) {
+  return originBranch.startsWith("feature/");
+}
+
+export function validateMergeTarget(sourceBranch, targetBranch) {
+  return sourceBranch.startsWith("feature/") && targetBranch === "development";
+}
+
+export function canMarkBuildDone(releaseState) {
+  return ["READY", "RUNNING"].includes(releaseState.build_status);
+}

package/src/release-state.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import { writeJson } from "./fs-utils.js";
+import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
+
+const allowedStatuses = {
+  idea_status: ["DRAFT", "CLEAR", "BLOCKED"],
+  architecture_status: ["DRAFT", "REVIEWED", "APPROVED"],
+  evidence_status: ["MISSING", "PARTIAL", "VERIFIED"],
+  logic_status: ["PENDING", "GREEN", "RED"],
+  security_status: ["PENDING", "GREEN", "RED"],
+  experience_status: ["PENDING", "GREEN", "RED", "WAIVED"],
+  build_status: ["LOCKED", "READY", "RUNNING", "DONE"],
+  merge_status: ["LOCKED", "READY", "MERGED_TO_DEVELOPMENT"],
+  release_status: ["LOCKED", "READY", "SHIPPED_TO_PROD"],
+};
+
+function validateWaiver(state) {
+  if (state.experience_status !== "WAIVED") {
+    return;
+  }
+
+  const waiver = state.waiver;
+  if (!waiver?.reason || !waiver.actor || !waiver.timestamp) {
+    throw new Error(
+      "experience_status=WAIVED requires waiver.reason, waiver.actor, and waiver.timestamp",
+    );
+  }
+}
+
+export function validateReleaseState(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw new Error("Release state must be an object");
+  }
+
+  for (const [field, allowed] of Object.entries(allowedStatuses)) {
+    if (!allowed.includes(state[field])) {
+      throw new Error(`Invalid ${field}: ${state[field]}`);
+    }
+  }
+
+  validateWaiver(state);
+  return state;
+}
+
+export async function loadReleaseState() {
+  const raw = await fs.readFile(getRuntimeReadPath("release.json"), "utf8");
+  const parsed = JSON.parse(raw);
+  return validateReleaseState(parsed);
+}
+
+export async function saveReleaseState(state) {
+  validateReleaseState(state);
+  const next = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+  await writeJson(getRuntimeWritePath("release.json"), next);
+  return next;
+}