onto-mcp 0.3.0

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

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { formatPreflightSummary, globalConfigPath, projectConfigPath, runPreflight, } from "./detect.js";
+const ENV_KEYS = [
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "LITELLM_BASE_URL",
+    "CLAUDECODE",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS",
+];
+let savedEnv = {};
+function saveEnv() {
+    savedEnv = {};
+    for (const key of ENV_KEYS) {
+        savedEnv[key] = process.env[key];
+        delete process.env[key];
+    }
+    savedEnv.PATH = process.env.PATH;
+    // Empty PATH neutralizes codex binary detection.
+    process.env.PATH = "";
+    savedEnv.HOME = process.env.HOME;
+}
+function restoreEnv() {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    }
+}
+/** Point HOME at a tmpdir so ~/.onto/ / ~/.codex/ checks are isolated. */
+function isolateHome() {
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-test-"));
+    process.env.HOME = tmpHome;
+    return tmpHome;
+}
+function cleanupHome(tmpHome) {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+}
+describe("runPreflight", () => {
+    let tmpHome;
+    let tmpProject;
+    beforeEach(() => {
+        saveEnv();
+        tmpHome = isolateHome();
+        tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-proj-"));
+    });
+    afterEach(() => {
+        restoreEnv();
+        cleanupHome(tmpHome);
+        fs.rmSync(tmpProject, { recursive: true, force: true });
+    });
+    it("returns all-false baseline when environment is empty", () => {
+        const result = runPreflight(tmpProject);
+        expect(result).toEqual({
+            existingGlobalConfig: false,
+            existingProjectConfig: false,
+            hasAnthropicKey: false,
+            hasOpenAiKey: false,
+            hasLitellmBaseUrl: false,
+            hasCodexBinary: false,
+            hasCodexAuth: false,
+            hostIsClaudeCode: false,
+        });
+    });
+    it("detects ANTHROPIC_API_KEY", () => {
+        process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+        const result = runPreflight(tmpProject);
+        expect(result.hasAnthropicKey).toBe(true);
+        expect(result.hasOpenAiKey).toBe(false);
+    });
+    it("detects OPENAI_API_KEY from env", () => {
+        process.env.OPENAI_API_KEY = "sk-test";
+        const result = runPreflight(tmpProject);
+        expect(result.hasOpenAiKey).toBe(true);
+    });
+    it("detects OPENAI_API_KEY from ~/.codex/auth.json", () => {
+        const codexDir = path.join(tmpHome, ".codex");
+        fs.mkdirSync(codexDir, { recursive: true });
+        fs.writeFileSync(path.join(codexDir, "auth.json"), JSON.stringify({ OPENAI_API_KEY: "sk-from-file" }));
+        const result = runPreflight(tmpProject);
+        expect(result.hasOpenAiKey).toBe(true);
+        expect(result.hasCodexAuth).toBe(true);
+    });
+    it("captures LITELLM_BASE_URL value when present", () => {
+        process.env.LITELLM_BASE_URL = "http://localhost:4000/v1";
+        const result = runPreflight(tmpProject);
+        expect(result.hasLitellmBaseUrl).toBe(true);
+        expect(result.litellmBaseUrlValue).toBe("http://localhost:4000/v1");
+    });
+    it("detects Claude Code session via CLAUDECODE env signal", () => {
+        process.env.CLAUDECODE = "1";
+        const result = runPreflight(tmpProject);
+        expect(result.hostIsClaudeCode).toBe(true);
+    });
+    it("splits codex binary and auth presence for install UX", () => {
+        // Binary present, auth missing — the "run `codex login`" branch.
+        const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-bin-"));
+        fs.writeFileSync(path.join(fakeBinDir, "codex"), "#!/bin/sh\nexit 0");
+        fs.chmodSync(path.join(fakeBinDir, "codex"), 0o755);
+        try {
+            process.env.PATH = fakeBinDir;
+            const result = runPreflight(tmpProject);
+            expect(result.hasCodexBinary).toBe(true);
+            expect(result.hasCodexAuth).toBe(false);
+        }
+        finally {
+            fs.rmSync(fakeBinDir, { recursive: true, force: true });
+        }
+    });
+    it("detects existing global and project config files independently", () => {
+        fs.mkdirSync(path.join(tmpHome, ".onto"), { recursive: true });
+        fs.writeFileSync(path.join(tmpHome, ".onto", "config.yml"), "output_language: ko\n");
+        fs.mkdirSync(path.join(tmpProject, ".onto"), { recursive: true });
+        fs.writeFileSync(path.join(tmpProject, ".onto", "config.yml"), "output_language: en\n");
+        const result = runPreflight(tmpProject);
+        expect(result.existingGlobalConfig).toBe(true);
+        expect(result.existingProjectConfig).toBe(true);
+    });
+});
+describe("path helpers", () => {
+    it("globalConfigPath points at ~/.onto/config.yml", () => {
+        expect(globalConfigPath()).toBe(path.join(os.homedir(), ".onto", "config.yml"));
+    });
+    it("projectConfigPath joins project root with .onto/config.yml", () => {
+        expect(projectConfigPath("/tmp/proj")).toBe("/tmp/proj/.onto/config.yml");
+    });
+});
+describe("formatPreflightSummary", () => {
+    it("uses ✓ for present signals and · for absent ones", () => {
+        const snapshot = {
+            existingGlobalConfig: true,
+            existingProjectConfig: false,
+            hasAnthropicKey: true,
+            hasOpenAiKey: false,
+            hasLitellmBaseUrl: true,
+            litellmBaseUrlValue: "http://localhost:4000/v1",
+            hasCodexBinary: false,
+            hasCodexAuth: false,
+            hostIsClaudeCode: true,
+        };
+        const out = formatPreflightSummary(snapshot);
+        expect(out).toContain("✓ global config");
+        expect(out).toContain("· project config");
+        expect(out).toContain("✓ ANTHROPIC_API_KEY");
+        expect(out).toContain("· OPENAI_API_KEY");
+        expect(out).toContain("http://localhost:4000/v1");
+        expect(out).toContain("✓ running inside Claude Code");
+    });
+});

package/dist/core-runtime/install/gitignore-update.js

@@ -0,0 +1,74 @@
+/**
+ * `.gitignore` updater for project-scope install.
+ *
+ * When the user picks project scope, the `.env` file lives under the
+ * repo at `<root>/.onto/.env` — secrets on a developer machine. The
+ * gitignore needs to exclude that path; otherwise a `git add` of
+ * anything under `.onto/` would stage credentials.
+ *
+ * Scope of this module:
+ *
+ *   - **In**: append `.onto/.env` to the project `.gitignore` if the
+ *     file exists and the entry is missing.
+ *   - **In**: create a new `.gitignore` with a single entry if it
+ *     doesn't exist yet.
+ *   - **Out**: touching `.env.example`, `config.yml`, or any other
+ *     tracked onto resource. Those are intentionally in git.
+ *   - **Out**: global scope — `~/.onto/.env` doesn't live in any repo.
+ *
+ * # Why idempotent match-on-trimmed-line
+ *
+ * `.gitignore` tolerates variations: blank lines, inline comments,
+ * leading slash, trailing slash. We normalize each line for the
+ * membership test but append the canonical form if missing. This
+ * means re-running install never produces a duplicate entry.
+ */
+import fs from "node:fs";
+const CANONICAL_ENTRY = ".onto/.env";
+/**
+ * Line-level check: does `line` match our target entry, ignoring
+ * leading/trailing whitespace, a leading `/`, and any inline comment
+ * (gitignore doesn't support inline comments on entry lines, but we
+ * tolerate them defensively)?
+ */
+function lineMatches(line, target) {
+    const stripped = line.split("#")[0]?.trim() ?? "";
+    if (!stripped)
+        return false;
+    const normalized = stripped.replace(/^\//, "");
+    return normalized === target;
+}
+/**
+ * Ensure `.onto/.env` is listed in the given `.gitignore` file.
+ *
+ * Creates the file if absent. Appends the entry if the file exists
+ * but the entry isn't found. No-ops when the entry is already
+ * present (as `/X`, `X`, `X  # comment`, etc.).
+ *
+ * Returns the resulting file content so the caller can log it in
+ * dry-run mode or include it in the completion summary.
+ */
+export function ensureGitignoreEntry(gitignorePath, options = {}) {
+    const { dryRun = false } = options;
+    if (!fs.existsSync(gitignorePath)) {
+        const content = `${CANONICAL_ENTRY}\n`;
+        if (!dryRun) {
+            fs.writeFileSync(gitignorePath, content, "utf8");
+        }
+        return { alreadyPresent: false, created: true, content };
+    }
+    const original = fs.readFileSync(gitignorePath, "utf8");
+    const lines = original.split(/\r?\n/);
+    const already = lines.some((line) => lineMatches(line, CANONICAL_ENTRY));
+    if (already) {
+        return { alreadyPresent: true, created: false, content: original };
+    }
+    // Append — preserve trailing newline convention.
+    const trailingNewline = original.endsWith("\n");
+    const prefix = trailingNewline ? original : `${original}\n`;
+    const content = `${prefix}${CANONICAL_ENTRY}\n`;
+    if (!dryRun) {
+        fs.writeFileSync(gitignorePath, content, "utf8");
+    }
+    return { alreadyPresent: false, created: false, content };
+}

package/dist/core-runtime/install/gitignore-update.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ensureGitignoreEntry } from "./gitignore-update.js";
+describe("ensureGitignoreEntry", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-git-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("creates a new .gitignore with the entry when file absent", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        const result = ensureGitignoreEntry(gi);
+        expect(result.created).toBe(true);
+        expect(result.alreadyPresent).toBe(false);
+        expect(fs.readFileSync(gi, "utf8")).toBe(".onto/.env\n");
+    });
+    it("appends the entry to an existing .gitignore without duplication", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        fs.writeFileSync(gi, "node_modules/\ndist/\n");
+        const result = ensureGitignoreEntry(gi);
+        expect(result.created).toBe(false);
+        expect(result.alreadyPresent).toBe(false);
+        const content = fs.readFileSync(gi, "utf8");
+        expect(content).toContain("node_modules/");
+        expect(content.trim().endsWith(".onto/.env")).toBe(true);
+    });
+    it("is a no-op when the entry is already present", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        const original = "dist/\n.onto/.env\nnode_modules/\n";
+        fs.writeFileSync(gi, original);
+        const result = ensureGitignoreEntry(gi);
+        expect(result.alreadyPresent).toBe(true);
+        expect(fs.readFileSync(gi, "utf8")).toBe(original);
+    });
+    it("recognizes leading slash variants", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        fs.writeFileSync(gi, "/.onto/.env\n");
+        const result = ensureGitignoreEntry(gi);
+        expect(result.alreadyPresent).toBe(true);
+    });
+    it("ignores inline comments on the entry line", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        fs.writeFileSync(gi, ".onto/.env  # secrets\n");
+        const result = ensureGitignoreEntry(gi);
+        expect(result.alreadyPresent).toBe(true);
+    });
+    it("adds a trailing newline when the existing file has none", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        fs.writeFileSync(gi, "dist/");
+        const result = ensureGitignoreEntry(gi);
+        expect(result.alreadyPresent).toBe(false);
+        expect(fs.readFileSync(gi, "utf8")).toBe("dist/\n.onto/.env\n");
+    });
+    it("dry-run returns expected content without writing", () => {
+        const gi = path.join(tmpDir, ".gitignore");
+        const result = ensureGitignoreEntry(gi, { dryRun: true });
+        expect(result.content).toBe(".onto/.env\n");
+        expect(fs.existsSync(gi)).toBe(false);
+    });
+});

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

@@ -0,0 +1,373 @@
+/**
+ * Integration-level tests for `onto install`.
+ *
+ * These drive `handleInstallCliWithOverrides()` with real argv,
+ * scoped to a tmp HOME + tmp project root, and exercise the full
+ * non-interactive orchestration end-to-end (flag parsing → preflight
+ * → decision resolution → write → validate → completion). Network
+ * calls go through a stub `fetch` passed via the overrides struct.
+ *
+ * The goal is to cover PR 4's promised scenario matrix:
+ *   - global-anthropic happy path
+ *   - project-main-native (with a learn provider required by design)
+ *   - reconfigure guard + --reconfigure bypass
+ *   - dry-run
+ *   - validation failure
+ *   - env-file loading
+ *   - ONTO_INSTALL_* env fallback
+ *
+ * Interactive path unit coverage lives in `prompts.test.ts`; this
+ * file intentionally skips re-covering prompts.
+ */
+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 { handleInstallCliWithOverrides } from "./cli.js";
+const MANAGED_ENV = [
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "LITELLM_BASE_URL",
+    "LITELLM_API_KEY",
+    "ONTO_INSTALL_NON_INTERACTIVE",
+    "ONTO_INSTALL_PROFILE_SCOPE",
+    "ONTO_INSTALL_REVIEW_PROVIDER",
+    "ONTO_INSTALL_LEARN_PROVIDER",
+    "ONTO_INSTALL_OUTPUT_LANGUAGE",
+    "ONTO_INSTALL_LITELLM_BASE_URL",
+    "ONTO_INSTALL_ENV_FILE",
+    "ONTO_INSTALL_RECONFIGURE",
+    "ONTO_INSTALL_SKIP_VALIDATION",
+    "ONTO_INSTALL_DRY_RUN",
+    "CLAUDECODE",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS",
+];
+let savedEnv;
+function saveAndClearEnv() {
+    savedEnv = {};
+    for (const key of MANAGED_ENV) {
+        savedEnv[key] = process.env[key];
+        delete process.env[key];
+    }
+    savedEnv.PATH = process.env.PATH;
+    process.env.PATH = "";
+    savedEnv.HOME = process.env.HOME;
+}
+function restoreEnv() {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+}
+function stubFetchReturning(status) {
+    return (async () => new Response("{}", { status }));
+}
+describe("handleInstallCliWithOverrides — non-interactive E2E", () => {
+    let tmpHome;
+    let tmpProject;
+    let stdout;
+    let stderr;
+    beforeEach(() => {
+        saveAndClearEnv();
+        tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-e2e-home-"));
+        tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), "onto-install-e2e-proj-"));
+        process.env.HOME = tmpHome;
+        stdout = [];
+        stderr = [];
+    });
+    afterEach(() => {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+        fs.rmSync(tmpProject, { recursive: true, force: true });
+        restoreEnv();
+    });
+    function runInstall(argv, extras = {}) {
+        for (const [k, v] of Object.entries(extras.envOverrides ?? {})) {
+            process.env[k] = v;
+        }
+        return handleInstallCliWithOverrides("/unused", argv, {
+            homeDir: tmpHome,
+            projectRoot: tmpProject,
+            ...(extras.fetch ? { fetch: extras.fetch } : {}),
+            write: (t) => stdout.push(t),
+            writeErr: (t) => stderr.push(t),
+        });
+    }
+    // -------------------------------------------------------------------
+    // Happy paths
+    // -------------------------------------------------------------------
+    it("global-anthropic writes config.yml + .env at ~/.onto/ and passes validation", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+        ], {
+            fetch: stubFetchReturning(200),
+            envOverrides: { ANTHROPIC_API_KEY: "sk-ant-xyz" },
+        });
+        expect(exit).toBe(0);
+        const configYmlPath = path.join(tmpHome, ".onto", "config.yml");
+        expect(fs.existsSync(configYmlPath)).toBe(true);
+        const config = yaml.parse(fs.readFileSync(configYmlPath, "utf8").replace(/^#[^\n]*\n/g, ""));
+        expect(config.output_language).toBe("ko");
+        expect(config.review.subagent.provider).toBe("anthropic");
+        expect(config.subagent_llm.provider).toBe("anthropic");
+        expect(config.external_http_provider).toBe("anthropic");
+        const envPath = path.join(tmpHome, ".onto", ".env");
+        const envText = fs.readFileSync(envPath, "utf8");
+        expect(envText).toContain("ANTHROPIC_API_KEY=sk-ant-xyz");
+        const mode = fs.statSync(envPath).mode & 0o777;
+        if (process.platform !== "win32")
+            expect(mode).toBe(0o600);
+    });
+    it("project scope adds .onto/.env to .gitignore", async () => {
+        await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "project",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--skip-validation",
+        ], { envOverrides: { ANTHROPIC_API_KEY: "sk-ant-xyz" } });
+        const giPath = path.join(tmpProject, ".gitignore");
+        expect(fs.existsSync(giPath)).toBe(true);
+        expect(fs.readFileSync(giPath, "utf8")).toContain(".onto/.env");
+    });
+    it("main-native review + separate learn provider succeeds with Claude Code host", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "main-native",
+            "--learn-provider",
+            "anthropic",
+        ], {
+            fetch: stubFetchReturning(200),
+            envOverrides: { ANTHROPIC_API_KEY: "sk-ant-xyz", CLAUDECODE: "1" },
+        });
+        expect(exit).toBe(0);
+        const config = yaml.parse(fs
+            .readFileSync(path.join(tmpHome, ".onto", "config.yml"), "utf8")
+            .replace(/^#[^\n]*\n/g, ""));
+        expect(config.review.subagent.provider).toBe("main-native");
+        expect(config.subagent_llm.provider).toBe("anthropic");
+    });
+    // -------------------------------------------------------------------
+    // Flag validation
+    // -------------------------------------------------------------------
+    it("errors when required flags are missing in non-interactive mode", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--review-provider",
+            "anthropic",
+            // missing --profile-scope
+        ]);
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("--profile-scope");
+    });
+    it("errors when review=main-native but no explicit --learn-provider", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "main-native",
+            // learn-provider defaults to 'same' which can't be main-native
+        ]);
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("main-native");
+    });
+    it("errors when credentials are missing", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--skip-validation",
+        ]);
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("ANTHROPIC_API_KEY");
+    });
+    // -------------------------------------------------------------------
+    // Reconfigure guard
+    // -------------------------------------------------------------------
+    it("halts when existing config present and --reconfigure absent", async () => {
+        fs.mkdirSync(path.join(tmpHome, ".onto"), { recursive: true });
+        fs.writeFileSync(path.join(tmpHome, ".onto", "config.yml"), "output_language: en\n");
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+        ]);
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("기존 config");
+    });
+    it("proceeds when --reconfigure is set", async () => {
+        fs.mkdirSync(path.join(tmpHome, ".onto"), { recursive: true });
+        fs.writeFileSync(path.join(tmpHome, ".onto", "config.yml"), "output_language: en\n");
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--reconfigure",
+            "--skip-validation",
+        ], { envOverrides: { ANTHROPIC_API_KEY: "sk-ant-xyz" } });
+        expect(exit).toBe(0);
+        const content = fs.readFileSync(path.join(tmpHome, ".onto", "config.yml"), "utf8");
+        expect(content).toContain("output_language: ko");
+    });
+    // -------------------------------------------------------------------
+    // Dry-run
+    // -------------------------------------------------------------------
+    it("--dry-run leaves no files on disk", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--dry-run",
+        ], { envOverrides: { ANTHROPIC_API_KEY: "sk-ant-xyz" } });
+        expect(exit).toBe(0);
+        expect(fs.existsSync(path.join(tmpHome, ".onto", "config.yml"))).toBe(false);
+        expect(stdout.join("")).toContain("미리보기");
+    });
+    // -------------------------------------------------------------------
+    // Validation
+    // -------------------------------------------------------------------
+    it("exits 1 when live validation fails", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+        ], {
+            fetch: stubFetchReturning(401),
+            envOverrides: { ANTHROPIC_API_KEY: "sk-bad" },
+        });
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("provider 검증 실패");
+    });
+    it("--skip-validation bypasses the ping", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--skip-validation",
+        ], { envOverrides: { ANTHROPIC_API_KEY: "sk-bad" } });
+        expect(exit).toBe(0);
+    });
+    // -------------------------------------------------------------------
+    // env-file loading
+    // -------------------------------------------------------------------
+    it("--env-file loads credentials from the specified file", async () => {
+        const envFilePath = path.join(tmpProject, "custom.env");
+        fs.writeFileSync(envFilePath, "ANTHROPIC_API_KEY=sk-from-file\n");
+        const exit = await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--env-file",
+            envFilePath,
+            "--skip-validation",
+        ]);
+        expect(exit).toBe(0);
+        const envText = fs.readFileSync(path.join(tmpHome, ".onto", ".env"), "utf8");
+        expect(envText).toContain("ANTHROPIC_API_KEY=sk-from-file");
+    });
+    it("--env-file errors when path does not exist", async () => {
+        const exit = await runInstall([
+            "--non-interactive",
+            "--env-file",
+            "/no/such/file",
+        ]);
+        expect(exit).toBe(1);
+        expect(stderr.join("")).toContain("--env-file");
+    });
+    // -------------------------------------------------------------------
+    // ONTO_INSTALL_* env fallback
+    // -------------------------------------------------------------------
+    it("reads ONTO_INSTALL_* env vars as flag defaults", async () => {
+        const exit = await runInstall(["--skip-validation"], {
+            envOverrides: {
+                ONTO_INSTALL_NON_INTERACTIVE: "1",
+                ONTO_INSTALL_PROFILE_SCOPE: "global",
+                ONTO_INSTALL_REVIEW_PROVIDER: "anthropic",
+                ONTO_INSTALL_LEARN_PROVIDER: "same",
+                ONTO_INSTALL_OUTPUT_LANGUAGE: "en",
+                ANTHROPIC_API_KEY: "sk-ant-xyz",
+            },
+        });
+        expect(exit).toBe(0);
+        const config = yaml.parse(fs
+            .readFileSync(path.join(tmpHome, ".onto", "config.yml"), "utf8")
+            .replace(/^#[^\n]*\n/g, ""));
+        expect(config.output_language).toBe("en");
+    });
+    it("argv flag wins over ONTO_INSTALL_* env", async () => {
+        await runInstall([
+            "--non-interactive",
+            "--profile-scope",
+            "global",
+            "--review-provider",
+            "anthropic",
+            "--learn-provider",
+            "same",
+            "--output-language",
+            "ko",
+            "--skip-validation",
+        ], {
+            envOverrides: {
+                ONTO_INSTALL_OUTPUT_LANGUAGE: "en",
+                ANTHROPIC_API_KEY: "sk-ant-xyz",
+            },
+        });
+        const config = yaml.parse(fs
+            .readFileSync(path.join(tmpHome, ".onto", "config.yml"), "utf8")
+            .replace(/^#[^\n]*\n/g, ""));
+        expect(config.output_language).toBe("ko");
+    });
+    // -------------------------------------------------------------------
+    // --help
+    // -------------------------------------------------------------------
+    it("--help prints usage and returns 0 without touching disk", async () => {
+        const exit = await runInstall(["--help"]);
+        expect(exit).toBe(0);
+        expect(stdout.join("")).toContain("Usage: onto install");
+        expect(fs.existsSync(path.join(tmpHome, ".onto"))).toBe(false);
+    });
+});