@jstn-sdk/ma 0.1.7 → 0.1.9

package/README.md

@@ -18,9 +18,9 @@
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.7` is a production-grade skills line.
+> Meta-Architect `v0.1.9` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.7` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+> From `v0.1.9` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
 
 ## Overview
 
@@ -57,7 +57,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.7</code></td>
+    <td><code>v0.1.9</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -230,7 +230,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.7
+8. Delivery plan for v0.1.9
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -256,10 +256,18 @@ See [example/usage-workflow.md](./example/usage-workflow.md) for the full prompt
 If you are working from a repository directly and need scaffolded local support files, use:
 
 ```bash
+ma bootstrap
+ma bootstrap --init-mcp
+ma doctor
 ma setup
 ma
 ```
 
+Recommended lazy-user path:
+- run `ma bootstrap` first to repair packaged assets, scaffold local runtime files, and verify the environment
+- add `--init-mcp` if you want starter GitMCP source files written into the local `mcp/` folder when it is empty or invalid
+- use `ma doctor` later when you want a check-only readiness report without changing files
+
 Expected output for `ma setup`:
 
 ```text
@@ -408,10 +416,23 @@ What `ma setup` and `ma init` do:
 - they prepare `.ma/` runtime files such as context, specs, plans, evidence, and runbook files
 - they do not run the skill workflow by themselves
 
+What `ma bootstrap` does:
+- checks whether `codex` is callable
+- repairs installed skills and support-bundle assets when possible
+- runs local scaffold setup
+- can seed starter MCP files with `--init-mcp` when the local MCP config is empty or invalid
+- reports `READY`, `READY_WITH_WARNINGS`, or `BLOCKED`
+
+What `ma doctor` does:
+- runs the same environment checks without changing files
+- prints the current readiness state and exact next step
+
 What to use when:
 - use Codex and run the skills in-session
 - use `$maestro` when you want Meta-Architect to choose the best next step for you
 - use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
+- use `ma bootstrap` when you want the lazy-user setup path
+- use `ma doctor` when you want a check-only environment report
 - use `ma setup` or `ma init` only when you want local scaffolding or scripted helper automation from the terminal
 - use `ma sdk-path` when you need the exact installed support-bundle path for packaged prompts, MCP files, sprint files, scripts, plugin metadata, or templates
 
@@ -587,7 +608,7 @@ Release automation:
 | [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
 | [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
 | [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.7.md) | QA evidence for the `v0.1.7` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.9.md) | QA evidence for the `v0.1.9` line |
 
 ## Release Hygiene
 

package/bin/ma.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { runBootstrap, runDoctor } from "../src/bootstrap.js";
 import {
   evaluateBuildGate,
   formatBuildBlockers,
@@ -36,6 +37,8 @@ import { syncStatusUpdates } from "../src/state-sync.js";
 function printUsage() {
   console.error("Secondary helper commands:");
   console.error("  ma");
+  console.error("  ma bootstrap [--init-mcp]");
+  console.error("  ma doctor");
   console.error("  ma setup");
   console.error("  ma init");
   console.error('  ma idea "..."');
@@ -220,6 +223,18 @@ async function main() {
     return;
   }
 
+  if (command === "bootstrap") {
+    const outcome = await runBootstrap({ initMcp: rest.includes("--init-mcp") });
+    process.exitCode = outcome.result === "BLOCKED" ? 1 : 0;
+    return;
+  }
+
+  if (command === "doctor") {
+    const outcome = await runDoctor();
+    process.exitCode = outcome.result === "BLOCKED" ? 1 : 0;
+    return;
+  }
+
   if (command === "init") {
     const created = await runInit();
     console.log("meta-architect init");

package/docs/README.md

@@ -17,7 +17,7 @@ Meta-Architect documentation is organized by operator task.
 
 ## QA and readiness
 
-- [Release Readiness 0.1.7](./qa/release-readiness-0.1.7.md)
+- [Release Readiness 0.1.9](./qa/release-readiness-0.1.9.md)
 
 ## Repo structure references
 

package/docs/getting-started.md

@@ -74,7 +74,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.7
+8. Delivery plan for v0.1.9
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -181,6 +181,17 @@ Easy rule:
 - they prepare context, specs, plans, evidence, and runbook files
 - they do not automatically run the skill workflow
 
+`ma bootstrap` is the lazy-user path:
+- it checks whether `codex` is callable
+- it repairs installed skills and support-bundle assets when possible
+- it runs local scaffold setup
+- it can seed starter MCP files with `--init-mcp` when the local MCP config is empty or invalid
+- it reports `READY`, `READY_WITH_WARNINGS`, or `BLOCKED`
+
+`ma doctor` is the check-only path:
+- it runs the same environment checks without changing files
+- it prints the current readiness state and exact next step
+
 `ma sdk-path` prints the installed packaged support-bundle root for relevant files such as prompts, MCP files, sprint files, scripts, plugin metadata, and templates.
 
 ## 5. Configure MCP / GitMCP

package/docs/qa/{release-readiness-0.1.7.md → release-readiness-0.1.9.md}

@@ -1,25 +1,25 @@
-# Release Readiness 0.1.7
+# Release Readiness 0.1.9
 
 ## Production bar
 
-`v0.1.7` is treated as production only when:
+`v0.1.9` is treated as production only when:
 - the package installs cleanly from the canonical public install command
 - the Codex-hosted runtime path works end to end
 - the helper flow remains valid for scripted verification
-- release docs, package metadata, and workflows all agree on `0.1.7`
+- release docs, package metadata, and workflows all agree on `0.1.9`
 
 Target release state:
-- npm package: `@jstn-sdk/ma@0.1.7`
+- npm package: `@jstn-sdk/ma@0.1.9`
 - npm registry state: pending publish
-- publishability note: `0.1.6` is already published, so `0.1.7` is the next publishable package line
-- git tag: `v0.1.7`
-- GitHub release: pending publish for `v0.1.7`
+- publishability note: `0.1.8` is already published, so `0.1.9` is the next publishable package line
+- git tag: `v0.1.9`
+- GitHub release: pending publish for `v0.1.9`
 
 ## Production checklist
 
 - skills-first product identity: PASS
 - package/plugin identity aligned to `@jstn-sdk/ma`: PASS
-- version/tag alignment `0.1.7` / `v0.1.7`: PASS
+- version/tag alignment `0.1.9` / `v0.1.9`: PASS
 - install/uninstall docs aligned: PASS
 - onboarding is concise and sequential: PASS
 - helper command documented as secondary: PASS

package/docs/release-spec.md

@@ -1,13 +1,13 @@
-# v0.1.7 Requirements & Rules
+# v0.1.9 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.7` is production only when:
+Meta-Architect `v0.1.9` is production only when:
 1. the package/install surface works
 2. the in-session skill workflow from `$arch` through `$build` works
 3. the release evidence matches the actual package and git tag
 
-## What `v0.1.7` must have
+## What `v0.1.9` must have
 
 ### 1. Canonical package/runtime path
 
@@ -49,11 +49,11 @@ Canonical state files:
 
 ### 4. Required release evidence
 
-- `package.json` version `0.1.7`
-- git tag `v0.1.7`
+- `package.json` version `0.1.9`
+- git tag `v0.1.9`
 - `RELEASE.md`
 - `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.7.md`
+- `docs/qa/release-readiness-0.1.9.md`
 - green `npm run release:check`
 
 ### 5. Dist-tag discipline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",

package/plugins/meta-architect/.app.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
   "displayName": "Meta-Architect",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
   "author": {
     "name": "JustineDevs",

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -105,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.7`
+- plugin scope is aligned to Meta-Architect `v0.1.9`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.

package/src/bootstrap.js

@@ -0,0 +1,342 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { loadMcpServers } from "./mcp-config.js";
+import { getRepoRoot, getRuntimeWritePath, packageRoot } from "./paths.js";
+import {
+  areSkillsInstalled,
+  ensureSkillsInstalled,
+  ensureSupportBundleInstalled,
+  getSkillInstallRoot,
+  getSupportBundleRoot,
+  isSupportBundleInstalled,
+} from "./skill-installer.js";
+import { runInit } from "./skills.js";
+
+function makeStatus(kind, label, detail = "") {
+  return { kind, label, detail };
+}
+
+function resolveCodexCommand() {
+  return process.env.MA_CODEX_BIN ?? "codex";
+}
+
+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 inspectCodex() {
+  const command = resolveCodexCommand();
+  const result = runCommand(command, ["--version"]);
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message ?? result.stderr.trim() ?? result.stdout.trim();
+    return {
+      ok: false,
+      command,
+      detail: detail || "Codex command failed",
+      version: "",
+    };
+  }
+
+  return {
+    ok: true,
+    command,
+    detail: "",
+    version: result.stdout.trim(),
+  };
+}
+
+function listCodexPaths() {
+  const result = spawnSync("which", ["-a", "codex"], { encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    return [];
+  }
+
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function isWindowsPathInWsl(value) {
+  return value.startsWith("/mnt/") && value.includes("/AppData/Roaming/npm/");
+}
+
+async function writeCodexWrapper() {
+  const wrapperDir = path.join(os.homedir(), ".local", "bin");
+  const wrapperPath = path.join(wrapperDir, "codex");
+  const content = `#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v node >/dev/null 2>&1; then
+  NODE_BIN="$(command -v node)"
+  NODE_DIR="$(dirname "$NODE_BIN")"
+  if [ -x "$NODE_DIR/codex" ] && [ "$NODE_DIR/codex" != "$0" ]; then
+    exec "$NODE_DIR/codex" "$@"
+  fi
+fi
+
+while IFS= read -r candidate; do
+  [ -n "$candidate" ] || continue
+  if [ "$candidate" = "$0" ]; then
+    continue
+  fi
+  case "$candidate" in
+    /mnt/*) continue ;;
+  esac
+  exec "$candidate" "$@"
+done < <(which -a codex 2>/dev/null || true)
+
+echo "Unable to locate a Linux Codex binary. Reinstall with: npm install -g @openai/codex@latest" >&2
+exit 1
+  `;
+
+  await fs.mkdir(wrapperDir, { recursive: true });
+  await fs.writeFile(wrapperPath, content, { mode: 0o755 });
+  await fs.chmod(wrapperPath, 0o755);
+  const pathEntries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  if (!pathEntries.includes(wrapperDir)) {
+    process.env.PATH = [wrapperDir, ...pathEntries].join(path.delimiter);
+  }
+  return wrapperPath;
+}
+
+async function inspectCodexResolution({ fix }) {
+  if (process.platform !== "linux") {
+    return null;
+  }
+
+  const paths = listCodexPaths();
+  if (paths.length === 0) {
+    return null;
+  }
+
+  const first = paths[0];
+  const linuxAlternative = paths.find((candidate) => !isWindowsPathInWsl(candidate));
+  if (!isWindowsPathInWsl(first) || !linuxAlternative) {
+    return null;
+  }
+
+  if (!fix) {
+    return makeStatus(
+      "WARN",
+      "codex path points at a Windows npm install inside WSL",
+      `Preferred path is ${first}; Linux alternative exists at ${linuxAlternative}`,
+    );
+  }
+
+  const wrapperPath = await writeCodexWrapper();
+  return makeStatus(
+    "FIXED",
+    "codex path will prefer a Linux wrapper inside WSL",
+    `Installed wrapper at ${wrapperPath}`,
+  );
+}
+
+async function inspectLocalScaffold() {
+  const requiredFiles = [
+    getRuntimeWritePath("decisions.json"),
+    getRuntimeWritePath("release.json"),
+    path.join(getRepoRoot(), "mcp", "servers.json"),
+  ];
+
+  for (const file of requiredFiles) {
+    try {
+      await fs.access(file);
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function seedStarterMcpConfig() {
+  const files = ["servers.json", "collections.json", "fallback.json"];
+  for (const file of files) {
+    await fs.copyFile(path.join(packageRoot, "mcp", file), path.join(getRepoRoot(), "mcp", file));
+  }
+}
+
+async function inspectMcpState({ fix, initMcp }) {
+  try {
+    const servers = await loadMcpServers();
+    if (servers.servers.length === 0) {
+      if (fix && initMcp) {
+        await seedStarterMcpConfig();
+        const seededServers = await loadMcpServers();
+        return makeStatus(
+          "FIXED",
+          "starter MCP sources were seeded into mcp/servers.json",
+          `${seededServers.servers.length} configured source(s)`,
+        );
+      }
+
+      return makeStatus(
+        "WARN",
+        "mcp/servers.json exists but contains no approved repo-backed sources",
+        initMcp
+          ? "Run `ma bootstrap --init-mcp` to seed starter sources, or add exact upstream GitMCP repo endpoints manually."
+          : "Add exact upstream GitMCP repo endpoints before claiming VERIFIED evidence.",
+      );
+    }
+
+    return makeStatus(
+      "OK",
+      "mcp/servers.json has approved starter sources",
+      `${servers.servers.length} configured source(s)`,
+    );
+  } catch (error) {
+    if (fix && initMcp) {
+      await seedStarterMcpConfig();
+      const seededServers = await loadMcpServers();
+      return makeStatus(
+        "FIXED",
+        "starter MCP sources replaced an invalid MCP configuration",
+        `${seededServers.servers.length} configured source(s)`,
+      );
+    }
+
+    return makeStatus("WARN", "mcp/servers.json is not ready for evidence binding", error.message);
+  }
+}
+
+async function runEnvironmentFlow({ fix, initMcp }) {
+  const statuses = [];
+
+  const codexResolution = await inspectCodexResolution({ fix });
+  if (codexResolution) {
+    statuses.push(codexResolution);
+  }
+
+  const codex = inspectCodex();
+  if (codex.ok) {
+    statuses.push(makeStatus("OK", "codex command is available", codex.version));
+  } else {
+    statuses.push(
+      makeStatus(
+        "BLOCKED",
+        "codex command is not usable",
+        "Install or repair Codex with: npm install -g @openai/codex@latest",
+      ),
+    );
+  }
+
+  const skillInstallRoot = getSkillInstallRoot();
+  if (fix) {
+    const result = await ensureSkillsInstalled();
+    statuses.push(
+      makeStatus(
+        result.installed.length > 0 ? "FIXED" : "OK",
+        "Codex skills are installed",
+        skillInstallRoot,
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await areSkillsInstalled()) ? "OK" : "WARN",
+        "Codex skills install state",
+        skillInstallRoot,
+      ),
+    );
+  }
+
+  const supportBundleRoot = getSupportBundleRoot();
+  if (fix) {
+    const result = await ensureSupportBundleInstalled();
+    statuses.push(
+      makeStatus(
+        result.installed.length > 0 ? "FIXED" : "OK",
+        "support bundle is installed",
+        supportBundleRoot,
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await isSupportBundleInstalled()) ? "OK" : "WARN",
+        "support bundle install state",
+        supportBundleRoot,
+      ),
+    );
+  }
+
+  if (fix) {
+    await runInit();
+    statuses.push(
+      makeStatus(
+        "FIXED",
+        "local Meta-Architect scaffold is ready",
+        path.join(getRepoRoot(), ".ma"),
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await inspectLocalScaffold()) ? "OK" : "WARN",
+        "local Meta-Architect scaffold state",
+        path.join(getRepoRoot(), ".ma"),
+      ),
+    );
+  }
+
+  statuses.push(await inspectMcpState({ fix, initMcp }));
+  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";
+  }
+  return "READY";
+}
+
+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}`);
+    }
+  }
+  const result = summarizeStatuses(statuses);
+  console.log();
+  console.log(`Result: ${result}`);
+  if (result === "BLOCKED") {
+    console.log("Next: install or repair blocked prerequisites, then rerun `ma bootstrap`.");
+  } else if (result === "READY_WITH_WARNINGS") {
+    console.log("Next: review warnings, then start Codex or run `ma run '$maestro'`.");
+  } else {
+    console.log("Next: start Codex or run `ma run '$maestro'`.");
+  }
+  return result;
+}
+
+export async function runDoctor() {
+  const statuses = await runEnvironmentFlow({ fix: false, initMcp: false });
+  return {
+    statuses,
+    result: printStatuses("Meta-Architect Doctor", statuses),
+  };
+}
+
+export async function runBootstrap({ initMcp = false } = {}) {
+  const statuses = await runEnvironmentFlow({ fix: true, initMcp });
+  return {
+    statuses,
+    result: printStatuses("Meta-Architect Bootstrap", statuses),
+  };
+}

package/src/launcher.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import path from "node:path";
 
 const nativeCommands = new Set([
+  "bootstrap",
+  "doctor",
   "setup",
   "init",
   "idea",

package/src/mcp-live-client.js

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

package/src/skills.js

@@ -508,8 +508,8 @@ export async function runInit() {
       path.join(getRepoRoot(), "docs", "release-spec.md"),
     ],
     [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.7.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.7.md"),
+      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.9.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.9.md"),
     ],
   ];