opencode-dotenv 0.4.1 → 0.5.1

package/README.md

@@ -2,16 +2,36 @@
 
 OpenCode plugin to load `.env` files at startup.
 
-## Features
+> **Important Limitation**
+> 
+> This plugin **cannot** set environment variables for use in OpenCode's config file (`opencode.jsonc`). The plugin loads *after* OpenCode parses its configuration, so `{env:VARNAME}` references in config are resolved before this plugin runs.
+> 
+> **Use this plugin for:** Managing environment variables available during chat sessions, tool executions, and bash commands.
+> 
+> **Do not use this plugin for:** Setting API keys or other config values referenced via `{env:VAR}` syntax in `opencode.jsonc`. For those, set variables in your shell profile (`~/.zshrc`, `~/.bashrc`) before starting OpenCode.
+> 
+> See [Architecture](docs/ARCHITECTURE.md) for details on the OpenCode startup sequence.
 
+## Features
+ 
 - Load multiple `.env` files in order via config file
 - Load `.env` from current working directory (optional)
 - Override existing environment variables (later files override earlier ones)
-- Configurable logging to `/tmp/opencode-dotenv.log` (enabled by default)
+- Configurable logging to `~/.local/share/opencode/dotenv.log` (disabled by default)
 - Prevents double loading with load guard
 - JSONC config file format (supports comments and trailing commas)
 - **Requires Bun runtime**
 
+## Limitations
+
+1. **Cannot modify existing OpenCode config** - Variables loaded by this plugin cannot be referenced in `opencode.jsonc` using `{env:VAR}` syntax. OpenCode reads its config before plugins initialize.
+
+2. **Only affects subsequent operations** - Loaded environment variables are only available to new chat sessions, tool calls, and operations that occur AFTER plugin initialization.
+
+3. **No config reload capability** - Changing `.env` files while OpenCode is running will NOT trigger config re-parsing. To apply changes, restart OpenCode.
+  
+**Recommended approach:** Set environment variables in your shell profile (`.zshrc`, `.bashrc`) before starting OpenCode.
+ 
 ## Installation
 
 Add to your `opencode.jsonc`:
@@ -33,12 +53,12 @@ After publishing to npm, you can use:
 
 ## Configuration
 
-Create `opencode-dotenv.jsonc` in one of these locations:
+Create `dotenv.jsonc` in one of these locations (searched in order, first found wins):
 
-1. `~/.config/opencode/opencode-dotenv.jsonc` (recommended, global config)
-2. `./opencode-dotenv.jsonc` in current working directory (project-specific)
+1. `./dotenv.jsonc` in current working directory (project-specific)
+2. `~/.config/opencode/dotenv.jsonc` (global config)
 
-**Note:** Config files are loaded in the order above; the first found file is used.
+**Note:** Only the first found config file is used; configs are not merged.
 
 ### Config Schema
 
@@ -56,7 +76,7 @@ Config file uses **JSONC format** (JSON with Comments), which supports:
   ],
   "load_cwd_env": true,
   "logging": {
-    "enabled": true
+    "enabled": false
   }
 }
 ```
@@ -64,13 +84,13 @@ Config file uses **JSONC format** (JSON with Comments), which supports:
 **Fields:**
 - `files` (array, optional): List of `.env` file paths to load in order. Later files override earlier ones.
 - `load_cwd_env` (boolean, optional): Whether to load `.env` from the directory where OpenCode is opened. Defaults to `true`.
-- `logging.enabled` (boolean, optional): Enable/disable logging to `/tmp/opencode-dotenv.log`. Defaults to `true`.
+- `logging.enabled` (boolean, optional): Enable/disable logging to `~/.local/share/opencode/dotenv.log`. Defaults to `false`.
 
 **Notes:**
 - Use `~` for home directory (automatically expanded)
 - Paths are expanded before loading
 - If no config file exists, only loads `./.env` from cwd (if present)
-- Logging writes to `/tmp/opencode-dotenv.log` for debugging
+- Logging writes to `~/.local/share/opencode/dotenv.log` for debugging
 
 ### Load Order
 
@@ -83,7 +103,7 @@ This ensures project-specific env vars have the highest precedence.
 
 ### Load global and project-specific .env files
 
-Config (`~/.config/opencode/opencode-dotenv.jsonc`):
+Config (`~/.config/opencode/dotenv.jsonc`):
 
 ```jsonc
 {
@@ -100,11 +120,11 @@ Config (`~/.config/opencode/opencode-dotenv.jsonc`):
 Result:
 1. Loads `~/.config/opencode/.env`
 2. Loads `./.env` from cwd (overrides any conflicts)
-3. Logs all activity to `/tmp/opencode-dotenv.log`
+3. Logs all activity to `~/.local/share/opencode/dotenv.log`
 
 ### Load multiple global files without cwd .env
 
-Config (`~/.config/opencode/opencode-dotenv.jsonc`):
+Config (`~/.config/opencode/dotenv.jsonc`):
 
 ```jsonc
 {
@@ -126,41 +146,42 @@ Result:
 4. No logging output
 
 ### Example .env files
-
+ 
 `~/.config/opencode/.env`:
-
+ 
 ```bash
 # OpenCode Dotenv Configuration
-OPENCODE_API_KEY=your_api_key_here
 OPENCODE_DEBUG=true
 OPENCODE_MAX_TOKENS=100000
+MY_PROJECT_KEY=secret123
 ```
 
-`./.env` (project-specific):
+**Note:** This plugin cannot inject variables into OpenCode's configuration loading process. To set `ANTHROPIC_API_KEY` or other provider API keys, set them in your shell profile (`~/.zshrc`, `~/.bashrc`) before starting OpenCode.
 
+`./.env` (project-specific):
 ```bash
 # Project-specific overrides
 OPENCODE_DEBUG=false
 PROJECT_API_KEY=project_specific_key
 ```
 
-Result: `OPENCODE_DEBUG` will be `false` (from cwd), `OPENCODE_API_KEY` from global, `PROJECT_API_KEY` from cwd.
+Result: `OPENCODE_DEBUG` will be `false` (from cwd), `MY_PROJECT_KEY` from global, `PROJECT_API_KEY` from cwd.
 
 ### Logging
 
 View plugin activity logs:
 
 ```bash
-tail -f /tmp/opencode-dotenv.log
+tail -f ~/.local/share/opencode/dotenv.log
 ```
 
-Disable logging in config:
+Enable logging in config:
 
 ```jsonc
 {
   "files": ["~/.config/opencode/.env"],
   "logging": {
-    "enabled": false
+    "enabled": true
   }
 }
 ```
@@ -173,7 +194,10 @@ Disable logging in config:
 opencode-dotenv/
 ├── package.json
 ├── src/
-│   └── index.ts
+│   ├── index.ts
+│   └── plugin.ts
+├── docs/
+│   └── ARCHITECTURE.md
 └── dist/
     └── index.js  (built)
 ```

package/dist/index.js

@@ -1,6 +1,7 @@
 // @bun
-// src/index.ts
+// src/plugin.ts
 import { homedir } from "os";
+import { appendFile, mkdir } from "fs/promises";
 
 // node_modules/jsonc-parser/lib/esm/impl/scanner.js
 function createScanner(text, ignoreTrivia = false) {
@@ -806,9 +807,165 @@ var ParseErrorCode;
   ParseErrorCode2[ParseErrorCode2["InvalidCharacter"] = 16] = "InvalidCharacter";
 })(ParseErrorCode || (ParseErrorCode = {}));
 
-// src/index.ts
-var LOG_FILE = "/tmp/opencode-dotenv.log";
+// src/profiler/profiler.ts
+function percentile(sorted, p) {
+  if (sorted.length === 0)
+    return 0;
+  const index = Math.ceil(p / 100 * sorted.length) - 1;
+  return sorted[Math.max(0, index)];
+}
+function calculateStats(measurements) {
+  if (measurements.length === 0)
+    return null;
+  const sorted = [...measurements].sort((a, b) => a - b);
+  const total = sorted.reduce((sum, v) => sum + v, 0);
+  return {
+    count: sorted.length,
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    avg: total / sorted.length,
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    p99: percentile(sorted, 99),
+    total
+  };
+}
+
+class Profiler {
+  marks = new Map;
+  measures = new Map;
+  fileMetrics = [];
+  initStartTime = null;
+  initEndTime = null;
+  initState = "idle";
+  configLoadTime = null;
+  configPath = null;
+  totalVars = 0;
+  startTime = performance.now();
+  mark(name) {
+    this.marks.set(name, performance.now());
+  }
+  measure(name, startMark) {
+    const start = this.marks.get(startMark);
+    if (start === undefined) {
+      return -1;
+    }
+    const duration = performance.now() - start;
+    const existing = this.measures.get(name) || [];
+    existing.push(duration);
+    this.measures.set(name, existing);
+    return duration;
+  }
+  record(name, duration) {
+    const existing = this.measures.get(name) || [];
+    existing.push(duration);
+    this.measures.set(name, existing);
+  }
+  getStats(name) {
+    const measurements = this.measures.get(name);
+    if (!measurements)
+      return null;
+    return calculateStats(measurements);
+  }
+  initStart() {
+    this.initStartTime = performance.now();
+    this.initState = "loading";
+  }
+  initComplete(state) {
+    this.initEndTime = performance.now();
+    this.initState = state;
+  }
+  recordConfigLoad(duration, path) {
+    this.configLoadTime = duration;
+    this.configPath = path;
+  }
+  recordFileLoad(path, duration, varCount, success, error) {
+    this.fileMetrics.push({
+      path,
+      duration,
+      varCount,
+      success,
+      error
+    });
+    if (success) {
+      this.totalVars += varCount;
+      this.record("file.load", duration);
+    }
+  }
+  getInitState() {
+    return this.initState;
+  }
+  getInitDuration() {
+    if (this.initStartTime === null)
+      return null;
+    if (this.initEndTime !== null) {
+      return this.initEndTime - this.initStartTime;
+    }
+    return performance.now() - this.initStartTime;
+  }
+  getTotalVars() {
+    return this.totalVars;
+  }
+  getFileMetrics() {
+    return [...this.fileMetrics];
+  }
+  export() {
+    return {
+      timestamp: new Date().toISOString(),
+      uptime: performance.now() - this.startTime,
+      initialization: {
+        startTime: this.initStartTime || 0,
+        endTime: this.initEndTime,
+        duration: this.getInitDuration(),
+        state: this.initState
+      },
+      config: {
+        loadTime: this.configLoadTime,
+        path: this.configPath
+      },
+      files: {
+        loadTimes: this.getStats("file.load"),
+        details: this.fileMetrics,
+        totalVars: this.totalVars
+      }
+    };
+  }
+  reset() {
+    this.marks.clear();
+    this.measures.clear();
+    this.fileMetrics = [];
+    this.initStartTime = null;
+    this.initEndTime = null;
+    this.initState = "idle";
+    this.configLoadTime = null;
+    this.configPath = null;
+    this.totalVars = 0;
+  }
+  startTimer(name) {
+    const start = performance.now();
+    return () => {
+      const duration = performance.now() - start;
+      this.record(name, duration);
+      return duration;
+    };
+  }
+}
+var globalProfiler = new Profiler;
+// src/plugin.ts
+var CONFIG_NAME = "dotenv.jsonc";
+var LOG_DIR = `${homedir()}/.local/share/opencode`;
+var LOG_FILE = `${LOG_DIR}/dotenv.log`;
 var LOAD_GUARD = "__opencodeDotenvLoaded";
+var isTestEnv = !!process.env.BUN_TEST;
+var loggingEnabled = false;
+function log(message) {
+  if (!loggingEnabled || isTestEnv)
+    return;
+  const timestamp = new Date().toISOString();
+  const line = `[${timestamp}] ${message}
+`;
+  mkdir(LOG_DIR, { recursive: true }).then(() => appendFile(LOG_FILE, line)).catch(() => {});
+}
 function parseDotenv(content) {
   const result = {};
   if (typeof content !== "string")
@@ -820,114 +977,112 @@ function parseDotenv(content) {
       continue;
     const match = trimmed.match(/^export\s+([^=]+)=(.*)$/);
     const key = match ? match[1] : trimmed.split("=")[0];
-    let value = match ? match[2] : trimmed.substring(key.length + 1);
-    if (key) {
-      let parsedValue = value.trim();
-      if (!parsedValue.startsWith('"') && !parsedValue.startsWith("'")) {
-        const inlineCommentIndex = parsedValue.indexOf(" #");
-        if (inlineCommentIndex !== -1) {
-          parsedValue = parsedValue.substring(0, inlineCommentIndex).trim();
-        }
-      }
-      if (parsedValue.startsWith('"') && parsedValue.endsWith('"') || parsedValue.startsWith("'") && parsedValue.endsWith("'")) {
-        parsedValue = parsedValue.slice(1, -1);
+    if (!key)
+      continue;
+    const value = match ? match[2] : trimmed.substring(key.length + 1);
+    if (value === undefined)
+      continue;
+    let parsedValue = value.trim();
+    if (!parsedValue.startsWith('"') && !parsedValue.startsWith("'")) {
+      const inlineCommentIndex = parsedValue.indexOf(" #");
+      if (inlineCommentIndex !== -1) {
+        parsedValue = parsedValue.substring(0, inlineCommentIndex).trim();
       }
-      result[key.trim()] = parsedValue;
     }
+    if (parsedValue.startsWith('"') && parsedValue.endsWith('"') || parsedValue.startsWith("'") && parsedValue.endsWith("'")) {
+      parsedValue = parsedValue.slice(1, -1);
+    }
+    result[key.trim()] = parsedValue;
   }
   return result;
 }
 function expandPath(path) {
   return path.replace(/^~/, homedir());
 }
-var loggingEnabled = true;
-function logToFile(message) {
-  if (!loggingEnabled)
-    return;
-  try {
-    const timestamp = new Date().toISOString();
-    Bun.appendFileSync(LOG_FILE, `[${timestamp}] ${message}
-`);
-  } catch (e) {}
-}
 async function loadConfig() {
+  const timer = globalProfiler.startTimer("config.load");
   const configPaths = [
-    `${homedir()}/.config/opencode/opencode-dotenv.jsonc`,
-    `${process.cwd()}/opencode-dotenv.jsonc`
+    `${process.cwd()}/${CONFIG_NAME}`,
+    `${homedir()}/.config/opencode/${CONFIG_NAME}`
   ];
   for (const configPath of configPaths) {
     try {
       const file = Bun.file(configPath);
-      if (!await file.exists())
-        continue;
       const content = await file.text();
-      const config = parse2(content, [], { allowTrailingComma: true });
-      loggingEnabled = config.logging?.enabled !== false;
-      return config;
-    } catch (e) {
-      logToFile(`Failed to load config: ${e}`);
-    }
+      if (!content || typeof content !== "string") {
+        continue;
+      }
+      const config = parse2(content, [], {
+        allowTrailingComma: true
+      });
+      if (config && typeof config === "object" && Array.isArray(config.files)) {
+        loggingEnabled = config.logging?.enabled === true;
+        const duration = timer();
+        globalProfiler.recordConfigLoad(duration, configPath);
+        return { config, path: configPath };
+      }
+    } catch {}
   }
-  return { files: [], load_cwd_env: true };
+  timer();
+  return { config: { files: [], load_cwd_env: true }, path: null };
 }
 async function loadDotenvFile(filePath) {
+  const start = performance.now();
   try {
     const file = Bun.file(filePath);
-    if (!await file.exists()) {
-      logToFile(`File not found: ${filePath}`);
-      return { count: 0, success: false };
-    }
     const content = await file.text();
-    if (typeof content !== "string") {
-      logToFile(`Invalid content type from ${filePath}: ${typeof content}`);
+    if (typeof content !== "string" || !content) {
+      const duration2 = performance.now() - start;
+      globalProfiler.recordFileLoad(filePath, duration2, 0, false, "Empty or invalid content");
+      log(`Invalid or empty content from ${filePath}`);
       return { count: 0, success: false };
     }
     const envVars = parseDotenv(content);
+    const count = Object.keys(envVars).length;
     for (const [key, value] of Object.entries(envVars)) {
       process.env[key] = value;
     }
-    return { count: Object.keys(envVars).length, success: true };
+    const duration = performance.now() - start;
+    globalProfiler.recordFileLoad(filePath, duration, count, true);
+    return { count, success: true };
   } catch (error) {
-    logToFile(`Failed to load ${filePath}: ${error}`);
+    const duration = performance.now() - start;
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    globalProfiler.recordFileLoad(filePath, duration, 0, false, errorMsg);
+    log(`Failed to load ${filePath}: ${errorMsg}`);
     return { count: 0, success: false };
   }
 }
-var DotEnvPlugin = async (ctx) => {
+var DotEnvPlugin = async (_ctx) => {
   if (globalThis[LOAD_GUARD]) {
     return {};
   }
   globalThis[LOAD_GUARD] = true;
-  logToFile("Plugin started");
-  const config = await loadConfig();
-  logToFile(`Config loaded: ${config.files.length} files, load_cwd_env=${config.load_cwd_env}, logging=${loggingEnabled}`);
+  globalProfiler.initStart();
+  log("Plugin started");
+  const { config, path: configPath } = await loadConfig();
+  log(`Config loaded from ${configPath || "default"}: ${config.files.length} files, load_cwd_env=${config.load_cwd_env}, logging=${loggingEnabled}`);
+  const filesToLoad = [...config.files.map(expandPath)];
+  if (config.load_cwd_env !== false) {
+    filesToLoad.push(`${process.cwd()}/.env`);
+  }
   let totalFiles = 0;
   let totalVars = 0;
-  for (const rawPath of config.files) {
-    const filePath = expandPath(rawPath);
-    logToFile(`Loading: ${filePath}`);
+  for (const filePath of filesToLoad) {
+    log(`Loading: ${filePath}`);
     const result = await loadDotenvFile(filePath);
     if (result.success) {
       totalFiles++;
       totalVars += result.count;
-      logToFile(`Loaded ${result.count} vars`);
-    }
-  }
-  if (config.load_cwd_env !== false) {
-    const cwdEnvPath = `${process.cwd()}/.env`;
-    logToFile(`Loading cwd: ${cwdEnvPath}`);
-    const result = await loadDotenvFile(cwdEnvPath);
-    if (result.success) {
-      totalFiles++;
-      totalVars += result.count;
-      logToFile(`Loaded ${result.count} vars from cwd`);
+      log(`Loaded ${result.count} vars from ${filePath}`);
     }
   }
-  logToFile(`Plugin finished: ${totalFiles} files, ${totalVars} vars`);
+  globalProfiler.initComplete("ready");
+  const initDuration = globalProfiler.getInitDuration();
+  log(`Plugin finished: ${totalFiles} files, ${totalVars} vars in ${initDuration?.toFixed(2)}ms`);
   return {};
 };
-var src_default = DotEnvPlugin;
 export {
-  parseDotenv,
-  src_default as default,
+  DotEnvPlugin as default,
   DotEnvPlugin
 };

package/package.json

@@ -1,24 +1,46 @@
 {
   "name": "opencode-dotenv",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "OpenCode plugin to load .env files at startup",
-  "main": "./dist/index.js",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
   "type": "module",
-  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target bun",
+    "dev": "bun --hot src/index.ts",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "bench": "bun run bench/init.bench.ts",
     "prepublishOnly": "bun run build"
   },
   "files": [
-    "dist/",
+    "dist",
     "README.md",
     "LICENSE"
   ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "dotenv",
+    "env",
+    "environment"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
   "peerDependencies": {
     "@opencode-ai/plugin": "*"
   },
   "dependencies": {
     "jsonc-parser": "^3.3.1"
-  },
-  "devDependencies": {}
+  }
 }