fix(version): Use versioned dev versions - #406
Merged
Merged
Conversation
While developing Claude skills that use the Clerk CLI, it's convenient to gate the skill on a minimum CLI version. However, when using a local dev version of the Clerk CLI, all versions would have the same version string `0.0.0-dev`. Instead, version dev versions based on the underlying version. Assuming the last release in `packages/cli/package.json` was 3.0.0: ``` 3.0.0-dev.20260803.f51f1e4 clean tree at commit f51f1e4 3.0.0-dev.20260803.f51f1e4.dirty ...with uncommitted changes 3.0.0-dev git unavailable, or not run from a checkout ``` I thought it was cleanest to include both the date and the commit, since the date provides human-readable information on how old your working tree is. But we can switch to just the commit, which would match our canary tags.
🦋 Changeset detectedLatest commit: b414270 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
📝 WalkthroughWalkthroughThe CLI replaces the fixed Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/cli-core/src/lib/version.ts`:
- Around line 80-81: Update the dirty-state detection in the version logic
around git() so untracked files are marked dirty as well as tracked
modifications. Use git status --porcelain --untracked-files=normal, or otherwise
query untracked paths separately, and preserve the existing ".dirty" suffix
behavior when any changes are present.
- Around line 93-96: Update resolveDevVersion and resolveCliVersion so an
injected CLI_VERSION containing -dev... is preserved as the complete runtime
version, including date and commit suffix. Prefer the injected development
version before describeCheckout or compiled-binary fallback, while retaining the
existing generated <base>-dev behavior when no injected version is available.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: fbf94fcc-686d-4fcb-86ba-9912084a0534
📒 Files selected for processing (12)
.changeset/silent-weeks-decide.mdCLAUDE.mddocs/releasing.mdpackages/cli-core/src/commands/mcp/probe.tspackages/cli-core/src/commands/update/index.tspackages/cli-core/src/lib/credential-store.test.tspackages/cli-core/src/lib/update-check.test.tspackages/cli-core/src/lib/update-check.tspackages/cli-core/src/lib/user-agent.tspackages/cli-core/src/lib/version.test.tspackages/cli-core/src/lib/version.tsscripts/build.ts
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
clerk/clerk_go(manual)clerk/dashboard(manual)clerk/accounts(manual)clerk/backoffice(manual)clerk/clerk(manual)clerk/clerk-docs(manual)clerk/cloudflare-workers(manual)
- Derive checkout metadata through a Bun macro - Preserve explicit release versions during compilation - Remove runtime Git version resolution from the CLI
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/releasing.md`:
- Line 260: Update the version-resolution documentation around the dev/start
commands to state that when Git is unavailable or the CLI runs outside a
checkout, the fallback is simply <version>-dev without a date, short SHA, or
.dirty suffix. Preserve the existing macro-derived version and explicit release
--version behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 7e435f5a-4ec9-4e67-a283-f12f0e7e9309
📒 Files selected for processing (8)
.changeset/silent-weeks-decide.mdCLAUDE.mddocs/releasing.mdpackages/cli-core/src/lib/credential-store.test.tspackages/cli-core/src/lib/version.macro.tspackages/cli-core/src/lib/version.test.tspackages/cli-core/src/lib/version.tsscripts/build.ts
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
clerk/clerk_go(manual)clerk/dashboard(manual)clerk/accounts(manual)clerk/backoffice(manual)clerk/clerk(manual)clerk/clerk-docs(manual)clerk/cloudflare-workers(manual)
💤 Files with no reviewable changes (1)
- packages/cli-core/src/lib/credential-store.test.ts
🚧 Files skipped from review as they are similar to previous changes (2)
- CLAUDE.md
- .changeset/silent-weeks-decide.md
| ``` | ||
|
|
||
| The `dev` and `start` commands do not inject a version (falls back to `0.0.0-dev`). The release workflow handles version injection. | ||
| The `dev` and `start` commands do not inject a version, so a Bun macro derives and inlines a dev version while transpiling or compiling the CLI: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, suffixed `.dirty` for an unclean tree. A local `build:compile:all` rehearsal leaves `CLI_VERSION` undefined and uses the same macro, so every binary retains the commit it was built from without running Git at runtime. The release workflow always passes an explicit `--version`, which replaces the macro fallback during compilation. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the no-Git fallback.
When Git is unavailable or the CLI runs outside a checkout, the version falls back to <version>-dev without the date, SHA, or .dirty suffix. Add this case so the documentation matches the supported version-resolution behavior.
Proposed documentation update
The `dev` and `start` commands do not inject a version, so a Bun macro derives and inlines a dev version while transpiling or compiling the CLI: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, suffixed `.dirty` for an unclean tree. A local `build:compile:all` rehearsal leaves `CLI_VERSION` undefined and uses the same macro, so every binary retains the commit it was built from without running Git at runtime. The release workflow always passes an explicit `--version`, which replaces the macro fallback during compilation.
+ If Git is unavailable or the CLI is not running from a checkout, the macro falls back to `<version in packages/cli/package.json>-dev`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The `dev` and `start` commands do not inject a version, so a Bun macro derives and inlines a dev version while transpiling or compiling the CLI: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, suffixed `.dirty` for an unclean tree. A local `build:compile:all` rehearsal leaves `CLI_VERSION` undefined and uses the same macro, so every binary retains the commit it was built from without running Git at runtime. The release workflow always passes an explicit `--version`, which replaces the macro fallback during compilation. | |
| The `dev` and `start` commands do not inject a version, so a Bun macro derives and inlines a dev version while transpiling or compiling the CLI: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, suffixed `.dirty` for an unclean tree. A local `build:compile:all` rehearsal leaves `CLI_VERSION` undefined and uses the same macro, so every binary retains the commit it was built from without running Git at runtime. The release workflow always passes an explicit `--version`, which replaces the macro fallback during compilation. If Git is unavailable or the CLI is not running from a checkout, the macro falls back to `<version in packages/cli/package.json>-dev`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/releasing.md` at line 260, Update the version-resolution documentation
around the dev/start commands to state that when Git is unavailable or the CLI
runs outside a checkout, the fallback is simply <version>-dev without a date,
short SHA, or .dirty suffix. Preserve the existing macro-derived version and
explicit release --version behavior.
wyattjoh
approved these changes
Aug 10, 2026
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
While developing Claude skills that use the Clerk CLI, it's convenient to gate the skill on a minimum CLI version. However, when using a local dev version of the Clerk CLI, all versions would have the same version string
0.0.0-dev.Instead, version dev versions based on the underlying version.
Assuming the last release in
packages/cli/package.jsonwas 3.0.0:I thought it was cleanest to include both the date and the commit, since the date provides human-readable information on how old your working tree is. But we can switch to just the commit, which would match our canary tags.