Skip to content

Self-improving AI Employees for everyone

docs(cloudflare,setup): state the Node floor as 18+, not 22

trohitg0cb1cc8d9ed5
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml
index 90228182..99088ad9 100644
--- a/.github/actions/setup/action.yml
+++ b/.github/actions/setup/action.yml
@@ -12,7 +12,8 @@ runs:
steps:
# Reads the bun version from the root package.json "packageManager" pin.
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
- # Node 22 stays the runtime (vite, vitest, eslint, the sidecar run on
+ # Node stays the runtime; CI builds on 22 LTS while the published
+ # package's floor is 18+ (vite, vitest, eslint, the sidecar run on
# node via shebang; bun is package manager + script runner only).
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
with:
diff --git a/CLAUDE.md b/CLAUDE.md
index 127d0cd5..c0c1dce2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -744,7 +744,7 @@ Execution routing falls back Temporal → sequential; the Temporal dev server +
## Development Commands
-**Package manager: bun** (pinned via `packageManager: [email protected]` in the root package.json). Source checkouts are gated to bun by `scripts/preinstall.js` (keys on `bunfig.toml` + a `bun` user agent) — `npm install` in the repo is rejected with a pointer to https://bun.sh; end-user installs of the published npm package are unaffected. `bunfig.toml` pins the **isolated linker** (pnpm-style symlinked `node_modules` with the store at `node_modules/.bun/`), the lockfile is the tracked text `bun.lock`, and Node 22 remains the runtime — bun only installs and runs scripts, never executes tools with `--bun`. Security pins live in the top-level `overrides` block (version-ranged keys). See [CONTRIBUTING.md](./CONTRIBUTING.md) → "Known differences from pnpm" for the guards that changed in the 2026-08 pnpm→bun migration.
+**Package manager: bun** (pinned via `packageManager: [email protected]` in the root package.json). Source checkouts are gated to bun by `scripts/preinstall.js` (keys on `bunfig.toml` + a `bun` user agent) — `npm install` in the repo is rejected with a pointer to https://bun.sh; end-user installs of the published npm package are unaffected. `bunfig.toml` pins the **isolated linker** (pnpm-style symlinked `node_modules` with the store at `node_modules/.bun/`), the lockfile is the tracked text `bun.lock`, and Node remains the runtime (floor Node 18+ per `engines.node` and `bin/cli.js`; CI and the desktop bundle use 22 LTS) — bun only installs and runs scripts, never executes tools with `--bun`. Security pins live in the top-level `overrides` block (version-ranged keys). See [CONTRIBUTING.md](./CONTRIBUTING.md) → "Known differences from pnpm" for the guards that changed in the 2026-08 pnpm→bun migration.
### CLI Commands (after the global install)
```bash
diff --git a/cli/terraform/aws/README.md b/cli/terraform/aws/README.md
index 433d1814..946081b7 100644
--- a/cli/terraform/aws/README.md
+++ b/cli/terraform/aws/README.md
@@ -14,7 +14,7 @@ Settings are the ones validated on a live t3.micro in September 2026:
| Credit mode | `standard` | Caps compute at the hourly rate under continuous CPU load. |
| Root disk | 10 GiB gp3, deleted with the instance | A fresh install uses ~4.5 GiB. |
| Image | Ubuntu 24.04 LTS (Canonical) | Python 3.12 inside the server's `<3.13` pin. |
-| Node | current LTS from NodeSource when none is present; an existing 18+ is kept | The published package may still require 22. |
+| Node | current LTS from NodeSource when none is present; an existing 18+ is kept | The published package runs on Node 18+; only the Cloudflare node's `cf` CLI needs 22+. |
| Install | `install.sh` as `ubuntu`, no sudo | Root installs leave the venvs unusable by the login user (errors.md #16). |
| Runtime | `company serve` under systemd as `ubuntu` on port 5678 | The server rejects ports below 1024; 80/443 stay free for a TLS front door. |
| Security group | 22, 80, 443 and the app port from `allow_cidr` | Same shape as the gcp module. |
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index 1683b374..ffe6705f 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -155,7 +155,7 @@ code or doc should carry the numerals.
| Dependency | Version | Install |
|------------|---------|---------|
-| Node.js | 22+ | https://nodejs.org/ |
+| Node.js | 18+ (22 LTS recommended; CI and the desktop bundle use 22; only the Cloudflare node's `cf` CLI needs 22+) | https://nodejs.org/ |
| Python | 3.12+ (CLI); server venv accepts 3.11–3.12 | https://python.org/ |
| uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| bun | 1.4.x | official installer (https://bun.sh); root `packageManager` pin read by `oven-sh/setup-bun` in CI |
diff --git a/docs-internal/cloudflare_service.md b/docs-internal/cloudflare_service.md
index 14d3fd6e..5fc6689b 100644
--- a/docs-internal/cloudflare_service.md
+++ b/docs-internal/cloudflare_service.md
@@ -13,7 +13,7 @@ grant** that makes the optional API token the only path to analytics.
|---|---|
| Node type | `cloudflareAction` (palette group `deployment`, dual-purpose AI tool `cloudflare`) |
| Operations | `whoami` / `zones_list` / `dns_records_list` / `dns_record_create` / `dns_record_delete` / `graphql_query` / `custom` |
-| CLI pin | `[email protected]` (`_NPM_SPEC` in `_install.py`), npm-installed into the shared `packages_dir()` tree, Node >= 22 |
+| CLI pin | `[email protected]` (`_NPM_SPEC` in `_install.py`), npm-installed into the shared `packages_dir()` tree; cf declares `engines.node >= 22`, above OpenCompany's 18+ floor (this is the only node that needs 22) |
| Auth | Dual-path: cf-owned OAuth login OR optional canonical `apiKey` field (stored under the provider id `cloudflare`) -> `CLOUDFLARE_API_TOKEN` env |
| Task queue | `TaskQueue.REST_API` |
| Output | `ui_hints = {"outputMode": "terminal"}`; `_shape` contract (parsed JSON -> `result`, text -> `stdout`, never both) + NDJSON recovery |
diff --git a/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md
index 293cc652..23dfc683 100644
--- a/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md
+++ b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md
@@ -163,7 +163,8 @@ flowchart TD
session created by `cf auth login` lives in cf's own user-level config and
is never read by OpenCompany; the modal badge is a synthetic `cli-managed`
marker OAuth row written by `_handlers.py`.
-- **Services**: the `cf` CLI (Node >= 22, `npm` on PATH for the install);
+- **Services**: the `cf` CLI (declares `engines.node >= 22`, above OpenCompany's
+ 18+ floor — the only node with that requirement; `npm` on PATH for the install);
Cloudflare's dashboard OAuth for login (cf opens the browser itself and
listens on a fixed loopback port it owns - see `_handlers.py` for the
single-flight guard and the never-kill rule).
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 1f3804ed..bd1e1cdd 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -19,8 +19,10 @@ The dev workspace runs on **bun** (migrated from [email protected], 2026-08; pinned
via `"packageManager": "[email protected]"` — CI's `oven-sh/setup-bun` reads that pin).
Facts that are load-bearing, each verified during the migration:
-- **Scope**: bun installs the workspace and runs scripts; **Node 22 stays the
- runtime** (vite/vitest/eslint/the sidecar run on node via shebang — never
+- **Scope**: bun installs the workspace and runs scripts; **Node stays the
+ runtime** — the floor is Node 18+ (`engines.node`, `bin/cli.js`, the
+ installers); CI and the desktop bundle happen to use 22 LTS
+ (vite/vitest/eslint/the sidecar run on node via shebang — never
pass `--bun`). Everything npm-facing is deliberately untouched: end-user
`npm install -g @zeenie-ai/opencompany`, the backend's
`npm install --prefix <DATA_DIR>/packages/` shared tree, the sidecar's
diff --git a/server/nodes/cloudflare/_install.py b/server/nodes/cloudflare/_install.py
index e01727d2..62f1422b 100644
--- a/server/nodes/cloudflare/_install.py
+++ b/server/nodes/cloudflare/_install.py
@@ -19,8 +19,10 @@ terminal is visible to this pinned binary too.
Pin ``_NPM_SPEC`` when bumping and re-verify every wrapped command via
``cf <cmd> --help-full`` (whatsapp precedent — ``@latest`` makes cold
-installs non-reproducible). cf requires Node >= 22, which is already
-OpenCompany's engines floor.
+installs non-reproducible). cf declares ``engines.node >= 22``, which is
+ABOVE OpenCompany's own floor of Node 18+ — so this plugin is the one place
+that needs a newer Node than the rest of the app, and its error text says
+so instead of implying the app requires 22.
"""
from __future__ import annotations
@@ -68,7 +70,10 @@ def _npm_install() -> Path:
npm_cmd = shutil.which("npm")
if not npm_cmd:
- raise RuntimeError("npm not on PATH — install Node.js 22+ (the cf CLI ships via npm)")
+ raise RuntimeError(
+ "npm not on PATH — the cf CLI ships via npm and needs Node.js 22+ "
+ "(OpenCompany itself runs on Node 18+; only this node needs 22)"
+ )
logger.info("[Cloudflare] installing %s into shared tree %s", _NPM_SPEC, root)
root.mkdir(parents=True, exist_ok=True)