feat(config): expand {env:VAR} and {file:path} tokens in magic-context.jsonc

Users of OpenCode's main config can already reference environment variables
as `{env:OPENAI_API_KEY}` and inline external files with `{file:./key.txt}`.
Magic Context didn't implement the same substitution, so writing
`"api_key": "{env:OPENAI_API_KEY}"` in magic-context.jsonc sent the literal
string to providers and caused silent auth failures — the most visible
symptom was reported in issue #29 with OpenRouter embeddings.

This change adds the same substitution pass, mirroring OpenCode's
`ConfigVariable.substitute` in `packages/opencode/src/config/variable.ts`
so the patterns are consistent across both config files:

- `{env:VAR}` — trimmed key looked up in `process.env`; missing values
  become empty strings and produce a warning (OpenCode throws by default;
  we soften to a warning because magic-context config is less critical).
- `{file:~/abs}`, `{file:./rel}`, `{file:rel}`, `{file:/abs}` —
  contents read, trimmed, and JSON-escaped so embedded quotes/newlines
  survive the outer JSONC parse. Paths resolve against the config file's
  directory; tokens inside `//` line comments pass through verbatim.

Substitution runs on raw text before JSONC parsing, matching OpenCode's
ordering. `loadConfigFile` now returns both the parsed config and any
substitution warnings, prefixed with the config path; warnings are bubbled
up through `loadPluginConfig`'s existing `configWarnings` channel so the
plugin's startup notifier already surfaces them without extra plumbing.

Docs: CONFIGURATION.md now shows `{env:OPENAI_API_KEY}` in the embedding
example and explains the substitution behavior.

Tests: 18 unit tests in `variable.test.ts` covering env present/missing/
trimmed/empty-string, file absolute/relative/home/missing, JSON escaping
of multiline contents, comment passthrough, combined env+file, nested
env-inside-file tokens, and no-token no-op cases. All 33 config tests
pass; full suite remains green.

Author: ualtinok

packages/plugin/src/config/index.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 
 import { detectConfigFile, parseJsonc } from "../shared/jsonc-parser";
 import { type MagicContextConfig, MagicContextConfigSchema } from "./schema/magic-context";
+import { substituteConfigVariables } from "./variable";
 
 export interface MagicContextPluginConfig extends MagicContextConfig {
     disabled_hooks?: string[];
@@ -30,12 +31,27 @@ function getProjectConfigBasePath(directory: string): string {
     return join(directory, ".opencode", CONFIG_FILE_BASENAME);
 }
 
-function loadConfigFile(configPath: string): Record<string, unknown> | null {
+interface LoadedConfigFile {
+    config: Record<string, unknown>;
+    /** Warnings from {env:} / {file:} substitution, with config-path prefix applied. */
+    warnings: string[];
+}
+
+function loadConfigFile(configPath: string): LoadedConfigFile | null {
     try {
         if (!existsSync(configPath)) {
             return null;
         }
-        return parseJsonc<Record<string, unknown>>(readFileSync(configPath, "utf-8"));
+        const rawText = readFileSync(configPath, "utf-8");
+        // Substitute {env:VAR} and {file:path} tokens on the raw text before
+        // parsing so users can reference env vars (API keys) and external files
+        // without leaking secrets into the config file itself. Matches OpenCode's
+        // ConfigVariable.substitute semantics exactly.
+        const substituted = substituteConfigVariables({ text: rawText, configPath });
+        return {
+            config: parseJsonc<Record<string, unknown>>(substituted.text),
+            warnings: substituted.warnings.map((w) => `${configPath}: ${w}`),
+        };
     } catch (error) {
         console.warn(
             `[magic-context] failed to load config from ${configPath}:`,
@@ -163,23 +179,27 @@ export function loadPluginConfig(
     const dotOpenCodeDetected = detectConfigFile(getProjectConfigBasePath(directory));
     const projectDetected = rootDetected.format !== "none" ? rootDetected : dotOpenCodeDetected;
 
-    const userConfig = userDetected.format === "none" ? null : loadConfigFile(userDetected.path);
-    const projectConfig =
+    const userLoaded = userDetected.format === "none" ? null : loadConfigFile(userDetected.path);
+    const projectLoaded =
         projectDetected.format === "none" ? null : loadConfigFile(projectDetected.path);
 
     let config: MagicContextPluginConfig & { configWarnings?: string[] } = parsePluginConfig({});
     const allWarnings: string[] = [];
 
-    if (userConfig) {
-        const parsed = parsePluginConfig(userConfig);
+    if (userLoaded) {
+        // Variable-substitution warnings surface first so users see missing
+        // env vars before any downstream schema-validation warnings.
+        allWarnings.push(...userLoaded.warnings.map((w) => `[user config] ${w}`));
+        const parsed = parsePluginConfig(userLoaded.config);
         if (parsed.configWarnings?.length) {
             allWarnings.push(...parsed.configWarnings.map((w) => `[user config] ${w}`));
         }
         config = mergeConfigs(config, parsed);
     }
 
-    if (projectConfig) {
-        const parsed = parsePluginConfig(projectConfig);
+    if (projectLoaded) {
+        allWarnings.push(...projectLoaded.warnings.map((w) => `[project config] ${w}`));
+        const parsed = parsePluginConfig(projectLoaded.config);
         if (parsed.configWarnings?.length) {
             allWarnings.push(...parsed.configWarnings.map((w) => `[project config] ${w}`));
         }

packages/plugin/src/config/variable.test.ts

@@ -0,0 +1,236 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, sep } from "node:path";
+
+import { substituteConfigVariables } from "./variable";
+
+describe("substituteConfigVariables", () => {
+    const ORIGINAL_ENV = { ...process.env };
+    let tmpDir: string;
+
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "mc-variable-test-"));
+    });
+
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+        process.env = { ...ORIGINAL_ENV };
+    });
+
+    describe("env substitution", () => {
+        it("replaces {env:VAR} with process.env value", () => {
+            process.env.MC_TEST_KEY = "sk-real-value";
+            const input = `{ "api_key": "{env:MC_TEST_KEY}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "sk-real-value" }`);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("trims whitespace inside env token", () => {
+            process.env.MC_TEST_KEY = "trimmed-value";
+            const input = `{ "api_key": "{env: MC_TEST_KEY }" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "trimmed-value" }`);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("emits warning and empty string for missing env var", () => {
+            delete process.env.MC_MISSING_VAR;
+            const input = `{ "api_key": "{env:MC_MISSING_VAR}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "" }`);
+            expect(result.warnings).toHaveLength(1);
+            expect(result.warnings[0]).toContain("MC_MISSING_VAR");
+            expect(result.warnings[0]).toContain("not set");
+        });
+
+        it("emits warning for empty-string env var", () => {
+            process.env.MC_EMPTY = "";
+            const input = `{ "api_key": "{env:MC_EMPTY}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "" }`);
+            expect(result.warnings).toHaveLength(1);
+        });
+
+        it("passes {env:} literally through (matches OpenCode regex: at least one char required)", () => {
+            const input = `{ "api_key": "{env:}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            // The regex `{env:([^}]+)}` requires ≥1 char between the colon and
+            // brace. An empty `{env:}` is not a valid token and passes through
+            // to be parsed as literal JSONC text.
+            expect(result.text).toBe(input);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("handles multiple env tokens in one text", () => {
+            process.env.MC_A = "alpha";
+            process.env.MC_B = "beta";
+            const input = `{ "a": "{env:MC_A}", "b": "{env:MC_B}", "c": "{env:MC_MISSING}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "a": "alpha", "b": "beta", "c": "" }`);
+            expect(result.warnings).toHaveLength(1);
+            expect(result.warnings[0]).toContain("MC_MISSING");
+        });
+    });
+
+    describe("file substitution", () => {
+        it("inlines file contents for absolute path", () => {
+            const keyFile = join(tmpDir, "key.txt");
+            writeFileSync(keyFile, "sk-from-file\n");
+            const input = `{ "api_key": "{file:${keyFile}}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "sk-from-file" }`);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("resolves relative path against configPath directory", () => {
+            const keyFile = join(tmpDir, "key.txt");
+            writeFileSync(keyFile, "relative-value");
+            const configPath = join(tmpDir, "magic-context.jsonc");
+
+            const input = `{ "api_key": "{file:./key.txt}" }`;
+            const result = substituteConfigVariables({ text: input, configPath });
+
+            expect(result.text).toBe(`{ "api_key": "relative-value" }`);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("resolves relative path without leading ./", () => {
+            const keyFile = join(tmpDir, "key.txt");
+            writeFileSync(keyFile, "no-dot-slash");
+            const configPath = join(tmpDir, "magic-context.jsonc");
+
+            const input = `{ "api_key": "{file:key.txt}" }`;
+            const result = substituteConfigVariables({ text: input, configPath });
+
+            expect(result.text).toBe(`{ "api_key": "no-dot-slash" }`);
+        });
+
+        it("expands ~/ to home directory", () => {
+            const input = `{ "marker": "{file:~/__mc-never-exists-${Date.now()}}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            // File doesn't exist, so warning fires — but warning must show it
+            // resolved under homedir, proving the ~ expansion happened.
+            expect(result.warnings).toHaveLength(1);
+            expect(result.warnings[0]).toContain(homedir() + sep);
+        });
+
+        it("JSON-escapes quotes and newlines in file contents", () => {
+            const keyFile = join(tmpDir, "multiline.txt");
+            writeFileSync(keyFile, 'line1 with "quote"\nline2');
+            const input = `{ "value": "{file:${keyFile}}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            // Escaped so the outer JSONC string still parses cleanly.
+            expect(result.text).toBe(`{ "value": "line1 with \\"quote\\"\\nline2" }`);
+            const parsed = JSON.parse(result.text);
+            expect(parsed.value).toBe('line1 with "quote"\nline2');
+        });
+
+        it("emits warning and empty string for missing file", () => {
+            const missing = join(tmpDir, "never-exists.txt");
+            const input = `{ "api_key": "{file:${missing}}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "" }`);
+            expect(result.warnings).toHaveLength(1);
+            expect(result.warnings[0]).toContain("not found");
+            expect(result.warnings[0]).toContain(missing);
+        });
+
+        it("passes {file:} literally through (matches OpenCode regex: at least one char required)", () => {
+            const input = `{ "api_key": "{file:}" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            // Same reasoning as {env:} — empty token pattern doesn't match.
+            expect(result.text).toBe(input);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("preserves {file:} tokens inside // line comments", () => {
+            const keyFile = join(tmpDir, "key.txt");
+            writeFileSync(keyFile, "should-not-appear");
+            const input = [
+                `{`,
+                `    // see docs: {file:${keyFile}}`,
+                `    "other": "value"`,
+                `}`,
+            ].join("\n");
+
+            const result = substituteConfigVariables({ text: input });
+
+            // Token inside comment stays literal — only active values substitute.
+            expect(result.text).toContain(`// see docs: {file:${keyFile}}`);
+            expect(result.text).not.toContain("should-not-appear");
+            expect(result.warnings).toHaveLength(0);
+        });
+    });
+
+    describe("combined substitution", () => {
+        it("handles env and file tokens together", () => {
+            process.env.MC_COMBINED = "env-val";
+            const keyFile = join(tmpDir, "combined.txt");
+            writeFileSync(keyFile, "file-val");
+
+            const input = `{ "e": "{env:MC_COMBINED}", "f": "{file:${keyFile}}" }`;
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "e": "env-val", "f": "file-val" }`);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("env tokens inside {file:} path expand before file read", () => {
+            // Tokens are substituted left-to-right in passes: env first, then
+            // file. So an env var naming a file path gets resolved during file
+            // substitution.
+            process.env.MC_FILE_DIR = tmpDir;
+            const keyFile = join(tmpDir, "indirect.txt");
+            writeFileSync(keyFile, "indirect-value");
+
+            const input = `{ "api_key": "{file:{env:MC_FILE_DIR}/indirect.txt}" }`;
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(`{ "api_key": "indirect-value" }`);
+        });
+    });
+
+    describe("no-op cases", () => {
+        it("returns text unchanged when no tokens present", () => {
+            const input = `{ "api_key": "literal-value", "provider": "openai-compatible" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(input);
+            expect(result.warnings).toHaveLength(0);
+        });
+
+        it("leaves partial patterns like {env alone", () => {
+            const input = `{ "note": "this {env is not a token" }`;
+
+            const result = substituteConfigVariables({ text: input });
+
+            expect(result.text).toBe(input);
+            expect(result.warnings).toHaveLength(0);
+        });
+    });
+});