onto-mcp 0.3.0

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

@@ -0,0 +1,254 @@
+/**
+ * File writer for `onto install` — persists the resolved decisions to
+ * `config.yml`, `.env`, and `.env.example` atomically.
+ *
+ * # What this module is
+ *
+ * A pure function seat (where possible): the rendering helpers
+ * (`renderConfigYml`, `renderEnvExample`, `renderEnv`, `parseEnv`) are
+ * filesystem-free so they can be unit-tested without tmpdirs. Only
+ * `writeInstallFiles` touches disk, and even that delegates content
+ * generation to the renderers.
+ *
+ * # Why atomic writes
+ *
+ * Both `config.yml` and `.env` are read on every onto invocation — a
+ * partial write (e.g. disk full mid-write, process killed) would leave
+ * an invalid file that blocks all future commands. Writing to a temp
+ * file in the same directory and renaming (POSIX atomic on same
+ * filesystem) means a crashed install leaves the prior state intact.
+ *
+ * # Why merge `.env` instead of overwrite
+ *
+ * The user may have unrelated keys in `.env` (third-party tool
+ * credentials, local overrides). Install touches only the keys it
+ * captured this session — the merge step preserves everything else.
+ * `.env.example` is overwritten wholesale since it's a template
+ * derived purely from the current install decisions.
+ *
+ * # File modes
+ *
+ * `.env` is set to 0600 so other users on the machine can't read the
+ * secrets file. On Windows, Node's fs module accepts the mode flag but
+ * NTFS ACLs don't map cleanly — treat the mode as best-effort and rely
+ * on filesystem isolation on that platform.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import yaml from "yaml";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the four file targets for a given profile scope.
+ *
+ * Global scope uses `~/.onto/` (no gitignore touched — there's no repo
+ * at the user-home layer). Project scope uses `<projectRoot>/.onto/`
+ * and also needs the project's root `.gitignore` path so the write
+ * step can ensure `.onto/.env` is ignored.
+ */
+export function resolveInstallPaths(scope, projectRoot, homeDir = os.homedir()) {
+    if (scope === "global") {
+        const ontoDir = path.join(homeDir, ".onto");
+        return {
+            ontoDir,
+            configYmlPath: path.join(ontoDir, "config.yml"),
+            envPath: path.join(ontoDir, ".env"),
+            envExamplePath: path.join(ontoDir, ".env.example"),
+        };
+    }
+    const ontoDir = path.join(projectRoot, ".onto");
+    return {
+        ontoDir,
+        configYmlPath: path.join(ontoDir, "config.yml"),
+        envPath: path.join(ontoDir, ".env"),
+        envExamplePath: path.join(ontoDir, ".env.example"),
+        gitignorePath: path.join(projectRoot, ".gitignore"),
+    };
+}
+// ---------------------------------------------------------------------------
+// config.yml rendering
+// ---------------------------------------------------------------------------
+/**
+ * Produce the YAML text that install writes for the current decisions.
+ *
+ * Shape rationale:
+ *
+ *   - `output_language` is always set (user-facing render boundary).
+ *   - `review.subagent.provider` records the review channel choice.
+ *     For `main-native` this is sufficient — no model_id / effort
+ *     fields at install time.
+ *   - `subagent_llm.provider` records the learn/background channel.
+ *   - `external_http_provider` is ALSO set when learn provider is
+ *     anthropic/openai/litellm — it's the ladder's user-override seat
+ *     in `llm-caller.ts`, so explicitly matching the user's choice
+ *     makes the intent sticky across future env drift.
+ *   - `external_http_provider` is NOT set for codex learn — codex is
+ *     not a valid value for that field (see config-chain.ts L37).
+ *   - Model fields are omitted intentionally. `onto config edit` is
+ *     the next step for users who want to pin a specific model; the
+ *     install completion message points there.
+ */
+export function renderConfigYml(decisions) {
+    const config = {
+        output_language: decisions.outputLanguage,
+        review: {
+            subagent: { provider: decisions.reviewProvider },
+        },
+        subagent_llm: {
+            provider: decisions.learnProvider,
+        },
+    };
+    if (decisions.learnProvider === "anthropic" ||
+        decisions.learnProvider === "openai" ||
+        decisions.learnProvider === "litellm") {
+        config.external_http_provider = decisions.learnProvider;
+    }
+    const header = [
+        "# Written by `onto install` — edit with `onto config edit` or",
+        "# re-run `onto install --reconfigure`. Full key reference:",
+        "# .onto/processes/configuration.md",
+        "",
+    ].join("\n");
+    return header + yaml.stringify(config);
+}
+// ---------------------------------------------------------------------------
+// .env / .env.example rendering
+// ---------------------------------------------------------------------------
+/**
+ * Lightweight `.env` parser. Preserves KEY=VALUE lines, drops comments
+ * and blanks. NOT a full shell parser — no variable expansion, no
+ * quoting nuance. The write path likewise emits unquoted values.
+ *
+ * Keys are trimmed; values are taken verbatim after the first `=`
+ * (including leading/trailing whitespace, which `.env` consumers
+ * typically preserve).
+ */
+export function parseEnv(contents) {
+    const out = new Map();
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1);
+        if (key)
+            out.set(key, value);
+    }
+    return out;
+}
+/**
+ * Serialize a KEY=VALUE map deterministically (sorted by key).
+ *
+ * Deterministic order matters so a reconfigure that doesn't change any
+ * key produces an identical file — no spurious diffs, easy to grep.
+ */
+export function renderEnv(kv) {
+    const header = "# onto runtime credentials — managed by `onto install`.\n";
+    const lines = [header];
+    const sorted = [...kv.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [k, v] of sorted) {
+        lines.push(`${k}=${v}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Build the `.env.example` text for the current install decisions.
+ *
+ * Only includes sections for providers actually selected — no point
+ * in shipping an ANTHROPIC_API_KEY template to a user who picked
+ * codex + openai. The LiteLLM section includes the expanded guidance
+ * block (local runtime examples) because that field is the one new
+ * users most often fumble — "just the port" is a common mistake.
+ */
+export function renderEnvExample(decisions) {
+    const needsAnthropic = decisions.reviewProvider === "anthropic" ||
+        decisions.learnProvider === "anthropic";
+    const needsOpenai = decisions.reviewProvider === "openai" ||
+        decisions.learnProvider === "openai";
+    const needsLitellm = decisions.reviewProvider === "litellm" ||
+        decisions.learnProvider === "litellm";
+    const lines = [
+        "# ---------------------------------------------------------------------------",
+        "# onto runtime credentials",
+        "# Copy this file to .env and fill in values as needed.",
+        "# Tracked in git; .env is gitignored.",
+        "# ---------------------------------------------------------------------------",
+        "",
+    ];
+    if (needsAnthropic) {
+        lines.push("# Anthropic API (per-token)", "# ANTHROPIC_API_KEY=sk-ant-...", "");
+    }
+    if (needsOpenai) {
+        lines.push("# OpenAI API (per-token)", "# OPENAI_API_KEY=sk-...", "");
+    }
+    if (needsLitellm) {
+        lines.push("# LiteLLM / OpenAI-compatible endpoint base URL", "#", "# Full URL required: scheme + host + port + /v1 path prefix.", "# Accepts any OpenAI-compatible endpoint — local runtime or remote proxy.", "#", "# Local examples:", "#   LiteLLM proxy   http://localhost:4000/v1", "#   Ollama          http://localhost:11434/v1", "#   LM Studio       http://localhost:1234/v1", "#   vLLM            http://localhost:8000/v1", "#   MLX             http://localhost:8080/v1", "#", "# Remote example:", "#   https://litellm.example.com/v1", "#", "# LITELLM_BASE_URL=http://localhost:4000/v1", "", "# Optional — only when the endpoint enforces authentication.", "# Local endpoints without auth (Ollama 등) leave this blank.", "# LITELLM_API_KEY=sk-proxy-token", "");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Atomic file write
+// ---------------------------------------------------------------------------
+function atomicWrite(target, content, mode) {
+    const dir = path.dirname(target);
+    const tmp = path.join(dir, `.${path.basename(target)}.tmp-${process.pid}-${Date.now()}`);
+    fs.writeFileSync(tmp, content, { encoding: "utf8", mode });
+    fs.renameSync(tmp, target);
+}
+/**
+ * Write (or dry-run) the three install output files.
+ *
+ * Order:
+ *   1. Ensure `.onto/` dir exists (idempotent).
+ *   2. Read existing `.env` to preserve unrelated keys.
+ *   3. Merge newly-captured secrets into the key map.
+ *   4. Atomic-write config.yml (0644), .env (0600), .env.example (0644).
+ *
+ * Returns the content strings for display / testing. Callers handle
+ * side-effects like the completion summary print — writer stays focused
+ * on file state.
+ */
+export function writeInstallFiles(args) {
+    const { paths, decisions, secrets, dryRun } = args;
+    const configYml = renderConfigYml(decisions);
+    const envExample = renderEnvExample(decisions);
+    // Merge existing .env (if any) with newly-captured secrets.
+    let envMap = new Map();
+    if (!dryRun && fs.existsSync(paths.envPath)) {
+        envMap = parseEnv(fs.readFileSync(paths.envPath, "utf8"));
+    }
+    if (secrets.anthropicApiKey) {
+        envMap.set("ANTHROPIC_API_KEY", secrets.anthropicApiKey);
+    }
+    if (secrets.openaiApiKey) {
+        envMap.set("OPENAI_API_KEY", secrets.openaiApiKey);
+    }
+    if (secrets.litellmBaseUrl) {
+        envMap.set("LITELLM_BASE_URL", secrets.litellmBaseUrl);
+    }
+    if (secrets.litellmApiKey) {
+        envMap.set("LITELLM_API_KEY", secrets.litellmApiKey);
+    }
+    const env = renderEnv(envMap);
+    if (!dryRun) {
+        fs.mkdirSync(paths.ontoDir, { recursive: true });
+        atomicWrite(paths.configYmlPath, configYml, 0o644);
+        atomicWrite(paths.envPath, env, 0o600);
+        atomicWrite(paths.envExamplePath, envExample, 0o644);
+    }
+    return {
+        configYml,
+        env,
+        envExample,
+        writtenTo: {
+            configYml: paths.configYmlPath,
+            env: paths.envPath,
+            envExample: paths.envExamplePath,
+        },
+    };
+}

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

@@ -0,0 +1,218 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import yaml from "yaml";
+import { parseEnv, renderConfigYml, renderEnv, renderEnvExample, resolveInstallPaths, writeInstallFiles, } from "./writer.js";
+const SAMPLE = {
+    profileScope: "project",
+    reviewProvider: "anthropic",
+    learnProvider: "anthropic",
+    outputLanguage: "ko",
+};
+describe("resolveInstallPaths", () => {
+    it("global scope points at ~/.onto/ and omits gitignorePath", () => {
+        const paths = resolveInstallPaths("global", "/unused", "/home/tester");
+        expect(paths.ontoDir).toBe("/home/tester/.onto");
+        expect(paths.configYmlPath).toBe("/home/tester/.onto/config.yml");
+        expect(paths.envPath).toBe("/home/tester/.onto/.env");
+        expect(paths.envExamplePath).toBe("/home/tester/.onto/.env.example");
+        expect(paths.gitignorePath).toBeUndefined();
+    });
+    it("project scope points at <projectRoot>/.onto/ and sets gitignorePath", () => {
+        const paths = resolveInstallPaths("project", "/tmp/proj", "/home/tester");
+        expect(paths.ontoDir).toBe("/tmp/proj/.onto");
+        expect(paths.configYmlPath).toBe("/tmp/proj/.onto/config.yml");
+        expect(paths.envPath).toBe("/tmp/proj/.onto/.env");
+        expect(paths.envExamplePath).toBe("/tmp/proj/.onto/.env.example");
+        expect(paths.gitignorePath).toBe("/tmp/proj/.gitignore");
+    });
+});
+describe("renderConfigYml", () => {
+    it("sets review.subagent.provider and subagent_llm.provider", () => {
+        const out = renderConfigYml(SAMPLE);
+        const parsed = yaml.parse(stripHeader(out));
+        expect(parsed.output_language).toBe("ko");
+        expect(parsed.review).toEqual({ subagent: { provider: "anthropic" } });
+        expect(parsed.subagent_llm).toEqual({ provider: "anthropic" });
+        expect(parsed.external_http_provider).toBe("anthropic");
+    });
+    it("omits external_http_provider for codex learn (codex not a valid value)", () => {
+        const decisions = {
+            ...SAMPLE,
+            reviewProvider: "codex",
+            learnProvider: "codex",
+        };
+        const parsed = yaml.parse(stripHeader(renderConfigYml(decisions)));
+        expect(parsed.external_http_provider).toBeUndefined();
+        expect(parsed.subagent_llm).toEqual({ provider: "codex" });
+    });
+    it("records main-native review provider without external fields", () => {
+        const decisions = {
+            ...SAMPLE,
+            reviewProvider: "main-native",
+            learnProvider: "anthropic",
+        };
+        const parsed = yaml.parse(stripHeader(renderConfigYml(decisions)));
+        expect(parsed.review).toEqual({
+            subagent: { provider: "main-native" },
+        });
+        expect(parsed.external_http_provider).toBe("anthropic");
+    });
+    it("emits a human-readable header comment at the top", () => {
+        const out = renderConfigYml(SAMPLE);
+        expect(out.startsWith("# Written by `onto install`")).toBe(true);
+        expect(out).toContain("onto config edit");
+    });
+});
+describe("parseEnv / renderEnv", () => {
+    it("parses KEY=VALUE lines and skips comments/blank lines", () => {
+        const input = [
+            "# comment",
+            "",
+            "FOO=bar",
+            "  # indented comment",
+            "BAZ=quux=extra",
+            "malformed-line-no-equals",
+        ].join("\n");
+        const kv = parseEnv(input);
+        expect(kv.get("FOO")).toBe("bar");
+        expect(kv.get("BAZ")).toBe("quux=extra");
+        expect(kv.has("malformed-line-no-equals")).toBe(false);
+    });
+    it("renderEnv emits keys sorted alphabetically", () => {
+        const kv = new Map([
+            ["ZZZ", "last"],
+            ["AAA", "first"],
+            ["MMM", "middle"],
+        ]);
+        const out = renderEnv(kv);
+        const keyOrder = out
+            .split("\n")
+            .filter((line) => !line.startsWith("#") && line.includes("="))
+            .map((line) => line.split("=")[0]);
+        expect(keyOrder).toEqual(["AAA", "MMM", "ZZZ"]);
+    });
+    it("roundtrips through parse → render", () => {
+        const original = new Map([
+            ["ANTHROPIC_API_KEY", "sk-ant-xyz"],
+            ["LITELLM_BASE_URL", "http://localhost:4000/v1"],
+        ]);
+        const rendered = renderEnv(original);
+        const reparsed = parseEnv(rendered);
+        expect(reparsed).toEqual(original);
+    });
+});
+describe("renderEnvExample", () => {
+    it("includes sections only for selected providers", () => {
+        const anthOnly = renderEnvExample({
+            ...SAMPLE,
+            reviewProvider: "anthropic",
+            learnProvider: "anthropic",
+        });
+        expect(anthOnly).toContain("ANTHROPIC_API_KEY");
+        expect(anthOnly).not.toContain("OPENAI_API_KEY");
+        expect(anthOnly).not.toContain("LITELLM_BASE_URL");
+    });
+    it("includes LiteLLM guidance block with local runtime examples", () => {
+        const out = renderEnvExample({
+            ...SAMPLE,
+            reviewProvider: "litellm",
+            learnProvider: "litellm",
+        });
+        expect(out).toContain("LITELLM_BASE_URL");
+        expect(out).toContain("Ollama");
+        expect(out).toContain("http://localhost:11434/v1");
+        expect(out).toContain("# LITELLM_API_KEY=");
+    });
+    it("merges sections when review and learn providers differ", () => {
+        const out = renderEnvExample({
+            ...SAMPLE,
+            reviewProvider: "openai",
+            learnProvider: "anthropic",
+        });
+        expect(out).toContain("OPENAI_API_KEY");
+        expect(out).toContain("ANTHROPIC_API_KEY");
+    });
+    it("produces no provider sections for codex-only setup", () => {
+        const out = renderEnvExample({
+            ...SAMPLE,
+            reviewProvider: "codex",
+            learnProvider: "codex",
+        });
+        expect(out).not.toContain("ANTHROPIC_API_KEY");
+        expect(out).not.toContain("OPENAI_API_KEY");
+        expect(out).not.toContain("LITELLM_BASE_URL");
+    });
+});
+describe("writeInstallFiles", () => {
+    let tmpHome;
+    beforeEach(() => {
+        tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-writer-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+    });
+    it("creates .onto/ and writes all three files with correct modes", () => {
+        const paths = resolveInstallPaths("global", "/unused", tmpHome);
+        const result = writeInstallFiles({
+            paths,
+            decisions: SAMPLE,
+            secrets: { anthropicApiKey: "sk-ant-test" },
+        });
+        expect(fs.existsSync(paths.ontoDir)).toBe(true);
+        expect(fs.existsSync(paths.configYmlPath)).toBe(true);
+        expect(fs.existsSync(paths.envPath)).toBe(true);
+        expect(fs.existsSync(paths.envExamplePath)).toBe(true);
+        expect(fs.readFileSync(paths.configYmlPath, "utf8")).toBe(result.configYml);
+        expect(fs.readFileSync(paths.envPath, "utf8")).toBe(result.env);
+        // .env mode should be 0600 on POSIX.
+        if (process.platform !== "win32") {
+            const mode = fs.statSync(paths.envPath).mode & 0o777;
+            expect(mode).toBe(0o600);
+        }
+    });
+    it("preserves unrelated keys during .env merge", () => {
+        const paths = resolveInstallPaths("global", "/unused", tmpHome);
+        fs.mkdirSync(paths.ontoDir, { recursive: true });
+        fs.writeFileSync(paths.envPath, "# user\nCUSTOM_TOOL_KEY=preserve-me\nANTHROPIC_API_KEY=old-value\n");
+        writeInstallFiles({
+            paths,
+            decisions: SAMPLE,
+            secrets: { anthropicApiKey: "new-value" },
+        });
+        const merged = parseEnv(fs.readFileSync(paths.envPath, "utf8"));
+        expect(merged.get("CUSTOM_TOOL_KEY")).toBe("preserve-me");
+        expect(merged.get("ANTHROPIC_API_KEY")).toBe("new-value");
+    });
+    it("dry-run returns content without touching the filesystem", () => {
+        const paths = resolveInstallPaths("global", "/unused", tmpHome);
+        const result = writeInstallFiles({
+            paths,
+            decisions: SAMPLE,
+            secrets: { anthropicApiKey: "sk-ant-test" },
+            dryRun: true,
+        });
+        expect(fs.existsSync(paths.ontoDir)).toBe(false);
+        expect(result.configYml).toContain("output_language: ko");
+        expect(result.env).toContain("ANTHROPIC_API_KEY=sk-ant-test");
+    });
+    it("atomic write: no partial temp file left behind on success", () => {
+        const paths = resolveInstallPaths("global", "/unused", tmpHome);
+        writeInstallFiles({
+            paths,
+            decisions: SAMPLE,
+            secrets: { anthropicApiKey: "sk" },
+        });
+        const files = fs.readdirSync(paths.ontoDir);
+        const tmpFiles = files.filter((f) => f.startsWith(".") && f.includes(".tmp-"));
+        expect(tmpFiles).toEqual([]);
+    });
+});
+/** Strip the leading comment header block so `yaml.parse` sees clean YAML. */
+function stripHeader(text) {
+    return text
+        .split("\n")
+        .filter((line) => !line.startsWith("#"))
+        .join("\n");
+}