@inthedark/wb 0.0.4 → 0.0.6

package/README.md

@@ -4,6 +4,15 @@
 an agentic ide about the human
 
 ## how 2 use
+
+you need to install these yourself first:
+1. [git](https://git-scm.com/)
+2. node, through whatever you like. [vite+](https://viteplus.dev/) recommended
+
+optional:
+1. [tailscale](https://tailscale.com/), if you want to connect to workbench agents on other devices
+
+and then workbench itself is just:
 ```bash
 # install & open
 npx @inthedark/wb
@@ -48,7 +57,9 @@ 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)  
+`/daemon/voice` — vtt service (rust)  
+`/daemon/repo` — vfs service (go)
+`/integration` — integrations in third party software
 `/instructions` — instructions for agents, copied into the user's `~/.workbench` folder whenever read  
 `/app/server` — server for frontend app  
 `/app/client` — frontend SPA  

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

@@ -11,21 +11,29 @@ import { fileURLToPath } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import WorkbenchInstallPrompt from "./WorkbenchInstallPrompt.mjs";
 import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
+import WorkbenchToolchain from "./WorkbenchToolchain.mjs";
+import WorkbenchPackageRegistration from "./WorkbenchPackageRegistration.mjs";
 
 export default class WorkbenchBootstrap {
   constructor({
     home = os.homedir(),
     packageRoot = path.dirname(fileURLToPath(import.meta.url)),
     environment = process.env,
+    platform = process.platform,
     prompt = new WorkbenchInstallPrompt(),
-    commands = new WorkbenchBootstrapCommand(),
+    commands = new WorkbenchBootstrapCommand({ environment }),
+    toolchain = new WorkbenchToolchain({ home, environment, commands }),
+    registration = new WorkbenchPackageRegistration({ home, environment, packageRoot }),
     write = text => process.stdout.write(text),
   } = {}) {
     this.home = home;
     this.packageRoot = packageRoot;
     this.environment = environment;
+    this.platform = platform;
     this.prompt = prompt;
     this.commands = commands;
+    this.toolchain = toolchain;
+    this.registration = registration;
     this.write = write;
     this.registry = path.join(home, ".workbench", "installation.json");
   }
@@ -35,7 +43,7 @@ export default class WorkbenchBootstrap {
       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, "scripts", "install.mjs"));
       await fs.access(path.join(root, "cli", "dispatch.mjs"));
       return true;
     } catch (error) {
@@ -88,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]));
@@ -151,12 +118,11 @@ export default class WorkbenchBootstrap {
     }
     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.` : "";
+      : installed ? `\nResuming incomplete install at ${installed.root}.` : "";
     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}`,
+      `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"],
     );
     if (choice !== "Let's go!") throw new DOMException("Setup cancelled.", "AbortError");
@@ -189,30 +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);
-      let record = { version: 1, root, phase: "cloning" };
-      await this.writeInstallation(record);
+      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();
       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, "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;
+          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.
@@ -220,7 +181,7 @@ export default class WorkbenchBootstrap {
     }
     // 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"),
+    await this.commands.run(process.execPath, [path.join(root, "scripts", "install.mjs"),
       args[0] === "connect" ? "--connect" : "--welcome"], { cwd: root, interactive: true });
   }
 

package/WorkbenchBootstrapCommand.mjs

@@ -20,9 +20,39 @@ export default class WorkbenchBootstrapCommand {
     return key === undefined ? undefined : this.environment[key];
   }
 
+  environmentFor(overrides = {}) {
+    const environment = { ...this.environment };
+    for (const [name, value] of Object.entries(overrides)) {
+      for (const key of Object.keys(environment)) {
+        if (key === name || process.platform === "win32" && key.toLowerCase() === name.toLowerCase()) delete environment[key];
+      }
+      if (value !== undefined && value !== null) environment[name] = value;
+    }
+    return environment;
+  }
+
+  async findExecutable(command) {
+    const names = process.platform === "win32" ? [`${command}.exe`] : [command];
+    for (const directory of (this.variable("PATH") || "").split(path.delimiter).filter(Boolean)) {
+      for (const name of names) {
+        const candidate = path.resolve(directory, name);
+        try {
+          const stat = await fs.stat(candidate);
+          if (stat.isFile()) return candidate;
+        } catch (error) {
+          if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+        }
+      }
+    }
+    return null;
+  }
+
   async resolve(command) {
     if (process.platform === "win32" && command === "bash") return [await this.resolveBash()];
-    if (process.platform !== "win32" || !["npm", "pnpm"].includes(command)) return [command];
+    if (!["npm", "pnpm"].includes(command)) return [command];
+    const direct = await this.findExecutable(command);
+    if (direct) return [direct];
+    if (process.platform !== "win32") throw Object.assign(new Error(`${command} is unavailable on PATH.`), { code: "ENOENT" });
     const directories = [path.dirname(process.execPath), ...(this.variable("PATH") || "").split(path.delimiter)];
     for (const directory of directories) {
       if (!directory) continue;
@@ -92,7 +122,7 @@ export default class WorkbenchBootstrapCommand {
     return await new Promise((resolve, reject) => {
       const child = spawn(executable, [...prefix, ...args], {
         cwd,
-        env: { ...this.environment, ...environment },
+        env: this.environmentFor(environment),
         windowsHide: true,
         stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
         signal,

package/WorkbenchPackageRegistration.mjs

@@ -0,0 +1,184 @@
+/*
+ * Exports:
+ * - WorkbenchPackageRegistration (default): capture the invoking package manager and register wb in its public global bin.
+ */
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
+
+const managers = {
+  npm: {
+    binArgs: ["prefix", "--global"],
+    packageArgs: ["root", "--global"],
+    packagePaths: roots => roots.map(root => path.join(root, "@inthedark", "wb")),
+    bin: prefix => process.platform === "win32" ? prefix : path.join(prefix, "bin"),
+    install: (root, prefix) => ["install", "--global", "--prefix", prefix, path.join(root, "package")],
+  },
+  pnpm: {
+    binArgs: ["bin", "--global"],
+    packageArgs: ["list", "--global", "--parseable", "@inthedark/wb"],
+    packagePaths: roots => roots.slice(1),
+    bin: directory => directory,
+    install: root => ["add", "--global", path.join(root, "package")],
+  },
+};
+
+export default class WorkbenchPackageRegistration {
+  constructor({
+    environment = process.env, home = os.homedir(), nodePath = process.execPath,
+    packageRoot = path.dirname(fileURLToPath(import.meta.url)),
+    commands = new WorkbenchBootstrapCommand({ environment: { ...environment } }),
+  } = {}) {
+    this.commands = commands;
+    this.home = home;
+    this.nodePath = nodePath;
+    this.packageRoot = packageRoot;
+  }
+
+  async capture() {
+    const userAgent = this.commands.variable("npm_config_user_agent");
+    const identity = userAgent?.match(/^([a-z]+)(?:\/|\s|$)/iu)?.[1]?.toLowerCase();
+    const entry = this.commands.variable("npm_execpath");
+    const entryIdentity = entry && /(?:^|[/\\])(npm-cli\.js|npx-cli\.js|pnpm(?:\.cjs|\.js|\.exe)?)$/iu.exec(entry)?.[1];
+    const identified = entryIdentity && (entryIdentity.toLowerCase().startsWith("pnpm") ? "pnpm" : "npm");
+    if (identity && !Object.hasOwn(managers, identity)) {
+      throw new Error(`Automatic wb registration supports npm and pnpm, not ${identity}. Run npx @inthedark/wb or pnpm dlx @inthedark/wb.`);
+    }
+    if (identity && identified && identity !== identified) {
+      throw new Error("Invoking package-manager metadata conflicts. Run Workbench directly with npx or pnpm dlx.");
+    }
+    const name = identity ?? identified ?? "npm";
+    let command;
+    if (entry && identified === name) {
+      if (!path.isAbsolute(entry)) throw new Error("Invoking package-manager executable must be an absolute path.");
+      await fs.access(entry);
+      command = /\.(?:cjs|mjs|js)$/iu.test(entry) ? [this.nodePath, entry] : [entry];
+    } else {
+      command = await this.commands.resolve(name);
+    }
+    return { name, command };
+  }
+
+  async execute(selection, args, options = {}) {
+    const [command, ...prefix] = selection.command;
+    return this.commands.run(command, [...prefix, ...args], { cwd: this.home, ...options });
+  }
+
+  async reportPaths(selection, args) {
+    let output = "";
+    await this.execute(selection, args, { output: { write: bytes => { output += bytes.toString(); } } });
+    const locations = output.trim().split(/\r?\n/u);
+    if (locations.some(location => !location || !path.isAbsolute(location))) {
+      throw new Error(`${selection.name} did not report absolute global installation paths.`);
+    }
+    return locations;
+  }
+
+  async destination(selection) {
+    const locations = await this.reportPaths(selection, managers[selection.name].binArgs);
+    if (locations.length !== 1) throw new Error(`${selection.name} reported more than one global bin directory.`);
+    const [location] = locations;
+    return { prefix: location, bin: managers[selection.name].bin(location) };
+  }
+
+  async checkWritable(directory) {
+    let current = directory;
+    while (true) {
+      try {
+        await fs.access(current, constants.W_OK);
+        return;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw new Error(`The package manager's global bin is not writable: ${directory}. Fix its permissions or configure a user-owned global prefix.`, { cause: error });
+        const parent = path.dirname(current);
+        if (parent === current) throw error;
+        current = parent;
+      }
+    }
+  }
+
+  samePath(left, right) {
+    const normalise = value => process.platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value);
+    return normalise(left) === normalise(right);
+  }
+
+  async publicCommand(bin) {
+    for (const name of process.platform === "win32" ? ["wb.exe", "wb.cmd", "wb.bat", "wb"] : ["wb"]) {
+      const candidate = path.join(bin, name);
+      try {
+        if ((await fs.stat(candidate)).isFile()) return candidate;
+      } catch (error) {
+        if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+      }
+    }
+    return null;
+  }
+
+  async checkExistingCommand(bin) {
+    const command = await this.publicCommand(bin);
+    if (!command) return;
+    const manager = managers[this.selection.name];
+    const roots = await this.reportPaths(this.selection, manager.packageArgs);
+    for (const packageRoot of manager.packagePaths(roots)) {
+      try {
+        const manifest = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+        if (manifest.name === "@inthedark/wb" && manifest.bin?.wb === "wb") {
+          await fs.access(path.join(packageRoot, "wb"));
+          return;
+        }
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    throw new Error(`The global bin already contains ${command}, but ${this.selection.name} does not own a Workbench package there. Resolve that conflict before installing.`);
+  }
+
+  async checkPath(bin) {
+    const directories = (this.commands.variable("PATH") || "").split(path.delimiter).filter(Boolean);
+    if (!directories.some(directory => this.samePath(directory, bin))) {
+      throw new Error(`${bin} is ${this.selection.name}'s global bin but is not on PATH. Add that directory to your PATH, open a new terminal, and retry.`);
+    }
+    const names = process.platform === "win32" ? ["wb.exe", "wb.cmd", "wb.bat", "wb"] : ["wb"];
+    const ownEntry = await fs.realpath(path.join(this.packageRoot, "wb"));
+    for (const directory of directories) {
+      if (this.samePath(directory, bin)) {
+        await this.checkExistingCommand(bin);
+        return;
+      }
+      for (const name of names) {
+        const candidate = path.join(directory, name);
+        let target;
+        try { target = await fs.realpath(candidate); }
+        catch (error) { if (error.code === "ENOENT" || error.code === "ENOTDIR") continue; throw error; }
+        if (this.samePath(target, ownEntry)) continue;
+        // npm's npx Windows wrappers sit beside the package's node_modules entry.
+        const injected = path.join(directory, "..", "@inthedark", "wb", "wb");
+        try {
+          if (this.samePath(await fs.realpath(injected), ownEntry)) continue;
+        } catch (error) { if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error; }
+        throw new Error(`Another wb command at ${candidate} precedes ${bin} on PATH. Resolve that conflict before installing; it was not changed.`);
+      }
+    }
+  }
+
+  async prepare() {
+    const selection = await this.capture();
+    const destination = await this.destination(selection);
+    this.selection = { ...selection, ...destination };
+    await this.checkPath(destination.bin);
+    await this.checkWritable(destination.bin);
+  }
+
+  async register(root) {
+    if (!this.selection) throw new Error("Package registration must be checked before installing Workbench.");
+    const current = await this.destination(this.selection);
+    if (!this.samePath(current.bin, this.selection.bin) || !this.samePath(current.prefix, this.selection.prefix)) {
+      throw new Error("The package manager's global destination changed during installation. Run Workbench again.");
+    }
+    await this.execute(this.selection, managers[this.selection.name].install(root, this.selection.prefix));
+    if (!await this.publicCommand(this.selection.bin)) throw new Error(`${this.selection.name} did not register the public wb command in ${this.selection.bin}.`);
+    await this.checkPath(this.selection.bin);
+  }
+}

package/WorkbenchToolchain.mjs

@@ -0,0 +1,185 @@
+/*
+ * Exports:
+ * - WorkbenchToolchain (default): persist Vite+ selection and own isolated provisioning and pinned child environments.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
+import resolveWorkbenchDataRoot from "./workbench-data-root.mjs";
+import installVitePlus from "./vite-plus-installer.mjs";
+
+const directoryVariables = ["VP_HOME", "VP_BIN_DIR", "VP_DATA_DIR", "VP_CACHE_DIR",
+  "XDG_DATA_HOME", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_STATE_HOME"];
+const versionVariables = ["VP_NODE_VERSION", "VP_PACKAGE_MANAGER", "VP_NPM_VERSION",
+  "VP_PNPM_VERSION", "VP_YARN_VERSION", "VP_BUN_VERSION", "VP_BYPASS"];
+
+export default class WorkbenchToolchain {
+  constructor({
+    environment = process.env, home = os.homedir(),
+    dataRoot = resolveWorkbenchDataRoot({ environment, homeDirectory: home }),
+    commands = new WorkbenchBootstrapCommand({ environment }), install = installVitePlus,
+  } = {}) {
+    this.commands = commands;
+    this.environment = environment;
+    this.dataRoot = path.resolve(dataRoot);
+    this.directory = path.join(this.dataRoot, "installation");
+    this.receipt = path.join(this.directory, "toolchain.json");
+    this.managedHome = path.join(this.dataRoot, "toolchain");
+    this.install = install;
+  }
+
+  async read() {
+    let text;
+    try { text = await fs.readFile(this.receipt, "utf8"); }
+    catch (error) { if (error.code === "ENOENT") return null; throw error; }
+    let record;
+    try { record = JSON.parse(text); }
+    catch (error) { throw new Error(`Invalid toolchain receipt: ${this.receipt}. It was preserved.`, { cause: error }); }
+    if (record?.version !== 1 || typeof record.ready !== "boolean" || !["managed", "external"].includes(record.kind)
+      || record.kind === "external" && !record.ready
+      || typeof record.executable !== "string" || !path.isAbsolute(record.executable)
+      || !record.environment || typeof record.environment !== "object" || Array.isArray(record.environment)
+      || Object.keys(record.environment).some(name => !directoryVariables.includes(name))
+      || directoryVariables.some(name => !(record.environment[name] === null
+        || typeof record.environment[name] === "string" && path.isAbsolute(record.environment[name])))) {
+      throw new Error(`Invalid toolchain receipt: ${this.receipt}. It was preserved.`);
+    }
+    if (record.kind === "managed" && (record.environment.VP_HOME !== this.managedHome
+      || record.executable !== this.managedExecutable())) {
+      throw new Error(`Managed toolchain receipt points outside its owned location: ${this.receipt}.`);
+    }
+    return record;
+  }
+
+  managedExecutable() {
+    return path.join(this.managedHome, "bin", process.platform === "win32" ? "vp.exe" : "vp");
+  }
+
+  selection(executable, kind) {
+    const environment = Object.fromEntries(directoryVariables.map(name => {
+      const value = this.commands.variable(name)?.trim();
+      if (value && !path.isAbsolute(value) && name.startsWith("VP_")) {
+        throw new Error(`${name} must be an absolute path to persist the Vite+ environment.`);
+      }
+      return [name, value && path.isAbsolute(value) ? value : null];
+    }));
+    if (kind === "managed") {
+      for (const name of directoryVariables.filter(name => name.startsWith("VP_"))) environment[name] = null;
+      environment.VP_HOME = this.managedHome;
+    }
+    return { version: 1, kind, ready: kind === "external", executable, environment };
+  }
+
+  childEnvironment(record, pins) {
+    return {
+      ...Object.fromEntries(versionVariables.map(name => [name, undefined])),
+      ...record.environment,
+      WORKBENCH_DATA_ROOT: this.dataRoot,
+      ...(pins ? {
+        VP_NODE_VERSION: pins.node,
+        VP_PACKAGE_MANAGER: `${pins.manager}@${pins.packageManager}`,
+        VP_PNPM_VERSION: pins.packageManager,
+      } : {}),
+    };
+  }
+
+  async verify(record) {
+    try {
+      await this.commands.run(record.executable, ["--version"], {
+        environment: this.childEnvironment(record), output: { write() {} }, errorOutput: { write() {} },
+      });
+    } catch (error) {
+      throw new Error(`Recorded Vite+ is unavailable at ${record.executable}. ${record.kind === "external"
+        ? "Restore that installation; Workbench will not replace a user-owned toolchain."
+        : "Run wb repair to restore the managed toolchain."}`, { cause: error });
+    }
+  }
+
+  async discover() {
+    const executable = await this.commands.findExecutable("vp");
+    if (!executable) return null;
+    const record = this.selection(executable, "external");
+    await this.verify(record);
+    return record;
+  }
+
+  async resolve() {
+    const record = await this.read() ?? await this.discover();
+    if (!record) throw new Error("Workbench's Vite+ toolchain is unavailable. Run wb repair.");
+    if (!record.ready) throw new Error("Workbench toolchain setup is incomplete. Run wb repair.");
+    return record;
+  }
+
+  async ensure({ onOutput } = {}) {
+    if (this.environment.WORKBENCH_THREAD_ID || this.environment.CODEX_THREAD_ID) {
+      throw new Error("Managed threads cannot provision Workbench's toolchain.");
+    }
+    await fs.mkdir(this.directory, { recursive: true });
+    const lock = new DatabaseSync(path.join(this.directory, "toolchain.lock.sqlite3"));
+    try {
+      try { lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE"); }
+      catch (error) {
+        if (error.errcode === 5 || error.errcode === 6) throw new Error("Another Workbench toolchain setup is running. Retry after it finishes.");
+        throw error;
+      }
+      let record = await this.read();
+      if (record?.ready) {
+        try { await this.verify(record); return record; }
+        catch (error) {
+          if (record.kind !== "managed") throw error;
+          if (error.cause?.code !== "ENOENT") throw error;
+        }
+      } else if (!record) {
+        record = await this.discover();
+        if (record) { await this.write(record); return record; }
+        record = this.selection(this.managedExecutable(), "managed");
+        await this.write(record);
+      }
+      if (record.ready) {
+        record = { ...record, ready: false };
+        await this.write(record);
+      }
+      onOutput?.(`Provisioning Workbench's managed Vite+ at ${this.managedHome}\n`);
+      await this.install({ home: this.managedHome, directory: this.directory, commands: this.commands, onOutput });
+      await this.verify(record);
+      record = { ...record, ready: true };
+      await this.write(record);
+      return record;
+    } finally { lock.close(); }
+  }
+
+  async write(record) {
+    const temporary = `${this.receipt}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, this.receipt);
+  }
+
+  async pins(root) {
+    const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+    const runtime = manifest.devEngines?.runtime;
+    const manager = manifest.devEngines?.packageManager;
+    const exact = value => typeof value === "string" && /^\d+\.\d+\.\d+$/u.test(value);
+    if (runtime?.name !== "node" || manager?.name !== "pnpm" || !exact(runtime.version) || !exact(manager.version)) {
+      throw new Error(`Workbench must declare exact Node and pnpm devEngines pins: ${root}`);
+    }
+    return { node: runtime.version, manager: manager.name, packageManager: manager.version };
+  }
+
+  async run(args, { cwd, ...options }) {
+    const [record, pins] = await Promise.all([this.resolve(), this.pins(cwd)]);
+    return this.commands.run(record.executable, args, {
+      ...options, cwd, environment: { ...options.environment, ...this.childEnvironment(record, pins) },
+    });
+  }
+
+  async runNode(root, entry, args = [], { nodeOptions = [], ...options } = {}) {
+    const [record, pins] = await Promise.all([this.resolve(), this.pins(root)]);
+    return this.commands.run(record.executable, [
+      "env", "exec", "--node", pins.node, "--package-manager", `${pins.manager}@${pins.packageManager}`,
+      "node", ...nodeOptions, entry, ...args,
+    ], { ...options, environment: { ...options.environment, ...this.childEnvironment(record, pins) } });
+  }
+}

package/index.mjs

@@ -17,10 +17,6 @@ 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;
 }
@@ -58,10 +54,6 @@ async function resolveReferences(parsed, definitions, { runner, signal, warn })
     }
   }
   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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inthedark/wb",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,6 +26,11 @@
     "wb",
     "WorkbenchBootstrap.mjs",
     "WorkbenchBootstrapCommand.mjs",
+    "WorkbenchToolchain.mjs",
+    "WorkbenchPackageRegistration.mjs",
+    "vite-plus-installer.mjs",
+    "workbench-data-root.mjs",
+    "workbench-data-root.d.mts",
     "WorkbenchInstallPrompt.mjs",
     "installer-cube.mjs",
     "index.mjs",

package/vite-plus-installer.mjs

@@ -0,0 +1,52 @@
+/*
+ * Exports:
+ * - default installVitePlus: execute the pinned official installer without user shell integration.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const VITE_PLUS_VERSION = "1.1.0";
+
+export default async function installVitePlus({
+  home, directory, commands, onOutput, fetchInstaller = fetch, platform = process.platform, files = fs,
+}) {
+  const windows = platform === "win32";
+  const extension = windows ? "ps1" : "sh";
+  const url = `https://raw.githubusercontent.com/voidzero-dev/vite-plus/v${VITE_PLUS_VERSION}/packages/cli/install.${extension}`;
+  const response = await fetchInstaller(url);
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`Vite+ installer download failed (HTTP ${response.status}).`);
+  }
+  const script = await response.text();
+  if (!script.trim()) throw new Error("Vite+ installer download was empty.");
+  await files.mkdir(directory, { recursive: true });
+  const filename = path.join(directory, `vite-plus-${randomUUID()}.${extension}`);
+  await files.writeFile(filename, script, { flag: "wx", mode: 0o600 });
+  let failure;
+  try {
+    const environment = Object.fromEntries(Object.keys(commands.environment)
+      .filter(name => /^VP_/iu.test(name)).map(name => [name, undefined]));
+    Object.assign(environment, {
+      VP_HOME: home,
+      VP_VERSION: VITE_PLUS_VERSION,
+      VP_NODE_MANAGER: "yes",
+      VP_PM_MANAGER: "yes",
+      // Release-pinned self-setup honours this on Unix and Windows; CI alone still edits profiles.
+      VP_SELF_SETUP_NO_MODIFY_PATH: "1",
+      CI: "true",
+    });
+    await commands.run(windows ? "powershell.exe" : "bash",
+      windows ? ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", filename] : [filename],
+      { cwd: directory, environment, onOutput });
+  } catch (error) {
+    failure = error;
+  }
+  try { await files.unlink(filename); }
+  catch (error) {
+    if (failure) throw new AggregateError([failure, error], `Vite+ setup failed and its downloaded script could not be removed: ${filename}`, { cause: failure });
+    throw error;
+  }
+  if (failure) throw failure;
+}

package/workbench-data-root.d.mts

@@ -0,0 +1,11 @@
+/*
+ * Exports:
+ * - WorkbenchDataRootOptions: environment, home and platform inputs for data storage.
+ * - default resolveWorkbenchDataRoot: dependency-free per-user data location.
+ */
+export interface WorkbenchDataRootOptions {
+  environment?: NodeJS.ProcessEnv;
+  homeDirectory?: string;
+  platform?: NodeJS.Platform;
+}
+export default function resolveWorkbenchDataRoot(options?: WorkbenchDataRootOptions): string;

package/workbench-data-root.mjs

@@ -0,0 +1,20 @@
+/*
+ * Exports:
+ * - default resolveWorkbenchDataRoot: resolve per-user OS data storage without installed dependencies.
+ */
+import os from "node:os";
+import path from "node:path";
+
+export default function resolveWorkbenchDataRoot({
+  environment = process.env, homeDirectory = os.homedir(), platform = process.platform,
+} = {}) {
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  const override = environment.WORKBENCH_DATA_ROOT?.trim();
+  if (override) return paths.resolve(override);
+  if (platform === "win32") {
+    return paths.resolve(environment.LOCALAPPDATA?.trim() || paths.join(homeDirectory, "AppData", "Local"), "inthedark", "wb");
+  }
+  if (platform === "darwin") return paths.resolve(homeDirectory, "Library", "Application Support", "inthedark", "wb");
+  const xdg = environment.XDG_DATA_HOME?.trim();
+  return paths.resolve(xdg && paths.isAbsolute(xdg) ? xdg : paths.join(homeDirectory, ".local", "share"), "inthedark", "wb");
+}