onto-mcp 0.3.0

package/dist/core-runtime/onboard/detect-review-axes.test.js

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { detectReviewAxes } from "./detect-review-axes.js";
+// ---------------------------------------------------------------------------
+// detectReviewAxes — Review UX Redesign P4 (2026-04-21)
+// ---------------------------------------------------------------------------
+//
+// These tests exercise the projection of env signals into the onboard
+// axis vocabulary. The underlying detection helpers (from discovery/) are
+// covered by their own suite; here we only verify:
+//
+//   (1) Host priority ordering — Claude Code > Codex CLI > plain.
+//   (2) agent_teams_available reads CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.
+//   (3) litellm_endpoint returns the URL string (not just a boolean).
+//   (4) codex_available is sourced from the shared discovery helper.
+//
+// The codex binary / auth.json probe is filesystem-backed, so we mock
+// `detectCodexBinaryAvailable` from the discovery module to keep the tests
+// hermetic.
+// ---------------------------------------------------------------------------
+vi.mock("../discovery/host-detection.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return {
+        ...actual,
+        // Override only the filesystem-dependent probe. The env-signal helpers
+        // remain real so we can control behaviour via process.env.
+        detectCodexBinaryAvailable: vi.fn(() => false),
+    };
+});
+const savedEnv = {};
+const VOLATILE_ENV_KEYS = [
+    "CLAUDECODE",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS",
+    "CODEX_THREAD_ID",
+    "CODEX_CI",
+    "LITELLM_BASE_URL",
+];
+beforeEach(() => {
+    for (const key of VOLATILE_ENV_KEYS) {
+        savedEnv[key] = process.env[key];
+        delete process.env[key];
+    }
+});
+afterEach(() => {
+    for (const key of VOLATILE_ENV_KEYS) {
+        const original = savedEnv[key];
+        if (original === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = original;
+        }
+    }
+    vi.resetAllMocks();
+});
+describe("detectReviewAxes — host category", () => {
+    it("returns plain-terminal when no host signal is present", () => {
+        const result = detectReviewAxes();
+        expect(result.detected.host).toBe("plain-terminal");
+    });
+    it("returns claude-code when CLAUDECODE=1", () => {
+        process.env.CLAUDECODE = "1";
+        expect(detectReviewAxes().detected.host).toBe("claude-code");
+    });
+    it("returns claude-code when CLAUDE_PROJECT_DIR is set", () => {
+        process.env.CLAUDE_PROJECT_DIR = "/tmp/proj";
+        expect(detectReviewAxes().detected.host).toBe("claude-code");
+    });
+    it("returns codex-cli when CODEX_THREAD_ID is set", () => {
+        process.env.CODEX_THREAD_ID = "thr-123";
+        expect(detectReviewAxes().detected.host).toBe("codex-cli");
+    });
+    it("prefers claude-code over codex-cli when both signals are present", () => {
+        // An inner Codex exec inside a Claude Code session — onboard context
+        // is Claude Code; codex availability is surfaced separately.
+        process.env.CLAUDECODE = "1";
+        process.env.CODEX_THREAD_ID = "thr-123";
+        expect(detectReviewAxes().detected.host).toBe("claude-code");
+    });
+});
+describe("detectReviewAxes — agent_teams_available (strict =1)", () => {
+    // The resolver uses `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === "1"`.
+    // Onboard MUST use the same check so the two layers never disagree on
+    // whether teams are available — otherwise onboard writes a config the
+    // runtime silently rejects (P3 would degrade it, violating the UX
+    // promise that "what onboard accepts is what runs").
+    it("is false when env var is absent", () => {
+        expect(detectReviewAxes().detected.agent_teams_available).toBe(false);
+    });
+    it('is true only when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === "1"', () => {
+        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
+        expect(detectReviewAxes().detected.agent_teams_available).toBe(true);
+    });
+    it('is false for truthy-looking strings that are not "1"', () => {
+        // These would pass a naive Boolean() check but must NOT activate teams.
+        // The resolver rejects them; onboard must match.
+        for (const value of ["true", "yes", "on", "enabled", "TRUE", "2"]) {
+            process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = value;
+            expect(detectReviewAxes().detected.agent_teams_available).toBe(false);
+        }
+    });
+    it('is false for falsy-looking strings ("0", "false", empty)', () => {
+        for (const value of ["0", "false", ""]) {
+            process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = value;
+            expect(detectReviewAxes().detected.agent_teams_available).toBe(false);
+        }
+    });
+});
+describe("detectReviewAxes — litellm_endpoint", () => {
+    it("is null when LITELLM_BASE_URL is unset", () => {
+        expect(detectReviewAxes().detected.litellm_endpoint).toBeNull();
+    });
+    it("returns the URL string when LITELLM_BASE_URL is set", () => {
+        process.env.LITELLM_BASE_URL = "http://localhost:4000";
+        expect(detectReviewAxes().detected.litellm_endpoint).toBe("http://localhost:4000");
+    });
+});
+describe("detectReviewAxes — codex_available", () => {
+    it("surfaces the discovery helper verdict (mocked false by default)", async () => {
+        const mod = await import("../discovery/host-detection.js");
+        const spy = vi.mocked(mod.detectCodexBinaryAvailable);
+        spy.mockReturnValue(false);
+        expect(detectReviewAxes().detected.codex_available).toBe(false);
+        spy.mockReturnValue(true);
+        expect(detectReviewAxes().detected.codex_available).toBe(true);
+    });
+});

package/dist/core-runtime/onboard/write-review-block.js

@@ -0,0 +1,188 @@
+/**
+ * Review UX Redesign P4 — write/update the `review:` block in `.onto/config.yml`.
+ *
+ * # What this module is
+ *
+ * A small helper that takes a validated `OntoReviewConfig` plus a path to
+ * an `.onto/config.yml` file and either (a) adds a `review:` block to the
+ * file or (b) replaces an existing one.
+ *
+ * # Why it exists
+ *
+ * Onboard stage 7 (design doc §5.2) writes the user's chosen review axes
+ * into `.onto/config.yml`. Without a dedicated seat this would require the
+ * prose to embed YAML serialization instructions, which is error-prone — a
+ * stray indent produces a silently invalid config. Centralizing the write
+ * path means the onboard prose can describe the intent ("record the user's
+ * answers in the review block") and delegate formatting to this helper.
+ *
+ * We use `yaml`'s `parseDocument` / `Document` API (not `parse` +
+ * `stringify`) because the document round-trip preserves comments and
+ * formatting where the existing file has them. That matters for configs
+ * authored by humans — they often annotate fields with rationale.
+ *
+ * # How it relates
+ *
+ * - Consumes: `OntoReviewConfig` type from `discovery/config-chain.ts`.
+ * - Validates with: `validateReviewConfig` from
+ *   `review/review-config-validator.ts` — we re-validate to catch caller
+ *   errors early (the onboard prose is a weak integrator).
+ * - Exposed via: `npm run onboard:write-review-block -- <path> <json>`.
+ *
+ * # Guarantees
+ *
+ * 1. Existing top-level fields are preserved in order.
+ * 2. Comments attached to preserved fields survive the round-trip.
+ * 3. If the file does not exist, it is created with a minimal document
+ *    containing only the `review:` block.
+ * 4. If the input is not a valid `OntoReviewConfig`, the function returns a
+ *    result object with `ok: false` and no write is performed.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { Document, parseDocument } from "yaml";
+import { validateReviewConfig, } from "../review/review-config-validator.js";
+/**
+ * Write (or update) the `review:` block in the given config file.
+ *
+ * The function re-validates `review` with `validateReviewConfig` before
+ * touching the file — if validation fails, nothing is written and the
+ * caller receives the structured error list.
+ */
+export function writeReviewBlock(configPath, review) {
+    // Re-validate. The type system alone cannot catch callers who constructed
+    // the object manually from JSON input (the most common P4 path — the
+    // onboard prose builds the object from interactive answers).
+    const validation = validateReviewConfig(review);
+    if (!validation.ok) {
+        return { ok: false, errors: validation.errors };
+    }
+    const absolute = path.resolve(configPath);
+    const exists = fs.existsSync(absolute);
+    // Load the existing document (or a fresh empty one). `parseDocument`
+    // returns a `Document` node the YAML library can mutate and re-serialize
+    // while preserving source formatting where practical.
+    let doc;
+    if (exists) {
+        const raw = fs.readFileSync(absolute, "utf8");
+        doc = parseDocument(raw, { keepSourceTokens: false });
+    }
+    else {
+        // Ensure the parent directory exists — `.onto/` may not be present on
+        // a brand-new project until onboard creates it.
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        doc = new Document({});
+    }
+    // Detect the prior state of the document so we can report it back to the
+    // onboard prose (for the user-facing summary).
+    const replacedExistingBlock = exists && doc.has("review");
+    // The yaml library accepts a plain object for `set` — it converts that
+    // into the internal Node graph. We filter out undefined leaves so the
+    // output does not carry `key: null` artifacts for absent axes.
+    const serializable = pruneUndefined(review);
+    doc.set("review", serializable);
+    const serialized = doc.toString();
+    fs.writeFileSync(absolute, serialized, "utf8");
+    return {
+        ok: true,
+        path: absolute,
+        created: !exists,
+        replacedExistingBlock,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Strip `undefined` leaves from a nested object. The `yaml` library would
+ * otherwise serialize them as `null`, which is semantically different from
+ * "absent" in the review block (an absent key = use review defaults).
+ */
+function pruneUndefined(input) {
+    if (input === null || input === undefined)
+        return input;
+    if (Array.isArray(input)) {
+        return input.map((v) => pruneUndefined(v));
+    }
+    if (typeof input !== "object")
+        return input;
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined)
+            continue;
+        out[key] = pruneUndefined(value);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// CLI entry — `npm run onboard:write-review-block -- <path> <json>`
+// ---------------------------------------------------------------------------
+function printHelp() {
+    const lines = [
+        "onboard:write-review-block",
+        "",
+        "Write or update the `review:` block in a .onto/config.yml file.",
+        "",
+        "Usage:",
+        "  npm run onboard:write-review-block -- <config-path> <review-json>",
+        "  npm run onboard:write-review-block -- --help",
+        "",
+        "Arguments:",
+        "  <config-path>  Path to .onto/config.yml (created if missing).",
+        "  <review-json>  JSON string representing an OntoReviewConfig.",
+        "",
+        "Example:",
+        "  npm run onboard:write-review-block -- .onto/config.yml \\",
+        "    '{\"teamlead\":{\"model\":\"main\"},\"subagent\":{\"provider\":\"main-native\"}}'",
+        "",
+        "Output: single-line JSON describing the write result on stdout.",
+        "Exit code 0 on success, 1 on validation/IO failure.",
+    ];
+    console.log(lines.join("\n"));
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (typeof entry !== "string" || entry.length === 0)
+        return false;
+    try {
+        const entryUrl = new URL(`file://${entry}`).href;
+        return import.meta.url === entryUrl;
+    }
+    catch {
+        return false;
+    }
+}
+function runCli(argv) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        printHelp();
+        return argv.length === 0 ? 1 : 0;
+    }
+    const unsupportedFlags = argv.filter((a) => a.startsWith("--"));
+    if (unsupportedFlags.length > 0) {
+        console.error(`error: unsupported option(s): ${unsupportedFlags.join(", ")}`);
+        return 1;
+    }
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    if (positional.length < 2) {
+        console.error("error: two positional arguments required: <config-path> <review-json>. " +
+            "Run with --help for usage.");
+        return 1;
+    }
+    const [configPath, reviewJson] = positional;
+    let parsed;
+    try {
+        parsed = JSON.parse(reviewJson);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`error: <review-json> is not valid JSON: ${message}`);
+        return 1;
+    }
+    const result = writeReviewBlock(configPath, parsed);
+    console.log(JSON.stringify(result));
+    return result.ok ? 0 : 1;
+}
+if (isMainModule()) {
+    const exitCode = runCli(process.argv.slice(2));
+    process.exit(exitCode);
+}

package/dist/core-runtime/onboard/write-review-block.test.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { writeReviewBlock } from "./write-review-block.js";
+// ---------------------------------------------------------------------------
+// writeReviewBlock — Review UX Redesign P4 (2026-04-21)
+// ---------------------------------------------------------------------------
+//
+// These tests cover the four behaviours the onboard prose flow depends on:
+//
+//   (1) Fresh-file creation — onboard on a brand-new project must create
+//       the file + parent directory + write the review block.
+//   (2) Round-trip preservation — existing top-level fields (e.g.
+//       output_language, domains) and their comments must survive the
+//       write.
+//   (3) Replace semantics — a pre-existing `review:` block is REPLACED,
+//       not merged. The caller's config object is the authoritative shape.
+//   (4) Legacy stripping — when stripLegacyPriority=true, the
+//       execution_topology_priority field is removed and reported.
+//
+// Validation failure paths (foreign provider without model_id, etc.) are
+// covered indirectly via validateReviewConfig's own tests — here we spot-
+// check that invalid input blocks the write entirely.
+// ---------------------------------------------------------------------------
+let tmpDir;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-onboard-p4-"));
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+function makeConfigPath(name = "config.yml") {
+    return path.join(tmpDir, ".onto", name);
+}
+function read(p) {
+    return fs.readFileSync(p, "utf8");
+}
+describe("writeReviewBlock — fresh file", () => {
+    it("creates the parent directory + file when neither exists", () => {
+        const configPath = makeConfigPath();
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "main-native" },
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.created).toBe(true);
+        expect(result.replacedExistingBlock).toBe(false);
+        expect(result.strippedLegacyPriority).toBe(false);
+        const written = read(configPath);
+        expect(written).toContain("review:");
+        expect(written).toContain("teamlead:");
+        expect(written).toContain("model: main");
+        expect(written).toContain("provider: main-native");
+    });
+    it("serializes foreign-provider subagent with model_id + effort", () => {
+        const configPath = makeConfigPath();
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "codex", model_id: "gpt-5.4", effort: "high" },
+            max_concurrent_lenses: 6,
+            lens_deliberation: "synthesizer-only",
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        const written = read(configPath);
+        expect(written).toContain("provider: codex");
+        expect(written).toContain("model_id: gpt-5.4");
+        expect(written).toContain("effort: high");
+        expect(written).toContain("max_concurrent_lenses: 6");
+        expect(written).toContain("lens_deliberation: synthesizer-only");
+    });
+});
+describe("writeReviewBlock — existing file", () => {
+    it("preserves top-level fields + trailing content when adding review", () => {
+        const configPath = makeConfigPath();
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        const original = [
+            "# Project config — hand-written",
+            "output_language: en",
+            "",
+            "domains:",
+            "  - software-engineering",
+            "  - ontology",
+            "",
+        ].join("\n");
+        fs.writeFileSync(configPath, original, "utf8");
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "main-native" },
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.created).toBe(false);
+        expect(result.replacedExistingBlock).toBe(false);
+        const written = read(configPath);
+        expect(written).toContain("output_language: en");
+        expect(written).toContain("software-engineering");
+        expect(written).toContain("ontology");
+        expect(written).toContain("review:");
+        expect(written).toContain("provider: main-native");
+    });
+    it("replaces (not merges) a pre-existing review block", () => {
+        const configPath = makeConfigPath();
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        const original = [
+            "output_language: en",
+            "review:",
+            "  teamlead:",
+            "    model: main",
+            "  subagent:",
+            "    provider: codex",
+            "    model_id: gpt-5.4",
+            "    effort: high",
+            "  max_concurrent_lenses: 6",
+            "",
+        ].join("\n");
+        fs.writeFileSync(configPath, original, "utf8");
+        // New config chooses main-native — previous codex fields must not leak.
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "main-native" },
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.replacedExistingBlock).toBe(true);
+        const written = read(configPath);
+        expect(written).toContain("provider: main-native");
+        expect(written).not.toContain("gpt-5.4");
+        expect(written).not.toContain("effort: high");
+        expect(written).not.toMatch(/max_concurrent_lenses:\s*6/);
+    });
+});
+describe("writeReviewBlock — legacy stripping", () => {
+    it("strips execution_topology_priority when stripLegacyPriority=true", () => {
+        const configPath = makeConfigPath();
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        const original = [
+            "output_language: en",
+            "execution_topology_priority:",
+            "  - cc-teams-codex-subprocess",
+            "  - cc-main-agent-subagent",
+            "",
+        ].join("\n");
+        fs.writeFileSync(configPath, original, "utf8");
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "codex", model_id: "gpt-5.4", effort: "high" },
+        };
+        const result = writeReviewBlock(configPath, review, {
+            stripLegacyPriority: true,
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.strippedLegacyPriority).toBe(true);
+        const written = read(configPath);
+        expect(written).not.toContain("execution_topology_priority");
+        expect(written).not.toContain("cc-teams-codex-subprocess");
+        expect(written).toContain("review:");
+        expect(written).toContain("provider: codex");
+    });
+    it("leaves legacy field alone when stripLegacyPriority is false/absent", () => {
+        const configPath = makeConfigPath();
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        const original = [
+            "output_language: en",
+            "execution_topology_priority:",
+            "  - cc-main-agent-subagent",
+            "",
+        ].join("\n");
+        fs.writeFileSync(configPath, original, "utf8");
+        const review = {
+            teamlead: { model: "main" },
+            subagent: { provider: "main-native" },
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.strippedLegacyPriority).toBe(false);
+        const written = read(configPath);
+        expect(written).toContain("execution_topology_priority");
+        expect(written).toContain("cc-main-agent-subagent");
+    });
+});
+describe("writeReviewBlock — validation failure", () => {
+    it("returns errors without writing when config is invalid", () => {
+        const configPath = makeConfigPath();
+        // provider=codex is a foreign provider, so model_id is required.
+        // The validator catches this; writeReviewBlock must propagate.
+        const invalid = {
+            subagent: { provider: "codex" },
+        };
+        const result = writeReviewBlock(configPath, invalid);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.length).toBeGreaterThan(0);
+        expect(result.errors.some((e) => e.path.includes("subagent"))).toBe(true);
+        expect(fs.existsSync(configPath)).toBe(false);
+    });
+    it("rejects mismatched deliberation + teamlead combination", () => {
+        const configPath = makeConfigPath();
+        const invalid = {
+            teamlead: {
+                model: { provider: "codex", model_id: "gpt-5.4" },
+            },
+            lens_deliberation: "sendmessage-a2a",
+        };
+        const result = writeReviewBlock(configPath, invalid);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.path === "review.lens_deliberation")).toBe(true);
+        expect(fs.existsSync(configPath)).toBe(false);
+    });
+});
+describe("writeReviewBlock — pruneUndefined behaviour", () => {
+    it("does not emit null keys for undefined axes", () => {
+        const configPath = makeConfigPath();
+        const review = {
+            teamlead: { model: "main" },
+            // subagent, max_concurrent_lenses, lens_deliberation intentionally absent
+        };
+        const result = writeReviewBlock(configPath, review);
+        expect(result.ok).toBe(true);
+        const written = read(configPath);
+        expect(written).not.toContain("subagent: null");
+        expect(written).not.toContain("max_concurrent_lenses: null");
+        expect(written).not.toContain("lens_deliberation: null");
+    });
+});