feat(migrate): add custom sources and migrate sources

.changeset/migrate-custom-sources.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk migrate sources`, and let `clerk migrate import --source` take the path to a source you wrote. `clerk migrate sources` lists the built-in sources with the passwords, MFA and metadata each brings across, and `clerk migrate sources <source>` shows where each field lands, how to export, and any caveats. A source you wrote is a `.ts` or `.js` file in your project, checked before use, so a platform with no built-in source can be imported without rebuilding the CLI. `clerk migrate` is still experimental and needs `CLERK_EXPERIMENTAL=migrate`.

packages/cli-core/src/commands/completion/__complete.ts

@@ -28,6 +28,16 @@ function noFileComp(completions: Completion[]): CompletionResult {
   return { completions, directive: DIRECTIVE.NO_FILE_COMP };
 }
 
+/** The known values that start with `partial`, from a registry entry. */
+function matching(known: Completion[], partial: string): CompletionResult {
+  const completions = known.filter((c) => c.name.startsWith(partial));
+  // A migrate source can be a path to one you wrote, so the shell still
+  // completes files beside the built-in keys.
+  return known === SOURCE_COMPLETIONS
+    ? { completions, directive: DIRECTIVE.DEFAULT }
+    : noFileComp(completions);
+}
+
 const HTTP_METHOD_COMPLETIONS: Completion[] = [
   { name: "GET", description: "Read resource" },
   { name: "POST", description: "Create resource" },
@@ -36,7 +46,10 @@ const HTTP_METHOD_COMPLETIONS: Completion[] = [
   { name: "DELETE", description: "Delete resource" },
 ];
 
-/** The built-in migrate sources. Kept off `.choices()` so an unknown key gets the source error. */
+/**
+ * The built-in migrate sources. `--source` also takes a path to a source you
+ * wrote, so it cannot use `.choices()`.
+ */
 const SOURCE_COMPLETIONS: Completion[] = sources.map((entry) => ({
   name: entry.key,
   description: entry.label,
@@ -86,6 +99,7 @@ const KNOWN_OPTION_VALUES: Record<string, Completion[]> = {
  * to root, e.g. "open dashboard".
  */
 const KNOWN_POSITIONAL_COMPLETIONS: Record<string, Completion[]> = {
+  "migrate sources": SOURCE_COMPLETIONS,
   "open dashboard": KNOWN_DASHBOARD_PATHS.map((path) => ({
     name: path,
     description: "Dashboard subpath",
@@ -130,13 +144,15 @@ export function generateCompletions(root: CommandUnknownOpts, args: string[]): C
   }
 
   // Combine subcommands + argument choices + options
+  const argument = completeArguments(command, partial, positionalCount);
   const completions = [
     ...completeSubcommands(command, partial).completions,
-    ...completeArguments(command, partial, positionalCount).completions,
+    ...argument.completions,
     ...completeOptions(command, "", usedOptions).completions,
   ];
 
-  return noFileComp(completions);
+  // The argument decides file completion: on only for one that can be a path.
+  return { completions, directive: argument.directive };
 }
 
 // ── Tree walking ─────────────────────────────────────────────────────────────
@@ -254,10 +270,10 @@ function completeArguments(
   const path = commandPath(cmd);
   const registered = KNOWN_POSITIONAL_COMPLETIONS[path];
   if (registered) {
-    return noFileComp(registered.filter((c) => c.name.startsWith(partial)));
+    return matching(registered, partial);
   }
 
-  return EMPTY_DEFAULT;
+  return EMPTY_NO_FILE;
 }
 
 function commandPath(cmd: CommandUnknownOpts): string {
@@ -290,7 +306,7 @@ function completeOptionValue(opt: Option, flag: string, partial: string): Comple
   const candidates = resolveOptionValues(opt, flag);
   if (!candidates) return EMPTY_DEFAULT;
 
-  return noFileComp(candidates.filter((c) => c.name.startsWith(partial)));
+  return matching(candidates, partial);
 }
 
 function resolveOptionValues(opt: Option, flag: string): Completion[] | undefined {

packages/cli-core/src/commands/completion/index.test.ts

@@ -75,6 +75,17 @@ describe("shell script generators", () => {
     expect(generateFish(BINARY)).toContain(`complete -c ${BINARY}`);
   });
 
+  test("fish reads the directive, and turns off files only when the candidates apply", () => {
+    const script = generateFish(BINARY);
+    // An unconditional -f would turn off file completion for every command.
+    expect(script).not.toContain(`complete -c ${BINARY} -f -a`);
+    expect(script).toContain(
+      `complete -c ${BINARY} -n '__${BINARY}_prepare_completions' -f -a '$__${BINARY}_comp_results'`,
+    );
+    // Bit 4 is NO_FILE_COMP.
+    expect(script).toContain("math --scale 0 $directive / 4 % 2");
+  });
+
   test("fish banner instructs users to mkdir ~/.config/fish/completions before writing", () => {
     const script = generateFish(BINARY);
     const mkdirIdx = script.indexOf("mkdir -p ~/.config/fish/completions");

packages/cli-core/src/commands/completion/shells/fish.ts

@@ -11,31 +11,34 @@ export function generate(binaryName: string): string {
 #   mkdir -p ~/.config/fish/completions
 #   ${binaryName} completion fish > ~/.config/fish/completions/${binaryName}.fish
 
-function __${binaryName}_complete
+function __${binaryName}_prepare_completions
+    set -g __${binaryName}_comp_results
     set -l tokens (commandline -opc)
     set -l current (commandline -ct)
 
     # Remove the command name, pass the rest + current token to __complete
     set -l args $tokens[2..]
     set -l output (${binaryName} __complete $args $current 2>/dev/null)
 
-    if test $status -ne 0
-        return
+    if test $status -ne 0; or test (count $output) -eq 0
+        return 0
     end
 
-    # Last line is the directive — skip it
-    set -l count (count $output)
-    if test $count -le 1
-        return
-    end
+    # Last line is the directive; the rest are the candidates
+    set -l directive (string replace ':' '' -- $output[-1])
+    set -e output[-1]
+    set -g __${binaryName}_comp_results $output
 
-    # Output all lines except the last (directive)
-    for i in (seq 1 (math $count - 1))
-        echo $output[$i]
+    # Nothing starts with what was typed, and the directive allows files (bit 4,
+    # NO_FILE_COMP, clear): false skips the entry below, so fish completes files.
+    set -l names (string replace -r '\\t.*' '' -- $output)
+    if not string match -q -- "$current*" $names; and test (math --scale 0 $directive / 4 % 2) -eq 0
+        return 1
     end
+    return 0
 end
 
-# Disable file completions by default, let __complete control it
-complete -c ${binaryName} -f -a '(__${binaryName}_complete)'
+# The candidates, with files off, whenever __complete has something to offer
+complete -c ${binaryName} -n '__${binaryName}_prepare_completions' -f -a '$__${binaryName}_comp_results'
 `;
 }