From aa764c98bb1bdd1e0066b333a9cf2988632a5427 Mon Sep 17 00:00:00 2001 From: Harsh Date: Thu, 12 Nov 2026 16:59:56 -0800 Subject: [PATCH 1/2] Document the local workspace UI contribution workflow CONTRIBUTING.md now covers prerequisites, clean-checkout install/build/ test commands, source-vs-generated assets (web/src vs bus/hostedweb), the CI drift check, single-test and headed runs, the CHROMIUM_PATH override, and the fact that no production credentials or paid services are needed. --- CONTRIBUTING.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87aef8d..28232bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,33 @@ cd sdk/typescript OCTOBER_BUS_BINARY=/tmp/agentintercom npm run test:integration ``` +## Workspace UI (browser) development + +The browser workspace needs no production credentials, paid AI subscription, or running hosted account service. The browser tests intercept every `/api` and auth request with fake accounts and API responses on loopback, so a clean checkout plus Node.js is enough. CI runs this workflow with Node.js 24 (see the `workspace-ui` job in `.github/workflows/ci.yml`); Node.js 20 or newer matches the repo floor. + +Source lives in `web/src`; the Go server embeds and serves generated files from `bus/hostedweb/`. Never edit `bus/hostedweb/` by hand: edit `web/src`, rebuild, and commit the regenerated files in the same pull request. + +From a clean checkout: + +```bash +cd web +npm ci --ignore-scripts +npm run build +npx playwright install chromium +npm test +``` + +`npm ci --ignore-scripts` installs UI dependencies, `npm run build` regenerates `bus/hostedweb/app.js`, `bus/hostedweb/index.html`, and `bus/hostedweb/style.css` from `web/src`, `npx playwright install chromium` fetches the browser the tests drive (add `--with-deps` on a fresh Linux machine for OS packages), and `npm test` serves the built bundle on `http://127.0.0.1:4794` and runs the mocked Playwright suite. Rebuild after every `web/src` change; CI rebuilds and fails on drift with `git diff --exit-code -- ../bus/hostedweb`, so an uncommitted regeneration breaks the build. + +Run one browser test by name while iterating: + +```bash +cd web +npx playwright test -g "part of the test name" +``` + +Watch it in a real browser window with `npx playwright test --headed -g "part of the test name"`. To drive a browser executable you already have instead of the downloaded one, set `CHROMIUM_PATH=/path/to/chromium` (see `web/playwright.config.js`). The tests also write full-page screenshots to `/tmp/agentintercom-*.png`, which is a quick way to inspect layout without keeping a browser open. + ## Protocol changes Protocol behavior belongs in the versioned specification and schemas. A change must include tests and explain its effect on existing clients. See [the specification policy](spec/README.md). From 1ea2078a91a5af1ea86b509d933aa1119d30e434 Mon Sep 17 00:00:00 2001 From: Harsh Savergaonkar Date: Fri, 13 Nov 2026 00:42:07 -0800 Subject: [PATCH 2/2] audit fix: correct workspace UI Node.js floor and clarify screenshots and debug inspection The UI's locked dependencies declare Node.js 22 as their minimum, so the SDK's Node.js 20 floor does not apply to the workspace UI section. Name the two tests that write screenshots, and point to --debug for pausing and stepping through a test in the Playwright Inspector. Co-Authored-By: Claude Fable 5.2 --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28232bf..b7c2b75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ OCTOBER_BUS_BINARY=/tmp/agentintercom npm run test:integration ## Workspace UI (browser) development -The browser workspace needs no production credentials, paid AI subscription, or running hosted account service. The browser tests intercept every `/api` and auth request with fake accounts and API responses on loopback, so a clean checkout plus Node.js is enough. CI runs this workflow with Node.js 24 (see the `workspace-ui` job in `.github/workflows/ci.yml`); Node.js 20 or newer matches the repo floor. +The browser workspace needs no production credentials, paid AI subscription, or running hosted account service. The browser tests intercept every `/api` and auth request with fake accounts and API responses on loopback, so a clean checkout plus Node.js is enough. Use Node.js 22 or newer: the UI's locked dependencies require it (see `web/package-lock.json`), so the TypeScript SDK's Node.js 20 floor does not apply here. CI runs this workflow with Node.js 24 (see the `workspace-ui` job in `.github/workflows/ci.yml`). Source lives in `web/src`; the Go server embeds and serves generated files from `bus/hostedweb/`. Never edit `bus/hostedweb/` by hand: edit `web/src`, rebuild, and commit the regenerated files in the same pull request. @@ -58,7 +58,7 @@ cd web npx playwright test -g "part of the test name" ``` -Watch it in a real browser window with `npx playwright test --headed -g "part of the test name"`. To drive a browser executable you already have instead of the downloaded one, set `CHROMIUM_PATH=/path/to/chromium` (see `web/playwright.config.js`). The tests also write full-page screenshots to `/tmp/agentintercom-*.png`, which is a quick way to inspect layout without keeping a browser open. +Watch it in a real browser window with `npx playwright test --headed -g "part of the test name"`. The window closes when the test ends; use `--debug` instead of `--headed` to pause and step through it in the Playwright Inspector. To drive a browser executable you already have instead of the downloaded one, set `CHROMIUM_PATH=/path/to/chromium` (see `web/playwright.config.js`). The mobile onboarding and signed-out sign-in tests also write full-page screenshots to `/tmp/agentintercom-*.png` each time they run, which is a quick way to inspect those layouts without keeping a browser open. ## Protocol changes