forgemap 0.5.0-dev.89-5f2e4a1 → 0.5.0-dev.90-1fa1595

package/dist/bin/forgemap.mjs

@@ -1335,146 +1335,6 @@ async function installRcBlock(shell, label, lines, legacyLabels = []) {
 	};
 }
 //#endregion
-//#region src/commands/completion.ts
-var SUBCOMMANDS = [
-	"clone",
-	"import",
-	"cleanup",
-	"delete",
-	"cd",
-	"path",
-	"open",
-	"search",
-	"pick",
-	"status",
-	"sync",
-	"validate",
-	"shell-init",
-	"completion",
-	"config"
-];
-var SLUG_COMMANDS = [
-	"clone",
-	"cd",
-	"path",
-	"open",
-	"search",
-	"pick",
-	"delete"
-];
-function renderBash() {
-	return `# forgemap bash completion — drop into your ~/.bashrc:
-#   eval "$(forgemap completion bash)"
-_forgemap_completion() {
-  local cur prev cmd words
-  COMPREPLY=()
-  cur="\${COMP_WORDS[COMP_CWORD]}"
-  cmd="\${COMP_WORDS[1]}"
-
-  if [ "$COMP_CWORD" = "1" ]; then
-    COMPREPLY=( $(compgen -W "${SUBCOMMANDS.join(" ")}" -- "$cur") )
-    return
-  fi
-
-  case "$cmd" in
-    ${SLUG_COMMANDS.join("|")})
-      local slugs
-      slugs=$(forgemap search '' --format slug 2>/dev/null)
-      COMPREPLY=( $(compgen -W "$slugs" -- "$cur") )
-      ;;
-  esac
-}
-complete -F _forgemap_completion forgemap
-`;
-}
-function renderZsh() {
-	return `# forgemap zsh completion — drop into your ~/.zshrc:
-#   eval "$(forgemap completion zsh)"
-_forgemap() {
-  local context state line
-  local -a subcommands slug_cmds
-  subcommands=(${SUBCOMMANDS.map((s) => `'${s}'`).join(" ")})
-  slug_cmds=(${SLUG_COMMANDS.map((s) => `'${s}'`).join(" ")})
-
-  _arguments -C \\
-    '1: :->cmd' \\
-    '*::arg:->args'
-
-  case "$state" in
-    cmd) _describe 'forgemap subcommand' subcommands ;;
-    args)
-      if (( $slug_cmds[(I)$words[1]] )); then
-        local -a slugs
-        slugs=("\${(@f)$(forgemap search '' --format slug 2>/dev/null)}")
-        _describe 'slug' slugs
-      fi
-      ;;
-  esac
-}
-compdef _forgemap forgemap
-`;
-}
-function renderFish$1() {
-	const slugCmdsList = SLUG_COMMANDS.map((s) => `"${s}"`).join(" ");
-	return `# forgemap fish completion — drop into your ~/.config/fish/config.fish:
-#   forgemap completion fish | source
-
-# Subcommands (depth 1).
-complete -c forgemap -f -n '__fish_use_subcommand' -a '${SUBCOMMANDS.join(" ")}'
-
-# Slugs (depth 2) for commands that take one.
-function __forgemap_needs_slug
-  set -l tokens (commandline -opc)
-  set -l slug_cmds ${slugCmdsList}
-  if test (count $tokens) -ge 2; and contains $tokens[2] $slug_cmds
-    return 0
-  end
-  return 1
-end
-
-complete -c forgemap -f -n '__forgemap_needs_slug' \\
-  -a '(forgemap search "" --format slug 2>/dev/null)'
-`;
-}
-var completionCommand = defineCommand({
-	meta: {
-		name: "completion",
-		description: "Print a shell completion script. Source via `eval \"$(forgemap completion)\"`."
-	},
-	args: {
-		shell: {
-			type: "positional",
-			description: `Shell flavor (${SUPPORTED_SHELLS.join(", ")}). Auto-detected from $SHELL if omitted.`,
-			required: false
-		},
-		install: {
-			type: "boolean",
-			description: "Append the completion loader to your shell's rc file (idempotent) instead of printing",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const requested = args.shell ?? detectShell();
-		if (!SUPPORTED_SHELLS.includes(requested)) {
-			consola.error(`Unsupported shell "${requested}". Supported: ${SUPPORTED_SHELLS.join(", ")}.`);
-			process.exitCode = 1;
-			return;
-		}
-		if (args.install) {
-			const { status, rcFile } = await installRcBlock(requested, "completion", [requested === "fish" ? "forgemap completion fish | source" : `eval "$(forgemap completion ${requested})"`]);
-			if (status === "present") consola.info(`forgemap completion already present in ${rcFile}.`);
-			else {
-				const verb = status === "updated" ? "Updated" : "Added";
-				consola.success(`${verb} forgemap completion in ${rcFile}.`);
-				consola.info(`Run \`source ${rcFile}\` or restart your shell to activate it.`);
-			}
-			return;
-		}
-		const out = requested === "fish" ? renderFish$1() : requested === "zsh" ? renderZsh() : renderBash();
-		process.stdout.write(out);
-	}
-});
-//#endregion
 //#region src/config/write.ts
 var HEADER = `/**
  * forgemap configuration.
@@ -2419,7 +2279,7 @@ var infoCommand = defineCommand({
 	async run({ args }) {
 		const binary = resolveBinary(process.argv[1]);
 		const info = {
-			version: "0.5.0-dev.89-5f2e4a1",
+			version: "0.5.0-dev.90-1fa1595",
 			build: detectBuild(binary.resolved),
 			binary,
 			node: process.version,
@@ -2433,9 +2293,74 @@ var infoCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/repos/filter.ts
+var FLAG = "--filter";
+/**
+* Shared `--filter` option for the commands that enumerate repos
+* (`status`, `sync`, `list`), so the flag reads identically everywhere.
+*/
+var filterArg = {
+	type: "string",
+	description: "Restrict to repos whose owner or forge name matches. Repeatable; a repo passes if it matches any value."
+};
+/**
+* Recover every `--filter` occurrence from the raw argv.
+*
+* citty (0.2.2) parses through `node:util` `parseArgs` and never sets
+* `multiple: true`, so Node keeps only the **last** value of a repeated option:
+* `--filter a --filter b` reaches `args.filter` as `'b'`, silently dropping
+* `a`. The raw argv is the only place the full list survives.
+*/
+function collectFilterArgs(rawArgs) {
+	const values = [];
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+		if (arg === "--") break;
+		if (arg === FLAG) {
+			const next = rawArgs[i + 1];
+			if (next !== void 0 && !next.startsWith("-")) {
+				values.push(next);
+				i++;
+			}
+			continue;
+		}
+		if (arg.startsWith(`${FLAG}=`)) values.push(arg.slice(9));
+	}
+	return values;
+}
+/**
+* Normalize the shapes a filter value arrives in — absent, a single string, or
+* a list — into a list, dropping blanks (`--filter ''`).
+*/
+function normalizeFilters(value) {
+	if (value === void 0) return [];
+	return (Array.isArray(value) ? value : [value]).map((v) => v.trim()).filter((v) => v.length > 0);
+}
+/**
+* The filter values for a run: the raw argv wins, since it is the only shape
+* that survives repetition. Fall back to the parsed value when the argv carries
+* no `--filter` at all, which is how the command is driven programmatically
+* (and in tests), where `rawArgs` may be empty.
+*/
+function resolveFilters(rawArgs, value) {
+	const fromRawArgs = collectFilterArgs(rawArgs);
+	return normalizeFilters(fromRawArgs.length > 0 ? fromRawArgs : value);
+}
+/**
+* Keep the repos matching any of `filters` (OR-combined). A value matches when
+* it equals the repo's owner or its forge name, compared case-insensitively —
+* forge and owner names are case-preserving but not case-significant. An empty
+* filter list is a no-op, so an unused flag never narrows the output.
+*/
+function filterRepos(repos, filters) {
+	if (filters.length === 0) return repos;
+	const wanted = new Set(filters.map((f) => f.toLowerCase()));
+	return repos.filter((r) => wanted.has(r.owner.toLowerCase()) || wanted.has(r.forgeName.toLowerCase()));
+}
+//#endregion
 //#region src/repos/match.ts
 /**
-* The one Fuse configuration every fuzzy lookup shares — `search`, `pick`
+* The one Fuse configuration every fuzzy lookup shares — `list`, `pick`
 * and the fuzzy slug fallback in `path`/`open`. Keeping it in one place is
 * what makes a query rank identically no matter which command runs it.
 */
@@ -2456,6 +2381,88 @@ function matchRepos(repos, query, limit) {
 	return createRepoFuse(repos).search(query, limit ? { limit } : void 0).map((r) => r.item);
 }
 //#endregion
+//#region src/commands/list.ts
+function renderTree$1(repos) {
+	const byForge = /* @__PURE__ */ new Map();
+	for (const r of repos) {
+		let owners = byForge.get(r.forgeName);
+		if (!owners) {
+			owners = /* @__PURE__ */ new Map();
+			byForge.set(r.forgeName, owners);
+		}
+		const list = owners.get(r.owner);
+		if (list) list.push(r);
+		else owners.set(r.owner, [r]);
+	}
+	return formatTree(Array.from(byForge, ([forge, owners]) => ({
+		text: colors.bold(forge),
+		children: Array.from(owners, ([owner, items]) => ({
+			text: owner,
+			children: items.map((r) => ({ text: `${colors.cyan(r.repo)}  ${colors.dim(r.localPath)}` }))
+		}))
+	})));
+}
+var listCommand = defineCommand({
+	meta: {
+		name: "list",
+		description: "List cloned repos; with a query, fuzzy-match by owner/repo and print matches"
+	},
+	args: {
+		query: {
+			type: "positional",
+			description: "Optional search term (matched fuzzily against <owner>/<repo>). Omit to list every repo.",
+			required: false
+		},
+		format: {
+			type: "string",
+			description: "Output format: auto (default), pretty, path, or slug. auto picks pretty in a TTY, path when piped.",
+			default: "auto"
+		},
+		filter: filterArg,
+		limit: {
+			type: "string",
+			description: "Maximum number of matches to print (default: unlimited)"
+		},
+		config: {
+			type: "string",
+			description: "Path to forgemap.config.ts (overrides walk-up discovery)"
+		}
+	},
+	async run({ args, rawArgs }) {
+		const loaded = await loadForgeMapConfig({ configFile: args.config });
+		const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
+		const repos = filterRepos(await scanRepos({
+			config: loaded.config,
+			configDir
+		}), resolveFilters(rawArgs, args.filter));
+		const limit = args.limit ? Number.parseInt(args.limit, 10) : void 0;
+		const query = args.query ?? "";
+		const items = matchRepos(repos, query, limit);
+		const allowed = [
+			"auto",
+			"pretty",
+			"path",
+			"slug"
+		];
+		if (!allowed.includes(args.format)) {
+			consola.error(`Invalid --format value "${args.format}". Allowed: ${allowed.join(", ")}.`);
+			process.exitCode = 1;
+			return;
+		}
+		const requested = args.format;
+		const format = requested === "auto" ? process.stdout.isTTY ? "pretty" : "path" : requested;
+		if (items.length === 0) {
+			if (format === "pretty") consola.info(query ? `No matches for "${query}".` : "No repos found.");
+			return;
+		}
+		if (format === "pretty") {
+			process.stdout.write(`${renderTree$1(items)}\n`);
+			return;
+		}
+		for (const item of items) process.stdout.write(`${format === "slug" ? item.slug : item.localPath}\n`);
+	}
+});
+//#endregion
 //#region src/repos/picker.ts
 /**
 * Show the interactive repo picker and return the chosen local path
@@ -2712,7 +2719,7 @@ var pickCommand = defineCommand({
 			return;
 		}
 		if (!canPrompt()) {
-			consola.error("pick requires an interactive terminal. Use `forgemap search` for non-interactive output.");
+			consola.error("pick requires an interactive terminal. Use `forgemap list` for non-interactive output.");
 			process.exitCode = 1;
 			return;
 		}
@@ -2721,152 +2728,6 @@ var pickCommand = defineCommand({
 	}
 });
 //#endregion
-//#region src/repos/filter.ts
-var FLAG = "--filter";
-/**
-* Shared `--filter` option for the commands that enumerate repos
-* (`status`, `sync`, `search`), so the flag reads identically everywhere.
-*/
-var filterArg = {
-	type: "string",
-	description: "Restrict to repos whose owner or forge name matches. Repeatable; a repo passes if it matches any value."
-};
-/**
-* Recover every `--filter` occurrence from the raw argv.
-*
-* citty (0.2.2) parses through `node:util` `parseArgs` and never sets
-* `multiple: true`, so Node keeps only the **last** value of a repeated option:
-* `--filter a --filter b` reaches `args.filter` as `'b'`, silently dropping
-* `a`. The raw argv is the only place the full list survives.
-*/
-function collectFilterArgs(rawArgs) {
-	const values = [];
-	for (let i = 0; i < rawArgs.length; i++) {
-		const arg = rawArgs[i];
-		if (arg === "--") break;
-		if (arg === FLAG) {
-			const next = rawArgs[i + 1];
-			if (next !== void 0 && !next.startsWith("-")) {
-				values.push(next);
-				i++;
-			}
-			continue;
-		}
-		if (arg.startsWith(`${FLAG}=`)) values.push(arg.slice(9));
-	}
-	return values;
-}
-/**
-* Normalize the shapes a filter value arrives in — absent, a single string, or
-* a list — into a list, dropping blanks (`--filter ''`).
-*/
-function normalizeFilters(value) {
-	if (value === void 0) return [];
-	return (Array.isArray(value) ? value : [value]).map((v) => v.trim()).filter((v) => v.length > 0);
-}
-/**
-* The filter values for a run: the raw argv wins, since it is the only shape
-* that survives repetition. Fall back to the parsed value when the argv carries
-* no `--filter` at all, which is how the command is driven programmatically
-* (and in tests), where `rawArgs` may be empty.
-*/
-function resolveFilters(rawArgs, value) {
-	const fromRawArgs = collectFilterArgs(rawArgs);
-	return normalizeFilters(fromRawArgs.length > 0 ? fromRawArgs : value);
-}
-/**
-* Keep the repos matching any of `filters` (OR-combined). A value matches when
-* it equals the repo's owner or its forge name, compared case-insensitively —
-* forge and owner names are case-preserving but not case-significant. An empty
-* filter list is a no-op, so an unused flag never narrows the output.
-*/
-function filterRepos(repos, filters) {
-	if (filters.length === 0) return repos;
-	const wanted = new Set(filters.map((f) => f.toLowerCase()));
-	return repos.filter((r) => wanted.has(r.owner.toLowerCase()) || wanted.has(r.forgeName.toLowerCase()));
-}
-//#endregion
-//#region src/commands/search.ts
-function renderTree$1(repos) {
-	const byForge = /* @__PURE__ */ new Map();
-	for (const r of repos) {
-		let owners = byForge.get(r.forgeName);
-		if (!owners) {
-			owners = /* @__PURE__ */ new Map();
-			byForge.set(r.forgeName, owners);
-		}
-		const list = owners.get(r.owner);
-		if (list) list.push(r);
-		else owners.set(r.owner, [r]);
-	}
-	return formatTree(Array.from(byForge, ([forge, owners]) => ({
-		text: colors.bold(forge),
-		children: Array.from(owners, ([owner, items]) => ({
-			text: owner,
-			children: items.map((r) => ({ text: `${colors.cyan(r.repo)}  ${colors.dim(r.localPath)}` }))
-		}))
-	})));
-}
-var searchCommand = defineCommand({
-	meta: {
-		name: "search",
-		description: "Fuzzy-search cloned repos by owner/repo and print matching repos"
-	},
-	args: {
-		query: {
-			type: "positional",
-			description: "Search term (matched fuzzily against <owner>/<repo>)",
-			required: true
-		},
-		format: {
-			type: "string",
-			description: "Output format: auto (default), pretty, path, or slug. auto picks pretty in a TTY, path when piped.",
-			default: "auto"
-		},
-		filter: filterArg,
-		limit: {
-			type: "string",
-			description: "Maximum number of matches to print (default: unlimited)"
-		},
-		config: {
-			type: "string",
-			description: "Path to forgemap.config.ts (overrides walk-up discovery)"
-		}
-	},
-	async run({ args, rawArgs }) {
-		const loaded = await loadForgeMapConfig({ configFile: args.config });
-		const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
-		const repos = filterRepos(await scanRepos({
-			config: loaded.config,
-			configDir
-		}), resolveFilters(rawArgs, args.filter));
-		const limit = args.limit ? Number.parseInt(args.limit, 10) : void 0;
-		const items = matchRepos(repos, args.query, limit);
-		const allowed = [
-			"auto",
-			"pretty",
-			"path",
-			"slug"
-		];
-		if (!allowed.includes(args.format)) {
-			consola.error(`Invalid --format value "${args.format}". Allowed: ${allowed.join(", ")}.`);
-			process.exitCode = 1;
-			return;
-		}
-		const requested = args.format;
-		const format = requested === "auto" ? process.stdout.isTTY ? "pretty" : "path" : requested;
-		if (items.length === 0) {
-			if (format === "pretty") consola.info(`No matches for "${args.query}".`);
-			return;
-		}
-		if (format === "pretty") {
-			process.stdout.write(`${renderTree$1(items)}\n`);
-			return;
-		}
-		for (const item of items) process.stdout.write(`${format === "slug" ? item.slug : item.localPath}\n`);
-	}
-});
-//#endregion
 //#region src/commands/shell-init.ts
 /** Append (idempotently) a loader that, plus completion, sets up the shell so
 *  the user only has to re-source their rc file. */
@@ -2896,7 +2757,7 @@ ${name}() {
       target=$(command forgemap pick) || return $?
     else
       local matches
-      matches=$(command forgemap search "$1" --format path)
+      matches=$(command forgemap list "$1" --format path)
       local count
       count=$(printf '%s' "$matches" | grep -c '^/' || true)
       if [ "$count" = "1" ]; then
@@ -2915,7 +2776,7 @@ ${name}() {
 }
 `;
 }
-function renderFish(name) {
+function renderFish$1(name) {
 	return `# forgemap shell integration — drop into your ~/.config/fish/config.fish:
 #   forgemap shell-init fish | source
 
@@ -2926,7 +2787,7 @@ function ${name} --description "forgemap with cd interception"
     if test (count $argv) -eq 0
       set target (command forgemap pick); or return $status
     else
-      set matches (command forgemap search $argv[1] --format path)
+      set matches (command forgemap list $argv[1] --format path)
       set count (count $matches)
       if test $count -eq 1
         set target $matches[1]
@@ -2978,7 +2839,7 @@ var shellInitCommand = defineCommand({
 			await install(requested, name);
 			return;
 		}
-		const out = requested === "fish" ? renderFish(name) : renderPosix(name);
+		const out = requested === "fish" ? renderFish$1(name) : renderPosix(name);
 		process.stdout.write(out);
 	}
 });
@@ -3326,12 +3187,296 @@ function severitySymbol(severity) {
 	if (severity === "warn") return colors.yellow("!");
 	return colors.red("✗");
 }
+var validateCommand = defineCommand({
+	meta: {
+		name: "validate",
+		description: "Preflight: check the config schema, required CLI tools, and root directory"
+	},
+	args: {
+		json: {
+			type: "boolean",
+			description: "Emit a machine-readable JSON report",
+			default: false
+		},
+		config: {
+			type: "string",
+			description: "Path to forgemap.config.ts (overrides walk-up discovery)"
+		}
+	},
+	async run({ args }) {
+		const loaded = await loadForgeMapConfig({ configFile: args.config });
+		const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
+		const checks = await runChecks(loaded.config, configDir);
+		const ok = checks.every((c) => c.severity !== "fail");
+		if (args.json) process.stdout.write(`${JSON.stringify({
+			ok,
+			checks
+		}, null, 2)}\n`);
+		else {
+			for (const c of checks) process.stdout.write(`${severitySymbol(c.severity)} ${c.name.padEnd(22)} ${colors.dim(c.message)}\n`);
+			process.stdout.write(`\n${ok ? colors.green("All checks passed.") : colors.red("Validation failed.")}\n`);
+		}
+		if (!ok) {
+			process.exitCode = 1;
+			return;
+		}
+		if (!loaded.configFile) consola.warn("No forgemap.config.ts found — using built-in defaults. Run `forgemap config init` to materialize one.");
+	}
+});
+//#endregion
+//#region src/commands/completion.ts
+var SLUG_COMMANDS = [
+	"clone",
+	"cd",
+	"path",
+	"open",
+	"list",
+	"pick",
+	"delete"
+];
+var STATIC_FLAG_VALUES = {
+	list: { "--format": [
+		"auto",
+		"pretty",
+		"path",
+		"slug"
+	] },
+	status: { "--format": ["pretty", "json"] },
+	import: {
+		"--format": ["pretty", "json"],
+		"--type": ["forgemap"]
+	}
+};
+var SHELL_POSITIONAL = /* @__PURE__ */ new Set(["completion", "shell-init"]);
+/** Every forgemap command declares `args` as a plain object literal (or omits
+*  it, like `config`), never a thunk — so no `Resolvable` unwrapping is needed. */
+function argsOf(cmd) {
+	return cmd.args ?? {};
+}
+/** Flag names a command exposes, derived from its `defineCommand` args so a new
+*  flag surfaces in completion automatically. Positionals are handled
+*  separately; negatable booleans (those with a `negativeDescription`) also get
+*  their `--no-<flag>` form. */
+function flagsOf(cmd) {
+	const flags = [];
+	for (const [name, def] of Object.entries(argsOf(cmd))) {
+		if (def.type === "positional") continue;
+		flags.push(`--${name}`);
+		if (def.type === "boolean" && def.negativeDescription) flags.push(`--no-${name}`);
+	}
+	return flags;
+}
+/** The ordered subcommand registry, mirroring `rootCommand.subCommands` in
+*  cli.ts. It is kept here rather than imported from cli.ts because that would
+*  form a cycle (cli → completion → cli). Built lazily so the self-reference to
+*  `completionCommand` resolves after the module finishes initializing. */
+function commandSpecs() {
+	return [
+		["clone", cloneCommand],
+		["import", importCommand],
+		["cleanup", cleanupCommand],
+		["delete", deleteCommand],
+		["cd", cdCommand],
+		["path", pathCommand],
+		["open", openCommand],
+		["list", listCommand],
+		["pick", pickCommand],
+		["status", statusCommand],
+		["sync", syncCommand],
+		["validate", validateCommand],
+		["info", infoCommand],
+		["completion", completionCommand],
+		["shell-init", shellInitCommand],
+		["config", configCommand]
+	].map(([name, cmd]) => ({
+		name,
+		flags: flagsOf(cmd),
+		flagValues: STATIC_FLAG_VALUES[name] ?? {},
+		positionalValues: SHELL_POSITIONAL.has(name) ? [...SUPPORTED_SHELLS] : [],
+		slugs: SLUG_COMMANDS.includes(name)
+	}));
+}
+function flagValuePairs(specs) {
+	return specs.flatMap((s) => Object.entries(s.flagValues).map(([flag, values]) => [
+		s.name,
+		flag,
+		values
+	]));
+}
+function renderBash(specs) {
+	const names = specs.map((s) => s.name).join(" ");
+	const valueArms = flagValuePairs(specs).map(([cmd, flag, values]) => `    ${cmd}:${flag}) COMPREPLY=( $(compgen -W "${values.join(" ")}" -- "$cur") ); return ;;`).join("\n");
+	const flagArms = specs.filter((s) => s.flags.length > 0).map((s) => `    ${s.name}) flags="${s.flags.join(" ")}" ;;`).join("\n");
+	const slugCmds = specs.filter((s) => s.slugs).map((s) => s.name);
+	return `# forgemap bash completion — drop into your ~/.bashrc:
+#   eval "$(forgemap completion bash)"
+_forgemap_completion() {
+  local cur prev cmd flags
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cmd="\${COMP_WORDS[1]}"
+
+  if [ "$COMP_CWORD" = "1" ]; then
+    COMPREPLY=( $(compgen -W "${names}" -- "$cur") )
+    return
+  fi
+
+  # Values for flags with a fixed set (e.g. --format), keyed by "<cmd>:<flag>".
+  case "$cmd:$prev" in
+${valueArms}
+  esac
+
+  # Flag names for the current subcommand.
+  if [[ "$cur" == -* ]]; then
+    case "$cmd" in
+${flagArms}
+    esac
+    COMPREPLY=( $(compgen -W "$flags" -- "$cur") )
+    return
+  fi
+
+  # Positional values (repo slugs, or a shell name).
+  case "$cmd" in
+${[slugCmds.length > 0 ? `    ${slugCmds.join("|")})
+      local slugs
+      slugs=$(forgemap list --format slug 2>/dev/null)
+      COMPREPLY=( $(compgen -W "$slugs" -- "$cur") )
+      ;;` : "", ...specs.filter((s) => s.positionalValues.length > 0).map((s) => `    ${s.name}) COMPREPLY=( $(compgen -W "${s.positionalValues.join(" ")}" -- "$cur") ) ;;`)].filter(Boolean).join("\n")}
+  esac
+}
+complete -F _forgemap_completion forgemap
+`;
+}
+function renderZsh(specs) {
+	return `# forgemap zsh completion — drop into your ~/.zshrc:
+#   eval "$(forgemap completion zsh)"
+_forgemap() {
+  local -a subcommands
+  subcommands=(${specs.map((s) => `'${s.name}'`).join(" ")})
+  local cmd="\${words[2]}"
+  local prev="\${words[CURRENT-1]}"
+  local cur="\${words[CURRENT]}"
+
+  if (( CURRENT == 2 )); then
+    _describe 'forgemap subcommand' subcommands
+    return
+  fi
+
+  # Values for flags with a fixed set (e.g. --format), keyed by "<cmd>:<flag>".
+  case "$cmd:$prev" in
+${flagValuePairs(specs).map(([cmd, flag, values]) => `    ${cmd}:${flag}) compadd ${values.join(" ")}; return ;;`).join("\n")}
+  esac
+
+  # Flag names for the current subcommand.
+  if [[ "$cur" == -* ]]; then
+    case "$cmd" in
+${specs.filter((s) => s.flags.length > 0).map((s) => `    ${s.name}) compadd -- ${s.flags.join(" ")}; return ;;`).join("\n")}
+    esac
+    return
+  fi
+
+  # Positional values (repo slugs, or a shell name).
+  case "$cmd" in
+    ${specs.filter((s) => s.slugs).map((s) => s.name).join("|")})
+      local -a slugs
+      slugs=("\${(@f)$(forgemap list --format slug 2>/dev/null)}")
+      _describe 'slug' slugs
+      ;;
+${specs.filter((s) => s.positionalValues.length > 0).map((s) => `    ${s.name}) compadd ${s.positionalValues.join(" ")} ;;`).join("\n")}
+  esac
+}
+compdef _forgemap forgemap
+`;
+}
+function renderFish(specs) {
+	const names = specs.map((s) => s.name).join(" ");
+	const flagLines = specs.flatMap((s) => s.flags.map((flag) => {
+		const long = flag.replace(/^--/, "");
+		const values = s.flagValues[flag];
+		const valuePart = values ? ` -x -a '${values.join(" ")}'` : "";
+		return `complete -c forgemap -n '__fish_seen_subcommand_from ${s.name}' -l ${long}${valuePart}`;
+	})).join("\n");
+	const shellCmds = specs.filter((s) => s.positionalValues.length > 0);
+	return `# forgemap fish completion — drop into your ~/.config/fish/config.fish:
+#   forgemap completion fish | source
+
+# Subcommands (depth 1).
+complete -c forgemap -f -n '__fish_use_subcommand' -a '${names}'
+
+# Flags per subcommand (with fixed value sets where applicable).
+${flagLines}
+
+# Shell flavor for completion / shell-init (depth 2).
+function __forgemap_needs_shell
+  set -l tokens (commandline -opc)
+  set -l shell_cmds ${shellCmds.map((s) => `"${s.name}"`).join(" ")}
+  if test (count $tokens) -ge 2; and contains $tokens[2] $shell_cmds
+    return 0
+  end
+  return 1
+end
+complete -c forgemap -f -n '__forgemap_needs_shell' -a '${shellCmds[0]?.positionalValues.join(" ") ?? ""}'
+
+# Slugs (depth 2) for commands that take one.
+function __forgemap_needs_slug
+  set -l tokens (commandline -opc)
+  set -l slug_cmds ${specs.filter((s) => s.slugs).map((s) => `"${s.name}"`).join(" ")}
+  if test (count $tokens) -ge 2; and contains $tokens[2] $slug_cmds
+    return 0
+  end
+  return 1
+end
+
+complete -c forgemap -f -n '__forgemap_needs_slug' \\
+  -a '(forgemap list --format slug 2>/dev/null)'
+`;
+}
+var completionCommand = defineCommand({
+	meta: {
+		name: "completion",
+		description: "Print a shell completion script. Source via `eval \"$(forgemap completion)\"`."
+	},
+	args: {
+		shell: {
+			type: "positional",
+			description: `Shell flavor (${SUPPORTED_SHELLS.join(", ")}). Auto-detected from $SHELL if omitted.`,
+			required: false
+		},
+		install: {
+			type: "boolean",
+			description: "Append the completion loader to your shell's rc file (idempotent) instead of printing",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const requested = args.shell ?? detectShell();
+		if (!SUPPORTED_SHELLS.includes(requested)) {
+			consola.error(`Unsupported shell "${requested}". Supported: ${SUPPORTED_SHELLS.join(", ")}.`);
+			process.exitCode = 1;
+			return;
+		}
+		if (args.install) {
+			const { status, rcFile } = await installRcBlock(requested, "completion", [requested === "fish" ? "forgemap completion fish | source" : `eval "$(forgemap completion ${requested})"`]);
+			if (status === "present") consola.info(`forgemap completion already present in ${rcFile}.`);
+			else {
+				const verb = status === "updated" ? "Updated" : "Added";
+				consola.success(`${verb} forgemap completion in ${rcFile}.`);
+				consola.info(`Run \`source ${rcFile}\` or restart your shell to activate it.`);
+			}
+			return;
+		}
+		const specs = commandSpecs();
+		const out = requested === "fish" ? renderFish(specs) : requested === "zsh" ? renderZsh(specs) : renderBash(specs);
+		process.stdout.write(out);
+	}
+});
 //#endregion
 //#region src/bin/forgemap.ts
 runMain(defineCommand({
 	meta: {
 		name: "forgemap",
-		version: "0.5.0-dev.89-5f2e4a1",
+		version: "0.5.0-dev.90-1fa1595",
 		description: "Manage a local repo layout of the form <root>/<forge.dir>/<owner>/<repo>"
 	},
 	subCommands: {
@@ -3342,46 +3487,11 @@ runMain(defineCommand({
 		cd: cdCommand,
 		path: pathCommand,
 		open: openCommand,
-		search: searchCommand,
+		list: listCommand,
 		pick: pickCommand,
 		status: statusCommand,
 		sync: syncCommand,
-		validate: defineCommand({
-			meta: {
-				name: "validate",
-				description: "Preflight: check the config schema, required CLI tools, and root directory"
-			},
-			args: {
-				json: {
-					type: "boolean",
-					description: "Emit a machine-readable JSON report",
-					default: false
-				},
-				config: {
-					type: "string",
-					description: "Path to forgemap.config.ts (overrides walk-up discovery)"
-				}
-			},
-			async run({ args }) {
-				const loaded = await loadForgeMapConfig({ configFile: args.config });
-				const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
-				const checks = await runChecks(loaded.config, configDir);
-				const ok = checks.every((c) => c.severity !== "fail");
-				if (args.json) process.stdout.write(`${JSON.stringify({
-					ok,
-					checks
-				}, null, 2)}\n`);
-				else {
-					for (const c of checks) process.stdout.write(`${severitySymbol(c.severity)} ${c.name.padEnd(22)} ${colors.dim(c.message)}\n`);
-					process.stdout.write(`\n${ok ? colors.green("All checks passed.") : colors.red("Validation failed.")}\n`);
-				}
-				if (!ok) {
-					process.exitCode = 1;
-					return;
-				}
-				if (!loaded.configFile) consola.warn("No forgemap.config.ts found — using built-in defaults. Run `forgemap config init` to materialize one.");
-			}
-		}),
+		validate: validateCommand,
 		info: infoCommand,
 		completion: completionCommand,
 		"shell-init": shellInitCommand,