@inthedark/wb 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+
+# workbench
+
+an agentic ide about the human
+
+## how 2 use
+```bash
+# install & open
+npx @inthedark/wb
+
+# set up daemon on another device
+npx @inthedark/wb connect
+```
+
+## features
+
+key features:
+- fully customisable agent instructions with support for comments & imports
+- strong thread transcript UX for when you need to keep an eye on a thread (command matching + html elements for agents)
+- strong thread management UX for when you're managing LOTS of threads (thread status-sorted sidebar)
+- better shared workspace support than any other agentic ide, because a lot of work is not worktree->pr shaped; agents claim the files they need and other agents don't freak out about unclaimed dirt
+- near-identical agent behaviour across providers (codex, opencode 2, claude code) as if they're the same harness
+- agents can orchestrate subagents working in threads across providers and projects
+- customisable voice to text ("what if voice to text was like working in a rich text editor")
+- git UI for doing your own work at the same time as other agents, allowing easy commits while agents have other files claimed
+- quickly switch between saved profiles for harness/model/effort/window/fast mode/agent identity
+- automatic compaction on turn start past configurable time & token thresholds (reduce cache write costs)
+- agents can search repos with shell tools like they're on disk via vfs
+
+setup/meta:
+- built on top of other harnesses (codex, opencode 2, claude code) so you can use subscriptions
+- tailscale integration
+- daemon sleeps when idle, leaving only a light http wake service up
+
+unpolished/unfinished/broken stuff (coming soon tm!!!!!):
+- soon, autocomplete/suggestions extension for vscode & similar (highly configurable, able to be FAST)
+- worktree->pr workflow is unsupported (gonna be honest i have been in a cave working solo on wb for so long that i have not needed this yet)
+- browse AX & UX
+- search UX
+- i'd like more git ui
+- many places around the app could use a UI polish pass
+- the codebase itself could use a polish pass, esp. the react & tailwind
+
+## tech
+
+note: have tried to keep dependencies minimal for the most part
+
+`/package` — the entrypoint/installer, what actually gets published to npm  
+`/daemon/host` — wake service  
+`/daemon/server` — workbench harness  
+`/daemon/voice` - vtt service (rust)  
+`/instructions` — instructions for agents, copied into the user's `~/.workbench` folder whenever read  
+`/app/server` — server for frontend app  
+`/app/client` — frontend SPA  
+`/app/tray` — system tray application for the frontend app (rust/tauri)  
+`/shared` — shared stuff between the projects  
+`/shared/network/native` — tailscale integration (go)  
+`/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

package/StoreCommandRunner.mjs

@@ -0,0 +1,50 @@
+/*
+ * Exports:
+ * - default StoreCommandRunner: run one store lookup argv without a shell and report bounded, sanitised outcomes.
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const PACKAGED_WB = path.join(path.dirname(fileURLToPath(import.meta.url)), "wb");
+
+export default class StoreCommandRunner {
+  constructor({ maxOutputBytes = MAX_OUTPUT_BYTES, packagedWb = PACKAGED_WB } = {}) {
+    this.maxOutputBytes = maxOutputBytes;
+    this.packagedWb = packagedWb;
+  }
+
+  /** Resolves `{ ok: true, stdout }` or `{ ok: false, reason, exitCode? }`; rejects only when `signal` aborts. */
+  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;
+    return await new Promise((resolve, reject) => {
+      const child = spawn(executable, args, { shell: false, signal, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+      const chunks = [];
+      let length = 0;
+      let overflow = false;
+      child.stdout.on("data", chunk => {
+        if (overflow) return;
+        length += chunk.length;
+        if (length > this.maxOutputBytes) {
+          overflow = true;
+          child.kill();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      child.once("error", error => {
+        if (signal?.aborted) reject(signal.reason);
+        else resolve({ ok: false, reason: error.code === "ENOENT" ? "missing-command" : "spawn-failed" });
+      });
+      child.once("close", exitCode => {
+        if (signal?.aborted) return reject(signal.reason);
+        if (overflow) return resolve({ ok: false, reason: "output-limit" });
+        if (exitCode !== 0) return resolve({ ok: false, reason: "exit", exitCode });
+        resolve({ ok: true, stdout: Buffer.concat(chunks).toString("utf8") });
+      });
+    });
+  }
+}

package/WorkbenchBootstrap.mjs

@@ -0,0 +1,240 @@
+/*
+ * Exports:
+ * - WorkbenchBootstrap (default): locates or installs an editable checkout and delegates to it.
+ */
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import WorkbenchBootstrapPrompt from "./WorkbenchBootstrapPrompt.mjs";
+import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
+
+export default class WorkbenchBootstrap {
+  constructor({
+    home = os.homedir(),
+    packageRoot = path.dirname(fileURLToPath(import.meta.url)),
+    environment = process.env,
+    prompt = new WorkbenchBootstrapPrompt(),
+    commands = new WorkbenchBootstrapCommand(),
+    write = text => process.stdout.write(text),
+  } = {}) {
+    this.home = home;
+    this.packageRoot = packageRoot;
+    this.environment = environment;
+    this.prompt = prompt;
+    this.commands = commands;
+    this.write = write;
+    this.registry = path.join(home, ".workbench", "installation.json");
+  }
+
+  async checkoutExists(root) {
+    try {
+      const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+      if (manifest.name !== "workbench-root") return false;
+      await fs.access(path.join(root, "wb"));
+      await fs.access(path.join(root, "installation", "install.mjs"));
+      await fs.access(path.join(root, "cli", "dispatch.mjs"));
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  async checkoutState(root) {
+    if (await this.checkoutExists(root)) return "usable";
+    try {
+      await fs.lstat(root);
+      return "invalid";
+    } catch (error) {
+      if (error.code === "ENOENT") return "missing";
+      throw error;
+    }
+  }
+
+  async readInstallation() {
+    try {
+      const record = JSON.parse(await fs.readFile(this.registry, "utf8"));
+      if (record.version !== 1 || typeof record.root !== "string" || !path.isAbsolute(record.root)
+        || !["cloning", "setup", "ready"].includes(record.phase)) {
+        throw new Error(`Invalid Workbench installation record: ${this.registry}. Existing files were not changed.`);
+      }
+      return record;
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async writeInstallation(record) {
+    const candidate = `${this.registry}.${randomUUID()}.tmp`;
+    await fs.writeFile(candidate, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await fs.rename(candidate, this.registry);
+  }
+
+  async requireTool(command, cwd) {
+    try {
+      await this.commands.run(command, ["--version"], {
+        cwd,
+        output: { write() {} },
+        errorOutput: { write() {} },
+      });
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      throw new Error(`${command} is required to install Workbench. Install it and make it available on PATH, then retry.`, { cause: error });
+    }
+  }
+
+  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]));
+    const humanCommand = view || args.length === 0 || (args.length === 1 && ["connect", "disconnect", "shortcut"].includes(args[0]));
+    if (managed && humanCommand) throw new Error("Managed threads cannot install or launch Workbench services.");
+    const linked = path.resolve(this.packageRoot, "..");
+    if (await this.checkoutExists(linked)) {
+      return await this.delegate(linked, args);
+    }
+    const installed = await this.readInstallation();
+    if (installed?.phase === "ready") {
+      const state = await this.checkoutState(installed.root);
+      if (state === "usable") return await this.delegate(installed.root, args);
+      if (state === "invalid") {
+        throw new Error(`Workbench checkout is unavailable at ${installed.root}. Restore or repair that installation; no replacement was created.`);
+      }
+    }
+    if (managed || !(args.length === 0 || (args.length === 1 && args[0] === "connect"))) {
+      throw new Error("Workbench is not installed. Run wb or wb connect in an interactive terminal first.");
+    }
+    await this.requireTool("git");
+    await this.requireTool("bash");
+    await this.requireTool("vp");
+    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.` : "";
+    const choice = await this.prompt.choose(
+      `Workbench is not installed. This command will clone the repository and run build commands. It may take 1-2 minutes. Continue?${warning}`,
+      ["Let's go!", "Cancel"],
+    );
+    if (choice !== "Let's go!") throw new DOMException("Setup cancelled.", "AbortError");
+    const defaultRoot = installed?.root ?? (process.platform === "win32"
+      ? path.join(this.environment.LOCALAPPDATA || path.join(this.home, "AppData", "Local"), "Programs", "inthedark", "wb")
+      : path.join(this.home, ".local", "lib", "inthedark", "wb"));
+    const root = path.resolve(await this.prompt.location("Install location", defaultRoot));
+    await fs.mkdir(path.dirname(this.registry), { recursive: true });
+    const lockPath = `${this.registry}.lock.sqlite3`;
+    const lock = new DatabaseSync(lockPath);
+    try {
+      lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
+    } catch (error) {
+      lock.close();
+      if (error.errcode === 5 || error.errcode === 6) {
+        throw new Error("Another Workbench installation is running. Let it finish before trying again.");
+      }
+      throw error;
+    }
+    try {
+      // Another invocation may have finished while this one was accepting input.
+      const latest = await this.readInstallation();
+      if (latest?.phase === "ready") {
+        const state = await this.checkoutState(latest.root);
+        if (state === "usable") return await this.delegate(latest.root, args);
+        if (state === "invalid") {
+          throw new Error(`Workbench checkout is unavailable at ${latest.root}. Restore or repair that installation; no replacement was created.`);
+        }
+      }
+      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);
+      let record = { version: 1, root, phase: "cloning" };
+      await this.writeInstallation(record);
+      await this.prompt.withHeader(async () => {
+        this.write(`Installing Workbench at ${root}\n`);
+        try {
+          // 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, "installation", "install.mjs"), "--prepare"], { cwd: 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;
+        }
+      });
+      record = { ...record, phase: "ready" };
+      await this.writeInstallation(record);
+    } 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.
+      lock.close();
+    }
+    // Persist readiness before optional platform actions: missing native artifacts
+    // must not turn a usable source installation into an endless setup loop.
+    await this.commands.run(process.execPath, [path.join(root, "installation", "install.mjs"),
+      args[0] === "connect" ? "--connect" : "--welcome"], { cwd: root, interactive: true });
+  }
+
+  async delegate(root, args) {
+    return await this.commands.run(process.execPath, [path.join(root, "cli", "dispatch.mjs"), ...args], { interactive: true });
+  }
+
+  async requireEmptyDestination(root) {
+    try {
+      if ((await fs.readdir(root)).length) throw new Error(`Installation destination must be empty: ${root}. Existing files were preserved.`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await fs.mkdir(path.dirname(root), { recursive: true });
+    await fs.access(path.dirname(root), constants.W_OK);
+  }
+}

package/WorkbenchBootstrapCommand.mjs

@@ -0,0 +1,140 @@
+/*
+ * Exports:
+ * - WorkbenchBootstrapCommand (default): owns bootstrap child commands, Windows executable lookup (including Git Bash), and failures.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export default class WorkbenchBootstrapCommand {
+  constructor({ output = process.stdout, errorOutput = process.stderr, environment = process.env } = {}) {
+    this.output = output;
+    this.errorOutput = errorOutput;
+    this.environment = environment;
+  }
+
+  /** Environment variable by name; Windows names are case-insensitive, but copied env objects are not. */
+  variable(name) {
+    if (process.platform !== "win32") return this.environment[name];
+    const key = Object.keys(this.environment).find(candidate => candidate.toLowerCase() === name.toLowerCase());
+    return key === undefined ? undefined : this.environment[key];
+  }
+
+  async resolve(command) {
+    if (process.platform === "win32" && command === "bash") return [await this.resolveBash()];
+    if (process.platform !== "win32" || !["npm", "pnpm"].includes(command)) return [command];
+    const directories = [path.dirname(process.execPath), ...(this.variable("PATH") || "").split(path.delimiter)];
+    for (const directory of directories) {
+      if (!directory) continue;
+      const executable = path.join(directory, `${command}.exe`);
+      try {
+        await fs.access(executable);
+        return [executable];
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      // npm/pnpm's Windows cmd wrappers cannot safely forward arbitrary paths.
+      // Invoke their installed Node entry instead of adding a command-shell layer.
+      const entry = command === "npm" ? "npm/bin/npm-cli.js" : "pnpm/bin/pnpm.cjs";
+      const script = path.join(directory, "node_modules", entry);
+      try {
+        await fs.access(script);
+        return [process.execPath, script];
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    throw new Error(`Cannot locate ${command}'s executable or Node entry. Install ${command} and ensure it is on PATH.`);
+  }
+
+  /**
+   * Windows bash that can run Workbench. Git for Windows usually puts only git on PATH, and the
+   * bash.exe Windows does find is often WSL's launcher, which runs scripts inside Linux.
+   */
+  async resolveBash() {
+    const exists = async file => {
+      try { await fs.access(file); return true; }
+      catch (error) { if (error.code === "ENOENT") return false; throw error; }
+    };
+    const directories = (this.variable("PATH") || "").split(path.delimiter).filter(Boolean);
+    const local = this.variable("LOCALAPPDATA");
+    const launchers = [
+      path.join(this.variable("SystemRoot") || "C:\\Windows", "System32"),
+      ...(local ? [path.join(local, "Microsoft", "WindowsApps")] : []),
+    ].map(directory => path.resolve(directory).toLowerCase());
+    let sawLauncher = false;
+    for (const directory of directories) {
+      const bash = path.join(directory, "bash.exe");
+      if (!await exists(bash)) continue;
+      if (launchers.includes(path.resolve(directory).toLowerCase())) sawLauncher = true;
+      else return bash;
+    }
+    // git.exe lives in Git\cmd, Git\bin or Git\mingw64\bin; Git Bash is always Git\bin\bash.exe.
+    for (const directory of directories) {
+      if (!await exists(path.join(directory, "git.exe"))) continue;
+      const parent = path.dirname(directory);
+      const root = path.basename(parent).toLowerCase() === "mingw64" ? path.dirname(parent) : parent;
+      const bash = path.join(root, "bin", "bash.exe");
+      if (await exists(bash)) return bash;
+    }
+    for (const base of [this.variable("ProgramFiles"), local && path.join(local, "Programs")]) {
+      if (!base) continue;
+      const bash = path.join(base, "Git", "bin", "bash.exe");
+      if (await exists(bash)) return bash;
+    }
+    throw new Error(`Workbench needs Git Bash on Windows.${sawLauncher ? " The bash on PATH is WSL's, which cannot run Workbench." : ""} Install Git for Windows, then retry.`);
+  }
+
+  async run(command, args, { cwd, signal, onOutput, environment = {}, output = this.output, errorOutput = this.errorOutput, interactive = false } = {}) {
+    signal?.throwIfAborted();
+    const [executable, ...prefix] = await this.resolve(command);
+    signal?.throwIfAborted();
+    return await new Promise((resolve, reject) => {
+      const child = spawn(executable, [...prefix, ...args], {
+        cwd,
+        env: { ...this.environment, ...environment },
+        windowsHide: true,
+        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+        signal,
+      });
+      let failure;
+      const relay = signal => { child.kill(signal); };
+      const interrupt = () => relay("SIGINT");
+      const terminate = () => relay("SIGTERM");
+      const hangup = () => relay("SIGHUP");
+      if (interactive) {
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", terminate);
+        process.on("SIGHUP", hangup);
+      }
+      child.on("error", error => { failure = error; });
+      const forward = (stream, output) => {
+        stream.on("data", bytes => {
+          output.write(bytes);
+          if (onOutput) {
+            try { onOutput(bytes.toString()); }
+            catch (error) { failure = error; child.kill(); }
+          }
+        });
+      };
+      if (!interactive) {
+        forward(child.stdout, output);
+        forward(child.stderr, errorOutput);
+      }
+      child.once("close", (code, exitSignal) => {
+        if (interactive) {
+          process.off("SIGINT", interrupt);
+          process.off("SIGTERM", terminate);
+          process.off("SIGHUP", hangup);
+        }
+        if (failure?.code === "ENOENT") {
+          reject(Object.assign(new Error(`Cannot start ${command}: executable not found. Install it and make it available on PATH, then retry.`, { cause: failure }), {
+            code: "ENOENT",
+          }));
+        } else if (failure) reject(failure);
+        else if (code === 0) resolve();
+        else reject(Object.assign(new Error(`${command} failed with ${exitSignal ? `signal ${exitSignal}` : `status ${code ?? "unknown"}`}.`), { exitCode: code ?? 1 }));
+      });
+    });
+  }
+}

package/WorkbenchBootstrapPrompt.mjs

@@ -0,0 +1,71 @@
+/*
+ * Exports:
+ * - WorkbenchBootstrapPrompt (default): owns the stable dependency-free consent and destination prompts used before cloning.
+ */
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+export default class WorkbenchBootstrapPrompt {
+  constructor({
+    input = process.stdin,
+    output = process.stdout,
+    platform = process.platform,
+    cwd = process.cwd(),
+    home = os.homedir(),
+    ask,
+  } = {}) {
+    this.input = input;
+    this.output = output;
+    this.paths = platform === "win32" ? path.win32 : path.posix;
+    this.windows = platform === "win32";
+    this.cwd = cwd;
+    this.home = home;
+    this.ask = ask ?? (question => this.question(question));
+  }
+
+  suffix(value) {
+    const name = this.paths.basename(value);
+    const comparable = this.windows ? name.toLowerCase() : name;
+    if (comparable === "wb" || comparable === "workbench") return "";
+    return `${value.endsWith(this.paths.sep) || (this.windows && value.endsWith("/")) ? "" : this.paths.sep}wb`;
+  }
+
+  destination(value) {
+    if (!value.trim()) throw new Error("Choose an installation directory.");
+    if (/[\u0000-\u001f\u007f]/u.test(value)) throw new Error("Installation paths cannot contain control characters.");
+    const expanded = value === "~" ? this.home
+      : value.startsWith("~/") || (this.windows && value.startsWith("~\\"))
+        ? this.paths.join(this.home, value.slice(2)) : value;
+    return this.paths.resolve(this.cwd, `${expanded}${this.suffix(expanded)}`);
+  }
+
+  async choose(label, choices) {
+    if (!choices.length) throw new Error("A setup choice needs options.");
+    const options = choices.map((choice, index) => `${index + 1}) ${choice}`).join("  ");
+    while (true) {
+      const answer = (await this.ask(`${label}\n${options}\nChoose [1]: `)).trim();
+      const selected = answer === "" ? 0 : Number(answer) - 1;
+      if (Number.isInteger(selected) && selected >= 0 && selected < choices.length) return choices[selected];
+      this.output.write(`Choose a number from 1 to ${choices.length}.\n`);
+    }
+  }
+
+  async location(label, initialValue) {
+    const answer = await this.ask(`${label} [${initialValue}]: `);
+    return this.destination(answer.trim() || initialValue);
+  }
+
+  withHeader(task) {
+    return task();
+  }
+
+  async question(text) {
+    if (!this.input.isTTY || !this.output.isTTY) {
+      throw new Error("Workbench setup needs an interactive terminal; no changes were accepted.");
+    }
+    const terminal = createInterface({ input: this.input, output: this.output });
+    try { return await terminal.question(text); }
+    finally { terminal.close(); }
+  }
+}

package/index.d.ts

@@ -0,0 +1,25 @@
+/*
+ * Exports:
+ * - WorkbenchConfigOptions: dotenv-compatible loading options plus 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.
+ */
+export interface WorkbenchConfigOptions {
+  /** One file or several; earlier files win unless `override` is set. Defaults to `.env`. */
+  path?: string | readonly string[];
+  encoding?: BufferEncoding;
+  /** Replace variables already present in `processEnv`, as dotenv does. */
+  override?: boolean;
+  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`. */
+  warn?: (message: string) => void;
+}
+
+export interface WorkbenchConfigOutput {
+  parsed: Record<string, string>;
+  error?: Error;
+}
+
+export function config(options?: WorkbenchConfigOptions): Promise<WorkbenchConfigOutput>;

package/index.mjs

@@ -0,0 +1,100 @@
+/*
+ * Exports:
+ * - config: load dotenv files, then replace resolvable `${store:key}` references through named WB_STORES commands.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import dotenv from "dotenv";
+import StoreCommandRunner from "./StoreCommandRunner.mjs";
+import {
+  DEFAULT_STORE_DEFINITIONS,
+  expandStoreCommand,
+  findStoreReferences,
+  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;
+}
+
+async function readParsed(paths, encoding, override) {
+  const parsed = {};
+  let error;
+  for (const file of paths) {
+    try {
+      const values = dotenv.parse(await fs.readFile(path.resolve(file), { encoding }));
+      for (const [name, value] of Object.entries(values)) {
+        if (override || !Object.hasOwn(parsed, name)) parsed[name] = value;
+      }
+    } catch (failure) {
+      error ??= failure;
+    }
+  }
+  return { parsed, error };
+}
+
+async function resolveReferences(parsed, definitions, { runner, signal, warn }) {
+  let stores;
+  try {
+    stores = parseStoreDefinitions(definitions);
+  } catch (failure) {
+    warn(`${failure.message} Store references were left unchanged.`);
+    return parsed;
+  }
+  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) {
+      const id = JSON.stringify([store, key]);
+      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.`);
+    }
+    return [id, result];
+  })));
+  return 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]));
+      next += value.slice(cursor, reference.start) + (result?.ok ? stripTerminalLineEnding(result.stdout) : reference.text);
+      cursor = reference.end;
+    }
+    return [name, next + value.slice(cursor)];
+  }));
+}
+
+export async function config({
+  path: paths = ".env",
+  encoding = "utf8",
+  override = false,
+  processEnv = process.env,
+  signal,
+  warn = warnDefault,
+  runner = new StoreCommandRunner(),
+} = {}) {
+  signal?.throwIfAborted();
+  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 });
+  return error ? { parsed, error } : { parsed };
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@inthedark/wb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ErisInTheDark/workbench.git",
+    "directory": "package"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "wb": "./wb"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "files": [
+    "wb",
+    "WorkbenchBootstrap.mjs",
+    "WorkbenchBootstrapCommand.mjs",
+    "WorkbenchBootstrapPrompt.mjs",
+    "index.mjs",
+    "index.d.ts",
+    "store-definitions.mjs",
+    "StoreCommandRunner.mjs",
+    "README.md"
+  ],
+  "dependencies": {
+    "dotenv": "^18.0.4"
+  }
+}

package/store-definitions.mjs

@@ -0,0 +1,91 @@
+/*
+ * Exports:
+ * - DEFAULT_STORE_DEFINITIONS: fallback WB_STORES text used when a file defines none.
+ * - parseStoreDefinitions: tokenise WB_STORES text into named argv templates without shell semantics.
+ * - expandStoreCommand: substitute one key into a template's arguments after tokenisation.
+ * - findStoreReferences: list `${store:key}` references in one value.
+ */
+
+export const DEFAULT_STORE_DEFINITIONS = "wb: wb store get {key}";
+
+const STORE_NAME = /^[A-Za-z0-9_-]+$/u;
+const REFERENCE = /\$\{([A-Za-z0-9_-]+):([^}\r\n]+)\}/gu;
+
+function tokenise(text) {
+  const definitions = [];
+  let tokens = [];
+  let token = "";
+  let started = false;
+  let quoted = false;
+  let quotedToken = false;
+  const endToken = () => {
+    if (started) tokens.push({ text: token, quoted: quotedToken });
+    token = "";
+    started = false;
+    quotedToken = false;
+  };
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quoted) {
+      if (character === "\\" && (text[index + 1] === "\"" || text[index + 1] === "\\")) {
+        token += text[index + 1];
+        index += 1;
+      } else if (character === "\"") {
+        quoted = false;
+      } else {
+        token += character;
+      }
+      continue;
+    }
+    if (character === "\"") {
+      quoted = true;
+      started = true;
+      quotedToken = true;
+    } else if (character === ";") {
+      endToken();
+      definitions.push(tokens);
+      tokens = [];
+    } else if (/\s/u.test(character)) {
+      endToken();
+    } else {
+      token += character;
+      started = true;
+    }
+  }
+  if (quoted) throw new Error("WB_STORES has an unterminated double quote.");
+  endToken();
+  definitions.push(tokens);
+  return definitions.filter(definition => definition.length);
+}
+
+export function parseStoreDefinitions(text) {
+  const stores = new Map();
+  for (const tokens of tokenise(text)) {
+    const [first, ...rest] = tokens;
+    const separator = first.quoted ? -1 : first.text.indexOf(":");
+    const name = separator > 0 ? first.text.slice(0, separator) : "";
+    if (!STORE_NAME.test(name)) throw new Error("Each WB_STORES entry must start with a store name followed by a colon.");
+    if (stores.has(name)) throw new Error(`WB_STORES defines the ${name} store more than once.`);
+    const remainder = first.text.slice(separator + 1);
+    const argv = [...(remainder ? [remainder] : []), ...rest.map(token => token.text)];
+    if (!argv.length) throw new Error(`WB_STORES gives the ${name} store no command.`);
+    if (argv[0].includes("{key}")) throw new Error(`WB_STORES cannot place {key} in the ${name} store's executable.`);
+    stores.set(name, argv);
+  }
+  return stores;
+}
+
+export function expandStoreCommand(template, key) {
+  const [executable, ...args] = template;
+  return [executable, ...args.map(arg => arg.replaceAll("{key}", key))];
+}
+
+export function findStoreReferences(value) {
+  return Array.from(value.matchAll(REFERENCE), match => ({
+    end: match.index + match[0].length,
+    key: match[2],
+    start: match.index,
+    store: match[1],
+    text: match[0],
+  }));
+}

package/wb

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/*
+ * No exports. Dependency-free npm entry locates an editable Workbench installation.
+ */
+import WorkbenchBootstrap from "./WorkbenchBootstrap.mjs";
+
+try { await new WorkbenchBootstrap().run(process.argv.slice(2)); }
+catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+}