@jstn-sdk/ma 0.1.4 → 0.1.5

package/src/setup.js

@@ -0,0 +1,375 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, writeFileIfMissing, writeJson } from "./fs-utils.js";
+import { getPackageRoot, getRepoRoot } from "./paths.js";
+
+const agentFiles = [
+  {
+    fileName: "architect.toml",
+    packageRelativePath: ".codex/agents/architect.toml",
+    fallbackContent:
+      'name = "Architect"\nrole = "architecture-design"\ntrigger = "$arch"\ndescription = "Produces blueprint architecture, stack rationale, tradeoffs, and subsystem design."\n',
+  },
+  {
+    fileName: "sage.toml",
+    packageRelativePath: ".codex/agents/sage.toml",
+    fallbackContent:
+      'name = "Sage"\nrole = "evidence-binding"\ntrigger = "$sage"\ndescription = "Maps recommendations to approved OSS evidence via MCP and GitMCP sources."\n',
+  },
+  {
+    fileName: "auditor.toml",
+    packageRelativePath: ".codex/agents/auditor.toml",
+    fallbackContent:
+      'name = "Auditor"\nrole = "security-review"\ntrigger = "$vet"\ndescription = "Reviews security posture, dependency risk, and release-sensitive findings."\n',
+  },
+  {
+    fileName: "flow.toml",
+    packageRelativePath: ".codex/agents/flow.toml",
+    fallbackContent:
+      'name = "Flow"\nrole = "logic-validation"\ntrigger = "$flow"\ndescription = "Validates state transitions, blockers, and business-logic flow."\n',
+  },
+  {
+    fileName: "vibe.toml",
+    packageRelativePath: ".codex/agents/vibe.toml",
+    fallbackContent:
+      'name = "Vibe"\nrole = "experience-review"\ntrigger = "$vibe"\ndescription = "Reviews developer and user experience implications before build execution."\n',
+  },
+  {
+    fileName: "builder.toml",
+    packageRelativePath: ".codex/agents/builder.toml",
+    fallbackContent:
+      'name = "Builder"\nrole = "build-planning"\ntrigger = "$build"\ndescription = "Plans bounded implementation work once all required gates are green."\n',
+  },
+];
+
+const codexPromptFiles = [
+  {
+    targetRelativePath: ".codex/prompts/enforcement.md",
+    packageRelativePath: ".codex/prompts/enforcement.md",
+    fallbackContent:
+      "# Meta-Architect enforcement\n\nUse the local release-state and evidence files as the source of truth for gating decisions.\n",
+  },
+  {
+    targetRelativePath: ".codex/prompts/release-rules.md",
+    packageRelativePath: ".codex/prompts/release-rules.md",
+    fallbackContent:
+      "# Release rules\n\nDo not unlock build, merge, or release flows unless the required gate statuses are satisfied.\n",
+  },
+  {
+    targetRelativePath: ".codex/prompts/skill-contract.md",
+    packageRelativePath: ".codex/prompts/skill-contract.md",
+    fallbackContent:
+      "# Skill contract\n\nKeep Meta-Architect skills explicit, deterministic, and evidence-backed.\n",
+  },
+  {
+    targetRelativePath: ".codex/prompts/onboarding.md",
+    packageRelativePath: ".codex/prompts/onboarding.md",
+    fallbackContent:
+      "# Onboarding\n\nInstall `@openai/codex` and `meta-architect`, launch `ma --madmax --high`, and operate through `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, and `$build`. Use `ma setup` only when repo-local support files are missing.\n",
+  },
+];
+
+const templateFiles = [
+  {
+    targetRelativePath: "AGENTS.md",
+    packageRelativePath: "templates/AGENTS.md",
+    fallbackContent:
+      "# Meta-Architect Project Contract\n\nCodex is the host interface. Use the local Meta-Architect workflow and repository files as the source of truth for setup, evidence, and release gates.\n",
+  },
+  {
+    targetRelativePath: "templates/AGENTS.md",
+    packageRelativePath: "templates/AGENTS.md",
+    fallbackContent:
+      "# Meta-Architect Project Contract\n\nCodex is the host interface. Use the local Meta-Architect workflow and repository files as the source of truth for setup, evidence, and release gates.\n",
+  },
+  {
+    targetRelativePath: "templates/catalog-manifest.json",
+    packageRelativePath: "templates/catalog-manifest.json",
+    fallbackContent: `${JSON.stringify({ schemaVersion: "1.0.0", entries: [] }, null, 2)}\n`,
+  },
+  {
+    targetRelativePath: "templates/model-instructions/core.md",
+    packageRelativePath: "templates/model-instructions/core.md",
+    fallbackContent:
+      "# Core model instructions\n\nCodex is the host. Meta-Architect provides the repo-local workflow layer and gate model.\n",
+  },
+  {
+    targetRelativePath: "templates/model-instructions/release.md",
+    packageRelativePath: "templates/model-instructions/release.md",
+    fallbackContent:
+      "# Release model instructions\n\nTreat release claims as true only after tags, GitHub releases, and npm publishes succeed.\n",
+  },
+  {
+    targetRelativePath: "templates/model-instructions/security.md",
+    packageRelativePath: "templates/model-instructions/security.md",
+    fallbackContent:
+      "# Security model instructions\n\nDo not approve builds or releases when unresolved critical security findings remain.\n",
+  },
+];
+
+const optionalDocFiles = [
+  "docs/README.md",
+  "docs/getting-started.md",
+  "docs/skills.md",
+  "docs/mcp-setup.md",
+  "docs/release-spec.md",
+  "docs/qa/release-readiness-0.1.5.md",
+  "docs/onboarding.md",
+];
+
+const sprintFiles = [
+  "sprint/00-idea.md",
+  "sprint/01-architecture.md",
+  "sprint/02-oss-evidence.md",
+  "sprint/03-logic.md",
+  "sprint/04-security.md",
+  "sprint/05-dx-ux.md",
+  "sprint/06-build-plan.md",
+  "sprint/07-release.md",
+];
+
+const mcpFiles = [
+  {
+    targetRelativePath: "mcp/servers.json",
+    packageRelativePath: "mcp/servers.json",
+    fallbackContent: `${JSON.stringify({ schemaVersion: "1.0.0", servers: [] }, null, 2)}\n`,
+  },
+  {
+    targetRelativePath: "mcp/collections.json",
+    packageRelativePath: "mcp/collections.json",
+    fallbackContent: `${JSON.stringify({ schemaVersion: "1.0.0", collections: {} }, null, 2)}\n`,
+  },
+  {
+    targetRelativePath: "mcp/fallback.json",
+    packageRelativePath: "mcp/fallback.json",
+    fallbackContent: `${JSON.stringify(
+      {
+        schemaVersion: "1.0.0",
+        fallback: {
+          endpoint: "https://gitmcp.io/docs",
+          policy: "Use only when no approved exact endpoint exists.",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  },
+];
+
+const hookFallback = `${JSON.stringify(
+  {
+    version: 1,
+    hooks: [
+      {
+        event: "prebuild",
+        action: "deny-unless-gates-green",
+        source: ".omx/decisions.json",
+      },
+      {
+        event: "prerelease",
+        action: "deny-unless-release-origin-valid",
+        allowedOrigins: ["development", "release/*"],
+      },
+    ],
+  },
+  null,
+  2,
+)}\n`;
+
+const codexConfigFallback =
+  "# Meta-Architect local Codex configuration\n# Codex is the host interface. Add per-project overrides here only when required.\n";
+
+const omxSkillTemplates = {
+  "arch.skill.md":
+    "# `$arch`\n\nProduces blueprint architecture, stack rationale, subsystem design, and tradeoffs.\n",
+  "sage.skill.md":
+    "# `$sage`\n\nMaps architectural choices to approved OSS candidates from GitMCP-backed collections.\n",
+  "vet.skill.md": "# `$vet`\n\nAudits security posture, CVE signals, and safer alternatives.\n",
+  "flow.skill.md": "# `$flow`\n\nValidates logic, state transitions, and unresolved blockers.\n",
+  "vibe.skill.md":
+    "# `$vibe`\n\nReviews developer and user experience risks before build execution.\n",
+  "build.skill.md": "# `$build`\n\nChecks gates and plans bounded build execution.\n",
+  "sync.skill.md":
+    "# `$sync`\n\nReserved for refreshing mapped MCP sources and availability records.\n",
+};
+
+async function tryReadPackageAsset(relativePath) {
+  try {
+    return await fs.readFile(path.join(getPackageRoot(), relativePath), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function materializeTextFile(targetRelativePath, options, warnings) {
+  const targetPath = path.join(getRepoRoot(), targetRelativePath);
+
+  try {
+    await fs.access(targetPath);
+    return;
+  } catch {
+    // Continue and create the file below.
+  }
+
+  const bundledContent = options.packageRelativePath
+    ? await tryReadPackageAsset(options.packageRelativePath)
+    : null;
+  const nextContent = bundledContent ?? options.fallbackContent ?? null;
+
+  if (nextContent === null) {
+    if (options.optional) {
+      warnings.push(`Skipped optional scaffold asset: ${targetRelativePath}`);
+      return;
+    }
+
+    throw new Error(`Missing required scaffold asset: ${targetRelativePath}`);
+  }
+
+  await writeFileIfMissing(targetPath, nextContent);
+}
+
+async function materializeJsonFile(targetRelativePath, value) {
+  const targetPath = path.join(getRepoRoot(), targetRelativePath);
+
+  try {
+    await fs.access(targetPath);
+    return;
+  } catch {
+    // Continue and create the file below.
+  }
+
+  await writeJson(targetPath, value);
+}
+
+export async function runSetupScaffold() {
+  const created = [
+    "AGENTS.md",
+    ".codex/agents",
+    ".codex/prompts",
+    ".omx/skills",
+    ".omx/evidence",
+    "mcp",
+    "templates",
+    "docs",
+    "docs/qa",
+    "sprint",
+  ];
+  const warnings = [];
+
+  for (const relative of created.filter((item) => item !== "AGENTS.md")) {
+    await ensureDir(path.join(getRepoRoot(), relative));
+  }
+
+  await materializeTextFile("AGENTS.md", templateFiles[0], warnings);
+  await materializeTextFile(
+    ".codex/config.toml",
+    { fallbackContent: codexConfigFallback },
+    warnings,
+  );
+  await materializeTextFile(
+    ".codex/hooks.json",
+    { packageRelativePath: ".codex/hooks.json", fallbackContent: hookFallback },
+    warnings,
+  );
+
+  for (const asset of agentFiles) {
+    await materializeTextFile(
+      path.join(".codex/agents", asset.fileName),
+      {
+        packageRelativePath: asset.packageRelativePath,
+        fallbackContent: asset.fallbackContent,
+      },
+      warnings,
+    );
+  }
+
+  for (const asset of codexPromptFiles) {
+    await materializeTextFile(asset.targetRelativePath, asset, warnings);
+  }
+
+  for (const asset of templateFiles.slice(1)) {
+    await materializeTextFile(asset.targetRelativePath, asset, warnings);
+  }
+
+  for (const asset of mcpFiles) {
+    await materializeTextFile(asset.targetRelativePath, asset, warnings);
+  }
+
+  for (const relativePath of optionalDocFiles) {
+    await materializeTextFile(
+      relativePath,
+      {
+        packageRelativePath: relativePath,
+        optional: true,
+      },
+      warnings,
+    );
+  }
+
+  for (const relativePath of sprintFiles) {
+    await materializeTextFile(
+      relativePath,
+      {
+        packageRelativePath: relativePath,
+        optional: true,
+      },
+      warnings,
+    );
+  }
+
+  for (const [fileName, content] of Object.entries(omxSkillTemplates)) {
+    await materializeTextFile(
+      path.join(".omx/skills", fileName),
+      { fallbackContent: content },
+      warnings,
+    );
+  }
+
+  await materializeJsonFile(".omx/decisions.json", {
+    schemaVersion: "1.0.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",
+    decisions: [],
+  });
+
+  await materializeJsonFile(".omx/release.json", {
+    schemaVersion: "1.0.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: new Date().toISOString(),
+  });
+
+  await materializeJsonFile(".omx/evidence/sources.json", {
+    schemaVersion: "1.0.0",
+    items: [],
+  });
+  await materializeJsonFile(".omx/evidence/audits.json", {
+    schemaVersion: "1.0.0",
+    items: [],
+  });
+  await materializeJsonFile(".omx/evidence/outcomes.json", {
+    schemaVersion: "1.0.0",
+    items: [],
+  });
+  await materializeJsonFile(".omx/evidence/cves.json", {
+    schemaVersion: "1.0.0",
+    items: [],
+  });
+
+  return { created, warnings };
+}