feat(init): support local debugging of clerk-cli skill source

wyattjoh · wyattjoh · commit 266ab755fa0a · 2026-04-07T13:39:17.000-06:00
Extends the clerk-cli skill source resolver from a CLI_VERSION-only
lookup to a four-tier flow:

  1. CLERK_CLI_SKILL_SOURCE env var (explicit override, any mode)
  2. CLI_VERSION → matching v${version} tag URL (released binary)
  3. Local working-tree path resolved via import.meta.url (bun run dev
     from a checked-out repo)
  4. tree/main/skills/clerk-cli (compiled local binary fallback)

The local working-tree path resolution is the killer feature for
developer iteration: edit skills/clerk-cli/SKILL.md in your checkout,
re-run `bun run dev -- init`, and the installer reads your working
tree directly. No push, no rebuild, uncommitted edits visible.

resolveSkillSource is exported as a pure function (takes its three
inputs as plain arguments) so it's testable without mocking process.env,
CLI_VERSION, or the filesystem. Adds 9 unit tests covering every branch.
diff --git a/packages/cli-core/src/commands/init/README.md b/packages/cli-core/src/commands/init/README.md
@@ -160,17 +160,36 @@ After scaffolding (and after env keys are pulled or keyless instructions are pri
 
 Two install commands run, sharing one runner:
 
-### 1. The version-pinned `clerk-cli` skill
+### 1. The `clerk-cli` skill (from this repo)
 
 The `clerk-cli` skill ships **from this repo** at [`<repo-root>/skills/clerk-cli/`](../../../../../skills/clerk-cli/). It is **not** bundled into the binary, it's fetched at install time by the `skills` CLI, the same way any other skill would be.
 
-The source URL is constructed from `CLI_VERSION` (the compile-time global injected by `scripts/build.ts`):
+The source is resolved by [`resolveSkillSource()`](./skills.ts) in this priority order:
 
-```
-https://github.com/clerk/cli/tree/v<CLI_VERSION>/skills/clerk-cli
-```
+1. **`CLERK_CLI_SKILL_SOURCE` env var**, explicit override. Accepts any source the `skills` CLI accepts (github URL, gitlab URL, local path, git URL). Wins over everything else, in any build mode. Use this for testing forks, feature branches, or custom builds. Label: `custom`.
+2. **`CLI_VERSION` injected at compile time**, released binary path. Builds the URL `https://github.com/clerk/cli/tree/v${CLI_VERSION}/skills/clerk-cli`. Every published release (stable, canary, snapshot) tags as `v${CLI_VERSION}` (see `.github/workflows/release.yml` and `scripts/snapshot.ts`), so the same template works for all of them. Label: `v0.0.2` (or whatever the version is).
+3. **Local working-tree path**, dev mode auto-detection. When running via `bun run dev` from a checked-out copy of this repo, [`resolveLocalSkillPath()`](./skills.ts) walks back from `import.meta.url` to `<repo-root>/skills/clerk-cli/` and passes the **filesystem path** as the source. Working-tree edits (committed or not) are picked up immediately, no push, no rebuild. In compiled binaries, `import.meta.url` resolves to a virtual bundle path that doesn't exist on disk, so `existsSync` returns false and this branch is skipped. Label: `local`.
+4. **`tree/main/skills/clerk-cli` fallback**, last resort for compiled local binaries (`bun run build:compile` without `--version`) where neither the env var nor a local working tree is available. Label: `main`.
+
+The label appears in the install heading (e.g. `Installing clerk-cli skill (local) with bunx...`) so the developer can tell at a glance which source the installer is hitting.
+
+#### Local debugging
 
-Every published release (stable, canary, and snapshot) tags as `v${CLI_VERSION}` (see `.github/workflows/release.yml`), so the same `tree/v<version>/skills/clerk-cli` URL works for all of them. The only case without a matching tag is the local-dev sentinel `0.0.0-dev` (set by `scripts/build.ts` when no `--version` is passed), which falls back to `main`.
+Two ways to test changes to the skill content:
+
+```sh
+# 1. Edit-then-run loop (the most common case): just edit the file and re-run.
+#    bun run dev auto-detects the local working-tree path, so uncommitted
+#    edits are visible to the installer immediately.
+$EDITOR skills/clerk-cli/SKILL.md
+bun run dev -- init  # Installing clerk-cli skill (local) with ...
+
+# 2. Test against a remote source: set CLERK_CLI_SKILL_SOURCE to override.
+#    Useful for QA-ing a feature branch, a fork, or a release candidate
+#    before it's tagged.
+CLERK_CLI_SKILL_SOURCE='https://github.com/clerk/cli/tree/feature-x/skills/clerk-cli' \
+  bun run dev -- init
+```
 
 ### 2. The upstream framework-pattern skills
 
diff --git a/packages/cli-core/src/commands/init/skills.test.ts b/packages/cli-core/src/commands/init/skills.test.ts
@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { buildSkillsArgs } from "./skills.ts";
+import { buildSkillsArgs, resolveSkillSource } from "./skills.ts";
 
 describe("buildSkillsArgs", () => {
   const skills = ["clerk", "clerk-setup", "clerk-nextjs-patterns"];
@@ -42,3 +42,102 @@ describe("buildSkillsArgs", () => {
     expect(args).not.toContain("--skill");
   });
 });
+
+const REPO = "https://github.com/clerk/cli";
+
+describe("resolveSkillSource", () => {
+  test("env override wins over everything else", () => {
+    const result = resolveSkillSource({
+      override: "https://github.com/fork/cli/tree/main/skills/clerk-cli",
+      cliVersion: "0.0.2",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("https://github.com/fork/cli/tree/main/skills/clerk-cli");
+    expect(result.label).toBe("custom");
+  });
+
+  test("env override accepts a local path", () => {
+    const result = resolveSkillSource({
+      override: "./my-skills/clerk-cli",
+      cliVersion: undefined,
+      localPath: null,
+    });
+    expect(result.source).toBe("./my-skills/clerk-cli");
+    expect(result.label).toBe("custom");
+  });
+
+  test("empty override string falls through to next branch", () => {
+    const result = resolveSkillSource({
+      override: "",
+      cliVersion: "0.0.2",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2");
+  });
+
+  test("released stable build → matching tag URL", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.2",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    // CLI_VERSION beats local path — released binaries should always use
+    // their pinned tag, even if a checked-out copy of the repo is reachable.
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2");
+  });
+
+  test("released canary build → matching canary tag URL", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.2-canary.v20260407010352",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2-canary.v20260407010352/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2-canary.v20260407010352");
+  });
+
+  test('"0.0.0-dev" sentinel is treated as "no version"', () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.0-dev",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("/home/dev/clerk/cli/skills/clerk-cli");
+    expect(result.label).toBe("local");
+  });
+
+  test("undefined cliVersion + local path available → local path", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: undefined,
+      localPath: "/Users/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("/Users/dev/clerk/cli/skills/clerk-cli");
+    expect(result.label).toBe("local");
+  });
+
+  test("no override, no version, no local path → main fallback", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: undefined,
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/main/skills/clerk-cli`);
+    expect(result.label).toBe("main");
+  });
+
+  test('"0.0.0-dev" sentinel without local path → main fallback', () => {
+    // This is the compiled-local-binary case: bun run build:compile produced
+    // a binary with no --version arg, no env var override, and no source
+    // files reachable on disk.
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.0-dev",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/main/skills/clerk-cli`);
+    expect(result.label).toBe("main");
+  });
+});
diff --git a/packages/cli-core/src/commands/init/skills.ts b/packages/cli-core/src/commands/init/skills.ts
@@ -3,11 +3,15 @@
  *
  * Two installer calls share one runner detection:
  *
- *  1. The `clerk-cli` skill ships from this repo (`clerk/cli`) at the
- *     same git tag as the CLI binary, so the skill content always matches
- *     the binary the user is running. The source URL is constructed from
- *     `CLI_VERSION` (compile-time global, falls back to "main" for the
- *     local-dev sentinel "0.0.0-dev").
+ *  1. The `clerk-cli` skill ships from this repo (`clerk/cli`). Source
+ *     resolution honours, in order:
+ *       a. The `CLERK_CLI_SKILL_SOURCE` env var (any source the `skills`
+ *          CLI accepts: github URL, gitlab URL, local path, etc.)
+ *       b. `CLI_VERSION` injected at compile time → matching `v${version}`
+ *          tag URL
+ *       c. A local working-tree path resolved via `import.meta.url`, when
+ *          running `bun run dev` from a checked-out copy of this repo
+ *       d. `tree/main/skills/clerk-cli` as the last-resort fallback
  *
  *  2. The framework-pattern skills (`clerk`, `clerk-setup`,
  *     `clerk-<framework>-patterns`) ship from the upstream `clerk/skills`
@@ -19,6 +23,10 @@
  * so it runs unattended with global scope and auto-detected agents.
  */
 
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { dim, cyan, yellow } from "../../lib/color.js";
 import { isHuman } from "../../mode.js";
 import { confirm, select } from "../../lib/prompts.js";
@@ -54,6 +62,9 @@ const UPSTREAM_SKILLS_SOURCE = "clerk/skills";
 /** Repo for the version-pinned clerk-cli skill (this repo). */
 const CLERK_CLI_REPO = "https://github.com/clerk/cli";
 
+/** Env var that overrides the clerk-cli skill source for local debugging. */
+const SKILL_SOURCE_OVERRIDE_ENV = "CLERK_CLI_SKILL_SOURCE";
+
 function resolveUpstreamSkills(frameworkDep: string | undefined): string[] {
   const skills = [...BASE_SKILLS];
   if (frameworkDep && FRAMEWORK_SKILL_MAP[frameworkDep]) {
@@ -63,21 +74,73 @@ function resolveUpstreamSkills(frameworkDep: string | undefined): string[] {
 }
 
 /**
- * Resolve the git ref to use when installing the clerk-cli skill from this
- * repo. Every release (stable, canary, snapshot) tags as `v${CLI_VERSION}` —
- * see `.github/workflows/release.yml` and `scripts/snapshot.ts`. The only
- * case without a matching tag is the local-dev sentinel `0.0.0-dev` (set
- * by `scripts/build.ts` when no `--version` is passed), which falls back
- * to `main`.
+ * A resolved skill source, plus a short label used in user-facing log lines
+ * (e.g. "v0.0.2", "main", "local", "custom") so the developer can tell at
+ * a glance which source the installer is hitting.
+ */
+export type SkillSource = { source: string; label: string };
+
+/**
+ * Pure resolver — given the three inputs, return the source URL/path and a
+ * short label. Exposed for unit testing without touching env vars, globals,
+ * or the filesystem.
+ *
+ * Resolution order: env override → released-binary tag → local working-tree
+ * path → main branch fallback. Empty strings count as "not set".
+ */
+export function resolveSkillSource(opts: {
+  override: string | undefined;
+  cliVersion: string | undefined;
+  localPath: string | null;
+}): SkillSource {
+  if (opts.override) {
+    return { source: opts.override, label: "custom" };
+  }
+
+  if (opts.cliVersion && opts.cliVersion !== "0.0.0-dev") {
+    return {
+      source: `${CLERK_CLI_REPO}/tree/v${opts.cliVersion}/skills/clerk-cli`,
+      label: `v${opts.cliVersion}`,
+    };
+  }
+
+  if (opts.localPath) {
+    return { source: opts.localPath, label: "local" };
+  }
+
+  return {
+    source: `${CLERK_CLI_REPO}/tree/main/skills/clerk-cli`,
+    label: "main",
+  };
+}
+
+/**
+ * Try to resolve the local checkout's `skills/clerk-cli/` directory, walking
+ * up from this module's path. Returns null in compiled binaries (where
+ * `import.meta.url` resolves to a virtual bundle path that doesn't exist on
+ * disk) and in npm-installed copies of the package (where the skills/ dir
+ * sits outside the published package).
+ *
+ * The math: skills.ts → init/ → commands/ → src/ → cli-core/ → packages/ →
+ * <repo-root>/. Five `..` segments to reach the repo root.
  */
-function clerkCliSkillRef(): string {
-  const version = typeof CLI_VERSION !== "undefined" ? CLI_VERSION : "0.0.0-dev";
-  if (version === "0.0.0-dev") return "main";
-  return `v${version}`;
+function resolveLocalSkillPath(): string | null {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = resolve(here, "../../../../../skills/clerk-cli");
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
 }
 
-function clerkCliSkillUrl(): string {
-  return `${CLERK_CLI_REPO}/tree/${clerkCliSkillRef()}/skills/clerk-cli`;
+/** Wrapper around {@link resolveSkillSource} that wires up the live inputs. */
+function getClerkCliSkillSource(): SkillSource {
+  return resolveSkillSource({
+    override: process.env[SKILL_SOURCE_OVERRIDE_ENV],
+    cliVersion: typeof CLI_VERSION !== "undefined" ? CLI_VERSION : undefined,
+    localPath: resolveLocalSkillPath(),
+  });
 }
 
 /**
@@ -155,7 +218,7 @@ export async function installSkills(
   skipPrompt: boolean,
 ): Promise<void> {
   const upstreamSkills = resolveUpstreamSkills(frameworkDep);
-  const skillRef = clerkCliSkillRef();
+  const cliSkillSource = getClerkCliSkillSource();
   const skillList = ["clerk-cli", ...upstreamSkills].join(", ");
 
   if (isHuman() && !skipPrompt) {
@@ -195,16 +258,16 @@ export async function installSkills(
 
   const interactive = isHuman() && !skipPrompt;
 
-  // Install the version-pinned clerk-cli skill from this repo, then the
-  // upstream framework patterns. Each call soft-fails independently so a
-  // problem with one source doesn't block the other.
+  // Install the clerk-cli skill from this repo, then the upstream framework
+  // patterns. Each call soft-fails independently so a problem with one source
+  // doesn't block the other.
   const cliSkillOk = await runSkillsAdd(
     runner,
     cwd,
-    clerkCliSkillUrl(),
+    cliSkillSource.source,
     [],
     interactive,
-    `clerk-cli skill (${skillRef})`,
+    `clerk-cli skill (${cliSkillSource.label})`,
   );
 
   const upstreamOk = await runSkillsAdd(
