@captainsafia/burrow 1.0.0-preview.0a24dbc → 1.0.0-preview.2be53e0

package/README.md

@@ -30,7 +30,7 @@ burrow set DATABASE_URL=postgres://localhost/mydb --path ~/projects
 ### Get a secret
 
 ```bash
-burrow get API_KEY --show
+burrow get API_KEY
 burrow get API_KEY --format json
 ```
 
@@ -44,8 +44,14 @@ burrow list --format json
 ### Export to your shell
 
 ```bash
+# Auto-detects your shell (bash, fish, powershell, cmd)
 eval "$(burrow export)"
-eval "$(burrow export --format shell)" && npm start
+
+# Or specify a format explicitly
+burrow export --format fish
+burrow export --format powershell
+burrow export --format dotenv
+burrow export --format json
 ```
 
 ### Block inheritance
@@ -54,6 +60,14 @@ eval "$(burrow export --format shell)" && npm start
 burrow unset API_KEY --path ~/projects/app/tests
 ```
 
+### Remove a secret
+
+```bash
+burrow remove API_KEY --path ~/projects/app
+```
+
+Unlike `unset` which blocks inheritance, `remove` deletes the entry entirely, restoring inheritance from parent directories.
+
 ## How It Works
 
 Secrets are stored in your user profile:
@@ -76,13 +90,26 @@ import { BurrowClient } from '@captainsafia/burrow';
 
 const client = new BurrowClient();
 
-await client.set('API_KEY', 'secret123', { path: '/my/project' });
+try {
+  await client.set('API_KEY', 'secret123', { path: '/my/project' });
+
+  const secret = await client.get('API_KEY', { cwd: '/my/project/subdir' });
+  console.log(secret?.value); // 'secret123'
+  console.log(secret?.sourcePath); // '/my/project'
 
-const secret = await client.get('API_KEY', { cwd: '/my/project/subdir' });
-console.log(secret?.value); // 'secret123'
-console.log(secret?.sourcePath); // '/my/project'
+  const allSecrets = await client.list({ cwd: '/my/project' });
+} finally {
+  client.close(); // Clean up database connection
+}
+```
 
-const allSecrets = await client.list({ cwd: '/my/project' });
+Or with TypeScript's `using` declarations for automatic cleanup:
+
+```typescript
+{
+  using client = new BurrowClient();
+  await client.set('API_KEY', 'secret123');
+} // Automatically cleaned up
 ```
 
 ## Contributing

package/dist/api.d.ts

@@ -5,7 +5,7 @@ export interface ResolvedSecret {
 	value: string;
 	sourcePath: string;
 }
-export type ExportFormat = "shell" | "dotenv" | "json";
+export type ExportFormat = "shell" | "bash" | "fish" | "powershell" | "cmd" | "dotenv" | "json";
 /**
  * Configuration options for creating a BurrowClient instance.
  */
@@ -21,7 +21,7 @@ export interface BurrowClientOptions {
 	configDir?: string;
 	/**
 	 * Custom filename for the secrets store.
-	 * Defaults to `store.json`.
+	 * Defaults to `store.db`.
 	 */
 	storeFileName?: string;
 	/**
@@ -72,6 +72,16 @@ export interface BlockOptions {
 	 */
 	path?: string;
 }
+/**
+ * Options for the `remove` method.
+ */
+export interface RemoveOptions {
+	/**
+	 * Directory path to remove the secret from.
+	 * Defaults to the current working directory.
+	 */
+	path?: string;
+}
 /**
  * Options for the `export` method.
  */
@@ -89,10 +99,6 @@ export interface ExportOptions {
 	 * - `json`: Exports as a JSON object
 	 */
 	format?: ExportFormat;
-	/**
-	 * Whether to show actual values (currently unused, reserved for future use).
-	 */
-	showValues?: boolean;
 	/**
 	 * Whether to include source paths in JSON output.
 	 * When true, JSON output includes `{ key: { value, sourcePath } }` format.
@@ -141,7 +147,7 @@ export declare class BurrowClient {
 	 * The secret will be available to the specified directory and all its
 	 * subdirectories, unless overridden or blocked at a deeper level.
 	 *
-	 * @param key - Environment variable name. Must match `^[A-Z_][A-Z0-9_]*$`
+	 * @param key - Environment variable name. Must match `^[A-Za-z_][A-Za-z0-9_]*$`
 	 * @param value - Secret value to store
 	 * @param options - Set options including target path
 	 * @throws Error if the key format is invalid
@@ -205,7 +211,7 @@ export declare class BurrowClient {
 	 *
 	 * A blocked key can be re-enabled by calling `set` at the same or deeper path.
 	 *
-	 * @param key - Environment variable name to block. Must match `^[A-Z_][A-Z0-9_]*$`
+	 * @param key - Environment variable name to block. Must match `^[A-Za-z_][A-Za-z0-9_]*$`
 	 * @param options - Block options including target path
 	 * @throws Error if the key format is invalid
 	 *
@@ -223,6 +229,33 @@ export declare class BurrowClient {
 	 * ```
 	 */
 	block(key: string, options?: BlockOptions): Promise<void>;
+	/**
+	 * Removes a secret entry entirely from the specified path.
+	 *
+	 * Unlike `block`, which creates a tombstone to prevent inheritance,
+	 * `remove` completely deletes the secret entry. After removal, the key
+	 * may still be inherited from parent directories if defined there.
+	 *
+	 * @param key - Environment variable name to remove. Must match `^[A-Za-z_][A-Za-z0-9_]*$`
+	 * @param options - Remove options including target path
+	 * @returns true if the secret was found and removed, false if it didn't exist
+	 * @throws Error if the key format is invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * // Set a secret
+	 * await client.set('API_KEY', 'secret', { path: '/projects/myapp' });
+	 *
+	 * // Remove it entirely
+	 * const removed = await client.remove('API_KEY', { path: '/projects/myapp' });
+	 * console.log(removed); // true
+	 *
+	 * // Trying to remove again returns false
+	 * const removedAgain = await client.remove('API_KEY', { path: '/projects/myapp' });
+	 * console.log(removedAgain); // false
+	 * ```
+	 */
+	remove(key: string, options?: RemoveOptions): Promise<boolean>;
 	/**
 	 * Exports resolved secrets in various formats.
 	 *
@@ -274,6 +307,36 @@ export declare class BurrowClient {
 	 * ```
 	 */
 	resolve(cwd?: string): Promise<Map<string, ResolvedSecret>>;
+	/**
+	 * Closes the database connection and releases resources.
+	 * After calling this method, the client instance should not be used.
+	 *
+	 * This method is safe to call multiple times.
+	 *
+	 * @example
+	 * ```typescript
+	 * const client = new BurrowClient();
+	 * try {
+	 *   await client.set('API_KEY', 'value');
+	 *   // ... do work
+	 * } finally {
+	 *   client.close();
+	 * }
+	 * ```
+	 */
+	close(): void;
+	/**
+	 * Allows using the BurrowClient with `using` declarations for automatic cleanup.
+	 *
+	 * @example
+	 * ```typescript
+	 * {
+	 *   using client = new BurrowClient();
+	 *   await client.set('API_KEY', 'value');
+	 * } // client.close() is called automatically
+	 * ```
+	 */
+	[Symbol.dispose](): void;
 }
 /**
  * Creates a new BurrowClient instance.

package/dist/api.js

@@ -1,7 +1,7 @@
 // src/storage/index.ts
-import { mkdir, rename, readFile, unlink } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import { chmod, mkdir } from "node:fs/promises";
 import { join as join2 } from "node:path";
-import { randomBytes } from "node:crypto";
 
 // src/platform/index.ts
 import { homedir } from "node:os";
@@ -44,18 +44,12 @@ function isWindows() {
 }
 
 // src/storage/index.ts
-var STORE_VERSION = 1;
-var DEFAULT_STORE_FILE = "store.json";
-function createEmptyStore() {
-  return {
-    version: STORE_VERSION,
-    paths: {}
-  };
-}
+var DEFAULT_STORE_FILE = "store.db";
 
 class Storage {
   configDir;
   storeFileName;
+  db = null;
   constructor(options = {}) {
     this.configDir = options.configDir ?? getConfigDir();
     this.storeFileName = options.storeFileName ?? DEFAULT_STORE_FILE;
@@ -63,68 +57,97 @@ class Storage {
   get storePath() {
     return join2(this.configDir, this.storeFileName);
   }
-  async read() {
-    try {
-      const content = await readFile(this.storePath, "utf-8");
-      const store = JSON.parse(content);
-      if (store.version !== STORE_VERSION) {
-        throw new Error(`Unsupported store version: ${store.version}. Expected: ${STORE_VERSION}`);
-      }
-      return store;
-    } catch (error) {
-      if (error.code === "ENOENT") {
-        return createEmptyStore();
-      }
-      throw error;
+  async ensureDb() {
+    if (this.db) {
+      return this.db;
     }
-  }
-  async write(store) {
     await mkdir(this.configDir, { recursive: true });
-    const tempFileName = `.store-${randomBytes(8).toString("hex")}.tmp`;
-    const tempPath = join2(this.configDir, tempFileName);
-    const content = JSON.stringify(store, null, 2);
-    try {
-      const file = Bun.file(tempPath);
-      await Bun.write(file, content);
-      await rename(tempPath, this.storePath);
-    } catch (error) {
-      try {
-        await unlink(tempPath);
-      } catch {}
-      throw error;
+    if (!isWindows()) {
+      await chmod(this.configDir, 448);
+    }
+    this.db = new Database(this.storePath);
+    if (!isWindows()) {
+      await chmod(this.storePath, 384);
     }
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS secrets (
+        path TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (path, key)
+      )
+    `);
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_secrets_path ON secrets (path)");
+    const versionResult = this.db.query("PRAGMA user_version").get();
+    const currentVersion = versionResult?.user_version ?? 0;
+    if (currentVersion === 0) {
+      this.db.run("PRAGMA user_version = 1");
+    } else if (currentVersion !== 1) {
+      throw new Error(`Unsupported store version: ${currentVersion}. Expected: 1`);
+    }
+    return this.db;
   }
   async setSecret(canonicalPath, key, value) {
-    const store = await this.read();
-    if (!store.paths[canonicalPath]) {
-      store.paths[canonicalPath] = {};
-    }
-    store.paths[canonicalPath][key] = {
-      value,
-      updatedAt: new Date().toISOString()
-    };
-    await this.write(store);
+    const db = await this.ensureDb();
+    const updatedAt = new Date().toISOString();
+    db.query(`
+      INSERT INTO secrets (path, key, value, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(path, key) DO UPDATE SET
+        value = excluded.value,
+        updated_at = excluded.updated_at
+    `).run(canonicalPath, key, value, updatedAt);
   }
   async getPathSecrets(canonicalPath) {
-    const store = await this.read();
-    return store.paths[canonicalPath];
+    const db = await this.ensureDb();
+    const rows = db.query("SELECT key, value, updated_at FROM secrets WHERE path = ?").all(canonicalPath);
+    if (rows.length === 0) {
+      return;
+    }
+    const secrets = {};
+    for (const row of rows) {
+      secrets[row.key] = {
+        value: row.value,
+        updatedAt: row.updated_at
+      };
+    }
+    return secrets;
   }
   async getAllPaths() {
-    const store = await this.read();
-    return Object.keys(store.paths);
+    const db = await this.ensureDb();
+    const rows = db.query("SELECT DISTINCT path FROM secrets").all();
+    return rows.map((row) => row.path);
+  }
+  async getAncestorPaths(canonicalPath) {
+    const db = await this.ensureDb();
+    let rows;
+    if (isWindows()) {
+      rows = db.query("SELECT DISTINCT path FROM secrets WHERE ? = path OR ? LIKE path || '\\' || '%' OR (length(path) = 3 AND path LIKE '_:\\' AND ? LIKE path || '%')").all(canonicalPath, canonicalPath, canonicalPath);
+    } else {
+      rows = db.query("SELECT DISTINCT path FROM secrets WHERE ? = path OR ? LIKE path || '/' || '%' OR path = '/'").all(canonicalPath, canonicalPath);
+    }
+    return rows.map((row) => row.path);
   }
   async removeKey(canonicalPath, key) {
-    const store = await this.read();
-    if (!store.paths[canonicalPath]?.[key]) {
+    const db = await this.ensureDb();
+    const existing = db.query("SELECT path FROM secrets WHERE path = ? AND key = ?").get(canonicalPath, key);
+    if (!existing) {
       return false;
     }
-    delete store.paths[canonicalPath][key];
-    if (Object.keys(store.paths[canonicalPath]).length === 0) {
-      delete store.paths[canonicalPath];
-    }
-    await this.write(store);
+    db.query("DELETE FROM secrets WHERE path = ? AND key = ?").run(canonicalPath, key);
     return true;
   }
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
 }
 
 // src/core/path.ts
@@ -161,16 +184,6 @@ function normalizePath(path) {
   }
   return normalized;
 }
-function isAncestorOf(ancestorPath, descendantPath) {
-  if (ancestorPath === descendantPath) {
-    return true;
-  }
-  const ancestorWithSep = ancestorPath.endsWith(sep) ? ancestorPath : ancestorPath + sep;
-  if (isWindows()) {
-    return descendantPath.toLowerCase().startsWith(ancestorWithSep.toLowerCase());
-  }
-  return descendantPath.startsWith(ancestorWithSep);
-}
 // src/core/resolver.ts
 class Resolver {
   storage;
@@ -184,8 +197,7 @@ class Resolver {
   async resolve(cwd) {
     const workingDir = cwd ?? process.cwd();
     const canonicalCwd = await canonicalize(workingDir, this.pathOptions);
-    const allPaths = await this.storage.getAllPaths();
-    const ancestorPaths = allPaths.filter((storedPath) => isAncestorOf(storedPath, canonicalCwd));
+    const ancestorPaths = await this.storage.getAncestorPaths(canonicalCwd);
     ancestorPaths.sort((a, b) => {
       if (isWindows()) {
         return a.toLowerCase().localeCompare(b.toLowerCase());
@@ -224,7 +236,7 @@ class Resolver {
   }
 }
 // src/core/formatter.ts
-var ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validateEnvKey(key) {
   return ENV_KEY_PATTERN.test(key);
 }
@@ -239,6 +251,9 @@ function escapeShellValue(value) {
 function escapeDoubleQuotes(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
+function escapePowerShellValue(value) {
+  return value.replace(/'/g, "''");
+}
 function formatShell(secrets) {
   const lines = [];
   const sortedKeys = Array.from(secrets.keys()).sort();
@@ -251,6 +266,42 @@ function formatShell(secrets) {
   return lines.join(`
 `);
 }
+function formatFish(secrets) {
+  const lines = [];
+  const sortedKeys = Array.from(secrets.keys()).sort();
+  for (const key of sortedKeys) {
+    const secret = secrets.get(key);
+    assertValidEnvKey(key);
+    const escapedValue = escapeShellValue(secret.value);
+    lines.push(`set -gx ${key} '${escapedValue}'`);
+  }
+  return lines.join(`
+`);
+}
+function formatPowerShell(secrets) {
+  const lines = [];
+  const sortedKeys = Array.from(secrets.keys()).sort();
+  for (const key of sortedKeys) {
+    const secret = secrets.get(key);
+    assertValidEnvKey(key);
+    const escapedValue = escapePowerShellValue(secret.value);
+    lines.push(`$env:${key} = '${escapedValue}'`);
+  }
+  return lines.join(`
+`);
+}
+function formatCmd(secrets) {
+  const lines = [];
+  const sortedKeys = Array.from(secrets.keys()).sort();
+  for (const key of sortedKeys) {
+    const secret = secrets.get(key);
+    assertValidEnvKey(key);
+    const escapedValue = secret.value.replace(/([&|<>^])/g, "^$1");
+    lines.push(`set ${key}=${escapedValue}`);
+  }
+  return lines.join(`
+`);
+}
 function formatDotenv(secrets) {
   const lines = [];
   const sortedKeys = Array.from(secrets.keys()).sort();
@@ -288,7 +339,14 @@ function formatJson(secrets, includeSources = false) {
 function format(secrets, fmt, options = {}) {
   switch (fmt) {
     case "shell":
+    case "bash":
       return formatShell(secrets);
+    case "fish":
+      return formatFish(secrets);
+    case "powershell":
+      return formatPowerShell(secrets);
+    case "cmd":
+      return formatCmd(secrets);
     case "dotenv":
       return formatDotenv(secrets);
     case "json":
@@ -333,6 +391,12 @@ class BurrowClient {
     const canonicalPath = await canonicalize(targetPath, this.pathOptions);
     await this.storage.setSecret(canonicalPath, key, null);
   }
+  async remove(key, options = {}) {
+    assertValidEnvKey(key);
+    const targetPath = options.path ?? process.cwd();
+    const canonicalPath = await canonicalize(targetPath, this.pathOptions);
+    return this.storage.removeKey(canonicalPath, key);
+  }
   async export(options = {}) {
     const secrets = await this.resolver.resolve(options.cwd);
     const fmt = options.format ?? "shell";
@@ -343,6 +407,12 @@ class BurrowClient {
   async resolve(cwd) {
     return this.resolver.resolve(cwd);
   }
+  close() {
+    this.storage.close();
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
 }
 function createClient(options) {
   return new BurrowClient(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captainsafia/burrow",
-  "version": "1.0.0-preview.0a24dbc",
+  "version": "1.0.0-preview.2be53e0",
   "description": "Platform-agnostic, directory-scoped secrets manager",
   "type": "module",
   "main": "dist/api.js",