@enactprotocol/secrets 2.0.0

package/src/env/manager.ts

@@ -0,0 +1,251 @@
+/**
+ * Unified environment variable manager
+ *
+ * Provides high-level functions for managing environment variables
+ * with priority resolution: local → global → default
+ */
+
+import type { EnvResolution, EnvironmentVariable } from "../types";
+import {
+  getGlobalEnvPath,
+  getLocalEnvPath,
+  globalEnvExists,
+  loadGlobalEnv,
+  loadLocalEnv,
+  localEnvExists,
+} from "./reader";
+import { deleteGlobalEnvVar, deleteLocalEnvVar, setGlobalEnvVar, setLocalEnvVar } from "./writer";
+
+/**
+ * Set an environment variable
+ *
+ * @param key - Variable key
+ * @param value - Variable value
+ * @param scope - Where to set: 'local' or 'global' (default: 'global')
+ * @param cwd - Current working directory for local scope
+ */
+export function setEnv(
+  key: string,
+  value: string,
+  scope: "local" | "global" = "global",
+  cwd?: string
+): void {
+  if (scope === "local") {
+    setLocalEnvVar(key, value, cwd);
+  } else {
+    setGlobalEnvVar(key, value);
+  }
+}
+
+/**
+ * Get an environment variable with priority resolution
+ *
+ * Priority: local → global → default
+ *
+ * @param key - Variable key
+ * @param defaultValue - Default value if not found
+ * @param cwd - Current working directory for local scope
+ * @returns Resolution result with value and source
+ */
+export function getEnv(key: string, defaultValue?: string, cwd?: string): EnvResolution | null {
+  // Check local first
+  const localVars = loadLocalEnv(cwd);
+  const localValue = localVars[key];
+  if (localValue !== undefined) {
+    return {
+      key,
+      value: localValue,
+      source: "local",
+      filePath: getLocalEnvPath(cwd),
+    };
+  }
+
+  // Check global
+  const globalVars = loadGlobalEnv();
+  const globalValue = globalVars[key];
+  if (globalValue !== undefined) {
+    return {
+      key,
+      value: globalValue,
+      source: "global",
+      filePath: getGlobalEnvPath(),
+    };
+  }
+
+  // Use default
+  if (defaultValue !== undefined) {
+    return {
+      key,
+      value: defaultValue,
+      source: "default",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get just the value of an environment variable
+ *
+ * @param key - Variable key
+ * @param defaultValue - Default value if not found
+ * @param cwd - Current working directory for local scope
+ * @returns The value, or default/undefined if not found
+ */
+export function getEnvValue(key: string, defaultValue?: string, cwd?: string): string | undefined {
+  const result = getEnv(key, defaultValue, cwd);
+  return result?.value;
+}
+
+/**
+ * Delete an environment variable
+ *
+ * @param key - Variable key
+ * @param scope - Where to delete from: 'local' or 'global' (default: 'global')
+ * @param cwd - Current working directory for local scope
+ * @returns true if variable existed and was deleted
+ */
+export function deleteEnv(
+  key: string,
+  scope: "local" | "global" = "global",
+  cwd?: string
+): boolean {
+  if (scope === "local") {
+    return deleteLocalEnvVar(key, cwd);
+  }
+  return deleteGlobalEnvVar(key);
+}
+
+/**
+ * List all environment variables from a scope
+ *
+ * @param scope - Which scope to list: 'local', 'global', or 'all'
+ * @param cwd - Current working directory for local scope
+ * @returns Array of environment variables with sources
+ */
+export function listEnv(
+  scope: "local" | "global" | "all" = "all",
+  cwd?: string
+): EnvironmentVariable[] {
+  const results: EnvironmentVariable[] = [];
+
+  if (scope === "global" || scope === "all") {
+    const globalVars = loadGlobalEnv();
+    for (const [key, value] of Object.entries(globalVars)) {
+      results.push({ key, value, source: "global" });
+    }
+  }
+
+  if (scope === "local" || scope === "all") {
+    const localVars = loadLocalEnv(cwd);
+    for (const [key, value] of Object.entries(localVars)) {
+      // If 'all' scope, we might already have the key from global
+      // In that case, replace with local (higher priority)
+      if (scope === "all") {
+        const existingIndex = results.findIndex((v) => v.key === key);
+        if (existingIndex !== -1) {
+          results[existingIndex] = { key, value, source: "local" };
+        } else {
+          results.push({ key, value, source: "local" });
+        }
+      } else {
+        results.push({ key, value, source: "local" });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get all environment variables with priority resolution
+ * Returns the effective value for each key (local overrides global)
+ *
+ * @param defaults - Default values for keys
+ * @param cwd - Current working directory for local scope
+ * @returns Map of key to resolution result
+ */
+export function resolveAllEnv(
+  defaults: Record<string, string> = {},
+  cwd?: string
+): Map<string, EnvResolution> {
+  const results = new Map<string, EnvResolution>();
+
+  // Start with defaults
+  for (const [key, value] of Object.entries(defaults)) {
+    results.set(key, { key, value, source: "default" });
+  }
+
+  // Add global (overrides defaults)
+  const globalVars = loadGlobalEnv();
+  for (const [key, value] of Object.entries(globalVars)) {
+    results.set(key, {
+      key,
+      value,
+      source: "global",
+      filePath: getGlobalEnvPath(),
+    });
+  }
+
+  // Add local (overrides global and defaults)
+  const localVars = loadLocalEnv(cwd);
+  for (const [key, value] of Object.entries(localVars)) {
+    results.set(key, {
+      key,
+      value,
+      source: "local",
+      filePath: getLocalEnvPath(cwd),
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Resolve environment variables for a tool manifest
+ * Checks that all required vars are present
+ *
+ * @param envDeclarations - Env declarations from manifest
+ * @param cwd - Current working directory
+ * @returns Object with resolved vars and any missing required vars
+ */
+export function resolveToolEnv(
+  envDeclarations: Record<string, { description?: string; default?: string; secret?: boolean }>,
+  cwd?: string
+): {
+  resolved: Map<string, EnvResolution>;
+  missing: string[];
+} {
+  const resolved = new Map<string, EnvResolution>();
+  const missing: string[] = [];
+
+  for (const [key, declaration] of Object.entries(envDeclarations)) {
+    // Skip secrets - they're handled by the keyring
+    if (declaration.secret) {
+      continue;
+    }
+
+    const result = getEnv(key, declaration.default, cwd);
+    if (result) {
+      resolved.set(key, result);
+    } else {
+      missing.push(key);
+    }
+  }
+
+  return { resolved, missing };
+}
+
+/**
+ * Check if local .env exists
+ */
+export function hasLocalEnv(cwd?: string): boolean {
+  return localEnvExists(cwd);
+}
+
+/**
+ * Check if global .env exists
+ */
+export function hasGlobalEnv(): boolean {
+  return globalEnvExists();
+}

package/src/env/parser.ts

@@ -0,0 +1,240 @@
+/**
+ * .env file parser
+ *
+ * Parses KEY=VALUE format with support for:
+ * - Comments (lines starting with #)
+ * - Empty lines
+ * - Quoted values (single and double quotes)
+ * - Inline comments
+ * - Values with = signs
+ */
+
+import type { EnvFileLine, ParsedEnvFile } from "../types";
+
+/**
+ * Parse a single line from an .env file
+ */
+function parseLine(line: string): EnvFileLine {
+  const trimmed = line.trim();
+
+  // Empty line
+  if (trimmed === "") {
+    return { type: "empty", raw: line };
+  }
+
+  // Comment line
+  if (trimmed.startsWith("#")) {
+    return { type: "comment", raw: line };
+  }
+
+  // Variable line - find the first =
+  const eqIndex = trimmed.indexOf("=");
+  if (eqIndex === -1) {
+    // No = sign, treat as comment (invalid line)
+    return { type: "comment", raw: line };
+  }
+
+  const key = trimmed.slice(0, eqIndex).trim();
+  let value = trimmed.slice(eqIndex + 1);
+
+  // Handle inline comments (but not inside quotes)
+  value = parseValue(value);
+
+  return {
+    type: "variable",
+    raw: line,
+    key,
+    value,
+  };
+}
+
+/**
+ * Parse a value, handling quotes and inline comments
+ */
+function parseValue(rawValue: string): string {
+  let value = rawValue.trim();
+
+  // Handle quoted values
+  if (value.length > 1) {
+    const firstChar = value[0];
+    if (firstChar === '"' || firstChar === "'") {
+      const quote = firstChar;
+      // Find the end quote, accounting for escaped quotes
+      let endQuote = -1;
+      for (let i = 1; i < value.length; i++) {
+        if (value[i] === quote && value[i - 1] !== "\\") {
+          endQuote = i;
+          break;
+        }
+      }
+
+      if (endQuote !== -1) {
+        // Extract value between quotes
+        value = value.slice(1, endQuote);
+        // Handle escape sequences in double-quoted strings
+        if (quote === '"') {
+          value = value
+            .replace(/\\n/g, "\n")
+            .replace(/\\r/g, "\r")
+            .replace(/\\t/g, "\t")
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, "\\");
+        }
+        return value;
+      }
+    }
+  }
+
+  // Handle inline comments for unquoted values
+  const commentIndex = value.indexOf(" #");
+  if (commentIndex !== -1) {
+    value = value.slice(0, commentIndex).trim();
+  }
+
+  return value;
+}
+
+/**
+ * Parse .env file content
+ *
+ * @param content - The file content to parse
+ * @returns Parsed env file with vars and preserved lines
+ */
+export function parseEnvFile(content: string): ParsedEnvFile {
+  const lines = content.split("\n");
+  const parsedLines: EnvFileLine[] = [];
+  const vars: Record<string, string> = {};
+
+  for (const line of lines) {
+    const parsed = parseLine(line);
+    parsedLines.push(parsed);
+
+    if (parsed.type === "variable" && parsed.key && parsed.value !== undefined) {
+      vars[parsed.key] = parsed.value;
+    }
+  }
+
+  return {
+    vars,
+    lines: parsedLines,
+  };
+}
+
+/**
+ * Parse .env file content to simple key-value object
+ *
+ * @param content - The file content to parse
+ * @returns Object with key-value pairs
+ */
+export function parseEnvContent(content: string): Record<string, string> {
+  return parseEnvFile(content).vars;
+}
+
+/**
+ * Serialize an env file back to string format
+ * Preserves comments and formatting
+ *
+ * @param parsed - The parsed env file
+ * @returns String content for .env file
+ */
+export function serializeEnvFile(parsed: ParsedEnvFile): string {
+  return parsed.lines
+    .map((line) => {
+      if (line.type === "variable" && line.key) {
+        const value = parsed.vars[line.key] ?? line.value ?? "";
+        // Quote values with spaces or special characters
+        if (value.includes(" ") || value.includes("=") || value.includes("#")) {
+          return `${line.key}="${value.replace(/"/g, '\\"')}"`;
+        }
+        return `${line.key}=${value}`;
+      }
+      return line.raw;
+    })
+    .join("\n");
+}
+
+/**
+ * Create a new env file content from a vars object
+ *
+ * @param vars - Key-value pairs to serialize
+ * @returns String content for .env file
+ */
+export function createEnvContent(vars: Record<string, string>): string {
+  const lines: string[] = [];
+
+  for (const [key, value] of Object.entries(vars)) {
+    // Quote values with spaces or special characters
+    if (value.includes(" ") || value.includes("=") || value.includes("#")) {
+      lines.push(`${key}="${value.replace(/"/g, '\\"')}"`);
+    } else {
+      lines.push(`${key}=${value}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Update a single variable in parsed env file
+ *
+ * @param parsed - The parsed env file
+ * @param key - The variable key
+ * @param value - The new value
+ * @returns Updated parsed env file
+ */
+export function updateEnvVar(parsed: ParsedEnvFile, key: string, value: string): ParsedEnvFile {
+  // Update the vars
+  const newVars = { ...parsed.vars, [key]: value };
+
+  // Check if key exists in lines
+  const existingIndex = parsed.lines.findIndex(
+    (line) => line.type === "variable" && line.key === key
+  );
+
+  let newLines: EnvFileLine[];
+  if (existingIndex !== -1) {
+    // Update existing line
+    newLines = [...parsed.lines];
+    newLines[existingIndex] = {
+      type: "variable",
+      raw: `${key}=${value}`,
+      key,
+      value,
+    };
+  } else {
+    // Add new line at end
+    newLines = [
+      ...parsed.lines,
+      {
+        type: "variable",
+        raw: `${key}=${value}`,
+        key,
+        value,
+      },
+    ];
+  }
+
+  return {
+    vars: newVars,
+    lines: newLines,
+  };
+}
+
+/**
+ * Remove a variable from parsed env file
+ *
+ * @param parsed - The parsed env file
+ * @param key - The variable key to remove
+ * @returns Updated parsed env file
+ */
+export function removeEnvVar(parsed: ParsedEnvFile, key: string): ParsedEnvFile {
+  const newVars = { ...parsed.vars };
+  delete newVars[key];
+
+  const newLines = parsed.lines.filter((line) => !(line.type === "variable" && line.key === key));
+
+  return {
+    vars: newVars,
+    lines: newLines,
+  };
+}

package/src/env/reader.ts

@@ -0,0 +1,105 @@
+/**
+ * .env file reader
+ *
+ * Reads .env files from global (~/.enact/.env) and local (.enact/.env) locations
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ParsedEnvFile } from "../types";
+import { parseEnvContent, parseEnvFile } from "./parser";
+
+/**
+ * Get the path to the global .env file
+ */
+export function getGlobalEnvPath(): string {
+  return join(homedir(), ".enact", ".env");
+}
+
+/**
+ * Get the path to the local (project) .env file
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ */
+export function getLocalEnvPath(cwd?: string): string {
+  return join(cwd ?? process.cwd(), ".enact", ".env");
+}
+
+/**
+ * Read and parse an .env file
+ *
+ * @param path - Path to the .env file
+ * @returns Parsed env file, or empty if file doesn't exist
+ */
+export function readEnvFile(path: string): ParsedEnvFile {
+  if (!existsSync(path)) {
+    return { vars: {}, lines: [] };
+  }
+
+  const content = readFileSync(path, "utf-8");
+  return parseEnvFile(content);
+}
+
+/**
+ * Read .env file to simple key-value object
+ *
+ * @param path - Path to the .env file
+ * @returns Object with key-value pairs, empty object if file doesn't exist
+ */
+export function readEnvVars(path: string): Record<string, string> {
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  const content = readFileSync(path, "utf-8");
+  return parseEnvContent(content);
+}
+
+/**
+ * Load global environment variables from ~/.enact/.env
+ */
+export function loadGlobalEnv(): Record<string, string> {
+  return readEnvVars(getGlobalEnvPath());
+}
+
+/**
+ * Load local (project) environment variables from .enact/.env
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ */
+export function loadLocalEnv(cwd?: string): Record<string, string> {
+  return readEnvVars(getLocalEnvPath(cwd));
+}
+
+/**
+ * Load global environment as parsed file (for updates)
+ */
+export function loadGlobalEnvFile(): ParsedEnvFile {
+  return readEnvFile(getGlobalEnvPath());
+}
+
+/**
+ * Load local environment as parsed file (for updates)
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ */
+export function loadLocalEnvFile(cwd?: string): ParsedEnvFile {
+  return readEnvFile(getLocalEnvPath(cwd));
+}
+
+/**
+ * Check if global .env file exists
+ */
+export function globalEnvExists(): boolean {
+  return existsSync(getGlobalEnvPath());
+}
+
+/**
+ * Check if local .env file exists
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ */
+export function localEnvExists(cwd?: string): boolean {
+  return existsSync(getLocalEnvPath(cwd));
+}

package/src/env/writer.ts

@@ -0,0 +1,118 @@
+/**
+ * .env file writer
+ *
+ * Writes .env files while preserving comments and formatting
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ParsedEnvFile } from "../types";
+import { createEnvContent, removeEnvVar, serializeEnvFile, updateEnvVar } from "./parser";
+import { getGlobalEnvPath, getLocalEnvPath, readEnvFile } from "./reader";
+
+/**
+ * Ensure directory exists for a file path
+ */
+function ensureDirectory(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Write a parsed env file to disk
+ *
+ * @param path - Path to write to
+ * @param parsed - Parsed env file to write
+ */
+export function writeEnvFile(path: string, parsed: ParsedEnvFile): void {
+  ensureDirectory(path);
+  const content = serializeEnvFile(parsed);
+  writeFileSync(path, content, "utf-8");
+}
+
+/**
+ * Write a vars object to an .env file
+ *
+ * @param path - Path to write to
+ * @param vars - Key-value pairs to write
+ */
+export function writeEnvVars(path: string, vars: Record<string, string>): void {
+  ensureDirectory(path);
+  const content = createEnvContent(vars);
+  writeFileSync(path, content, "utf-8");
+}
+
+/**
+ * Set an environment variable in a file
+ * Creates file if it doesn't exist, preserves existing content
+ *
+ * @param path - Path to the .env file
+ * @param key - Variable key
+ * @param value - Variable value
+ */
+export function setEnvVar(path: string, key: string, value: string): void {
+  const parsed = readEnvFile(path);
+  const updated = updateEnvVar(parsed, key, value);
+  writeEnvFile(path, updated);
+}
+
+/**
+ * Delete an environment variable from a file
+ *
+ * @param path - Path to the .env file
+ * @param key - Variable key to delete
+ * @returns true if variable existed and was deleted
+ */
+export function deleteEnvVar(path: string, key: string): boolean {
+  const parsed = readEnvFile(path);
+  if (!(key in parsed.vars)) {
+    return false;
+  }
+  const updated = removeEnvVar(parsed, key);
+  writeEnvFile(path, updated);
+  return true;
+}
+
+/**
+ * Set a global environment variable (~/.enact/.env)
+ *
+ * @param key - Variable key
+ * @param value - Variable value
+ */
+export function setGlobalEnvVar(key: string, value: string): void {
+  setEnvVar(getGlobalEnvPath(), key, value);
+}
+
+/**
+ * Set a local environment variable (.enact/.env)
+ *
+ * @param key - Variable key
+ * @param value - Variable value
+ * @param cwd - Current working directory (defaults to process.cwd())
+ */
+export function setLocalEnvVar(key: string, value: string, cwd?: string): void {
+  setEnvVar(getLocalEnvPath(cwd), key, value);
+}
+
+/**
+ * Delete a global environment variable
+ *
+ * @param key - Variable key to delete
+ * @returns true if variable existed and was deleted
+ */
+export function deleteGlobalEnvVar(key: string): boolean {
+  return deleteEnvVar(getGlobalEnvPath(), key);
+}
+
+/**
+ * Delete a local environment variable
+ *
+ * @param key - Variable key to delete
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @returns true if variable existed and was deleted
+ */
+export function deleteLocalEnvVar(key: string, cwd?: string): boolean {
+  return deleteEnvVar(getLocalEnvPath(cwd), key);
+}