onto-mcp 0.3.0

package/dist/core-runtime/cli/write-review-interpretation.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { parseBooleanFlag, } from "../review/review-artifact-utils.js";
+import { writeInvocationInterpretationArtifact } from "../review/materializers.js";
+import { printOntoReleaseChannelNotice } from "../release-channel/release-channel.js";
+function requireString(value, optionName) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required option --${optionName}`);
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : "";
+}
+function requireReviewTargetScopeKind(value) {
+    if (value === "file" || value === "directory" || value === "bundle") {
+        return value;
+    }
+    throw new Error(`Invalid --target-scope-kind: ${value}`);
+}
+function requireReviewMode(value) {
+    if (value === "core-axis" || value === "full") {
+        return value;
+    }
+    throw new Error(`Invalid --review-mode-recommendation: ${value}`);
+}
+async function main() {
+    await printOntoReleaseChannelNotice();
+    const { values } = parseArgs({
+        options: {
+            "session-root": { type: "string" },
+            entrypoint: { type: "string", default: "review" },
+            "target-scope-kind": { type: "string" },
+            "primary-ref": { type: "string" },
+            "member-ref": { type: "string", multiple: true, default: [] },
+            "bundle-kind": { type: "string" },
+            "intent-summary": { type: "string" },
+            "domain-recommendation": { type: "string", default: "" },
+            "domain-selection-required": { type: "string", default: "true" },
+            "review-mode-recommendation": { type: "string" },
+            "always-include-lens-id": { type: "string", multiple: true, default: [] },
+            "recommended-lens-id": { type: "string", multiple: true, default: [] },
+            rationale: { type: "string", multiple: true, default: [] },
+            "ambiguity-note": { type: "string", multiple: true, default: [] },
+            "confirm-value-alignment": { type: "boolean", default: false },
+        },
+        strict: true,
+        allowPositionals: false,
+    });
+    const sessionRoot = path.resolve(requireString(values["session-root"], "session-root"));
+    const targetScopeKind = requireReviewTargetScopeKind(requireString(values["target-scope-kind"], "target-scope-kind"));
+    const primaryRef = requireString(values["primary-ref"], "primary-ref");
+    const reviewModeRecommendation = requireReviewMode(requireString(values["review-mode-recommendation"], "review-mode-recommendation"));
+    const interpretationParams = {
+        sessionRoot,
+        entrypoint: requireString(values.entrypoint, "entrypoint"),
+        targetScopeKind,
+        primaryRef,
+        memberRefs: values["member-ref"],
+        intentSummary: requireString(values["intent-summary"], "intent-summary"),
+        domainRecommendation: optionalString(values["domain-recommendation"]),
+        domainSelectionRequired: parseBooleanFlag(values["domain-selection-required"], "domain-selection-required"),
+        reviewModeRecommendation,
+        alwaysIncludeLensIds: values["always-include-lens-id"],
+        recommendedLensIds: values["recommended-lens-id"],
+        rationale: values.rationale,
+        ambiguityNotes: values["ambiguity-note"],
+        valueAlignmentConfirmed: Boolean(values["confirm-value-alignment"]),
+        ...(typeof values["bundle-kind"] === "string" && values["bundle-kind"].length > 0
+            ? { bundleKind: values["bundle-kind"] }
+            : {}),
+    };
+    const interpretationArtifactPath = await writeInvocationInterpretationArtifact(interpretationParams);
+    console.log(interpretationArtifactPath);
+    return 0;
+}
+main().then((exitCode) => process.exit(exitCode), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/core-runtime/config/onto-config-cli.js

@@ -0,0 +1,278 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertNoRetiredConfigFiles, defaultReviewExecution, projectSettingsPath, resolveSettingsChain, } from "../discovery/settings-chain.js";
+const SUPPORTED_SET_PATHS = [
+    "llm.auth",
+    "llm.provider",
+    "llm.model",
+    "llm.effort",
+    "llm.service_tier",
+    "llm.base_url",
+    "llm.api_key_env",
+    "review.execution.mode",
+    "review.execution.teamlead.seat",
+    "review.execution.lens.seat",
+    "review.execution.max_concurrent_workers",
+    "output_language",
+    "review_mode",
+];
+export async function handleConfigCli(ontoHome, argv) {
+    const subcommand = argv[0] ?? "show";
+    const args = argv.slice(1);
+    const projectRoot = process.cwd();
+    try {
+        switch (subcommand) {
+            case "show":
+                return handleShow(ontoHome, projectRoot);
+            case "validate":
+                return handleValidate(ontoHome, projectRoot);
+            case "set":
+                return handleSet(ontoHome, projectRoot, args);
+            case "use":
+                return handleUse(ontoHome, projectRoot, args);
+            case "--help":
+            case "-h":
+                printHelp();
+                return 0;
+            default:
+                throw new Error(`Unknown settings subcommand: ${subcommand}`);
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+function printHelp() {
+    console.log([
+        "onto config - inspect or edit .onto/settings.json",
+        "",
+        "Usage:",
+        "  onto config show",
+        "  onto config validate",
+        "  onto config set <path> <value>",
+        "  onto config use main-workers",
+        "  onto config use nested-workers",
+        "",
+        "Supported set paths:",
+        ...SUPPORTED_SET_PATHS.map((keyPath) => `  - ${keyPath}`),
+    ].join("\n"));
+}
+async function handleShow(ontoHome, projectRoot) {
+    const settings = await resolveSettingsChain(ontoHome, projectRoot);
+    console.log(JSON.stringify({
+        settings_path: projectSettingsPath(projectRoot),
+        settings,
+    }, null, 2));
+    return 0;
+}
+async function handleValidate(ontoHome, projectRoot) {
+    await resolveSettingsChain(ontoHome, projectRoot);
+    console.log(JSON.stringify({
+        ok: true,
+        settings_path: projectSettingsPath(projectRoot),
+    }, null, 2));
+    return 0;
+}
+async function handleSet(ontoHome, projectRoot, argv) {
+    if (argv.length !== 2) {
+        throw new Error("onto config set requires <path> and <value>.");
+    }
+    const [keyPath, rawValue] = argv;
+    if (!SUPPORTED_SET_PATHS.includes(keyPath)) {
+        throw new Error(`Unsupported settings path: ${keyPath}. Supported: ${SUPPORTED_SET_PATHS.join(", ")}`);
+    }
+    const settings = await readProjectSettings(projectRoot);
+    setValue(settings, keyPath, rawValue);
+    await writeProjectSettings(projectRoot, settings);
+    await resolveSettingsChain(ontoHome, projectRoot);
+    console.log(JSON.stringify({
+        ok: true,
+        changed: keyPath,
+        settings_path: projectSettingsPath(projectRoot),
+    }, null, 2));
+    return 0;
+}
+async function handleUse(ontoHome, projectRoot, argv) {
+    const mode = argv[0];
+    if (mode !== "main-workers" && mode !== "nested-workers") {
+        throw new Error("onto config use supports main-workers or nested-workers.");
+    }
+    const settings = await readProjectSettings(projectRoot);
+    const execution = settings.review?.execution ?? defaultReviewExecution();
+    settings.review = {
+        ...(settings.review ?? { execution }),
+        execution: {
+            ...execution,
+            mode,
+            teamlead: {
+                ...(execution.teamlead ?? { llm: "inherit" }),
+                seat: mode === "main-workers" ? "main" : "worker",
+            },
+            lens: {
+                ...(execution.lens ?? { llm: "inherit" }),
+                seat: "worker",
+            },
+            deliberation: "controlled-lens-deliberation",
+        },
+    };
+    const maxConcurrent = readOption(argv.slice(1), "max-concurrent-workers");
+    if (maxConcurrent !== undefined) {
+        settings.review.execution.max_concurrent_workers =
+            parsePositiveInteger(maxConcurrent, "--max-concurrent-workers");
+    }
+    await writeProjectSettings(projectRoot, settings);
+    await resolveSettingsChain(ontoHome, projectRoot);
+    console.log(JSON.stringify({
+        ok: true,
+        mode,
+        settings_path: projectSettingsPath(projectRoot),
+    }, null, 2));
+    return 0;
+}
+async function readProjectSettings(projectRoot) {
+    await assertNoRetiredConfigFiles(projectRoot);
+    const settingsPath = projectSettingsPath(projectRoot);
+    try {
+        const raw = await fs.readFile(settingsPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {};
+        }
+        throw new Error(`Failed to read ${settingsPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function writeProjectSettings(projectRoot, settings) {
+    const settingsPath = projectSettingsPath(projectRoot);
+    await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+    await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+function setValue(settings, keyPath, rawValue) {
+    switch (keyPath) {
+        case "llm.auth":
+            settings.llm = { ...(settings.llm ?? {}), auth: parseAuth(rawValue) };
+            return;
+        case "llm.provider":
+            settings.llm = { ...(settings.llm ?? {}), provider: parseProvider(rawValue) };
+            return;
+        case "llm.model":
+            settings.llm = { ...(settings.llm ?? {}), model: requireNonEmpty(rawValue, keyPath) };
+            return;
+        case "llm.effort":
+            settings.llm = { ...(settings.llm ?? {}), effort: requireNonEmpty(rawValue, keyPath) };
+            return;
+        case "llm.service_tier":
+            settings.llm = { ...(settings.llm ?? {}), service_tier: requireNonEmpty(rawValue, keyPath) };
+            return;
+        case "llm.base_url":
+            settings.llm = { ...(settings.llm ?? {}), base_url: requireNonEmpty(rawValue, keyPath) };
+            return;
+        case "llm.api_key_env":
+            settings.llm = { ...(settings.llm ?? {}), api_key_env: requireNonEmpty(rawValue, keyPath) };
+            return;
+        case "review.execution.mode":
+            ensureExecution(settings).mode = parseMode(rawValue);
+            normalizeExecutionSeats(settings);
+            return;
+        case "review.execution.teamlead.seat":
+            ensureExecution(settings).teamlead = {
+                ...ensureExecution(settings).teamlead,
+                seat: parseSeat(rawValue),
+            };
+            return;
+        case "review.execution.lens.seat":
+            ensureExecution(settings).lens = {
+                ...ensureExecution(settings).lens,
+                seat: parseSeat(rawValue),
+            };
+            return;
+        case "review.execution.max_concurrent_workers":
+            ensureExecution(settings).max_concurrent_workers =
+                parsePositiveInteger(rawValue, keyPath);
+            return;
+        case "output_language":
+            settings.output_language = requireNonEmpty(rawValue, keyPath);
+            return;
+        case "review_mode":
+            if (rawValue !== "core-axis" && rawValue !== "full") {
+                throw new Error("review_mode must be core-axis or full.");
+            }
+            settings.review_mode = rawValue;
+            return;
+    }
+}
+function ensureExecution(settings) {
+    const execution = settings.review?.execution ?? defaultReviewExecution();
+    settings.review = {
+        ...(settings.review ?? { execution }),
+        execution,
+    };
+    return settings.review.execution;
+}
+function normalizeExecutionSeats(settings) {
+    const execution = ensureExecution(settings);
+    execution.teamlead = {
+        ...execution.teamlead,
+        seat: execution.mode === "main-workers" ? "main" : "worker",
+    };
+    execution.lens = {
+        ...execution.lens,
+        seat: "worker",
+    };
+}
+function parseAuth(rawValue) {
+    if (rawValue === "api_key" || rawValue === "oauth" || rawValue === "local") {
+        return rawValue;
+    }
+    throw new Error("llm.auth must be api_key, oauth, or local.");
+}
+function parseProvider(rawValue) {
+    if (rawValue === "openai" ||
+        rawValue === "anthropic" ||
+        rawValue === "grok" ||
+        rawValue === "lmstudio") {
+        return rawValue;
+    }
+    throw new Error("llm.provider must be openai, anthropic, grok, or lmstudio.");
+}
+function parseMode(rawValue) {
+    if (rawValue === "main-workers" || rawValue === "nested-workers") {
+        return rawValue;
+    }
+    throw new Error("review.execution.mode must be main-workers or nested-workers.");
+}
+function parseSeat(rawValue) {
+    if (rawValue === "main" || rawValue === "worker") {
+        return rawValue;
+    }
+    throw new Error("review execution seat must be main or worker.");
+}
+function parsePositiveInteger(rawValue, label) {
+    if (!/^\d+$/.test(rawValue)) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    const value = Number.parseInt(rawValue, 10);
+    if (value < 1) {
+        throw new Error(`${label} must be >= 1.`);
+    }
+    return value;
+}
+function requireNonEmpty(rawValue, label) {
+    if (rawValue.length === 0) {
+        throw new Error(`${label} cannot be empty.`);
+    }
+    return rawValue;
+}
+function readOption(argv, name) {
+    const token = `--${name}`;
+    const index = argv.indexOf(token);
+    if (index < 0)
+        return undefined;
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${token} requires a value.`);
+    }
+    return value;
+}

package/dist/core-runtime/config/onto-config-key-path.js

@@ -0,0 +1,288 @@
+/**
+ * Review UX Redesign P5 — pure helper for `onto config set <key> <value>`.
+ *
+ * # What this module is
+ *
+ * A small set of pure functions that translate the user-facing key-path
+ * vocabulary (`subagent.provider`, `max_concurrent_lenses`,
+ * `teamlead.model`, etc.) into mutations on an `OntoReviewConfig` object.
+ * Callers pass the current config + key + raw string value; the helper
+ * returns the mutated config OR a structured error explaining why the
+ * assignment is invalid.
+ *
+ * # Why it exists
+ *
+ * `onto config set subagent.provider codex` must (1) type-coerce the value,
+ * (2) respect the discriminated-union semantics of `SubagentSpec`, and
+ * (3) refuse paths that would produce an invalid config even before calling
+ * the main validator. Putting this in a pure module lets both the `set`
+ * subcommand and the `edit` subcommand share the exact same write semantics
+ * without duplicating coercion logic.
+ *
+ * # How it relates
+ *
+ * - Input : current `OntoReviewConfig` + dotted key path + raw string value.
+ * - Output: `{ ok: true, config }` or `{ ok: false, error }`.
+ * - Next stage: caller feeds the returned config into `validateReviewConfig`
+ *   then `writeReviewBlock`. This helper performs SHAPE coercion only;
+ *   semantic constraints are the validator's job.
+ */
+/**
+ * Supported user-facing key paths. `set` rejects anything else with a hint
+ * pointing to the `edit` subcommand for fields that need richer input
+ * (notably external-teamlead spec objects).
+ */
+export const SUPPORTED_SET_PATHS = [
+    "teamlead.model",
+    "teamlead.model.provider",
+    "teamlead.model.model_id",
+    "teamlead.model.effort",
+    "subagent.provider",
+    "subagent.model_id",
+    "subagent.effort",
+    "max_concurrent_lenses",
+    "lens_deliberation",
+];
+const SUBAGENT_PROVIDER_VALUES = [
+    "main-native",
+    "codex",
+];
+const FOREIGN_PROVIDER_VALUES = ["codex"];
+const LENS_DELIBERATION_VALUES = [
+    "controlled-lens-deliberation",
+];
+/**
+ * Apply a `set key value` mutation and return the resulting config.
+ *
+ * Does NOT invoke `validateReviewConfig` — the caller is responsible for
+ * running the full validator against the returned object before writing.
+ * This separation lets `edit` (which performs multiple sets in a session)
+ * validate once at the end, and `set` (single-shot) validate immediately.
+ */
+export function applySet(current, path, rawValue) {
+    if (!isSupportedPath(path)) {
+        return {
+            ok: false,
+            error: `Unknown key path "${path}". Supported paths: ${SUPPORTED_SET_PATHS.join(", ")}. ` +
+                "For external teamlead specs or multi-field changes, use `onto config edit`.",
+        };
+    }
+    // Deep-clone the current config so the mutation is pure.
+    const next = structuredClone(current);
+    switch (path) {
+        case "teamlead.model":
+            return setTeamleadModel(next, rawValue);
+        case "teamlead.model.provider":
+            return setTeamleadModelProvider(next, rawValue);
+        case "teamlead.model.model_id":
+            return setTeamleadModelId(next, rawValue);
+        case "teamlead.model.effort":
+            return setTeamleadEffort(next, rawValue);
+        case "subagent.provider":
+            return setSubagentProvider(next, rawValue);
+        case "subagent.model_id":
+            return setSubagentModelId(next, rawValue);
+        case "subagent.effort":
+            return setSubagentEffort(next, rawValue);
+        case "max_concurrent_lenses":
+            return setMaxConcurrentLenses(next, rawValue);
+        case "lens_deliberation":
+            return setLensDeliberation(next, rawValue);
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-path handlers
+// ---------------------------------------------------------------------------
+function setTeamleadModel(config, rawValue) {
+    if (rawValue === "main") {
+        config.teamlead = { model: "main" };
+        return { ok: true, config };
+    }
+    return {
+        ok: false,
+        error: `teamlead.model via \`set\` only accepts "main" (the host main session). ` +
+            "Use `onto config edit` to configure an external teamlead provider " +
+            "(requires provider + model_id + optional effort).",
+    };
+}
+function getExistingExternalTeamleadModel(config) {
+    const model = config.teamlead?.model;
+    if (!model || model === "main")
+        return null;
+    return model;
+}
+function setTeamleadModelProvider(config, rawValue) {
+    if (!FOREIGN_PROVIDER_VALUES.includes(rawValue)) {
+        return {
+            ok: false,
+            error: `teamlead.model.provider must be one of: ${FOREIGN_PROVIDER_VALUES.join(", ")} (got "${rawValue}").`,
+        };
+    }
+    const provider = rawValue;
+    const prev = getExistingExternalTeamleadModel(config);
+    config.teamlead = {
+        model: {
+            provider,
+            model_id: prev?.model_id ?? "",
+            ...(prev?.effort !== undefined ? { effort: prev.effort } : {}),
+        },
+    };
+    return { ok: true, config };
+}
+function setTeamleadModelId(config, rawValue) {
+    if (rawValue.length === 0) {
+        return {
+            ok: false,
+            error: "teamlead.model.model_id cannot be empty.",
+        };
+    }
+    const prev = getExistingExternalTeamleadModel(config);
+    if (!prev) {
+        return {
+            ok: false,
+            error: "teamlead.model.model_id can only be set when teamlead.model.provider is codex. " +
+                "Set teamlead.model.provider first, or use `onto config use codex-nested --model <id>`.",
+        };
+    }
+    config.teamlead = {
+        model: {
+            provider: prev.provider,
+            model_id: rawValue,
+            ...(prev.effort !== undefined ? { effort: prev.effort } : {}),
+        },
+    };
+    return { ok: true, config };
+}
+function setTeamleadEffort(config, rawValue) {
+    if (rawValue.length === 0) {
+        return {
+            ok: false,
+            error: "teamlead.model.effort cannot be empty (omit the field to clear it).",
+        };
+    }
+    const prev = getExistingExternalTeamleadModel(config);
+    if (!prev) {
+        return {
+            ok: false,
+            error: "teamlead.model.effort can only be set when teamlead.model.provider is codex. " +
+                "For main teamlead, effort is host-managed.",
+        };
+    }
+    config.teamlead = {
+        model: {
+            provider: prev.provider,
+            model_id: prev.model_id,
+            effort: rawValue,
+        },
+    };
+    return { ok: true, config };
+}
+function setSubagentProvider(config, rawValue) {
+    if (!SUBAGENT_PROVIDER_VALUES.includes(rawValue)) {
+        return {
+            ok: false,
+            error: `subagent.provider must be one of: ${SUBAGENT_PROVIDER_VALUES.join(", ")} (got "${rawValue}").`,
+        };
+    }
+    const provider = rawValue;
+    const prev = config.subagent;
+    if (provider === "main-native") {
+        // Switching to main-native drops any model_id / effort from the
+        // foreign branch — they are not allowed under the main-native branch
+        // per the discriminated union.
+        config.subagent = { provider: "main-native" };
+        return { ok: true, config };
+    }
+    // Foreign provider — carry over model_id/effort if previously set (same
+    // provider or different foreign provider). Missing model_id is caught
+    // later by `validateReviewConfig`, not here, because the user may be
+    // composing the change in multiple `set` calls.
+    const prevModelId = prev && prev.provider !== "main-native" ? prev.model_id : "";
+    const prevEffort = prev && prev.provider !== "main-native" ? prev.effort : undefined;
+    const nextSpec = {
+        provider,
+        model_id: prevModelId,
+        ...(prevEffort !== undefined ? { effort: prevEffort } : {}),
+    };
+    config.subagent = nextSpec;
+    return { ok: true, config };
+}
+function setSubagentModelId(config, rawValue) {
+    if (rawValue.length === 0) {
+        return {
+            ok: false,
+            error: "subagent.model_id cannot be empty.",
+        };
+    }
+    const prev = config.subagent;
+    if (!prev || prev.provider === "main-native") {
+        return {
+            ok: false,
+            error: "subagent.model_id can only be set when subagent.provider is codex. " +
+                "Set subagent.provider first, or use `onto config edit`.",
+        };
+    }
+    // Type narrowing: prev.provider is ForeignProvider here, so model_id is required.
+    config.subagent = {
+        provider: prev.provider,
+        model_id: rawValue,
+        ...(prev.effort !== undefined ? { effort: prev.effort } : {}),
+    };
+    return { ok: true, config };
+}
+function setSubagentEffort(config, rawValue) {
+    if (rawValue.length === 0) {
+        return {
+            ok: false,
+            error: "subagent.effort cannot be empty (omit the field to clear it).",
+        };
+    }
+    const prev = config.subagent;
+    if (!prev || prev.provider === "main-native") {
+        return {
+            ok: false,
+            error: "subagent.effort can only be set when subagent.provider is a foreign provider. " +
+                "For main-native, effort is host-managed (not expressible in OntoReviewConfig).",
+        };
+    }
+    config.subagent = {
+        provider: prev.provider,
+        model_id: prev.model_id,
+        effort: rawValue,
+    };
+    return { ok: true, config };
+}
+function setMaxConcurrentLenses(config, rawValue) {
+    // Accept decimal integers only. Reject floats, hex, negative, zero.
+    if (!/^\d+$/.test(rawValue)) {
+        return {
+            ok: false,
+            error: `max_concurrent_lenses must be a positive decimal integer (got "${rawValue}").`,
+        };
+    }
+    const n = Number.parseInt(rawValue, 10);
+    if (n < 1) {
+        return {
+            ok: false,
+            error: "max_concurrent_lenses must be >= 1.",
+        };
+    }
+    config.max_concurrent_lenses = n;
+    return { ok: true, config };
+}
+function setLensDeliberation(config, rawValue) {
+    if (!LENS_DELIBERATION_VALUES.includes(rawValue)) {
+        return {
+            ok: false,
+            error: `lens_deliberation must be one of: ${LENS_DELIBERATION_VALUES.join(", ")} (got "${rawValue}").`,
+        };
+    }
+    config.lens_deliberation = rawValue;
+    return { ok: true, config };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isSupportedPath(path) {
+    return SUPPORTED_SET_PATHS.includes(path);
+}