@captainsafia/burrow 0.1.0 → 1.0.0-preview.0a24dbc

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2025 Safia Abdalla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -1,15 +1,120 @@
 # burrow
 
-To install dependencies:
+A platform-agnostic, directory-scoped secrets manager. Store secrets outside your repos, inherit them through directory ancestry.
+
+```
+~/projects/                     # DATABASE_URL, API_KEY defined here
+├── app-a/                      # inherits both secrets
+├── app-b/                      # inherits both, overrides API_KEY
+│   └── tests/                  # blocks API_KEY (uses none)
+└── app-c/                      # inherits both secrets
+```
+
+## Installation
+
+**Linux/macOS:**
 
 ```bash
+curl -fsSL https://safia.rocks/burrow/install.sh | sh
+```
+
+## Usage
+
+### Set a secret
+
+```bash
+burrow set API_KEY=sk-live-abc123
+burrow set DATABASE_URL=postgres://localhost/mydb --path ~/projects
+```
+
+### Get a secret
+
+```bash
+burrow get API_KEY --show
+burrow get API_KEY --format json
+```
+
+### List all secrets
+
+```bash
+burrow list
+burrow list --format json
+```
+
+### Export to your shell
+
+```bash
+eval "$(burrow export)"
+eval "$(burrow export --format shell)" && npm start
+```
+
+### Block inheritance
+
+```bash
+burrow unset API_KEY --path ~/projects/app/tests
+```
+
+## How It Works
+
+Secrets are stored in your user profile:
+- **Linux/macOS:** `$XDG_CONFIG_HOME/burrow` or `~/.config/burrow`
+- **Windows:** `%APPDATA%\burrow`
+
+When you request secrets for a directory, burrow:
+
+1. Finds all ancestor paths with stored secrets
+2. Merges them from shallowest to deepest
+3. Deeper scopes override shallower ones
+4. Tombstones (from `unset`) block inheritance
+
+## Library Usage
+
+Burrow also works as a TypeScript/JavaScript library:
+
+```typescript
+import { BurrowClient } from '@captainsafia/burrow';
+
+const client = new BurrowClient();
+
+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 allSecrets = await client.list({ cwd: '/my/project' });
+```
+
+## Contributing
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.0 or later
+
+### Setup
+
+```bash
+git clone https://github.com/captainsafia/burrow.git
+cd burrow
 bun install
 ```
 
-To run:
+### Development
 
 ```bash
-bun run index.ts
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Build npm package
+bun run build
+
+# Compile binary
+bun run compile
 ```
 
-This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## License
+
+MIT

package/dist/api.d.ts

@@ -6,41 +6,292 @@ export interface ResolvedSecret {
 	sourcePath: string;
 }
 export type ExportFormat = "shell" | "dotenv" | "json";
+/**
+ * Configuration options for creating a BurrowClient instance.
+ */
 export interface BurrowClientOptions {
+	/**
+	 * Custom directory for storing the secrets database.
+	 * Defaults to platform-specific user config directory:
+	 * - Linux/macOS: `$XDG_CONFIG_HOME/burrow` or `~/.config/burrow`
+	 * - Windows: `%APPDATA%\burrow`
+	 *
+	 * Can also be set via the `BURROW_CONFIG_DIR` environment variable.
+	 */
 	configDir?: string;
+	/**
+	 * Custom filename for the secrets store.
+	 * Defaults to `store.json`.
+	 */
 	storeFileName?: string;
+	/**
+	 * Whether to follow symlinks when canonicalizing paths.
+	 * Defaults to `true`.
+	 */
 	followSymlinks?: boolean;
 }
+/**
+ * Options for the `set` method.
+ */
 export interface SetOptions {
+	/**
+	 * Directory path to scope the secret to.
+	 * Defaults to the current working directory.
+	 */
 	path?: string;
 }
+/**
+ * Options for the `get` method.
+ */
 export interface GetOptions {
+	/**
+	 * Directory to resolve secrets from.
+	 * Secrets are inherited from ancestor directories.
+	 * Defaults to the current working directory.
+	 */
 	cwd?: string;
 }
+/**
+ * Options for the `list` method.
+ */
 export interface ListOptions {
+	/**
+	 * Directory to resolve secrets from.
+	 * Secrets are inherited from ancestor directories.
+	 * Defaults to the current working directory.
+	 */
 	cwd?: string;
 }
+/**
+ * Options for the `block` method.
+ */
 export interface BlockOptions {
+	/**
+	 * Directory path to scope the tombstone to.
+	 * Defaults to the current working directory.
+	 */
 	path?: string;
 }
+/**
+ * Options for the `export` method.
+ */
 export interface ExportOptions {
+	/**
+	 * Directory to resolve secrets from.
+	 * Secrets are inherited from ancestor directories.
+	 * Defaults to the current working directory.
+	 */
 	cwd?: string;
+	/**
+	 * Output format for the exported secrets.
+	 * - `shell`: Exports as `export KEY='value'` statements (default)
+	 * - `dotenv`: Exports as `KEY="value"` lines
+	 * - `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.
+	 * Only applies when format is `json`.
+	 */
 	includeSources?: boolean;
 }
+/**
+ * Client for managing directory-scoped secrets.
+ *
+ * Secrets are stored outside your repository in the user's config directory
+ * and are scoped to filesystem paths. Child directories automatically inherit
+ * secrets from parent directories, with deeper scopes overriding shallower ones.
+ *
+ * @example
+ * ```typescript
+ * import { BurrowClient } from '@captainsafia/burrow';
+ *
+ * const client = new BurrowClient();
+ *
+ * // Set a secret scoped to a directory
+ * await client.set('API_KEY', 'sk-live-abc123', { path: '/projects/myapp' });
+ *
+ * // Get a secret (inherits from parent directories)
+ * const secret = await client.get('API_KEY', { cwd: '/projects/myapp/src' });
+ * console.log(secret?.value); // 'sk-live-abc123'
+ *
+ * // Export secrets for shell usage
+ * const shellExport = await client.export({ format: 'shell' });
+ * // Returns: export API_KEY='sk-live-abc123'
+ * ```
+ */
 export declare class BurrowClient {
 	private readonly storage;
 	private readonly resolver;
 	private readonly pathOptions;
+	/**
+	 * Creates a new BurrowClient instance.
+	 *
+	 * @param options - Configuration options for the client
+	 */
 	constructor(options?: BurrowClientOptions);
+	/**
+	 * Sets a secret at the specified path scope.
+	 *
+	 * 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 value - Secret value to store
+	 * @param options - Set options including target path
+	 * @throws Error if the key format is invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * // Set at current directory
+	 * await client.set('DATABASE_URL', 'postgres://localhost/mydb');
+	 *
+	 * // Set at specific path
+	 * await client.set('API_KEY', 'secret', { path: '/projects/myapp' });
+	 * ```
+	 */
 	set(key: string, value: string, options?: SetOptions): Promise<void>;
+	/**
+	 * Gets a secret resolved through directory ancestry.
+	 *
+	 * Starting from the specified directory (or cwd), walks up the directory
+	 * tree to find the nearest scope that defines the key. Deeper scopes
+	 * override shallower ones.
+	 *
+	 * @param key - Environment variable name to retrieve
+	 * @param options - Get options including working directory
+	 * @returns The resolved secret with its source path, or undefined if not found
+	 *
+	 * @example
+	 * ```typescript
+	 * const secret = await client.get('API_KEY', { cwd: '/projects/myapp/src' });
+	 * if (secret) {
+	 *   console.log(secret.value);      // The secret value
+	 *   console.log(secret.sourcePath); // Path where it was defined
+	 * }
+	 * ```
+	 */
 	get(key: string, options?: GetOptions): Promise<ResolvedSecret | undefined>;
+	/**
+	 * Lists all secrets resolved for a directory.
+	 *
+	 * Returns all secrets that would be available in the specified directory,
+	 * including those inherited from parent directories. Each secret includes
+	 * its source path indicating where it was defined.
+	 *
+	 * @param options - List options including working directory
+	 * @returns Array of resolved secrets sorted by key name
+	 *
+	 * @example
+	 * ```typescript
+	 * const secrets = await client.list({ cwd: '/projects/myapp' });
+	 * for (const secret of secrets) {
+	 *   console.log(`${secret.key} from ${secret.sourcePath}`);
+	 * }
+	 * ```
+	 */
 	list(options?: ListOptions): Promise<ResolvedSecret[]>;
+	/**
+	 * Blocks a secret from being inherited at the specified path.
+	 *
+	 * Creates a "tombstone" that prevents the key from being inherited from
+	 * parent directories. The block only affects the specified directory and
+	 * its subdirectories. The secret remains available in parent directories.
+	 *
+	 * 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 options - Block options including target path
+	 * @throws Error if the key format is invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * // Parent has API_KEY defined
+	 * await client.set('API_KEY', 'prod-key', { path: '/projects' });
+	 *
+	 * // Block it in the test directory
+	 * await client.block('API_KEY', { path: '/projects/myapp/tests' });
+	 *
+	 * // Now API_KEY won't resolve in /projects/myapp/tests or below
+	 * const secret = await client.get('API_KEY', { cwd: '/projects/myapp/tests' });
+	 * console.log(secret); // undefined
+	 * ```
+	 */
 	block(key: string, options?: BlockOptions): Promise<void>;
+	/**
+	 * Exports resolved secrets in various formats.
+	 *
+	 * Generates a formatted string of all secrets resolved for the specified
+	 * directory, suitable for shell evaluation or configuration files.
+	 *
+	 * @param options - Export options including format and working directory
+	 * @returns Formatted string of secrets
+	 *
+	 * @example
+	 * ```typescript
+	 * // Shell format (default) - use with eval
+	 * const shell = await client.export({ format: 'shell' });
+	 * // Returns: export API_KEY='value'\nexport DB_URL='...'
+	 *
+	 * // Dotenv format - save to .env file
+	 * const dotenv = await client.export({ format: 'dotenv' });
+	 * // Returns: API_KEY="value"\nDB_URL="..."
+	 *
+	 * // JSON format - for programmatic use
+	 * const json = await client.export({ format: 'json' });
+	 * // Returns: { "API_KEY": "value", "DB_URL": "..." }
+	 *
+	 * // JSON with source paths
+	 * const jsonWithSources = await client.export({
+	 *   format: 'json',
+	 *   includeSources: true
+	 * });
+	 * // Returns: { "API_KEY": { "value": "...", "sourcePath": "/..." } }
+	 * ```
+	 */
 	export(options?: ExportOptions): Promise<string>;
+	/**
+	 * Resolves all secrets for a directory as a Map.
+	 *
+	 * Lower-level method that returns the raw resolution result. Useful for
+	 * programmatic access when you need to iterate over secrets or perform
+	 * custom processing.
+	 *
+	 * @param cwd - Directory to resolve secrets from. Defaults to current working directory.
+	 * @returns Map of key names to resolved secrets
+	 *
+	 * @example
+	 * ```typescript
+	 * const secrets = await client.resolve('/projects/myapp');
+	 * for (const [key, secret] of secrets) {
+	 *   console.log(`${key}=${secret.value} (from ${secret.sourcePath})`);
+	 * }
+	 * ```
+	 */
 	resolve(cwd?: string): Promise<Map<string, ResolvedSecret>>;
 }
+/**
+ * Creates a new BurrowClient instance.
+ *
+ * Convenience function equivalent to `new BurrowClient(options)`.
+ *
+ * @param options - Configuration options for the client
+ * @returns A new BurrowClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@captainsafia/burrow';
+ *
+ * const client = createClient({
+ *   configDir: '/custom/config/path'
+ * });
+ * ```
+ */
 export declare function createClient(options?: BurrowClientOptions): BurrowClient;
 
 export {};

package/dist/api.js

@@ -7,7 +7,12 @@ import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 var APP_NAME = "burrow";
+var CONFIG_DIR_ENV = "BURROW_CONFIG_DIR";
 function getConfigDir() {
+  const envOverride = process.env[CONFIG_DIR_ENV];
+  if (envOverride) {
+    return envOverride;
+  }
   const platform = process.platform;
   if (platform === "win32") {
     return getWindowsConfigDir();
@@ -170,11 +175,8 @@ function isAncestorOf(ancestorPath, descendantPath) {
 class Resolver {
   storage;
   pathOptions;
-  constructor(options = {}) {
-    this.storage = new Storage({
-      configDir: options.configDir,
-      storeFileName: options.storeFileName
-    });
+  constructor(options) {
+    this.storage = options.storage;
     this.pathOptions = {
       followSymlinks: options.followSymlinks
     };
@@ -306,8 +308,7 @@ class BurrowClient {
       storeFileName: options.storeFileName
     });
     this.resolver = new Resolver({
-      configDir: options.configDir,
-      storeFileName: options.storeFileName,
+      storage: this.storage,
       followSymlinks: options.followSymlinks
     });
     this.pathOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captainsafia/burrow",
-  "version": "0.1.0",
+  "version": "1.0.0-preview.0a24dbc",
   "description": "Platform-agnostic, directory-scoped secrets manager",
   "type": "module",
   "main": "dist/api.js",
@@ -49,5 +49,8 @@
     "direnv",
     "configuration"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.2"
+  }
+}