Skip to content

Self-improving AI Employees for everyone

docs(build): correct stale statements in setup, scripts and CI docs

trohitgca666d813780
diff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.yml
index f4c02c6b..258afc87 100644
--- a/.github/workflows/predeploy.yml
+++ b/.github/workflows/predeploy.yml
@@ -1,5 +1,5 @@
# Reusable validation workflow. Called by ci.yml and release.yml.
-# Three jobs: client build + lint, backend tests, cross-OS smoke test.
+# Four jobs: client build + lint, backend tests, CLI tests, cross-OS build + start smoke test.
name: Predeploy
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index 0aacfae1..2537517d 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -34,15 +34,19 @@ deprecation warning; kept for upgrade compatibility).
| `company dev` | Start in dev mode (Vite HMR + uvicorn). `--force` re-bundles Vite deps (recovers "Outdated Optimize Dep"); `--daemon` binds backend to 0.0.0.0 |
| `company serve` | Single-port production runtime (uvicorn serves API + WS + built SPA; optional daemons incl. the JS executor sidecar (bun) are backend-spawned on demand) — the systemd `ExecStart` on deployed VMs |
| `company stop` | Stop all services and free configured ports |
-| `company build` | Full production build (bun install → client → sidecar → uv sync → bytecode → temporal binary). Step [0/6] scaffolds `.env` from `.env.template` when missing, generating fresh random secrets (`secrets.token_hex(24)`) for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the dev placeholders; an existing `.env` is untouched |
+| `company build` | Full production build (bun install → client → sidecar → `uv sync --extra docs` → bytecode → temporal binary). Step [0/6] scaffolds `.env` from `.env.template` when missing, generating fresh random secrets (`secrets.token_hex(24)`) for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the dev placeholders; an existing `.env` is untouched |
| `company clean` | Stop services, then remove build artifacts, node_modules, `.venv`, repo-local state (preserves `.opencompany/{workflows,deploy,packages}`) |
| `company deploy up/status/destroy` | Self-deploy a login-gated VM (gcloud preflight + Terraform; see `cli/commands/deploy/`) |
| `company daemon start/stop/status/restart` | Detached backend management (PID file under user data dir) |
| `company version sync [tag]` | Write a git tag's version (default: the latest) into every version file: root / client / desktop `package.json`, `pyproject.toml`, `cli/__init__.py`. Never `server/pyproject.toml`, which `server/uv.lock` records. The release procedure is in [ci_cd.md -> Cutting a release](./ci_cd.md#cutting-a-release) |
| `company docs nodes [--check]` | Regenerate (or verify) the `docs-internal/node-logic-flows/` index |
-There is no `help` verb: `company` with no arguments, `company --help`, and
-`company <verb> --help` print Typer's help (`no_args_is_help=True` in `cli/cli.py`).
+Help comes from two places. `company` with no arguments, `company help`,
+`company --help` and `company -h` are answered by the launcher itself
+(`printHelp()` in `bin/cli.js`, its `COMMANDS` table), without starting
+Python. `company <verb> --help` is forwarded to `python -m cli <verb> --help`
+and prints Typer's help for that verb (`cli/cli.py`); `python -m cli` with no
+arguments prints Typer's own command list (`no_args_is_help=True`).
### Desktop shell scripts (`desktop/package.json`, run from `desktop/`)
diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.md
index 52f99c8b..9b80f7b8 100644
--- a/docs-internal/SETUP.md
+++ b/docs-internal/SETUP.md
@@ -32,12 +32,12 @@ command provisions the Python side (uv, the venvs, bytecode; a minute or two).
`curl -fsSL https://opencompany.sh/install.sh | bash` (or `install.ps1` on
Windows) installs bun, Python and uv first and provisions eagerly.
-**Known issue on 0.2.0 and 0.2.1**: a registry install provisions but then
-`company start` (and `company serve`) stops with "Project not built", and the
-package ships without the JS executor sidecar bundle; `company build` in the
-installed package works around both. Details and status in
-[errors.md #25 and #26](./errors.md). The desktop app is not affected and is
-the recommended install.
+**Known issue in registry installs (open since 0.2.0; the status line of
+[errors.md #25 and #26](./errors.md) says whether your version is fixed)**: a
+registry install provisions but then `company start` (and `company serve`)
+stops with "Project not built", and the package ships without the JS executor
+sidecar bundle; `company build` in the installed package works around both.
+The desktop app is not affected and is the recommended install.
Open `http://localhost:$PYTHON_BACKEND_PORT` — `company start` is single-port (API +
WebSocket + built SPA on the backend port).
@@ -213,7 +213,7 @@ built from source; see [docker.md](./docker.md).
|---------|-------------|
| `bun run start` | Start the app (backend-owned daemons start on demand) |
| `bun run stop` | Stop all services |
-| `bun run build` | Full production build (`company build`: bun install, client, sidecar, uv sync, bytecode, Temporal binary) |
+| `bun run build` | Full production build (`company build`: bun install, client, sidecar, `uv sync --extra docs`, bytecode, Temporal binary) |
| `bun run dev` | Start development server |
## Troubleshooting
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index 308dd480..6a694f74 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -91,7 +91,7 @@ Reusable `workflow_call` workflow with four independent jobs (no plan/change-det
- `build-and-lint` — `bun install --frozen-lockfile` + `bun run build`, then client lint (`bun run --filter react-flow-client lint`), TypeScript check (`... typecheck`), and frontend tests (`... test`, vitest). Runs on `ubuntu-latest`.
- `backend-tests` — `uv lock --check` (the committed `server/uv.lock` must match `pyproject.toml`; the desktop app installs from it with `--frozen`), then `uv sync` + `uv run pytest tests/ -v` in `server/`. Whole suite, unsharded. Runs on `ubuntu-latest`.
- `cli-tests` — `uv pip install --system pytest pytest-asyncio pyyaml` + `python -m pytest cli/tests/ -v`. Runs on `ubuntu-latest`.
-- `test-build-start` — cross-OS matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`, `fail-fast: false`). Runs `bun run build`, then `bun run tsc --version` (proves the per-platform TypeScript 7 Go binary delivered via `optionalDependencies` resolves on every OS — the type-check gate itself runs on ubuntu only; `bun run`, never `bunx`, so it resolves strictly from the root `node_modules/.bin`), then a start smoke test. On Unix it backgrounds `bun run start`, reads `PYTHON_BACKEND_PORT` out of `.env.template` and polls `http://localhost:${APP_PORT}/health` for up to ~30 s, then `bun run stop`. On Windows it starts the supervisor as a background job, waits 15 s, and fails if the job already exited.
+- `test-build-start` — cross-OS matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`, `fail-fast: false`). Runs `bun run build`, then `bun run tsc --version` (proves the per-platform TypeScript 7 Go binary delivered via `optionalDependencies` resolves on every OS — the type-check gate itself runs on ubuntu only; `bun run`, never `bunx`, so it resolves strictly from the root `node_modules/.bin`), then a start smoke test. On Unix it backgrounds `bun run start`, reads `PYTHON_BACKEND_PORT` out of `.env.template` and polls `http://localhost:${APP_PORT}/health` for up to ~30 s, but only as a wait: the loop exits after its last attempt whether or not `/health` ever answered. The pass condition is that the backgrounded `bun run start` process is still alive (`kill -0`) and `bun run stop` then succeeds; a backend that stays up without ever serving `/health` passes. On Windows it starts the supervisor as a background job, waits 15 s, and fails if the job already exited.
---
@@ -128,6 +128,7 @@ publish-npm publish-github-packages
- Both publish jobs `needs: predeploy`, run on `ubuntu-latest`, and share the same prefix: immutable `actions/checkout` with `persist-credentials: false` → composite setup → `bun install --frozen-lockfile` → `bun run build` → `python -m cli version sync`. There is no `setup-node` step and no npm CLI anywhere in the release: bun packs, authenticates and publishes.
- `publish-npm` — writes `//registry.npmjs.org/:_authToken=<NPM_TOKEN>` to `~/.npmrc`, validates it with `bun pm whoami`, then publishes the canonical public npmjs package `@zeenie-ai/opencompany` via `bun publish --access public`. npm provenance attestation was an npm-CLI feature and is gone with it.
- `publish-github-packages` — writes `@zeenie-ai:registry=https://npm.pkg.github.com/` and the `//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>` line to `~/.npmrc`, then a plain `bun publish`. bun 1.4 ignores `publishConfig.registry`, and it keeps an `.npmrc` token only for the registry that same file points at, so the route and the token must sit together; the v0.2.0 mirror publish went to npmjs with the GitHub token and failed with `missing authentication` before this was known ([errors.md #24](./errors.md#24-github-packages-publish-fails-with-missing-authentication-although-the-job-wrote-a-token-for-npmpkggithubcom)).
+- `bun publish` runs the root `prepublishOnly` script in both jobs, so `python -m cli version sync` runs a second time inside the publish step (a no-op after the explicit sync step), followed by a `bun -e` check that `package.json` still has `bin` and `version`. The root `publishConfig` still carries `registry: https://registry.npmjs.org` beside `access: public` (`test_root_package_uses_public_zeenie_scope` locks both), but bun ignores that `registry` key: each job's `~/.npmrc` alone decides where it publishes.
Both registries use `@zeenie-ai/opencompany`, matching the npm and GitHub
organization owned by the project.
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index ca4fc0ad..2102689b 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -11,7 +11,7 @@ User scope (confirmed before this work): stay on the registry-tarball distributi
| TypeScript type-check | `typescript@7` (the native Go compiler) at the **repo root** | **5.9× faster** on `--noEmit` — measured 2026-07-26 on this codebase, 3 warm runs each: **~820 ms** vs **~4830 ms** under `tsc` 5.9.3. Type-check only; Vite/esbuild keep producing the actual JS bundles. Lives in root `devDependencies`, exact-pinned, never ships to users. |
| Vite output | `manualChunks` + `target: 'es2022'` | Split heavy libs (reactflow, radix-ui, lobehub, react-markdown stack) so the main bundle no longer hits the 1500KB warning ceiling. ES2022 unlocks `findLast` / optional-chaining-assignment without polyfills (Chrome 94+, FF 93+, Safari 15.4+ — within React 19 / Tailwind 4 baseline). |
| JS executor sidecar | `bun build src/index.ts --target=bun --outfile=dist/index.js`, run via `bun dist/index.js` | Drops tsx interpreter startup (~500ms-1s every server boot). `--target=bun` yields a self-contained bundle with Express inlined — no `node_modules` at runtime, which is what lets the desktop bundle copy one file. (The first cut was an esbuild bundle with `--packages=external` run on Node; superseded when bun became the only shipped JavaScript runtime.) |
-| Python | `python -m compileall -q -j 0 <project dirs>` + `[tool.uv] compile-bytecode = true` | Pre-compile bytecode. Implemented as step `[5/6]` in [`cli/commands/build.py`](../cli/commands/build.py) (`COMPILEALL_SOURCE_DIRS` constant lists the dirs); `server/pyproject.toml`'s `compile-bytecode = true` makes `uv sync` (step `[4/6]`) compile `.venv/` site-packages too. No `-O`: every runtime launches python without `-O`, and per PEP 488 a non-optimized interpreter only loads plain `.pyc` — the earlier `-O` invocation produced `.opt-1.pyc` that nothing ever loaded (fixed 2026-07-14; ~30-50s cold-start gain, see [performance.md](performance.md)). |
+| Python | `python -m compileall -q -j 0 <project dirs>` + `[tool.uv] compile-bytecode = true` | Pre-compile bytecode. Implemented as step `[5/6]` in [`cli/commands/build.py`](../cli/commands/build.py) (`COMPILEALL_SOURCE_DIRS` constant lists the dirs); `server/pyproject.toml`'s `compile-bytecode = true` makes step `[4/6]`'s `uv sync --extra docs` compile `.venv/` site-packages too. No `-O`: every runtime launches python without `-O`, and per PEP 488 a non-optimized interpreter only loads plain `.pyc` — the earlier `-O` invocation produced `.opt-1.pyc` that nothing ever loaded (fixed 2026-07-14; ~30-50s cold-start gain, see [performance.md](performance.md)). |
## Package manager (bun)
@@ -128,7 +128,8 @@ Two halves (both required; see [performance.md](performance.md) for the
2026-07-14 cold-boot measurements that motivated the split):
- `server/pyproject.toml` → `[tool.uv] compile-bytecode = true` makes
- `uv sync` (step `[4/6]`) compile all `.venv/` site-packages at install
+ every `uv sync` (step `[4/6]` runs `uv sync --extra docs`; `scripts/install.js`
+ runs plain `uv sync`) compile all `.venv/` site-packages at install
time. uv's default is **false** — without this, every dependency `.py`
compiles lazily on the first import after a fresh sync.
- [`cli/commands/build.py`](../cli/commands/build.py) → step `[5/6]`