@inthedark/wb 0.0.6 → 0.0.7

package/README.md

@@ -69,3 +69,45 @@ note: have tried to keep dependencies minimal for the most part
 `/test` — test runner  
 `/scripts` — stuff used by package scripts plus anything i didn't notice an agent left behind :3  
 `/docs` — help agents find things and not break them without eating all their tokens
+
+## .env secrets
+
+workbench's npm package `@inthedark/wb` can be used as a dotenv replacement. its `config` is async, so await it before reading your env vars:
+
+```js
+import { config } from "@inthedark/wb";
+
+await config();
+```
+
+the following syntax in your .env file can be used to load data from workbench's private store:
+
+```dotenv
+API_KEY=${wb:API_KEY}
+```
+
+configure secrets in workbench at settings > projects & folders > environment > store. select the folder you want to configure.
+
+the env loader by default silently acts like dotenv would for loading the .env if workbench is not installed, so it's safe to use in teams where some devs are using other stuff. references it can't resolve stay as literal text. existing env vars still take precedence. pass a `warn` callback to opt into lookup warnings.
+
+you can choose what happens when values are missing:
+
+```js
+await config({ required: ["DATABASE_URL"] }); // all others optional
+await config({ optional: ["ANALYTICS_KEY"] }); // all others required
+```
+
+use one list or the other. missing optional vars become empty strings, including the whole value if a store reference fails. missing required vars throw one error listing all their names before changing the environment. explicitly empty values are valid. "all others" means vars in your .env files.
+
+you can use wb's env loader to load from other clis too, not just wb store:
+
+```dotenv
+WB_STORES="wb: wb store get {key}; other: my-secret-cli get {key}"
+API_KEY=${other:API_KEY}
+```
+
+replace `my-secret-cli get {key}` with your cli's command. `{key}` is substituted into its arguments, and stdout becomes the value. commands run without a shell.
+
+### security note
+
+wb's env secret storage is not built for maximum security. it's built to prevent agents accidentally obtaining secrets. values use aes-256-gcm with a key derived from the device identity, username and project location, not a separate password, so this isn't protection against hostile code running as you.

package/index.d.ts

@@ -1,10 +1,10 @@
 /*
  * Exports:
- * - WorkbenchConfigOptions: dotenv-compatible loading options plus cancellation and warning hooks.
+ * - WorkbenchConfigOptions: dotenv loading, mutually exclusive missing-value policies, cancellation and warning hooks.
  * - WorkbenchConfigOutput: parsed values after store replacement, with the first file read error.
- * - config: load dotenv files, then replace resolvable `${store:key}` references through named WB_STORES commands.
+ * - config: load dotenv and store values; reject missing required names before writing the environment.
  */
-export interface WorkbenchConfigOptions {
+export type WorkbenchConfigOptions = {
   /** One file or several; earlier files win unless `override` is set. Defaults to `.env`. */
   path?: string | readonly string[];
   encoding?: BufferEncoding;
@@ -13,13 +13,26 @@ export interface WorkbenchConfigOptions {
   processEnv?: Record<string, string | undefined>;
   /** Aborting kills running store commands and rejects. */
   signal?: AbortSignal;
-  /** Receives bounded messages that never contain command output. Defaults to `process.emitWarning`. */
+  /** Opt into bounded lookup warnings that never contain command output. Silent by default. */
   warn?: (message: string) => void;
-}
+} & ({
+  /** Only these names are required; all other dotenv variables are optional. Empty values count as supplied. */
+  required?: readonly string[];
+  optional?: never;
+} | {
+  required?: never;
+  /** These names are optional; all other dotenv variables are required. Empty values count as supplied. */
+  optional?: readonly string[];
+});
 
 export interface WorkbenchConfigOutput {
   parsed: Record<string, string>;
   error?: Error;
 }
 
+/**
+ * Without a policy, unresolved references remain literal. With a policy, missing optional
+ * variables become empty strings in their entirety. Missing required names reject together
+ * before any environment writes. Existing environment values win unless override is set.
+ */
 export function config(options?: WorkbenchConfigOptions): Promise<WorkbenchConfigOutput>;

package/index.mjs

@@ -1,6 +1,6 @@
 /*
  * Exports:
- * - config: load dotenv files, then replace resolvable `${store:key}` references through named WB_STORES commands.
+ * - config: load dotenv files, resolve named store references, and enforce an optional missing-variable policy.
  */
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -13,10 +13,6 @@ import {
   parseStoreDefinitions,
 } from "./store-definitions.mjs";
 
-function warnDefault(message) {
-  process.emitWarning(message, "WorkbenchStoreWarning");
-}
-
 function stripTerminalLineEnding(value) {
   return value.endsWith("\r\n") ? value.slice(0, -2) : value.endsWith("\n") ? value.slice(0, -1) : value;
 }
@@ -37,15 +33,17 @@ async function readParsed(paths, encoding, override) {
   return { parsed, error };
 }
 
-async function resolveReferences(parsed, definitions, { runner, signal, warn }) {
+async function resolveReferences(parsed, definitions, { runner, signal, warn, policy }) {
+  const references = new Map(Object.entries(parsed).map(([name, value]) => [name, findStoreReferences(value)]));
+  const unresolved = new Set();
   let stores;
   try {
     stores = parseStoreDefinitions(definitions);
   } catch (failure) {
-    warn(`${failure.message} Store references were left unchanged.`);
-    return parsed;
+    warn(policy ? failure.message : `${failure.message} Store references were left unchanged.`);
+    for (const [name, found] of references) if (found.length) unresolved.add(name);
+    return { parsed, unresolved };
   }
-  const references = new Map(Object.entries(parsed).map(([name, value]) => [name, findStoreReferences(value)]));
   const lookups = new Map();
   for (const [name, found] of references) {
     for (const { key, store } of found) {
@@ -53,25 +51,52 @@ async function resolveReferences(parsed, definitions, { runner, signal, warn })
       if (stores.has(store) && !lookups.has(id)) lookups.set(id, { argv: expandStoreCommand(stores.get(store), key), owner: name, store });
     }
   }
-  if (!lookups.size) return parsed;
   const results = new Map(await Promise.all(Array.from(lookups, async ([id, lookup]) => {
     const result = await runner.run(lookup.argv, { signal });
     if (!result.ok) {
       const detail = result.reason === "exit" ? `exited with ${result.exitCode}` : `failed (${result.reason})`;
-      warn(`The ${lookup.store} store lookup for ${lookup.owner} ${detail}. The reference was left unchanged.`);
+      warn(`The ${lookup.store} store lookup for ${lookup.owner} ${detail}.${policy ? "" : " The reference was left unchanged."}`);
     }
     return [id, result];
   })));
-  return Object.fromEntries(Object.entries(parsed).map(([name, value]) => {
+  const resolved = Object.fromEntries(Object.entries(parsed).map(([name, value]) => {
     let next = "";
     let cursor = 0;
     for (const reference of references.get(name)) {
       const result = results.get(JSON.stringify([reference.store, reference.key]));
+      if (!result?.ok) unresolved.add(name);
       next += value.slice(cursor, reference.start) + (result?.ok ? stripTerminalLineEnding(result.stdout) : reference.text);
       cursor = reference.end;
     }
     return [name, next + value.slice(cursor)];
   }));
+  return { parsed: resolved, unresolved };
+}
+
+function missingPolicy(required, optional) {
+  if (required !== undefined && optional !== undefined) {
+    throw new TypeError("Specify either required or optional, not both.");
+  }
+  const names = required ?? optional;
+  if (required === undefined && optional === undefined) return null;
+  if (!Array.isArray(names) || names.some(name => typeof name !== "string" || !name.length)) {
+    throw new TypeError("required and optional must be arrays of nonempty environment variable names.");
+  }
+  return { names: new Set(names), listedRequired: required !== undefined };
+}
+
+function applyMissingPolicy(parsed, unresolved, policy, processEnv, override) {
+  if (!policy) return;
+  const missing = [];
+  for (const name of new Set([...Object.keys(parsed), ...policy.names])) {
+    const existing = Object.hasOwn(processEnv, name) && processEnv[name] !== undefined;
+    const fromFile = Object.hasOwn(parsed, name);
+    if (existing && (!override || !fromFile)) continue;
+    if (fromFile && !unresolved.has(name)) continue;
+    if (policy.names.has(name) === policy.listedRequired) missing.push(name);
+    else Object.defineProperty(parsed, name, { value: "", writable: true, enumerable: true, configurable: true });
+  }
+  if (missing.length) throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
 }
 
 export async function config({
@@ -80,13 +105,20 @@ export async function config({
   override = false,
   processEnv = process.env,
   signal,
-  warn = warnDefault,
+  warn = () => {},
   runner = new StoreCommandRunner(),
+  required,
+  optional,
 } = {}) {
   signal?.throwIfAborted();
+  const policy = missingPolicy(required, optional);
   const { parsed: raw, error } = await readParsed(Array.isArray(paths) ? paths : [paths], encoding, override);
   const definitions = raw.WB_STORES?.trim() || processEnv.WB_STORES?.trim() || DEFAULT_STORE_DEFINITIONS;
-  const parsed = await resolveReferences(raw, definitions, { runner, signal, warn });
-  dotenv.populate(processEnv, parsed, { override });
+  const { parsed, unresolved } = await resolveReferences(raw, definitions, { runner, signal, warn, policy });
+  applyMissingPolicy(parsed, unresolved, policy, processEnv, override);
+  const values = policy && !override
+    ? Object.fromEntries(Object.entries(parsed).filter(([name]) => !Object.hasOwn(processEnv, name) || processEnv[name] === undefined))
+    : parsed;
+  dotenv.populate(processEnv, values, { override: policy ? true : override });
   return error ? { parsed, error } : { parsed };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inthedark/wb",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "type": "module",
   "repository": {
     "type": "git",