Add boxel realm sync status command (CS-10621) by FadhlanR · Pull Request #4781 · cardstack/boxel

FadhlanR · 2026-05-12T08:21:48Z

Summary

Ports the status command from the standalone boxel-cli into the monorepo as boxel realm sync status (alias st). It's git status for a Boxel realm sync — a read-only inspector that shows pending changes between a local sync directory and its remote realm.

boxel realm sync status [local-dir]
boxel realm sync st [local-dir]

--pull downloads only the safe one-way subset (new + modified remote, conflicts left untouched). Lighter than the existing pull command, which is an unconditional overwrite.
--all recursively scans cwd for .boxel-sync.json dirs and prints a one-line summary per workspace.
Attached as a subcommand of sync; the existing bidirectional boxel realm sync <dir> <url> invocation is unaffected.
Reuses classifyLocal / classifyRemote / determineAction from lib/sync-logic.ts — same diff engine push/pull/sync already use.

See docs/cs-10621-realm-sync-status-plan.md for the full design (classification mapping, pitfalls, exit codes).

Linear: https://linear.app/cardstack/issue/CS-10621

Test plan

16 new integration tests in packages/boxel-cli/tests/integration/realm-sync-status.test.ts covering all 7 file-state categories, --pull (safe / leaves conflicts / no-op), --all (walks, skips node_modules, continues past malformed manifest), --all + --pull rejection, missing manifest error.
Existing realm-sync.test.ts regression — passes (no breakage from registerSyncCommand returning Command).
Full boxel-cli unit suite (153 tests) — passes.
pnpm tsc --noEmit and pnpm lint — clean.
Manual smoke: boxel realm sync --help lists status|st; boxel realm sync status --help shows the new flags; boxel realm sync <dir> <url> parent action still works.

🤖 Generated with Claude Code

Port the status command from standalone boxel-cli to the monorepo. It's git status for a Boxel realm sync — a read-only inspector that shows pending changes between a local sync directory and its remote realm. boxel realm sync status [local-dir] boxel realm sync st [local-dir] Options: --pull Download only the safe one-way subset (new + modified remote, never clobbers unsynced local edits or conflicts). --all Recursively scan cwd for .boxel-sync.json dirs and report a summary per workspace. Attached as a subcommand of sync; the existing bidirectional `boxel realm sync <dir> <url>` invocation is unaffected. Reuses the existing classifyLocal / classifyRemote / determineAction shared between push/pull/sync. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

FadhlanR · 2026-05-12T08:48:37Z

Please ignore the lint error it will be fixed once #4751 is merged. I'll improve the boxel-cli CI, so it wont block multiple open PRs.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40bedbcb7a

ℹ️ 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-05-12T08:52:03Z

+      [localFilesWithMtimes, this.remoteMtimes] = await Promise.all([
+        this.getLocalFileListWithMtimes(),
+        this.getRemoteMtimes(),
+      ]);


Fall back when _mtimes cannot be fetched

When getRemoteMtimes() returns an empty map (for example on realms that do not expose _mtimes, or when fetch errors are swallowed by the base helper), this code proceeds to classify against manifest entries without any remote existence fallback. That makes previously synced files appear as deleted-remote (or new-local) even though they still exist remotely, so status reports incorrect diffs and --pull can miss real remote files. sync already avoids this by falling back to directory listing; status needs the same guard before classification.

Useful? React with 👍 / 👎.

Fixed in 0cf5aa4 — fall back to getRemoteFileList() when _mtimes returns empty, mirroring sync.ts. Files land in classifyRemote's 'known in manifest.files → changed' branch (rendered as modified-remote) instead of deleted-remote.

jurgenwerk · 2026-05-12T09:18:09Z

@@ -0,0 +1,207 @@
+# CS-10621 — Reimplement `boxel realm sync status`


Is this file needed?

Removed in 0cf5aa4.

Copilot

Pull request overview

Adds a new Boxel CLI subcommand to inspect realm sync state (boxel realm sync status / st), including an optional “safe pull” mode and a multi-workspace scanner, ported into the monorepo’s @cardstack/boxel-cli.

Changes:

Introduces boxel realm sync status (alias st) with --pull and --all functionality.
Adjusts registerSyncCommand to return the created Commander Command so subcommands can be attached.
Adds Vitest integration coverage for status categories, safe-pull behavior, and --all scanning.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/boxel-cli/src/commands/realm/status.ts	Implements status logic, safe pull, `--all` directory discovery, and CLI rendering/exit codes.
packages/boxel-cli/src/commands/realm/sync.ts	Returns the `sync` command instance to enable attaching `status` as a subcommand.
packages/boxel-cli/src/commands/realm/index.ts	Wires `registerStatusCommand(sync)` under `realm sync`.
packages/boxel-cli/tests/integration/realm-sync-status.test.ts	Adds integration tests for all status categories and new flags.
docs/cs-10621-realm-sync-status-plan.md	Documents the intended design/behavior and exit codes for the new command.

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

FadhlanR · 2026-05-12T13:12:33Z

+    manifestMtime,
+    changes: inspector.changes,
+    pulled: inspector.pulled.slice().sort(),
+    inSync: inspector.changes.length === 0,


Fixed in 0cf5aa4 — inSync is now !inspector.hasError && inspector.changes.length === 0.

FadhlanR · 2026-05-12T13:12:51Z

+      } catch (err) {
+        this.hasError = true;
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ${FG_RED}✗ ${change.file}${RESET} (${msg})`);
+      }


Fixed in 0cf5aa4 — failures accumulate into a failures[] array, and this.error is set to a summary of <file> (<message>) entries so programmatic callers see a non-empty message alongside hasError: true.

FadhlanR · 2026-05-12T13:13:02Z

+  const maxDepth = Number(
+    process.env.BOXEL_STATUS_ALL_MAX_DEPTH ?? DEFAULT_MAX_DEPTH,
+  );


Fixed in 0cf5aa4 — the env var is now validated with Number.isFinite(parsedDepth) && parsedDepth >= 0, falling back to DEFAULT_MAX_DEPTH on invalid input (NaN, negative, non-numeric).

FadhlanR · 2026-05-12T13:13:09Z

+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (ALL_IGNORED_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith('.')) continue;


Fixed in 0cf5aa4 — dropped the blanket entry.name.startsWith('.') skip. The explicit ALL_IGNORED_DIRS list still excludes .git / .boxel-history / .cache / .vscode; other dot-prefixed dirs (e.g. .workspaces/) are now walkable. Added a regression test.

FadhlanR · 2026-05-12T13:13:21Z

+    try {
+      JSON.parse(rawContent);
+    } catch {
+      workspaces.push({
+        localDir: dir,
+        realmUrl: '',
+        changes: [],
+        pulled: [],
+        inSync: false,
+        hasError: true,
+        skipped: 'malformed',
+      });
+      hasError = true;
+      continue;
+    }


Fixed in 0cf5aa4 — statusAll now passes the parsed JSON through isValidManifest(), so JSON-valid-but-shape-wrong manifests bucket as skipped: 'malformed' instead of falling through to status() and being reported as fetch-failed. Added a regression test.

FadhlanR · 2026-05-12T13:13:32Z

+    return;
+  }
+  if (result.workspaces.length === 0) {
+    console.log('No .boxel-sync.json directories found under cwd.');


Fixed in 0cf5aa4 — StatusAllResult now includes rootDir, and the empty-result message uses it: No .boxel-sync.json directories found under ${result.rootDir}.

- Drop docs/cs-10621-realm-sync-status-plan.md (jurgenwerk: not needed). - Fall back to directory listing when _mtimes is unavailable (Codex P1): mirrors sync.ts so remote-existing files don't get classified as `deleted-remote` when the endpoint doesn't return mtimes. - Compute inSync as `!hasError && changes.length === 0` so a realm fetch failure doesn't masquerade as "in sync" (Copilot). - Populate `error` with a summary of failed files on partial --pull failures, instead of setting `hasError: true` with no message (Copilot). - Validate BOXEL_STATUS_ALL_MAX_DEPTH with Number.isFinite and clamp to >= 0; fall back to DEFAULT_MAX_DEPTH on invalid input so the depth limit can't be defeated by a NaN env var (Copilot). - Drop the blanket `entry.name.startsWith('.')` skip in the --all walker. The explicit ignore list already covers .git, .boxel-history, .cache, .vscode; other dot-prefixed dirs (e.g. .workspaces/) should be walkable (Copilot). - Use isValidManifest() in statusAll's pre-check so JSON-valid but shape-invalid manifests are bucketed as `malformed` instead of `fetch-failed` (Copilot). - Include rootDir in StatusAllResult and use it in the "no dirs found" message instead of hard-coding "under cwd" (Copilot). - Add two regression tests: shape-invalid manifest → malformed, and walker discovers sync dirs under non-ignored dot-prefixed dirs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

FadhlanR marked this pull request as ready for review May 12, 2026 08:47

FadhlanR requested a review from a team May 12, 2026 08:47

chatgpt-codex-connector Bot reviewed May 12, 2026

View reviewed changes

jurgenwerk approved these changes May 12, 2026

View reviewed changes

jurgenwerk requested a review from Copilot May 12, 2026 12:29

Copilot started reviewing on behalf of jurgenwerk May 12, 2026 12:30 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

		@@ -0,0 +1,207 @@
		# CS-10621 — Reimplement `boxel realm sync status`

Conversation

FadhlanR commented May 12, 2026

Summary

Test plan

Uh oh!

FadhlanR commented May 12, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants