Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(build): correct stale statements in setup, scripts and CI docs
trohitgca666d813780
diff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.ymlindex 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: Predeploydiff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.mdindex 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.mdindex 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` onWindows) 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 |## Troubleshootingdiff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.mdindex 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 GitHuborganization owned by the project.diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.mdindex 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 the2026-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 installtime. 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]`