Skip to content

Document a complete local workflow for contributing to the workspace UI - #201

Open
harshsaver wants to merge 3 commits into
mainfrom
docs/187-workspace-ui-workflow
Open

harshsaver wants to merge 3 commits into
mainfrom
docs/187-workspace-ui-workflow

Conversation

@harshsaver

Copy link
Copy Markdown
Member

Fixes #187.

Adds a "Workspace UI (browser) development" section to CONTRIBUTING.md: prerequisites, exact clean-checkout commands, source (web/src) vs generated (bus/hostedweb/) assets and rebuild rules, the CI drift check, single-test and headed runs, the CHROMIUM_PATH override, and an explicit no-credentials-needed statement. Contributor docs only; no README or deployment changes.

Clean-checkout verification (fresh clone, no node_modules, macOS, Node 26): npm ci --ignore-scripts ok, npm run build ok with git diff --exit-code -- ../bus/hostedweb clean, npx playwright install chromium ok, npm test 14/14 green, single-test -g" ok, CHROMIUM_PATH=override ok,--headed` single-test ok.

harshsaver and others added 3 commits November 12, 2026 16:59
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.
… 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 <noreply@anthropic.com>
@harshsaver harshsaver added the agentbox: ready to merge Audited by Claude and Codex; Harsh can merge label Nov 13, 2026
@harshsaver

Copy link
Copy Markdown
Member Author

🤖 Agentbox PR audit: small fixes applied, then ready to merge

What this PR changes

  • What it does: Adds a contributor-guide section explaining how to edit, build and test the browser workspace, including how to watch one browser test.
  • What changes in the product: Nothing visible. Only the contributor guide changes; the application, dependencies and automated checks stay the same.
  • Why it exists: Issue Document a complete local workflow for contributing to the workspace UI #187 asks for a complete local workflow so newcomers do not have to discover the browser setup themselves.
  • Why merge (or why not yet): The workflow matches the repository, but its Node.js 20 prerequisite conflicts with a dependency's declared minimum of Node.js 22. Correct that sentence and clarify screenshots and interactive inspection.
  • What to expect after merging: Contributors have a documented workflow using fake accounts, without production credentials or paid services. No product rollout or follow-up is needed.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 2 turns, commit 1ea2078)

PR audit: #201 — Document a complete local workflow for contributing to the workspace UI

Head: 74781d5

Sign-off

  • Claude (fable, xhigh): ❌ not satisfied — the stated Node.js 20 prerequisite contradicts the UI's locked dependencies (Node 22+); a one-sentence fix makes it mergeable
  • Codex (gpt-6-astra, xhigh): ✅ satisfied — independently confirmed the prerequisite finding and all three proposed edits; agree with the fix decision, with no material changes

Decision

fix — docs-only PR with one unsupported prerequisite claim and two small clarity improvements; retain the three proposed edits to CONTRIBUTING.md.

What changes (plain language)

  • What it does: Adds a contributor-guide section explaining how to edit, build and test the browser workspace, including how to watch one browser test.
  • What changes in the product: Nothing visible. Only the contributor guide changes; the application, dependencies and automated checks stay the same.
  • Why it exists: Issue Document a complete local workflow for contributing to the workspace UI #187 asks for a complete local workflow so newcomers do not have to discover the browser setup themselves.
  • Why merge (or why not yet): The workflow matches the repository, but its Node.js 20 prerequisite conflicts with a dependency's declared minimum of Node.js 22. Correct that sentence and clarify screenshots and interactive inspection.
  • What to expect after merging: Contributors have a documented workflow using fake accounts, without production credentials or paid services. No product rollout or follow-up is needed.

Findings

Blocking

  • CONTRIBUTING.md:38 — "Node.js 20 or newer matches the repo floor" is wrong for the workspace UI's declared dependency requirements. It violates the evidence-based compatibility rule and issue Document a complete local workflow for contributing to the workspace UI #187's prerequisite criterion. Fix plan item 1 resolves it.
    • web/package-lock.json:476-486 pins @supabase/auth-js 2.118.0 with engines.node: ">=22.0.0"; the published package manifest independently confirms this.
    • The other locked tools declare lower floors: Playwright requires Node 20 (web/package-lock.json:472-474,542-544,555-557) and esbuild requires Node 18 (:498-500). Node 22 satisfies the locked set's declared engines.
    • The explicit Node 20 project floor belongs to the SDK (sdk/typescript/package.json:18-20, CONTRIBUTING.md:14). The Node 20/22 CI matrix operates only in sdk/typescript (.github/workflows/ci.yml:85-100); the UI job uses Node 24 (:158-176). The PR author reports local verification on Node 26.
    • Impact is an unsupported prerequisite recommendation and an engine warning on Node 20/21 under normal npm settings. This is not a demonstrated build or runtime failure: the auth library is bundled into browser code (web/src/app.js:1, web/build.mjs:6), and npm treats dependency engines as advisory unless engine-strict is enabled. No repository .npmrc sets it. See npm's engines documentation. Neither auditor ran the workflow on Node 20/21 or Node 22.
    • Node 20 is also listed as end-of-life by the Node.js release table; the lockfile mismatch is sufficient evidence for the correction regardless.

Non-blocking

  • CONTRIBUTING.md:61 — the screenshot statement is true for the full suite, but does not identify which tests produce screenshots. Only mobile onboarding and signed-out sign-in write them (web/tests/workspace.spec.js:111,120). Selecting another test with -g produces neither screenshot and may leave an older image in /tmp. Fix plan item 2 makes the iteration guidance precise; this is a clarification, not a broken full-suite instruction.
  • CONTRIBUTING.md:61 — --headed correctly opens a browser, but does not pause the test for inspection. The pinned Playwright v1.64.1 CLI implementation explicitly overrides headless: true for both headed and inspector modes. The Playwright debugging documentation confirms that --debug provides the Inspector, stepping and no default test timeout. Fix plan item 3 is a useful inspection improvement; the existing headed command is not defective.
  • CONTRIBUTING.md:52 — the three generated filenames match the current tree. web/build.mjs:6 uses legalComments: 'linked', and bus/hosted_web.go:36-37 can serve an additional app.js.LEGAL.txt. The pinned esbuild linker writes that file only when legal comments exist. The committed bundle has no legal-file link and no such file is tracked. CI's git diff --exit-code (.github/workflows/ci.yml:174) does not detect untracked additions; that is a pre-existing limitation, not a blocker or additional fix for this PR.
  • CONTRIBUTING.md:48,58 — plain npx playwright resolves the installed binary after npm ci in web/. CI uses npx --no-install playwright (.github/workflows/ci.yml:175) to prevent an installation if the binary is missing. Both work in the documented sequence. The npm documentation also identifies --no-install as a deprecated alias for --no; no change is needed here.
  • The PR description records 14/14 browser tests from the author's fresh-clone check. The head contains 16 tests because it merged main's two dialog tests (web/tests/workspace.spec.js:346,369; commit 85d411e, PR Fix workspace dialog accessibility and keyboard focus #192). All checks, including workspace-ui, passed for the current head. This is historical verification text, not missing coverage at the head.
  • Checked and correct, no action:
    • Go embeds and serves the generated assets (bus/hosted_web.go:10,27-65); the documented source and output directories match web/build.mjs:4-7.
    • npm test invokes Playwright (web/package.json:6-8), which starts the static server on 127.0.0.1:4794 (web/playwright.config.js:5-6, web/tests/serve.mjs:3-9). The app path is /app.
    • All 16 tests call the fixture, which installs fake session data and intercepts the configured auth origin and API routes (web/tests/workspace.spec.js:4-69). The mocks belong to those test pages, not the static server; an ordinary browser tab would not acquire a mocked account. Headed/debug test execution is therefore the appropriate inspection path.
    • CHROMIUM_PATH is read into Playwright's launchOptions.executablePath (web/playwright.config.js:5). The real hosted command requires Supabase configuration and PostgreSQL (cmd/agentintercom/hosted.go:57-62); none is needed by this test workflow.
    • npm ci --ignore-scripts matches CI and the dependency guide (.github/workflows/ci.yml:171, docs/dependencies.md:37-38). esbuild's installation documentation confirms this works with its platform optional dependency present; the documented command does not omit optional dependencies.
    • The documented Linux --with-deps option matches CI and Playwright's browser installation instructions.
    • The change stays within issue Document a complete local workflow for contributing to the workspace UI #187's contributor-documentation scope. It adds no compatibility layer, obsolete path, dependency, abstraction or architectural change; the remaining ruleset items introduce no additional concern.

Fix plan

All in CONTRIBUTING.md; nothing else changes. Retained from turn 1.

  1. Line 38, replace the last sentence:

    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.

    with:

    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).

  2. Line 61, replace:

    The tests also write full-page screenshots to /tmp/agentintercom-*.png, which is a quick way to inspect layout without keeping a browser open.

    with:

    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.

  3. Line 61, after the first sentence (Watch it in a real browser window with ...), insert:

    The window closes when the test ends; use --debug instead of --headed to pause and step through it in the Playwright Inspector.

Message to the developer

n/a

Questions for Harsh

n/a

Verification

  • Neither auditor installed dependencies, built, typechecked, linted or ran tests. This was a review of code, history, configuration, published documentation and existing CI evidence, as required. Only the untracked audit document was written; no tracked files or GitHub state were changed.
  • Independently read the complete PR diff against 85d411e77a1c866295f33ed3462cd4d364b2c107: only CONTRIBUTING.md, +27/-0. Read the full contributor guide, package manifests, build script, Playwright configuration, static server, all 16 browser tests, CI workflow, dependency guide, embedded-asset handler, hosted command, source HTML and repository ignore/ownership files. Read the relevant lockfile entries and browser app's API/auth initialization; inspected the tracked generated-file list and searched the committed bundle for legal-file links.
  • Retrieved the PR body, discussion and reviews, the full linked issue Document a complete local workflow for contributing to the workspace UI #187 and its comments, and review comments through read-only gh calls. The requested plain gh pr view --comments failed because this installed CLI requests the retired Projects Classic field; explicit --json fields succeeded. Issue Document a complete local workflow for contributing to the workspace UI #187 has five acceptance criteria and no comments. The documented flow covers them, subject to correcting the prerequisite. The author records the clean-checkout exercise in the PR body.
  • Rechecked all external claims using the published Supabase manifest, npm engines/npx documentation, Playwright CLI/browser/debugging documentation and pinned v1.64.1 source, esbuild documentation and pinned v0.28.2 linker source, and Node's release table. Sources are linked beside the relevant findings.
  • CI run 43390551514 reports headSha: 74781d55896be01c25791be1d6c5ce7d5040b45e, success, and all 11 jobs successful. The UI install, build, drift check, Chromium installation and tests all succeeded. GitHub reports MERGEABLE, BLOCKED, and REVIEW_REQUIRED; no PR comments, inline review comments or reviews were present. The branch contains local origin/main at 85d411e.
  • Not independently executed: the workflow on Node 20/21 or Node 22, headed/debug interaction, or CHROMIUM_PATH. The Node 22 minimum is a declared-engine requirement, not a measured minimum runtime. The author's Node 26 and CI's Node 24 evidence are distinct from our read-only review.
  • Final checks after the prose fixes, once audit agreement is complete, from a fresh checkout in web/ on Node 22 or newer (Node 24 matches CI):
    • npm ci --ignore-scripts
    • npm run build
    • git diff --exit-code -- ../bus/hostedweb
    • npx playwright install chromium (add --with-deps on fresh Linux)
    • npm test — expect 16 passed.
    • npx playwright test -g "signed-out" — expect one passed and a fresh /tmp/agentintercom-signin.png.
    • On a desktop, npx playwright test --debug -g "signed-out" — confirm the Inspector opens and stepping reaches the sign-in page; this checks the newly added inspection guidance.
    • No UI typecheck or lint script exists (web/package.json:6-8). Go and SDK checks are unaffected by this documentation-only change; existing required CI must remain green.

Audit log

  • Turn 1 (Claude (fable, xhigh)): Audited from scratch. Checked every command, path, port, flag and claim in the new section against the repo, CI, the lockfile and upstream docs/source. Found one wrong prerequisite (Node 20 vs the locked @supabase/auth-js floor of 22) and two wording gaps (screenshots come from 2 of 16 tests; --headed closes immediately). Wrote a 3-line fix plan; decision fix.
  • Turn 2 (Codex (gpt-6-astra, xhigh)): Independently verified every finding against the diff, surrounding code, exact issue body, current-head CI and upstream sources. Confirmed the Node engine mismatch without claiming a proven runtime failure; clarified that screenshots and debug mode are non-blocking improvements. Checked mock scope, esbuild installation and conditional legal output, and retained the decision and all three fixes without material changes. No additional blocker; satisfied with the audit.

Fixes applied by the audit

  • Applied all three Fix plan edits to CONTRIBUTING.md (Node.js 22+ prerequisite replacing the Node.js 20 claim; screenshots attributed to the mobile onboarding and signed-out sign-in tests; --debug pointer after the --headed sentence) and committed as 1ea2078 on the local branch; only CONTRIBUTING.md changed (2 lines), nothing pushed, AUDIT.md left untracked.
  • Reviewed by Codex (gpt-6-astra, xhigh): All three fixes match the agreed plan exactly, are supported by the reviewed code and documentation, follow the ruleset, and add no scope. Final checks remain pending.

Final checks (run once, after both agents agreed)

Fresh worktree at 1ea2078 on Linux arm64, Node 24.22.0.
npm ci --ignore-scripts — passed; 0 vulnerabilities.
npm run build — passed.
git diff --exit-code -- ../bus/hostedweb — passed; no generated-asset drift.
git diff --check 85d411e..HEAD — passed.
npx playwright install chromium — passed.
npm test — 16/16 passed; output directory redirected under $HOME.
npx playwright test -g "signed-out" — 1/1 passed; confirmed fresh sign-in screenshot.
Screenshot validation — both documented screenshots are valid PNGs.
Typecheck/lint — no applicable scripts configured; Go/SDK checks unaffected.
Interactive --debug check — skipped because no display; not a failure.
Final Git checks — no tracked files changed in either checkout.
Logs: /home/harshsaver/pr201-checks-1ea2078-pfwfvg/logs
No failures; base comparison unnecessary.

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

@harshsaver

Copy link
Copy Markdown
Member Author

Verified the audit fix at head 1ea2078 (pushed before the audit's reviewed head 74781d5): all three CONTRIBUTING.md edits are in — Node.js 22 prerequisite with the lockfile rationale, the two screenshot-writing tests named, and the --debug Inspector sentence. CI green at this head. No further push.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agentbox: ready to merge Audited by Claude and Codex; Harsh can merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document a complete local workflow for contributing to the workspace UI

1 participant