Skip to content

Self-improving AI Employees for everyone

build(bun): drop the npm hops from root scripts and the company shim

trohitg0fcdf586eaa3
diff --git a/CLAUDE.md b/CLAUDE.md
index c0c1dce2..aac27b25 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -757,15 +757,16 @@ company clean # Clean build artifacts
company help # Show all commands
```
-### npm Scripts
+### package.json scripts (run with bun)
```bash
# Core (thin wrappers over the Python CLI)
-npm run start # Start all services (python -m cli start)
-npm run stop # Stop all services (python -m cli stop)
-npm run build # Build for production (python -m cli build)
-npm run clean # Clean build artifacts (python -m cli clean)
-npm run deploy # Self-deploy to a cloud VM (python -m cli deploy)
+bun run start # Start all services (python -m cli start)
+bun run stop # Stop all services (python -m cli stop)
+bun run build # Build for production (python -m cli build)
+bun run clean # Clean build artifacts (python -m cli clean)
+bun run deploy # Self-deploy to a cloud VM (python -m cli deploy)
```
+No root script hops through `npm run`; cross-package scripts use `bun --cwd=<dir> run <script>`.
### Cross-Platform Scripts
Service orchestration lives in the Python CLI (`company start/dev/stop/build/clean/serve/daemon/deploy/docs/version` — see `cli/`). The `scripts/` directory retains only the npm install lifecycle helpers (`install.js`, `preinstall.js`, `postinstall.js`). `company start` is single-port: uvicorn serves API + WS + built SPA on the backend port (`SERVE_STATIC_CLIENT`, default on); the retired `scripts/serve-client.js` static server and its `:3000` frontend port are gone.
diff --git a/bin/cli.js b/bin/cli.js
index eb0b414a..5b324156 100755
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -53,6 +53,13 @@ Documentation: https://docs.opencompany.sh/
`);
}
+// bun is the dev package manager and script runner for source checkouts.
+// End-user global installs (the npm tarball) may not have it, so every
+// bun use below keeps an npm fallback.
+function hasBun() {
+ return getVersion('bun --version') !== null;
+}
+
function getVersion(cmd) {
try {
return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
@@ -117,7 +124,8 @@ function checkDeps() {
function doctor() {
console.log('\nOpenCompany Doctor\n');
try {
- execSync('npx envinfo --system --binaries --npmPackages edgymeow,agent-browser,cross-env', {
+ const runner = hasBun() ? 'bun x' : 'npx';
+ execSync(`${runner} envinfo --system --binaries --npmPackages edgymeow,agent-browser,cross-env`, {
cwd: ROOT, stdio: 'inherit', shell: true,
});
} catch { /* envinfo not available, continue with manual checks */ }
@@ -138,7 +146,8 @@ function doctor() {
}
// Resolve <ROOT>/.cli-venv Python if the postinstall step provisioned it.
-// Returns null on source checkouts (no venv -> fall back to ``npm run``).
+// Returns null on source checkouts (no venv -> fall back to ``bun run``,
+// or ``npm run`` when bun is not installed).
function venvPython() {
const py = process.platform === 'win32'
? resolve(ROOT, '.cli-venv', 'Scripts', 'python.exe')
@@ -150,9 +159,10 @@ function run(script, extraArgs = []) {
// Global-install fast path: spawn the venv's Python directly with
// ``-m cli <cmd>``. Skips the ``npm run`` shim that previously re-
// resolved the system ``python`` (which on PEP 668 systems lacks
- // the CLI runtime deps -- typer/rich/anyio/psutil). The npm-run
- // path stays as the source-checkout fallback (``bun run start``
- // uses package.json scripts directly).
+ // the CLI runtime deps -- typer/rich/anyio/psutil). The script-runner
+ // path stays as the source-checkout fallback: ``bun run <script>``
+ // when bun is on PATH (source checkouts are bun-only), else ``npm run``
+ // for a global install whose .cli-venv provisioning did not happen.
const venvPy = venvPython();
if (venvPy) {
const child = spawn(venvPy, ['-m', 'cli', script, ...extraArgs], {
@@ -164,9 +174,12 @@ function run(script, extraArgs = []) {
return;
}
- const npmArgs = ['run', script];
- if (extraArgs.length) npmArgs.push('--', ...extraArgs);
- const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', npmArgs, {
+ const runnerArgs = ['run', script];
+ if (extraArgs.length) runnerArgs.push('--', ...extraArgs);
+ const runner = hasBun()
+ ? (process.platform === 'win32' ? 'bun.exe' : 'bun')
+ : (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+ const child = spawn(runner, runnerArgs, {
cwd: ROOT,
stdio: 'inherit',
shell: true,
diff --git a/cli/commands/build.py b/cli/commands/build.py
index d8700f27..4eb3a0ca 100644
--- a/cli/commands/build.py
+++ b/cli/commands/build.py
@@ -188,11 +188,22 @@ def build_command() -> None:
error_block("Node.js is required.", [])
raise typer.Exit(code=1)
+ # npm is informational only: the build never calls it, but runtime
+ # plugins (`npm install --prefix`) and the sidecar's package endpoint do.
npm_version = capture(["npm", "--version"])
console.print(f" npm: {npm_version or '[red]not found[/]'}")
+ # bun installs the workspace and runs every JS build script below
+ # (`bun install`, `bun run --filter ...`), so a missing bun is fatal
+ # here rather than a confusing failure inside step [1/6].
bun_version = capture(["bun", "--version"])
console.print(f" bun: {bun_version or '[red]not found[/]'}")
+ if not bun_version:
+ error_block(
+ "bun is required to build from source.",
+ ["Install from https://bun.sh (the root package.json pins the version)"],
+ )
+ raise typer.Exit(code=1)
python_cmd = _which_python()
if not python_cmd or not _check_python(python_cmd):
diff --git a/cli/commands/dev.py b/cli/commands/dev.py
index b59c6fc6..be470c3d 100644
--- a/cli/commands/dev.py
+++ b/cli/commands/dev.py
@@ -12,8 +12,9 @@ esbuild re-optimize (minutes on Windows) on every first page load.
(``optimizeDeps.force`` via the ``VITE_FORCE`` env var, read in
``client/vite.config.js``) -- the documented recovery for an
"Outdated Optimize Dep" error. Env var rather than argv because the
-client spec runs ``bun run client:start`` -> ``npm run start`` and a
-``--force`` suffix does not survive the double ``run`` indirection.
+client spec runs ``bun run client:start`` -> ``bun --cwd=client run
+start`` and a ``--force`` suffix does not survive the double ``run``
+indirection.
uvicorn ``--reload``-style restarts (exit code 1) used to cascade-kill
the frontend under ``concurrently --kill-others``. Our supervisor
diff --git a/cli/tests/test_release_pipeline_config.py b/cli/tests/test_release_pipeline_config.py
index 28d67d37..b6f3590b 100644
--- a/cli/tests/test_release_pipeline_config.py
+++ b/cli/tests/test_release_pipeline_config.py
@@ -563,6 +563,28 @@ def test_root_manifest_declares_bun_as_the_dev_package_manager(root_pkg: dict):
)
+def test_root_scripts_never_hop_through_npm(root_pkg: dict):
+ """Every root script that reaches another package's script does so via
+ ``bun --cwd=<dir> run`` (the ``=`` form — bun 1.4 rejects the
+ space-separated spelling). The end-user npm lifecycle hooks
+ (``preinstall`` / ``postinstall`` / ``preuninstall``) are the deliberate
+ exception: they run under the installing user's Node, where bun may be
+ absent.
+ """
+ lifecycle = {"preinstall", "postinstall", "preuninstall"}
+ for name, cmd in root_pkg["scripts"].items():
+ if name in lifecycle:
+ continue
+ assert "npm run" not in cmd and "npx " not in cmd, (
+ f"root script {name!r} hops through npm: {cmd!r}"
+ )
+ assert not cmd.startswith("node "), (
+ f"root script {name!r} invokes node directly: {cmd!r}"
+ )
+ assert root_pkg["scripts"]["client:start"] == "bun --cwd=client run start"
+ assert root_pkg["scripts"]["test:frontend"] == "bun --cwd=client run test"
+
+
def test_bunfig_pins_the_isolated_linker(root: Path):
"""``linker = "isolated"`` preserves pnpm's phantom-dependency guard
(symlinked layout); the tsgo typeRoots / vite-env.d.ts workarounds
diff --git a/client/vite.config.js b/client/vite.config.js
index 4e444fed..872b933e 100644
--- a/client/vite.config.js
+++ b/client/vite.config.js
@@ -171,8 +171,8 @@ export default defineConfig(({ mode }) => {
// `company dev --force` sets VITE_FORCE to re-run dependency
// pre-bundling — Vite's own recovery for "Outdated Optimize Dep"
// (equivalent to `vite --force`, which can't be threaded through
- // the `bun run client:start` -> `npm run start` indirection as an
- // argv flag).
+ // the `bun run client:start` -> `bun --cwd=client run start`
+ // indirection as an argv flag).
force: !!getEnv('VITE_FORCE', ''),
// Pre-bundle the heavy deps reached through lazily-loaded panels
// (chat/markdown stack, canvas) so a late discovery can't trigger
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index ffe6705f..d83fc628 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -53,8 +53,10 @@ The Electron shell is its own bun package with its own lockfile; root `bun run`
### Dependency checks
-`build` checks that Node.js and npm/bun are present (no version floor), verifies
-Python 3.12+ (`_check_python`), and installs `uv` via pip if missing. `start` runs
+`build` requires Node.js (the runtime under vite/esbuild; no version floor beyond
+the package's 18+) and bun (installs the workspace and runs every JS build step),
+reports npm as informational only (runtime plugins use it, the build does not),
+verifies Python 3.12+ (`_check_python`), and installs `uv` via pip if missing. `start` runs
no toolchain check, only the `_sqlalchemy_preflight` venv-health probe.
---
@@ -64,10 +66,10 @@ no toolchain check, only the `_sqlalchemy_preflight` venv-health probe.
Run with `bun run <script>` from the project root (`package.json` is
the source of truth). The dev package manager is [email protected] —
`scripts/preinstall.js` rejects `npm install` in a source checkout.
-The commands below are quoted verbatim from `package.json`; two of them
-(`client:start`, `test:frontend`) still spell `npm run` internally
-because they invoke another package's script, which bun executes on
-Node either way (recorded follow-up).
+The commands below are quoted verbatim from `package.json`. No script
+hops through `npm run` any more: cross-package scripts use
+`bun --cwd=<dir> run <script>` (the `=` form is mandatory on bun 1.4),
+and the tools they reach (vite, vitest) still execute on Node.
### CLI wrappers
@@ -83,7 +85,7 @@ Node either way (recorded follow-up).
| Script | Command | Description |
|--------|---------|-------------|
-| `client:start` | `cd client && npm run start` | React frontend (Vite dev server) |
+| `client:start` | `bun --cwd=client run start` | React frontend (Vite dev server) |
| `python:start` | `cd server && uv run python main.py` | Backend only (`main.py` reads `HOST` / `PYTHON_BACKEND_PORT` from the env) |
| `python:daemon` | `cd server && cross-env HOST=0.0.0.0 uv run python main.py` | Backend only, LAN-reachable |
| `temporal:worker` | `cd server && uv run python -m services.temporal.worker` | Standalone Temporal worker |
@@ -96,7 +98,7 @@ The Temporal dev server is backend-owned: the FastAPI lifespan starts it via `Te
|--------|---------|
| `test` | backend + frontend suites |
| `test:backend` | `cd server && uv run pytest tests/ -v` |
-| `test:frontend` | `cd client && npm run test` (vitest) |
+| `test:frontend` | `bun --cwd=client run test` (vitest) |
| `test:nodes` | node-plugin tests with handler coverage |
### Lifecycle hooks
diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.md
index b0e1eab2..00fa25c3 100644
--- a/docs-internal/node_panels.md
+++ b/docs-internal/node_panels.md
@@ -208,14 +208,13 @@ Locked in by the test suite at:
## 9. Test Run
```bash
-cd client
-npm install
-npm run test -- src/hooks/__tests__/useDragVariable.test.ts \
- src/components/parameterPanel/__tests__
+bun install
+bun --cwd=client run test -- src/hooks/__tests__/useDragVariable.test.ts \
+ src/components/parameterPanel/__tests__
```
Or use the dedicated script (added in `client/package.json`):
```bash
-npm run test:nodepanels
+bun --cwd=client run test:nodepanels
```
diff --git a/package.json b/package.json
index 1997eda1..ea9908ea 100644
--- a/package.json
+++ b/package.json
@@ -73,7 +73,7 @@
"dev": "python -m cli dev",
"serve": "python -m cli serve",
"start:temporal": "cross-env TEMPORAL_ENABLED=true python -m cli start",
- "client:start": "cd client && npm run start",
+ "client:start": "bun --cwd=client run start",
"python:start": "cd server && uv run python main.py",
"python:daemon": "cd server && cross-env HOST=0.0.0.0 uv run python main.py",
"temporal:start": "temporal api",
@@ -83,9 +83,9 @@
"build": "python -m cli build",
"clean": "python -m cli clean",
"stop": "python -m cli stop",
- "test": "npm run test:backend && npm run test:frontend",
+ "test": "bun run test:backend && bun run test:frontend",
"test:backend": "cd server && uv run pytest tests/ -v",
- "test:frontend": "cd client && npm run test",
+ "test:frontend": "bun --cwd=client run test",
"test:nodes": "cd server && uv run pytest tests/nodes/ -v --cov=services.handlers --cov-report=term-missing",
"docs:nodes": "python -m cli docs nodes",
"docs:nodes:check": "python -m cli docs nodes --check",
@@ -96,7 +96,7 @@
"daemon:restart": "python -m cli daemon restart",
"version:sync": "python -m cli version sync",
"typecheck": "tsc --noEmit -p client/tsconfig.json",
- "prepublishOnly": "python -m cli version sync && node -e \"const p=require('./package.json'); if(!p.bin||!p.version){process.exit(1)}\"",
+ "prepublishOnly": "python -m cli version sync && bun -e \"const p=require('./package.json'); if(!p.bin||!p.version){process.exit(1)}\"",
"preinstall": "node scripts/preinstall.js",
"postinstall": "node scripts/postinstall.js",
"preuninstall": "node scripts/preinstall.js"
diff --git a/server/nodes/browser/browser/__init__.py b/server/nodes/browser/browser/__init__.py
index 3709b347..3af335be 100644
--- a/server/nodes/browser/browser/__init__.py
+++ b/server/nodes/browser/browser/__init__.py
@@ -356,7 +356,9 @@ class BrowserNode(ActionNode):
svc = get_browser_service()
if not svc:
raise RuntimeError(
- "agent-browser not installed. Run: bun install && npx agent-browser install",
+ "agent-browser not installed. OpenCompany installs it on first use "
+ "with `npm install agent-browser --prefix <DATA_DIR>/packages`; check "
+ "that npm is on PATH and see the backend log for the install error.",
)
op = params.operation