@inthedark/wb 0.0.5 → 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/StoreCommandRunner.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const PACKAGED_WB = path.join(path.dirname(fileURLToPath(import.meta.url)), "wb");
+const DANGEROUS_ACCESS = "DANGEROUSLY_ACCESS_ENV_VARS";
 
 export default class StoreCommandRunner {
   constructor({ maxOutputBytes = MAX_OUTPUT_BYTES, packagedWb = PACKAGED_WB } = {}) {
@@ -19,9 +20,16 @@ export default class StoreCommandRunner {
   async run(argv, { signal } = {}) {
     signal?.throwIfAborted();
     // `wb` means this package's own bootstrap so lookups work without PATH setup.
-    const [executable, ...args] = argv[0] === "wb" ? [process.execPath, this.packagedWb, ...argv.slice(1)] : argv;
+    const packaged = argv[0] === "wb";
+    const [executable, ...args] = packaged ? [process.execPath, this.packagedWb, ...argv.slice(1)] : argv;
     return await new Promise((resolve, reject) => {
-      const child = spawn(executable, args, { shell: false, signal, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+      const child = spawn(executable, args, {
+        env: packaged ? { ...process.env, [DANGEROUS_ACCESS]: "1" } : process.env,
+        shell: false,
+        signal,
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+      });
       const chunks = [];
       let length = 0;
       let overflow = false;

package/WorkbenchBootstrap.mjs

@@ -19,6 +19,7 @@ export default class WorkbenchBootstrap {
     home = os.homedir(),
     packageRoot = path.dirname(fileURLToPath(import.meta.url)),
     environment = process.env,
+    platform = process.platform,
     prompt = new WorkbenchInstallPrompt(),
     commands = new WorkbenchBootstrapCommand({ environment }),
     toolchain = new WorkbenchToolchain({ home, environment, commands }),
@@ -28,6 +29,7 @@ export default class WorkbenchBootstrap {
     this.home = home;
     this.packageRoot = packageRoot;
     this.environment = environment;
+    this.platform = platform;
     this.prompt = prompt;
     this.commands = commands;
     this.toolchain = toolchain;
@@ -94,47 +96,6 @@ export default class WorkbenchBootstrap {
     }
   }
 
-  async discardIncomplete(record) {
-    const root = path.resolve(record.root);
-    if (root !== record.root || !["wb", "workbench"].includes(path.basename(root).toLowerCase())) {
-      throw new Error(`Cannot verify failed install destination ${record.root}; it was preserved.`);
-    }
-    let stat;
-    try { stat = await fs.lstat(root); }
-    catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      await fs.unlink(this.registry);
-      return;
-    }
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      throw new Error(`Failed install destination ${root} is not an ordinary directory; it was preserved.`);
-    }
-    if (await fs.realpath(root) !== root) {
-      throw new Error(`Failed install destination ${root} resolves elsewhere; it was preserved.`);
-    }
-    if ((await fs.readdir(root)).length) {
-      if (!await this.checkoutExists(root)) {
-        throw new Error(`Failed install destination ${root} is not a complete Workbench checkout; it was preserved.`);
-      }
-      const git = await fs.lstat(path.join(root, ".git")).catch(error => {
-        if (error.code === "ENOENT") return null;
-        throw error;
-      });
-      if (!git?.isDirectory() || git.isSymbolicLink()) {
-        throw new Error(`Failed install destination ${root} is not a regular Git clone; it was preserved.`);
-      }
-      let changes = "";
-      await this.commands.run("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
-        cwd: root,
-        output: { write: bytes => { changes += bytes.toString(); } },
-        errorOutput: { write() {} },
-      });
-      if (changes.trim()) throw new Error(`Failed install destination ${root} has changes; it was preserved.`);
-    }
-    await fs.rm(root, { recursive: true });
-    await fs.unlink(this.registry);
-  }
-
   async run(args) {
     const managed = this.environment.WORKBENCH_THREAD_ID || this.environment.CODEX_THREAD_ID;
     const view = args[0] === "view" && (args.length === 1 || args.length === 2 && ["daemon", "app"].includes(args[1]));
@@ -159,7 +120,7 @@ export default class WorkbenchBootstrap {
     await this.requireTool("bash");
     const warning = installed?.phase === "ready"
       ? `\nNote: Previous installation at ${installed.root} no longer exists and will be recreated.`
-      : installed ? `\nNote: Incomplete install attempt at ${installed.root} will be removed.` : "";
+      : installed ? `\nResuming incomplete install at ${installed.root}.` : "";
     const choice = await this.prompt.choose(
       `Workbench is not installed. This command will provision a private Vite+ toolchain if needed, clone the repository, run build commands, and register wb through your package manager. Continue?${warning}`,
       ["Let's go!", "Cancel"],
@@ -194,33 +155,25 @@ export default class WorkbenchBootstrap {
       if (latest?.root !== installed?.root || latest?.phase !== installed?.phase) {
         throw new Error("The selected Workbench installation changed while setup was open. Run wb again.");
       }
-      if (latest && latest.phase !== "ready") await this.discardIncomplete(latest);
-      await this.requireEmptyDestination(root);
+      const resume = latest?.root === root && await this.checkoutExists(root);
+      if (!resume) await this.requireEmptyDestination(root);
+      // Recording before provisioning keeps the chosen location as the next default if anything fails.
+      await this.writeInstallation({ version: 1, root, phase: resume ? "setup" : "cloning" });
       await this.registration.prepare();
       await this.toolchain.ensure();
-      let record = { version: 1, root, phase: "cloning" };
-      await this.writeInstallation(record);
       await this.prompt.withHeader(async () => {
-        this.write(`Installing Workbench at ${root}\n`);
-        try {
+        this.write(`${resume ? "Resuming" : "Installing"} Workbench at ${root}\n`);
+        if (!resume) {
           // Install sandboxes substitute a local snapshot; ordinary installs clone the public repository.
           const repository = this.environment.WORKBENCH_INSTALL_REPOSITORY || "https://github.com/ErisInTheDark/workbench.git";
           await this.commands.run("git", ["clone", "--progress", "--branch", "main", "--single-branch", repository, root]);
           if (!await this.checkoutExists(root)) throw new Error("Clone did not produce a Workbench checkout.");
-          record = { ...record, phase: "setup" };
-          await this.writeInstallation(record);
-          await this.commands.run(process.execPath, [path.join(root, "scripts", "install.mjs"), "--prepare"], { cwd: root });
-          await this.registration.register(root);
-        } catch (error) {
-          try { await this.discardIncomplete(record); }
-          catch (cleanupError) {
-            throw new Error(`${error.message} Incomplete checkout was preserved at ${root}: ${cleanupError.message}`, { cause: error });
-          }
-          throw error;
+          await this.writeInstallation({ version: 1, root, phase: "setup" });
         }
+        await this.commands.run(process.execPath, [path.join(root, "scripts", "install.mjs"), "--prepare"], { cwd: root });
+        await this.registration.register(root);
       });
-      record = { ...record, phase: "ready" };
-      await this.writeInstallation(record);
+      await this.writeInstallation({ version: 1, root, phase: "ready" });
     } finally {
       // Closing the connection also releases the OS lock after normal completion;
       // process death releases it without a stale PID or lock-file recovery path.

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,14 +13,6 @@ import {
   parseStoreDefinitions,
 } from "./store-definitions.mjs";
 
-function warnDefault(message) {
-  process.emitWarning(message, "WorkbenchStoreWarning");
-}
-
-function isManagedAgentProcess() {
-  return Boolean(process.env.WORKBENCH_THREAD_ID?.trim() || process.env.CODEX_THREAD_ID?.trim());
-}
-
 function stripTerminalLineEnding(value) {
   return value.endsWith("\r\n") ? value.slice(0, -2) : value.endsWith("\n") ? value.slice(0, -1) : value;
 }
@@ -41,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) {
@@ -57,29 +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;
-  if (isManagedAgentProcess()) {
-    warn("Store lookups are disabled in Workbench-managed agent processes. Store references were left unchanged.");
-    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({
@@ -88,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.5",
+  "version": "0.0.7",
   "type": "module",
   "repository": {
     "type": "git",