boxel-cli: add `boxel realm milestone` command by FadhlanR · Pull Request #4751 · cardstack/boxel

FadhlanR · 2026-05-11T04:02:47Z

Summary

Ports the milestone command from the standalone cardstack/boxel-cli repo into the monorepo as boxel realm milestone
New command lives at packages/boxel-cli/src/commands/realm/milestone.ts, following the same pattern as realm history
Backed by the existing CheckpointManager methods (markMilestone, unmarkMilestone, getMilestones) — no library changes needed

Commands

boxel realm milestone <local-dir>                            # list all milestones
boxel realm milestone <local-dir> --mark <ref> --name <n>   # tag a checkpoint as milestone
boxel realm milestone <local-dir> --remove <ref>            # remove milestone tag
boxel realm milestone <local-dir> --json                    # machine-readable output

<ref> accepts a 1-based index, 7-char short hash, or full hash (via existing findCheckpoint).

Test plan

18 new integration tests in tests/integration/realm-milestone.test.ts — all passing locally
Existing checkpoint-manager unit tests (28) still pass
pnpm tsc --noEmit clean

Closes CS-10626

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 21a6c246de

ℹ️ 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-12T07:55:02Z

+    if (!(await manager.isInitialized())) {
+      return { ok: true, milestones: [] };
+    }
+    const milestones = await manager.getMilestones();


List all milestones instead of only latest 100

listMilestonesStep calls manager.getMilestones() without any way to override its internal cap (currently 100 checkpoints), so boxel realm milestone <local-dir> silently omits milestones on older commits in long-lived workspaces. Because this command is presented as listing milestones generally, users can miss existing milestone tags unless they happen to be in the newest 100 checkpoints; consider plumbing a limit through list mode (or removing the cap) so listing is complete/predictable.

Useful? React with 👍 / 👎.

Good catch. Fixed in d6d4d08 by rewriting getMilestones to enumerate by milestone/* tag via git log --no-walk rather than walking the most recent N checkpoints — no internal cap, and milestones buried deep in history are now returned. Added a unit test that tags an old checkpoint then buries it under 120 more to lock the behavior in.

Copilot

Pull request overview

Adds a new boxel realm milestone subcommand to the monorepo CLI for listing, marking, and removing checkpoint milestones in a workspace’s local .boxel-history/ repository, along with integration tests and a small plugin/docs update.

Changes:

Introduces realmMilestone() programmatic API + registerMilestoneCommand() Commander wiring for boxel realm milestone.
Adds new Vitest integration coverage for list/mark/remove/validation flows.
Updates the realm-sync skill doc and bumps the plugin version.

Reviewed changes

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

Show a summary per file

File	Description
packages/boxel-cli/tests/integration/realm-milestone.test.ts	New integration tests covering milestone list/mark/remove behaviors.
packages/boxel-cli/src/commands/realm/milestone.ts	Implements the `boxel realm milestone` command and core logic (ref resolution, printing, JSON mode).
packages/boxel-cli/src/commands/realm/index.ts	Registers the new `milestone` subcommand under `boxel realm`.
packages/boxel-cli/plugin/skills/realm-sync/SKILL.md	Adjusts generated command docs for `boxel realm watch` (and related prose).
packages/boxel-cli/plugin/.claude-plugin/plugin.json	Plugin version bump to reflect updated skills/docs.

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

FadhlanR · 2026-05-12T13:18:41Z

+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exit(1);
+        return;


Fixed in d6d4d08 — --json branch now uses cliLog.output(...). Smoke-tested --quiet --json (JSON still reaches stdout) and --quiet alone (decorative output is silenced).

FadhlanR · 2026-05-12T13:18:50Z

+### `boxel realm watch`

-Watch a Boxel realm for server-side changes and pull them into a local directory
-
-**Arguments:**
-
- `<realm-url>` — The URL of the realm to watch (e.g., https://app.boxel.ai/demo/)
- `<local-dir>` — The local directory to write changes into
-
-**Options:**
-
- `-i, --interval <seconds>` — Polling interval in seconds
- `-d, --debounce <seconds>` — Seconds to wait after a burst of changes before applying them
- `--realm-secret-seed` — Administrative auth: prompt for a realm secret seed and mint a JWT locally instead of using a Matrix profile (env: BOXEL_REALM_SECRET_SEED)
+Watch a Boxel realm; subcommands manage watch processes


Fixed in d6d4d08. Replaced the bare realm watch entry in SKILL_SPECS with realm watch start and realm watch stop, regenerated the synopsis, and updated the prose table at the top of the file (added a row for watch stop too).

FadhlanR · 2026-05-12T13:18:54Z

+    });
+
+    it('returns error for non-existent directory', async () => {
+      const result = await realmMilestone('/tmp/no-such-dir-boxel-milestone');


Fixed in d6d4d08 — the test now creates a temp dir via mkdtempSync and immediately rmSyncs it, so the path is guaranteed not to exist when realmMilestone is invoked.

Ports the milestone command from the standalone boxel-cli into the monorepo under `boxel realm milestone`. Exposes list, --mark, and --remove modes backed by the existing CheckpointManager methods, with --json output and 18 integration tests. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- checkpoint-manager: getMilestones now enumerates by milestone/* tag via `git log --no-walk`, so list mode is complete regardless of how deep the tagged checkpoints sit in history (was capped at the newest 100). Extract parseCheckpointLine helper to share log-line parsing. - realm milestone: --json branch uses cliLog.output so payload reaches stdout even under --quiet. - realm-sync SKILL.md: replace bare `realm watch` entry with the `watch start` and `watch stop` subcommands (in SKILL_SPECS + regenerated synopsis), and update the prose table accordingly. - realm-milestone integration test: derive non-existent-dir path via mkdtempSync+rmSync instead of a hard-coded /tmp path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Synopsis-bump CI gate: plugin.json must diff vs main when any generated:commands block in plugin/skills/**/SKILL.md changes. Main has moved to 0.1.3 independently of this branch, so bump to 0.1.4 to satisfy the check. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

FadhlanR force-pushed the cs-10626-realm-milestone branch from 628b92e to 8ca476d Compare May 12, 2026 06:56

FadhlanR marked this pull request as ready for review May 12, 2026 07:51

chatgpt-codex-connector Bot reviewed May 12, 2026

View reviewed changes

This was referenced May 12, 2026

Add boxel realm sync status command (CS-10621) #4781

Open

Add boxel consolidate-workspaces command (CS-10632) #4780

Open

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

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

Copilot AI reviewed May 12, 2026

View reviewed changes

habdelra approved these changes May 12, 2026

View reviewed changes

FadhlanR and others added 4 commits May 12, 2026 20:57

lint fix

ba2289c

FadhlanR force-pushed the cs-10626-realm-milestone branch from d6d4d08 to 6846334 Compare May 12, 2026 13:59

FadhlanR merged commit 3898bbd into main May 12, 2026
25 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

boxel-cli: add `boxel realm milestone` command#4751

boxel-cli: add `boxel realm milestone` command#4751
FadhlanR merged 4 commits into
mainfrom
cs-10626-realm-milestone

FadhlanR commented May 11, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 12, 2026

Uh oh!

FadhlanR May 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

FadhlanR May 12, 2026

Uh oh!

FadhlanR May 12, 2026

Uh oh!

FadhlanR May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

FadhlanR commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Commands

Test plan

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!

FadhlanR May 12, 2026

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!

FadhlanR May 12, 2026

Choose a reason for hiding this comment

Uh oh!

FadhlanR May 12, 2026

Choose a reason for hiding this comment

Uh oh!

FadhlanR May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

FadhlanR commented May 11, 2026 •

edited

Loading