feat(config)!: default config files to YAML with ordered detection

[wyattjoh]

What & why

Makes YAML the default config format for clerk config, with ordered file
detection. YAML is friendlier to hand-edit and review than JSON for
config-as-code.

• config pull outputs YAML by default (was JSON). Pass --json for JSON;
  a --output path ending in .json also writes JSON.
• config patch / config put accept YAML input (a superset of JSON, so
  existing JSON files and --json '{...}' keep working) and auto-detect a
  config file when none is given, in order:
  .clerk/config.yaml → .clerk/config.yml → .clerk/config.json.

No wire-format change — input is parsed to an object and the Platform API still
receives JSON. Uses the existing yaml dependency.

Breaking

config pull's default output flips from JSON to YAML, so clerk config pull | jq
and any agent/script assuming JSON will break.
Migration: add --json to any clerk config pull whose output is consumed as JSON.

Testing

format / lint / typecheck / test pass. Added coverage for the resolver
precedence, YAML input, default-file detection, and the --json/extension output
rules; verified a pull → patch round-trip against a local instance.

[wyattjoh]

Stack: config-yaml

• feat(config)!: default config files to YAML with ordered detection #337 👈 this PR
  • feat(cli): add clerk branch commands and --branch targeting #346

Part of a stacked-prs chain. Do not merge manually.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3324d9c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Major

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

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR introduces YAML as the default output format for clerk config pull, replacing unconditional JSON serialization. A new --json flag (and .json extension detection on --output) opts back into JSON. A new config-file.ts module exports CONFIG_FILE_PRECEDENCE (.clerk/config.yaml → .clerk/config.yml → .clerk/config.json) and resolveConfigFile(), which returns the first existing path. config push/patch/put now parse input as YAML (a superset of JSON) and readInput falls back to the auto-detected config file when no --file or piped stdin is present. Documentation, tests, and integration tests are updated throughout.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately describes the main change: making YAML the default config format with ordered file detection, which is the primary objective of this changeset.
Description check	✅ Passed	The description comprehensively explains what changed, why it changed, and includes migration guidance for the breaking change, directly relating to the changeset.

_{✏️ 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.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/cli-core/src/lib/config-file.test.ts (1)

2-11: Use Bun-native file writes in this test helper.

The makeClerkDir helper uses writeFileSync from node:fs; per the Bun guideline for TS/JS files, prefer Bun.write() instead. All call sites are already in async test functions, so converting the helper to async is compatible.

♻️ Proposed refactor

-import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync } from "node:fs";
@@
-function makeClerkDir(files: string[]): string {
+async function makeClerkDir(files: string[]): Promise<string> {
   const dir = mkdtempSync(join(tmpdir(), "clerk-cfg-"));
   mkdirSync(join(dir, ".clerk"), { recursive: true });
-  for (const f of files) writeFileSync(join(dir, f), "x");
+  for (const f of files) await Bun.write(join(dir, f), "x");
   return dir;
 }
@@
-    const dir = makeClerkDir([".clerk/config.yaml", ".clerk/config.json"]);
+    const dir = await makeClerkDir([".clerk/config.yaml", ".clerk/config.json"]);
@@
-    const dir = makeClerkDir([".clerk/config.json"]);
+    const dir = await makeClerkDir([".clerk/config.json"]);
@@
-    const dir = makeClerkDir([]);
+    const dir = await makeClerkDir([]);

🤖 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 `@packages/cli-core/src/lib/config-file.test.ts` around lines 2 - 11, The
makeClerkDir helper function should use Bun-native file writing instead of
node:fs. Convert the makeClerkDir function to async, replace the writeFileSync
import and calls with Bun.write(), and update the loop to await the Bun.write()
calls since they are asynchronous. Since all test call sites are already async,
this change is compatible and aligns with Bun guidelines.

Source: Coding guidelines

🤖 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.

Nitpick comments:
In `@packages/cli-core/src/lib/config-file.test.ts`:
- Around line 2-11: The makeClerkDir helper function should use Bun-native file
writing instead of node:fs. Convert the makeClerkDir function to async, replace
the writeFileSync import and calls with Bun.write(), and update the loop to
await the Bun.write() calls since they are asynchronous. Since all test call
sites are already async, this change is compatible and aligns with Bun
guidelines.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 72a47eb3-d05b-49eb-8cbd-7258bdcba923

📥 Commits

Reviewing files that changed from the base of the PR and between 41ad30e and f40c0db.

📒 Files selected for processing (11)

• .changeset/config-yaml-default.md
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/config/README.md
• packages/cli-core/src/commands/config/pull.test.ts
• packages/cli-core/src/commands/config/pull.ts
• packages/cli-core/src/commands/config/push.test.ts
• packages/cli-core/src/commands/config/push.ts
• packages/cli-core/src/lib/config-file.test.ts
• packages/cli-core/src/lib/config-file.ts
• packages/cli-core/src/test/integration/config-management.test.ts
• packages/cli-core/src/test/integration/input-json.test.ts

[wyattjoh]

!snapshot

[github-actions]

Snapshot published

npm install -g clerk@2.0.1-snapshot.3324d9c

Package	Version
clerk	2.0.1-snapshot.3324d9c

Published from 3324d9c