boxel cli: add `boxel realm create` command by jurgenwerk · Pull Request #4368 · cardstack/boxel

jurgenwerk · 2026-04-09T09:10:59Z

Summary

Implement full boxel realm create command with proper Matrix auth flow (login → OpenID → server token → create realm)
Store new realm JWT and realm server token in profile store (~/.boxel-cli/profiles.json) so subsequent commands work without re-auth
Register new realms in Matrix account data so they appear in the Boxel dashboard
Default to random background image and letter-based icon when --background/--icon not provided
Cache realm server token with automatic re-auth on 401 expiry

Test plan

Unit tests cover full auth flow, JWT storage, Matrix account data registration
Endpoint validation tests (uppercase, spaces, special chars rejected)
Error handling tests (Matrix login failure, server token failure, network errors, 401/500)
Non-fatal failure tests (realm token fetch failure, account data failure don't block creation)
Default background/icon selection verified
All 45 tests pass, type check passes, build succeeds
Manual test: created 3 realms against local realm server successfully

🤖 Generated with Claude Code

Port profile management from standalone boxel-cli into monorepo. Adds ProfileManager class for CRUD operations on ~/.boxel-cli/profiles.json with subcommands: list, add, switch, remove, migrate. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Extract shared ANSI color constants to src/lib/colors.ts - Remove duplicate getEnvironmentShortLabel (keep getEnvironmentLabel) - Remove fragile realmServerUrl inference from matrixUrl hostname pattern - Return distinct result from migrateFromEnv for new vs existing profiles - Update existing profile password on re-migration - Add REALM_SERVER_URL to migrate command precheck - Remove configDir param from singleton getProfileManager() - Fix promptPassword raw mode cleanup with try/finally pattern - Reject unknown domains in addProfile without explicit URLs - Validate JSON shape in loadConfig() - Skip Windows-incompatible file permission test Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Wrap setup code in try/catch so raw mode is restored if anything throws between setRawMode(true) and the data handler. Pair stdin.resume() with stdin.pause() on cleanup to restore original flow state. Use reject() instead of throw for proper promise error propagation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implement the full realm creation flow in boxel-cli: - Matrix login → OpenID token → realm server token → POST /_create-realm - Store realm JWT in profile store for subsequent commands - Cache realm server token to skip auth round-trips on repeat calls - Auto re-auth on 401 when cached server token expires - Register new realm in Matrix account data (Boxel dashboard visibility) - Default random background and letter-based icon when not provided - Add realm token storage (realmTokens, realmServerToken) to ProfileManager Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Remove mocked unit tests (tests/commands/realm-create.test.ts) - Add integration tests that start their own realm server on port 4446 using realm-server test helpers (PostgreSQL + Synapse required) - Register a fresh Matrix user per test run for full auth flow testing - Add test:unit and test:integration scripts for split CI execution - Rename endpoint to realmName in create.ts for clarity - Add @cardstack/postgres devDependency and vitest realm-server alias Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-09T12:07:03Z

Host Test Results

2 194 tests +2 194 2 179 ✅ +2 179 2h 5m 35s ⏱️ + 2h 5m 35s
1 suites + 1 15 💤 + 15
1 files + 1 0 ❌ ± 0

Results for commit cb93163. ± Comparison against base commit dffc745.

♻️ This comment has been updated with latest results.

- Update CI job to start realm-server test services (PostgreSQL, Synapse, host-dist, prerenderer) before running integration tests - Split CI into test:unit (always) and test:integration (with services) - Use env-var defaults for PGHOST/PGPORT/PGUSER so CI and local both work Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The integration tests need the boxel_migrated_template database which is created by the realm-server's prepare-test-pg.sh script (separate Docker PostgreSQL on port 55436). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mise sets PGPORT=5435 for the dev PG, which caused ${PGPORT:-55436} to resolve to 5435 in CI. The test PG with boxel_migrated_template is always on port 55436. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace inline env vars with a shell script that mirrors realm-server's run-qunit-with-test-pg.sh: prepare test PG, set PGPORT=55436, run tests, clean up on exit. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-09T13:00:03Z

Realm Server Test Results

1 files ± 0 0 suites - 1 0s ⏱️ - 14m 1s
0 tests - 843 0 ✅ - 843 0 💤 ±0 0 ❌ ±0
0 runs - 914 0 ✅ - 914 0 💤 ±0 0 ❌ ±0

Results for commit cb93163. ± Comparison against base commit dffc745.

♻️ This comment has been updated with latest results.

…and-2

ProfileManager now owns the full auth flow: - getOrRefreshServerToken() — cached token or Matrix login → server token - refreshServerToken() — force re-auth (for 401 retry) - fetchAndStoreRealmTokens() — get realm JWTs and persist them - registerRealmInDashboard() — Matrix account data registration createRealm no longer imports or knows about Matrix login, OpenID tokens, or server session endpoints. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

authedFetch wraps fetch with automatic server token injection and 401 retry. createRealm now uses pm.authedFetch() instead of manually getting tokens and handling re-auth. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Reimplements the boxel realm create CLI command with a full Matrix-based auth flow, token persistence in the CLI profile store, and dashboard registration, plus adds integration test coverage and CI wiring to run those tests.

Changes:

Added boxel realm create command implementation and supporting Matrix/realm-server auth helpers.
Extended profile storage to cache realm JWTs and realm-server session tokens, with auto-refresh on 401.
Added integration test harness (with test Postgres) and updated CI/workspace config to run integration tests.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`packages/boxel-cli/src/commands/realm/create.ts`	Implements realm creation request + defaults + post-create token/dashboard steps
`packages/boxel-cli/src/commands/realm/index.ts`	Registers new `realm` command namespace
`packages/boxel-cli/src/index.ts`	Hooks realm command registration into CLI entrypoint
`packages/boxel-cli/src/lib/auth.ts`	Implements Matrix login → OpenID → realm server session + realm token/account-data helpers
`packages/boxel-cli/src/lib/profile-manager.ts`	Adds persisted realm token storage, cached server token, and `authedFetch` w/ refresh
`packages/boxel-cli/tests/integration/realm-create.test.ts`	Integration coverage for create + token caching behavior
`packages/boxel-cli/tests/helpers/integration.ts`	Starts test realm server + Synapse user registration + profile test utilities
`packages/boxel-cli/tests/helpers/setup-realm-server.ts`	Test logging setup for realm-server dependencies
`packages/boxel-cli/tests/scripts/run-integration-with-test-pg.sh`	Script to run integration suite with test PG lifecycle
`packages/boxel-cli/vitest.config.mjs`	Adds alias to realm-server test helpers + increases timeout
`packages/boxel-cli/tsconfig.json`	Excludes integration helpers/tests from `tsc --noEmit` typecheck
`packages/boxel-cli/package.json`	Adds postgres devDependency and splits unit vs integration test scripts
`.github/workflows/ci.yaml`	Runs CLI integration tests and restores test web assets artifact
`pnpm-lock.yaml`	Updates lockfile for new workspace dependency usage

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/boxel-cli/src/lib/profile-manager.ts

packages/boxel-cli/src/lib/auth.ts

.github/workflows/ci.yaml

packages/boxel-cli/tests/scripts/run-integration-with-test-pg.sh

packages/boxel-cli/tests/helpers/integration.ts

packages/boxel-cli/src/commands/realm/create.ts

- Import APP_BOXEL_REALMS_EVENT_TYPE from runtime-common instead of duplicating the string constant - Check PUT response in addRealmToMatrixAccountData and throw on failure - Preserve Request headers in authedFetch when input is a Request object - Allow iconURL to be undefined instead of sending empty string - Run integration tests single-forked to prevent port collisions - Add wait-on step in CI before running integration tests - Include boxel-cli in test-web-assets trigger condition Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fetchAndStoreRealmToken now takes a specific realm URL and only persists that one token, instead of dumping every accessible realm token into profiles.json. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wait-on is not a dependency of boxel-cli so npx can't find it. Replace with a simple curl polling loop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLI tests only need _create-realm and _realm-auth — no card rendering. Replacing the real prerenderer with a no-op stub avoids launching Chrome, which fails in CI and was the slowest part of the tests (~15s → ~2.4s). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

With the noop prerenderer, we don't need test-web-assets, host-dist, icons, prerender services, or the dev realm server. Just Matrix (for user registration/login) and the test PG (started by the integration test script). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests setRealmToken, getRealmToken, setRealmServerToken, getRealmServerToken — including disk persistence and edge cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb93163344

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-10T12:25:02Z

packages/boxel-cli/src/lib/auth.ts

+  } catch {
+    // Best-effort — if we can't read existing realms, start fresh
+  }
+
+  if (!existingRealms.includes(realmUrl)) {


Preserve existing realm list when account-data read fails

If reading Matrix account data fails (network error, malformed JSON, or any non-OK response), this code falls through with existingRealms = [] and still performs the PUT, which can overwrite the user's app.boxel.realms event with only the newly created realm and silently drop previously saved realms from the dashboard. The safer behavior is to abort/update with a warning when the read is not trustworthy (except the explicit "not found" case), rather than "starting fresh" and writing back.

Useful? React with 👍 / 👎.

FadhlanR and others added 6 commits April 8, 2026 15:55

Update imports

1d9086f

jurgenwerk and others added 4 commits April 9, 2026 14:07

Add prepare-test-pg step to boxel-cli CI

b95848e

The integration tests need the boxel_migrated_template database which is created by the realm-server's prepare-test-pg.sh script (separate Docker PostgreSQL on port 55436). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Hardcode test PG port 55436 in test:integration script

6958d62

Mise sets PGPORT=5435 for the dev PG, which caused ${PGPORT:-55436} to resolve to 5435 in CI. The test PG with boxel_migrated_template is always on port 55436. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jurgenwerk mentioned this pull request Apr 9, 2026

CS-10615: Reimplement boxel profile command #4354

Merged

3 tasks

jurgenwerk and others added 6 commits April 10, 2026 09:32

Merge branch 'main' into cs-10619-reimplement-boxel-realm-create-comm…

281e49d

…and-2

Add authedFetch to ProfileManager

1d8d5a5

authedFetch wraps fetch with automatic server token injection and 401 retry. createRealm now uses pm.authedFetch() instead of manually getting tokens and handling re-auth. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Hardcode test realm server port instead of using testPort()

27e3fad

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Inline test realm server URL

738c538

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lint fix

d1a726c

jurgenwerk requested a review from Copilot April 10, 2026 09:11

Copilot started reviewing on behalf of jurgenwerk April 10, 2026 09:12 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

jurgenwerk and others added 5 commits April 10, 2026 11:27

Lint fix

d4f076f

Fix CI: use curl loop instead of npx wait-on

185c005

wait-on is not a dependency of boxel-cli so npx can't find it. Replace with a simple curl polling loop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use background-action for service wait (same pattern as other CI jobs)

0e805aa

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jurgenwerk changed the title ~~CS-10619: Reimplement boxel realm create command~~ boxel cli: add boxel realm create command Apr 10, 2026

jurgenwerk and others added 2 commits April 10, 2026 12:53

jurgenwerk and others added 4 commits April 10, 2026 13:28

Remove unnecessary comment about CI

6cdc3a6

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove unnecessary 60s beforeAll timeout

861f39b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rename registerRealmInDashboard to addToUserRealms

d09eaf1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add unit tests for realm token storage in ProfileManager

cb93163

Tests setRealmToken, getRealmToken, setRealmServerToken, getRealmServerToken — including disk persistence and edge cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jurgenwerk marked this pull request as ready for review April 10, 2026 12:18

jurgenwerk requested review from a team and habdelra April 10, 2026 12:18

chatgpt-codex-connector bot reviewed Apr 10, 2026

View reviewed changes

habdelra approved these changes Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

boxel cli: add `boxel realm create` command#4368

boxel cli: add `boxel realm create` command#4368
jurgenwerk wants to merge 27 commits intomainfrom
cs-10619-reimplement-boxel-realm-create-command-2

jurgenwerk commented Apr 9, 2026

Uh oh!

github-actions bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jurgenwerk commented Apr 9, 2026

Summary

Test plan

Uh oh!

github-actions bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

github-actions bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Realm Server Test Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Apr 9, 2026 •

edited

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading