refactor: restructure into Bun workspace monorepo [1/4]

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.

[wyattjoh]

Summary

Today the CLI is distributed as a bundled JS file (bun build → dist/cli.js) that runs under Node. This works for development but doesn't support distributing a standalone npx clerk binary -- users would need Bun installed, and we can't cross-compile or ship platform-specific native executables.

This PR restructures the repo into a Bun workspace monorepo to enable that:

• packages/cli-core/ -- all CLI source code, commands, and tests (moved from src/). Compiled via bun build --compile into a standalone native binary per platform.
• packages/cli/ -- the clerk npm package users install via npx clerk or npm install -g clerk. Contains a lightweight Node shim (bin/clerk) that:
  1. Detects process.platform, process.arch, and libc variant (glibc vs musl)
  2. Resolves the matching platform package (@clerk/cli-darwin-arm64, @clerk/cli-linux-x64, etc.)
  3. Spawns the prebuilt native binary, forwarding args and exit codes

This is the same pattern used by esbuild, SWC, Turbopack, and other tools that ship native binaries through npm -- a thin wrapper package with optionalDependencies on per-platform packages, so npm install only downloads the binary for the user's OS.

Other changes

• Update CI workflow to use workspace-filtered scripts
• Add .ts extension fixes in imports and test isolation improvements

Review note: 106 files changed, but ~57 are pure renames (src/ → packages/cli-core/src/) with zero content diff -- collapse them in the review UI.

Merge instructions

This is PR 1 of a 4-PR stack. After squash-merging this PR:

git fetch origin main
git rebase origin/main wyattjoh/cross-compile
git push --force-with-lease origin wyattjoh/cross-compile

Then merge PR 2, and repeat for the rest of the stack.

Test plan

• CI passes: bun install, format:check, lint, build, test
• bun run dev launches the CLI from the new workspace path
• bun run build:compile produces a working binary

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures the repository from a single-package CLI into a Bun workspace monorepo. The main CLI source code moves to packages/cli-core/ with TypeScript configuration and build scripts added. A new packages/cli/ package provides a Node.js entry point (bin/clerk) that loads platform-specific prebuilt binaries. All import paths throughout the codebase are updated from .js to .ts extensions. The root package.json converts to a workspace configuration delegating build, test, and lint tasks to @clerk/cli-core. GitHub Actions workflows are updated with job timeouts and simplified test execution. Documentation and linting configurations are adjusted to reference the new package structure.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor: restructure into Bun workspace monorepo [1/4]' accurately and specifically summarizes the main change: converting the repository from a single-package layout into a Bun workspace monorepo structure.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wyattjoh]

PR Stack — Supersedes #31

	PR	Description
1	#43	Monorepo restructure — ← this PR
2	#44	Cross-compile build + smoke tests
3	#45	Release infrastructure (changesets)
4	#46	Release documentation + LICENSE

Review in parallel, merge sequentially 1→2→3→4.
Squash-merge each PR, then rebase the next branch onto the updated base before merging it.