onto-mcp 0.3.0

package/dist/core-runtime/install/types.js

@@ -0,0 +1,26 @@
+/**
+ * Shared types for `onto install` — the interactive + non-interactive
+ * first-run setup command.
+ *
+ * Design reference: spec v3 laid out in the install command design
+ * discussion (2026-04-21 session). Key decisions codified here:
+ *
+ *   1. Two provider channels: review (for 9-lens execution) and learn
+ *      (for background tasks — learn/govern/promote). They may share
+ *      a provider or be configured separately.
+ *
+ *   2. `main-native` is a valid ReviewProvider but NOT a valid
+ *      LearnProvider. The background ladder in llm-caller.ts does not
+ *      support host main-model delegation (fail-fast on missing
+ *      credentials). The type-level exclusion prevents accidentally
+ *      writing a learn config that would always fail at runtime.
+ *
+ *   3. API keys are never captured into typed decision shape — they
+ *      flow via environment (env var or `.env` file) only. This keeps
+ *      secrets out of logs, serialized state, and command history.
+ *
+ *   4. Profile scope is atomic (per config-profile.ts adoption rule) —
+ *      either global owns the full profile set or project does. The
+ *      scope choice is what determines where every file writes.
+ */
+export {};

package/dist/core-runtime/install/validation.js

@@ -0,0 +1,295 @@
+/**
+ * Live provider validation for `onto install`.
+ *
+ * Given a freshly resolved `{ decisions, secrets, detection }`, this
+ * module sends a minimal reachability probe to each non-main-native
+ * provider the user selected. A failed probe produces a clear
+ * `ValidationCheck` result that the orchestrator surfaces alongside
+ * instructions (re-run with `--skip-validation` or fix the credential).
+ *
+ * # What "ping" means per provider
+ *
+ *   - anthropic   GET https://api.anthropic.com/v1/models with the
+ *                 key — models list is free and confirms the key.
+ *   - openai      GET https://api.openai.com/v1/models with the key
+ *                 — same rationale, zero token cost.
+ *   - litellm     GET {base_url}/models (OpenAI-compatible). The
+ *                 `/models` suffix is the OpenAI-compat standard;
+ *                 LiteLLM proxy and every listed local runtime
+ *                 (Ollama, LM Studio, vLLM, MLX) respond to it.
+ *   - codex       Local check only — binary present + auth.json
+ *                 present. No network call; the codex CLI handles
+ *                 its own OAuth dance.
+ *   - main-native Skipped — there's nothing to probe; the runtime
+ *                 is the host session itself.
+ *
+ * # Why fetch directly instead of SDK
+ *
+ * The `@anthropic-ai/sdk` and `openai` SDKs carry non-trivial startup
+ * cost and change their response shapes between majors. A raw HTTP
+ * GET is dependency-free, gives a crisp HTTP status code (401 vs 200
+ * vs 5xx), and doesn't couple install's validation surface to SDK
+ * version drift. LiteLLM is already OpenAI-compatible HTTP, so the
+ * same pattern works there.
+ *
+ * # Testability
+ *
+ * All network and filesystem access flows through a `PingDependencies`
+ * struct. Tests inject a stub `fetch` that returns the desired
+ * `Response` shape, and stub codex-presence booleans directly.
+ */
+// ---------------------------------------------------------------------------
+// Shape guard
+// ---------------------------------------------------------------------------
+/**
+ * Runtime sanity check on the `InstallDecisions` shape.
+ *
+ * TypeScript already enforces most of this at compile time. The one
+ * thing that still benefits from a runtime check is the
+ * learn-provider exclusion (it's excluded at the type level via the
+ * `LearnProvider` union but a consumer could still construct
+ * decisions outside the normal flow).
+ */
+export function checkDecisionShape(decisions) {
+    const checks = [];
+    if (decisions.learnProvider === "main-native") {
+        checks.push({
+            name: "decisions",
+            passed: false,
+            message: "learn provider는 main-native를 지원하지 않습니다. " +
+                "background ladder(llm-caller.ts)에서 main-native는 ladder의 일부가 아닙니다.",
+        });
+    }
+    return checks;
+}
+// ---------------------------------------------------------------------------
+// Fetch helpers
+// ---------------------------------------------------------------------------
+async function fetchWithTimeout(fetchFn, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchFn(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function resolveFetch(deps) {
+    return deps.fetch ?? globalThis.fetch;
+}
+// ---------------------------------------------------------------------------
+// Per-provider pings
+// ---------------------------------------------------------------------------
+export async function pingAnthropic(apiKey, deps = {}) {
+    const fetchFn = resolveFetch(deps);
+    const timeoutMs = deps.timeoutMs ?? 5000;
+    try {
+        const res = await fetchWithTimeout(fetchFn, "https://api.anthropic.com/v1/models", {
+            method: "GET",
+            headers: {
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+        }, timeoutMs);
+        if (res.status >= 200 && res.status < 300) {
+            return { name: "anthropic", passed: true };
+        }
+        if (res.status === 401 || res.status === 403) {
+            return {
+                name: "anthropic",
+                passed: false,
+                message: "인증 실패 (API key 거부). 키 값을 확인하세요.",
+            };
+        }
+        return {
+            name: "anthropic",
+            passed: false,
+            message: `api.anthropic.com 응답 HTTP ${res.status}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: "anthropic",
+            passed: false,
+            message: `네트워크 오류: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export async function pingOpenai(apiKey, deps = {}) {
+    const fetchFn = resolveFetch(deps);
+    const timeoutMs = deps.timeoutMs ?? 5000;
+    try {
+        const res = await fetchWithTimeout(fetchFn, "https://api.openai.com/v1/models", {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+        }, timeoutMs);
+        if (res.status >= 200 && res.status < 300) {
+            return { name: "openai", passed: true };
+        }
+        if (res.status === 401 || res.status === 403) {
+            return {
+                name: "openai",
+                passed: false,
+                message: "인증 실패 (API key 거부). 키 값을 확인하세요.",
+            };
+        }
+        return {
+            name: "openai",
+            passed: false,
+            message: `api.openai.com 응답 HTTP ${res.status}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: "openai",
+            passed: false,
+            message: `네트워크 오류: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export async function pingLitellm(baseUrl, apiKey, deps = {}) {
+    const fetchFn = resolveFetch(deps);
+    const timeoutMs = deps.timeoutMs ?? 5000;
+    const url = baseUrl.replace(/\/+$/, "") + "/models";
+    try {
+        const headers = {};
+        if (apiKey)
+            headers.Authorization = `Bearer ${apiKey}`;
+        const res = await fetchWithTimeout(fetchFn, url, { method: "GET", headers }, timeoutMs);
+        if (res.status >= 200 && res.status < 300) {
+            return { name: "litellm", passed: true };
+        }
+        if (res.status === 401 || res.status === 403) {
+            return {
+                name: "litellm",
+                passed: false,
+                message: "인증 실패. 엔드포인트가 key를 요구합니다 — LITELLM_API_KEY를 설정하세요.",
+            };
+        }
+        return {
+            name: "litellm",
+            passed: false,
+            message: `${url} 응답 HTTP ${res.status}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: "litellm",
+            passed: false,
+            message: `연결 실패 (${url}): ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export function verifyCodex(detection, deps = {}) {
+    const binaryPresent = deps.codexBinaryPresent
+        ? deps.codexBinaryPresent()
+        : detection.hasCodexBinary;
+    const authPresent = deps.codexAuthPresent
+        ? deps.codexAuthPresent()
+        : detection.hasCodexAuth;
+    if (!binaryPresent) {
+        return {
+            name: "codex",
+            passed: false,
+            message: "codex binary가 PATH에 없습니다.",
+        };
+    }
+    if (!authPresent) {
+        return {
+            name: "codex",
+            passed: false,
+            message: "~/.codex/auth.json 없음. `codex login` 실행 필요.",
+        };
+    }
+    return { name: "codex", passed: true };
+}
+/**
+ * Validate the full install outcome.
+ *
+ * Dedupes the review + learn providers (when same, only pings once),
+ * reads credentials from `secrets` with `process.env` as the fallback
+ * (so a user who set ANTHROPIC_API_KEY in the shell gets validated
+ * without install having to re-capture the key).
+ *
+ * Never throws — all errors surface as failed `ValidationCheck`
+ * entries so the orchestrator can render a complete summary.
+ */
+export async function validateInstall(args) {
+    const { decisions, secrets, detection, deps = {} } = args;
+    const checks = [];
+    checks.push(...checkDecisionShape(decisions));
+    const providers = new Set();
+    providers.add(decisions.reviewProvider);
+    providers.add(decisions.learnProvider);
+    for (const provider of providers) {
+        switch (provider) {
+            case "main-native":
+                // Nothing to probe — host session is the runtime.
+                break;
+            case "anthropic": {
+                const apiKey = secrets.anthropicApiKey ?? process.env.ANTHROPIC_API_KEY;
+                if (!apiKey) {
+                    checks.push({
+                        name: "anthropic",
+                        passed: false,
+                        message: "ANTHROPIC_API_KEY를 찾을 수 없습니다.",
+                    });
+                }
+                else {
+                    checks.push(await pingAnthropic(apiKey, deps));
+                }
+                break;
+            }
+            case "openai": {
+                const apiKey = secrets.openaiApiKey ?? process.env.OPENAI_API_KEY;
+                if (!apiKey) {
+                    checks.push({
+                        name: "openai",
+                        passed: false,
+                        message: "OPENAI_API_KEY를 찾을 수 없습니다.",
+                    });
+                }
+                else {
+                    checks.push(await pingOpenai(apiKey, deps));
+                }
+                break;
+            }
+            case "litellm": {
+                const baseUrl = secrets.litellmBaseUrl ?? process.env.LITELLM_BASE_URL;
+                const apiKey = secrets.litellmApiKey ?? process.env.LITELLM_API_KEY;
+                if (!baseUrl) {
+                    checks.push({
+                        name: "litellm",
+                        passed: false,
+                        message: "LITELLM_BASE_URL을 찾을 수 없습니다.",
+                    });
+                }
+                else {
+                    checks.push(await pingLitellm(baseUrl, apiKey, deps));
+                }
+                break;
+            }
+            case "codex":
+                checks.push(verifyCodex(detection, deps));
+                break;
+        }
+    }
+    return {
+        ok: checks.every((c) => c.passed),
+        checks,
+    };
+}
+/**
+ * Pretty-print a validation result as text. One line per check,
+ * `✓` / `✗` prefix, and indented error message on the same line.
+ */
+export function formatValidationResult(result) {
+    const lines = [];
+    for (const check of result.checks) {
+        const mark = check.passed ? "✓" : "✗";
+        const suffix = check.message ? ` — ${check.message}` : "";
+        lines.push(`  ${mark} ${check.name}${suffix}`);
+    }
+    return lines.join("\n");
+}

package/dist/core-runtime/install/validation.test.js

@@ -0,0 +1,313 @@
+import { describe, it, expect } from "vitest";
+import { formatValidationResult, pingAnthropic, pingLitellm, pingOpenai, validateInstall, verifyCodex, } from "./validation.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const BLANK_DETECTION = {
+    existingGlobalConfig: false,
+    existingProjectConfig: false,
+    hasAnthropicKey: false,
+    hasOpenAiKey: false,
+    hasLitellmBaseUrl: false,
+    hasCodexBinary: false,
+    hasCodexAuth: false,
+    hostIsClaudeCode: false,
+};
+/** Build a stub fetch that returns a fixed Response for every call. */
+function stubFetchReturning(status, body = {}) {
+    return (async () => new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    }));
+}
+/** Build a stub fetch that throws — network error scenario. */
+function stubFetchThrowing(message) {
+    return (async () => {
+        throw new Error(message);
+    });
+}
+/** Capture the URL + headers of the first request. */
+function spyFetch() {
+    const calls = [];
+    const fetchFn = async (url, init) => {
+        const headers = {};
+        const raw = init?.headers;
+        if (raw && !Array.isArray(raw) && !(raw instanceof Headers)) {
+            Object.assign(headers, raw);
+        }
+        calls.push({ url: String(url), headers });
+        return new Response("{}", { status: 200 });
+    };
+    return { fetch: fetchFn, calls };
+}
+// ---------------------------------------------------------------------------
+// pingAnthropic
+// ---------------------------------------------------------------------------
+describe("pingAnthropic", () => {
+    it("returns passed=true on 200", async () => {
+        const check = await pingAnthropic("sk-ant-test", {
+            fetch: stubFetchReturning(200),
+        });
+        expect(check).toEqual({ name: "anthropic", passed: true });
+    });
+    it("reports auth failure on 401", async () => {
+        const check = await pingAnthropic("sk-ant-bad", {
+            fetch: stubFetchReturning(401),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("인증 실패");
+    });
+    it("reports generic HTTP failure on 5xx", async () => {
+        const check = await pingAnthropic("sk-ant-test", {
+            fetch: stubFetchReturning(500),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("500");
+    });
+    it("reports network error on fetch throw", async () => {
+        const check = await pingAnthropic("sk-ant-test", {
+            fetch: stubFetchThrowing("ECONNREFUSED"),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("네트워크");
+        expect(check.message).toContain("ECONNREFUSED");
+    });
+    it("sends x-api-key header and anthropic-version", async () => {
+        const spy = spyFetch();
+        await pingAnthropic("sk-ant-xyz", { fetch: spy.fetch });
+        expect(spy.calls[0]?.url).toBe("https://api.anthropic.com/v1/models");
+        expect(spy.calls[0]?.headers["x-api-key"]).toBe("sk-ant-xyz");
+        expect(spy.calls[0]?.headers["anthropic-version"]).toBeTruthy();
+    });
+});
+// ---------------------------------------------------------------------------
+// pingOpenai
+// ---------------------------------------------------------------------------
+describe("pingOpenai", () => {
+    it("returns passed=true on 200", async () => {
+        const check = await pingOpenai("sk-test", {
+            fetch: stubFetchReturning(200),
+        });
+        expect(check.passed).toBe(true);
+    });
+    it("sends Authorization: Bearer header", async () => {
+        const spy = spyFetch();
+        await pingOpenai("sk-test", { fetch: spy.fetch });
+        expect(spy.calls[0]?.url).toBe("https://api.openai.com/v1/models");
+        expect(spy.calls[0]?.headers.Authorization).toBe("Bearer sk-test");
+    });
+    it("reports 401 as auth failure", async () => {
+        const check = await pingOpenai("bad", {
+            fetch: stubFetchReturning(401),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("인증 실패");
+    });
+});
+// ---------------------------------------------------------------------------
+// pingLitellm
+// ---------------------------------------------------------------------------
+describe("pingLitellm", () => {
+    it("appends /models to the base URL", async () => {
+        const spy = spyFetch();
+        await pingLitellm("http://localhost:4000/v1", undefined, {
+            fetch: spy.fetch,
+        });
+        expect(spy.calls[0]?.url).toBe("http://localhost:4000/v1/models");
+    });
+    it("strips trailing slashes before appending /models", async () => {
+        const spy = spyFetch();
+        await pingLitellm("http://localhost:4000/v1/", undefined, {
+            fetch: spy.fetch,
+        });
+        expect(spy.calls[0]?.url).toBe("http://localhost:4000/v1/models");
+    });
+    it("omits Authorization when no apiKey given", async () => {
+        const spy = spyFetch();
+        await pingLitellm("http://localhost:11434/v1", undefined, {
+            fetch: spy.fetch,
+        });
+        expect(spy.calls[0]?.headers.Authorization).toBeUndefined();
+    });
+    it("sends Bearer token when apiKey provided", async () => {
+        const spy = spyFetch();
+        await pingLitellm("https://litellm.example.com/v1", "sk-proxy", {
+            fetch: spy.fetch,
+        });
+        expect(spy.calls[0]?.headers.Authorization).toBe("Bearer sk-proxy");
+    });
+    it("reports 401 with guidance to set LITELLM_API_KEY", async () => {
+        const check = await pingLitellm("http://localhost:4000/v1", undefined, {
+            fetch: stubFetchReturning(401),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("LITELLM_API_KEY");
+    });
+    it("reports network failure on ECONNREFUSED", async () => {
+        const check = await pingLitellm("http://localhost:4000/v1", undefined, {
+            fetch: stubFetchThrowing("fetch failed"),
+        });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("연결 실패");
+    });
+});
+// ---------------------------------------------------------------------------
+// verifyCodex (filesystem-level, no network)
+// ---------------------------------------------------------------------------
+describe("verifyCodex", () => {
+    it("passes when both binary and auth present in detection", () => {
+        const check = verifyCodex({
+            ...BLANK_DETECTION,
+            hasCodexBinary: true,
+            hasCodexAuth: true,
+        });
+        expect(check).toEqual({ name: "codex", passed: true });
+    });
+    it("fails with binary missing message", () => {
+        const check = verifyCodex(BLANK_DETECTION);
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("binary");
+    });
+    it("fails with auth missing message when binary present", () => {
+        const check = verifyCodex({ ...BLANK_DETECTION, hasCodexBinary: true });
+        expect(check.passed).toBe(false);
+        expect(check.message).toContain("codex login");
+    });
+    it("dependency overrides win over detection values", () => {
+        const check = verifyCodex(BLANK_DETECTION, {
+            codexBinaryPresent: () => true,
+            codexAuthPresent: () => true,
+        });
+        expect(check.passed).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// validateInstall orchestrator
+// ---------------------------------------------------------------------------
+const ANTHROPIC_DECISIONS = {
+    profileScope: "project",
+    reviewProvider: "anthropic",
+    learnProvider: "anthropic",
+    outputLanguage: "ko",
+};
+describe("validateInstall", () => {
+    it("skips network probe for main-native review + anthropic learn", async () => {
+        const spy = spyFetch();
+        const result = await validateInstall({
+            decisions: {
+                ...ANTHROPIC_DECISIONS,
+                reviewProvider: "main-native",
+            },
+            secrets: { anthropicApiKey: "sk-ant-test" },
+            detection: BLANK_DETECTION,
+            deps: { fetch: spy.fetch },
+        });
+        // Only anthropic is probed — main-native contributes no network call.
+        expect(spy.calls.length).toBe(1);
+        expect(spy.calls[0]?.url).toContain("api.anthropic.com");
+        expect(result.ok).toBe(true);
+    });
+    it("dedupes when review and learn providers match", async () => {
+        const spy = spyFetch();
+        await validateInstall({
+            decisions: ANTHROPIC_DECISIONS,
+            secrets: { anthropicApiKey: "sk-ant-test" },
+            detection: BLANK_DETECTION,
+            deps: { fetch: spy.fetch },
+        });
+        expect(spy.calls.length).toBe(1);
+    });
+    it("probes both providers when they differ", async () => {
+        const spy = spyFetch();
+        await validateInstall({
+            decisions: {
+                ...ANTHROPIC_DECISIONS,
+                reviewProvider: "anthropic",
+                learnProvider: "openai",
+            },
+            secrets: { anthropicApiKey: "sk-ant", openaiApiKey: "sk-oai" },
+            detection: BLANK_DETECTION,
+            deps: { fetch: spy.fetch },
+        });
+        const urls = spy.calls.map((c) => c.url);
+        expect(urls.some((u) => u.includes("api.anthropic.com"))).toBe(true);
+        expect(urls.some((u) => u.includes("api.openai.com"))).toBe(true);
+    });
+    it("fails when credential is missing entirely", async () => {
+        const result = await validateInstall({
+            decisions: ANTHROPIC_DECISIONS,
+            secrets: {},
+            detection: BLANK_DETECTION,
+            deps: { fetch: stubFetchReturning(200) },
+        });
+        expect(result.ok).toBe(false);
+        expect(result.checks.some((c) => c.message?.includes("ANTHROPIC_API_KEY"))).toBe(true);
+    });
+    it("falls back to process.env when secrets are empty", async () => {
+        const prev = process.env.ANTHROPIC_API_KEY;
+        process.env.ANTHROPIC_API_KEY = "from-env";
+        try {
+            const spy = spyFetch();
+            const result = await validateInstall({
+                decisions: ANTHROPIC_DECISIONS,
+                secrets: {},
+                detection: BLANK_DETECTION,
+                deps: { fetch: spy.fetch },
+            });
+            expect(result.ok).toBe(true);
+            expect(spy.calls[0]?.headers["x-api-key"]).toBe("from-env");
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.ANTHROPIC_API_KEY;
+            else
+                process.env.ANTHROPIC_API_KEY = prev;
+        }
+    });
+    it("surfaces codex check in mixed-provider setup", async () => {
+        const result = await validateInstall({
+            decisions: {
+                ...ANTHROPIC_DECISIONS,
+                reviewProvider: "codex",
+                learnProvider: "anthropic",
+            },
+            secrets: { anthropicApiKey: "sk-ant" },
+            detection: BLANK_DETECTION,
+            deps: { fetch: stubFetchReturning(200) },
+        });
+        expect(result.checks.some((c) => c.name === "codex")).toBe(true);
+        expect(result.ok).toBe(false); // codex check fails on blank detection
+    });
+    it("catches learn-provider=main-native shape violation", async () => {
+        const result = await validateInstall({
+            decisions: {
+                ...ANTHROPIC_DECISIONS,
+                reviewProvider: "main-native",
+                // @ts-expect-error — intentional runtime-only invalid shape
+                learnProvider: "main-native",
+            },
+            secrets: {},
+            detection: BLANK_DETECTION,
+            deps: { fetch: stubFetchReturning(200) },
+        });
+        expect(result.ok).toBe(false);
+        expect(result.checks.some((c) => c.message?.includes("main-native"))).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// formatValidationResult
+// ---------------------------------------------------------------------------
+describe("formatValidationResult", () => {
+    it("marks passed checks with ✓ and failed with ✗", () => {
+        const text = formatValidationResult({
+            ok: false,
+            checks: [
+                { name: "anthropic", passed: true },
+                { name: "openai", passed: false, message: "oops" },
+            ],
+        });
+        expect(text).toContain("✓ anthropic");
+        expect(text).toContain("✗ openai");
+        expect(text).toContain("oops");
+    });
+});