forgemap 0.5.0 → 0.6.0

package/dist/bin/forgemap.mjs

@@ -3,12 +3,13 @@ import { defineCommand, runMain } from "citty";
 import consola from "consola";
 import { access, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { colors, formatTree } from "consola/utils";
-import { dirname, isAbsolute, join, resolve } from "pathe";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "pathe";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { loadConfig } from "c12";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
+import { updateConfig } from "c12/update";
 import Fuse from "fuse.js";
 //#region src/commands/cd.ts
 /**
@@ -81,6 +82,39 @@ function findGlobalConfig() {
 		if (existsSync(candidate)) return candidate;
 	}
 }
+/**
+* Every `forgemap.config.*` a change could be written to, in resolution order:
+* one per directory walking up from `start` (nearest first, mirroring the
+* loader's first-basename-wins rule), then the global config. Used by the
+* `forge` command to let the user pick a target when more than one exists.
+*/
+function discoverConfigFiles(start = process.cwd()) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	let dir = resolve(start);
+	for (;;) {
+		for (const base of CONFIG_BASENAMES) {
+			const candidate = join(dir, base);
+			if (existsSync(candidate)) {
+				seen.add(candidate);
+				found.push({
+					path: candidate,
+					source: "walk-up"
+				});
+				break;
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const global = findGlobalConfig();
+	if (global && !seen.has(global)) found.push({
+		path: global,
+		source: "global"
+	});
+	return found;
+}
 var DEFAULT_CONFIG$1 = {
 	root: ".",
 	defaultForge: "github",
@@ -117,6 +151,7 @@ async function loadForgeMapConfig(options = {}) {
 			}
 		}
 	}
+	if (explicit) explicit = resolve(startDir, explicit);
 	const cwd = explicit ? dirname(explicit) : startDir;
 	const { config, configFile } = await loadConfig({
 		name: "forgemap",
@@ -1335,146 +1370,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.
@@ -1729,66 +1624,687 @@ var deleteCommand = defineCommand({
 	}
 });
 //#endregion
-//#region src/repos/import.ts
-async function listDirs(path) {
-	try {
-		return (await readdir(path, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
-	} catch (error) {
-		if (error.code === "ENOENT") return [];
-		throw error;
+//#region src/config/forges.ts
+/** Every forge `type` the config schema accepts, in prompt/display order. */
+var FORGE_TYPES = [
+	"github",
+	"gitlab",
+	"gitea",
+	"codeberg",
+	"git"
+];
+/** Canonical host per forge type, offered as the host prompt's default. The
+*  self-hosted flavors (`gitea`, plain `git`) have no universal host, so none
+*  is suggested for them. */
+var DEFAULT_HOSTS = {
+	github: "github.com",
+	gitlab: "gitlab.com",
+	codeberg: "codeberg.org"
+};
+/** Git clone protocols, in prompt order (`ssh` is the schema default). */
+var GIT_PROTOCOLS = ["ssh", "https"];
+/** Reject empty / whitespace-only keys; any other string is a valid map key.
+*  Returns an error message, or `null` when the key is acceptable. */
+function validateForgeKey(raw) {
+	if (raw.trim().length === 0) return "Forge key must not be empty.";
+	return null;
+}
+/** Whether `value` is one of the schema's forge types (narrows a raw flag). */
+function isForgeType(value) {
+	return FORGE_TYPES.includes(value);
+}
+/** Whether `value` is a supported git protocol. */
+function isGitProtocol(value) {
+	return GIT_PROTOCOLS.includes(value);
+}
+/** Build a `ForgeConfig` from collected input, keeping `protocol` only when it
+*  is the non-default (`https`) git protocol. */
+function buildForge(input) {
+	if (input.type === "git") {
+		const forge = {
+			type: "git",
+			host: input.host,
+			dir: input.dir
+		};
+		if (input.protocol === "https") forge.protocol = "https";
+		return forge;
 	}
+	return {
+		type: input.type,
+		host: input.host,
+		dir: input.dir
+	};
+}
+function addForge(config, key, forge) {
+	if (!config.forges) config.forges = {};
+	config.forges[key] = forge;
+}
+function removeForge(config, key) {
+	if (config.forges) delete config.forges[key];
+}
+function setDefaultForge(config, key) {
+	config.defaultForge = key;
 }
+/** Apply a partial change to an existing forge in place. Clears `protocol`
+*  whenever the resulting type is not `git`, since it is meaningless there. */
+function editForge(config, key, patch) {
+	const forge = config.forges?.[key];
+	if (!forge) return;
+	if (patch.type !== void 0) forge.type = patch.type;
+	if (patch.host !== void 0) forge.host = patch.host;
+	if (patch.dir !== void 0) forge.dir = patch.dir;
+	if (forge.type !== "git") delete forge.protocol;
+	else if (patch.protocol === null) delete forge.protocol;
+	else if (patch.protocol !== void 0) forge.protocol = patch.protocol;
+}
+//#endregion
+//#region src/config/mutate.ts
 /**
-* Structure-driven depth-3 walk of `<path>/<serverDir>/<owner>/<repo>`.
-* Unlike `scanRepos`, this is config-free: every top-level directory is a
-* candidate server dir, and the names are discovered rather than configured.
+* Apply an in-place mutation to a `forgemap.config.*` file, preserving its
+* formatting and comments.
+*
+* `.ts`/`.mts`/`.js`/… are round-tripped through c12's `updateConfig`, which
+* parses the module with magicast and edits the exported object literal — it
+* transparently unwraps a `defineForgeMapConfig(...)` call. Plain `.json`
+* configs, which magicast/updateConfig refuse, are read, mutated and written
+* back directly.
+*
+* Rejects when the source can't be edited safely (e.g. forges built dynamically
+* rather than declared as a literal); callers surface that as a manual-edit
+* fallback rather than crashing.
 */
-async function discoverForgemapLayout(path) {
-	const repos = [];
-	for (const serverDir of await listDirs(path)) {
-		const serverPath = join(path, serverDir);
-		for (const owner of await listDirs(serverPath)) {
-			const ownerPath = join(serverPath, owner);
-			for (const repo of await listDirs(ownerPath)) repos.push({
-				serverDir,
-				owner,
-				repo,
-				localPath: join(ownerPath, repo)
-			});
+async function mutateConfigFile(path, mutate) {
+	if (extname(path) === ".json") {
+		const current = JSON.parse(await readFile(path, "utf8"));
+		mutate(current);
+		await writeFile(path, `${JSON.stringify(current, null, 2)}\n`, "utf8");
+		return;
+	}
+	await updateConfig({
+		cwd: dirname(path),
+		configFile: "forgemap.config",
+		onUpdate: (config) => {
+			mutate(config);
 		}
+	});
+}
+//#endregion
+//#region src/repos/picker.ts
+/**
+* Show the interactive repo picker and return the chosen local path
+* (undefined when the user cancels).
+*
+* `$(forgemap pick)` / `$(forgemap path <q>)` captures stdout, so the
+* interactive TUI must not go there. consola/clack writes the UI to stdout AND
+* reads stdout.rows/columns for layout — but a captured stdout is a pipe (no
+* rows → nothing renders). So for the duration of the prompt: route stdout
+* writes to stderr (the real TTY) and borrow stderr's dimensions, then
+* restore. stdout stays clean for the chosen path only.
+*
+* Callers must check {@link canPrompt} first — without a TTY on stdin there is
+* nobody to answer.
+*/
+async function promptRepoChoice(candidates) {
+	const out = process.stdout;
+	const realWrite = out.write;
+	const saved = {
+		rows: Object.getOwnPropertyDescriptor(out, "rows"),
+		columns: Object.getOwnPropertyDescriptor(out, "columns"),
+		isTTY: Object.getOwnPropertyDescriptor(out, "isTTY")
+	};
+	const fake = (key, value) => {
+		Object.defineProperty(out, key, {
+			configurable: true,
+			value
+		});
+	};
+	const restore = (key) => {
+		if (saved[key]) Object.defineProperty(out, key, saved[key]);
+		else delete out[key];
+	};
+	out.write = process.stderr.write.bind(process.stderr);
+	fake("rows", process.stderr.rows ?? 24);
+	fake("columns", process.stderr.columns ?? 80);
+	fake("isTTY", true);
+	let choice;
+	try {
+		choice = await consola.prompt("Select a repo", {
+			type: "select",
+			options: candidates.map((r) => ({
+				label: `${colors.gray(`${r.forgeName}:`)}${r.slug}`,
+				value: r.localPath,
+				hint: r.localPath
+			}))
+		});
+	} finally {
+		out.write = realWrite;
+		restore("rows");
+		restore("columns");
+		restore("isTTY");
 	}
-	return repos;
+	return typeof choice === "string" && choice ? choice : void 0;
 }
-function forgeTypeForHost(host) {
-	return host === "github.com" ? "github" : "git";
+/** Whether an interactive prompt can be shown at all. */
+function canPrompt() {
+	return Boolean(process.stdin.isTTY);
+}
+//#endregion
+//#region src/commands/forge/shared.ts
+/** Whether interactive prompts can be shown (a TTY on stdin to answer them). */
+function interactive() {
+	return canPrompt();
+}
+/** Prompt for free text. Returns the raw string, or `null` when cancelled. */
+async function promptText(message, placeholder) {
+	const answer = await consola.prompt(message, {
+		type: "text",
+		placeholder,
+		cancel: "null"
+	});
+	return typeof answer === "string" ? answer : null;
+}
+/** Prompt to pick one of `options`. Returns the value, or `null` when cancelled. */
+async function promptSelect(message, options) {
+	const answer = await consola.prompt(message, {
+		type: "select",
+		options: [...options],
+		cancel: "null"
+	});
+	return typeof answer === "string" && answer ? answer : null;
+}
+/** Yes/no confirmation. Returns `false` when declined or cancelled. */
+async function confirmChange(message) {
+	return await consola.prompt(message, {
+		type: "confirm",
+		cancel: "null"
+	}) === true;
 }
 /**
-* Derive a `root` + one forge per server dir from the analyzed reports.
-* Host (and therefore type) come from the dominant origin host of the repos
-* under each server dir.
+* Choose which config file `add` writes to.
+*  - `--config <path>` always wins (created when it does not exist).
+*  - otherwise discover candidates: one → use it; several with a TTY → present a
+*    select (the final step before confirming); several without a TTY → nearest.
+*  - nothing discovered → a fresh `forgemap.config.ts` in the cwd.
+*
+* Returns `null` when the user cancels the select.
 */
-function deriveConfig(reports, path) {
-	const forges = {};
-	const counts = /* @__PURE__ */ new Map();
-	const byServer = /* @__PURE__ */ new Map();
-	for (const report of reports) {
-		const list = byServer.get(report.repo.serverDir);
-		if (list) list.push(report);
-		else byServer.set(report.repo.serverDir, [report]);
-	}
-	for (const [serverDir, group] of byServer) {
-		counts.set(serverDir, group.length);
-		const hostTally = /* @__PURE__ */ new Map();
-		for (const report of group) if (report.originHost) hostTally.set(report.originHost, (hostTally.get(report.originHost) ?? 0) + 1);
-		const host = [...hostTally.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
-		forges[serverDir] = {
-			type: host ? forgeTypeForHost(host) : "git",
-			host,
-			dir: serverDir
+async function resolveAddTarget(explicit) {
+	if (explicit) {
+		const path = resolve(process.cwd(), explicit);
+		return {
+			path,
+			create: !existsSync(path)
 		};
 	}
-	return {
-		root: path,
+	const candidates = discoverConfigFiles();
+	if (candidates.length === 0) return {
+		path: join(process.cwd(), "forgemap.config.ts"),
+		create: true
+	};
+	if (candidates.length === 1 || !interactive()) return {
+		path: candidates[0].path,
+		create: false
+	};
+	const choice = await consola.prompt("Which config file should this change be written to?", {
+		type: "select",
+		options: candidates.map((c) => ({
+			label: relative(process.cwd(), c.path) || c.path,
+			value: c.path,
+			hint: c.source
+		})),
+		cancel: "null"
+	});
+	if (typeof choice !== "string" || !choice) {
+		consola.info("Aborted — nothing changed.");
+		return null;
+	}
+	return {
+		path: choice,
+		create: false
+	};
+}
+/**
+* The config file `edit`/`remove` operate on — the forge already lives in a real
+* file, so `--config` or the resolved config file is used. Prints an error and
+* returns `null` when only the built-in defaults are in effect (no file).
+*/
+function existingConfigFile(loaded, explicit) {
+	if (explicit) return resolve(process.cwd(), explicit);
+	if (!loaded.configFile) {
+		consola.error("No forgemap config file found. Run `forgemap config init` or `forgemap forge add` first.");
+		return null;
+	}
+	return loaded.configFile;
+}
+/**
+* Round-trip `mutate` into `path`; on failure (a config too dynamic to rewrite)
+* report it and print the change for manual application instead of crashing.
+* Returns whether the file was updated.
+*/
+async function applyChange(path, mutate, manualHint) {
+	try {
+		await mutateConfigFile(path, mutate);
+		return true;
+	} catch (error) {
+		consola.error(`Could not update ${path} automatically: ${error.message}`);
+		consola.info("Apply this change by hand instead:");
+		manualHint();
+		return false;
+	}
+}
+/** Print a forge as a `forgemap.config` block (the manual-edit fallback). */
+function printManualForge(key, forge) {
+	consola.log(`  ${key}: {`);
+	consola.log(`    type: '${forge.type}',`);
+	consola.log(`    host: '${forge.host}',`);
+	consola.log(`    dir: '${forge.dir}'${forge.protocol ? "," : ""}`);
+	if (forge.protocol) consola.log(`    protocol: '${forge.protocol}'`);
+	consola.log("  }");
+}
+//#endregion
+//#region src/commands/forge/add.ts
+var forgeAddCommand = defineCommand({
+	meta: {
+		name: "add",
+		description: "Add a forge to the config (prompts for anything not passed)"
+	},
+	args: {
+		key: {
+			type: "positional",
+			required: false,
+			description: "Forge key, e.g. github or work"
+		},
+		type: {
+			type: "string",
+			description: `Forge type (${FORGE_TYPES.join(", ")})`
+		},
+		host: {
+			type: "string",
+			description: "Forge host, e.g. github.com"
+		},
+		dir: {
+			type: "string",
+			description: "Directory under root, e.g. comGithub"
+		},
+		protocol: {
+			type: "string",
+			description: `Clone protocol for type=git (${GIT_PROTOCOLS.join(", ")})`
+		},
+		default: {
+			type: "boolean",
+			description: "Set this forge as the default",
+			default: false
+		},
+		config: {
+			type: "string",
+			description: "Path to the forgemap config file to modify"
+		},
+		yes: {
+			type: "boolean",
+			description: "Skip the confirmation prompt",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const loaded = await loadForgeMapConfig({ configFile: args.config });
+		const tty = interactive();
+		let key = typeof args.key === "string" ? args.key.trim() : "";
+		if (!key && tty) {
+			const answer = await promptText("Forge key (e.g. github, work):");
+			if (answer === null) return abort$2();
+			key = answer.trim();
+		}
+		const keyError = validateForgeKey(key);
+		if (keyError) return fail$2(keyError);
+		if (loaded.configFile && key in loaded.config.forges) return fail$2(`Forge "${key}" already exists. Use \`forgemap forge edit ${key}\` to change it.`);
+		let type;
+		if (typeof args.type === "string") {
+			if (!isForgeType(args.type)) return fail$2(invalidType$1(args.type));
+			type = args.type;
+		} else if (tty) {
+			const answer = await promptSelect("Forge type:", FORGE_TYPES);
+			if (answer === null || !isForgeType(answer)) return abort$2();
+			type = answer;
+		}
+		if (!type) return fail$2("Missing forge type. Pass --type.");
+		const suggestedHost = DEFAULT_HOSTS[type] ?? "";
+		let host = typeof args.host === "string" ? args.host.trim() : "";
+		if (!host && tty) {
+			const answer = await promptText("Host:", suggestedHost);
+			if (answer === null) return abort$2();
+			host = answer.trim() || suggestedHost;
+		} else if (!host) host = suggestedHost;
+		if (!host) return fail$2("Missing host. Pass --host.");
+		let dir = typeof args.dir === "string" ? args.dir.trim() : "";
+		if (!dir && tty) {
+			const answer = await promptText("Directory (under root):");
+			if (answer === null) return abort$2();
+			dir = answer.trim();
+		}
+		if (!dir) return fail$2("Missing directory. Pass --dir.");
+		let protocol;
+		if (type === "git") {
+			if (typeof args.protocol === "string") {
+				if (!isGitProtocol(args.protocol)) return fail$2(invalidProtocol$1(args.protocol));
+				protocol = args.protocol;
+			} else if (tty) {
+				const answer = await promptSelect("Clone protocol:", GIT_PROTOCOLS);
+				if (answer !== null && isGitProtocol(answer)) protocol = answer;
+			}
+		}
+		let makeDefault = args.default === true;
+		if (!loaded.configFile) makeDefault = true;
+		else if (!makeDefault && tty) makeDefault = await confirmChange(`Set "${key}" as the default forge?`);
+		const forge = buildForge({
+			type,
+			host,
+			dir,
+			protocol
+		});
+		const target = await resolveAddTarget(args.config);
+		if (!target) return;
+		consola.info(`Add forge "${key}" (${type} → ${host}) into ${target.create ? "new " : ""}${target.path}`);
+		if (tty && !args.yes && !await confirmChange("Apply this change?")) return abort$2();
+		if (target.create) {
+			const written = await writeConfigFile({
+				root: loaded.config.root,
+				defaultForge: key,
+				forges: { [key]: forge }
+			}, { outDir: dirname(target.path) });
+			if (!written) return fail$2(`${target.path} already exists.`);
+			consola.success(`Added forge "${key}" — wrote ${written.path}`);
+			return;
+		}
+		if (await applyChange(target.path, (c) => {
+			addForge(c, key, forge);
+			if (makeDefault) setDefaultForge(c, key);
+		}, () => printManualForge(key, forge))) consola.success(`Added forge "${key}" to ${target.path}`);
+		else process.exitCode = 1;
+	}
+});
+function fail$2(message) {
+	consola.error(message);
+	process.exitCode = 1;
+}
+function abort$2() {
+	consola.info("Aborted — nothing changed.");
+}
+function invalidType$1(value) {
+	return `Invalid type "${value}". Expected one of: ${FORGE_TYPES.join(", ")}.`;
+}
+function invalidProtocol$1(value) {
+	return `Invalid protocol "${value}". Expected one of: ${GIT_PROTOCOLS.join(", ")}.`;
+}
+//#endregion
+//#region src/commands/forge/edit.ts
+var forgeEditCommand = defineCommand({
+	meta: {
+		name: "edit",
+		description: "Edit an existing forge (prompts for fields when none are passed)"
+	},
+	args: {
+		key: {
+			type: "positional",
+			required: false,
+			description: "Forge key to edit"
+		},
+		type: {
+			type: "string",
+			description: `New forge type (${FORGE_TYPES.join(", ")})`
+		},
+		host: {
+			type: "string",
+			description: "New host"
+		},
+		dir: {
+			type: "string",
+			description: "New directory under root"
+		},
+		protocol: {
+			type: "string",
+			description: `New clone protocol for type=git (${GIT_PROTOCOLS.join(", ")})`
+		},
+		config: {
+			type: "string",
+			description: "Path to the forgemap config file to modify"
+		},
+		yes: {
+			type: "boolean",
+			description: "Skip the confirmation prompt",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const loaded = await loadForgeMapConfig({ configFile: args.config });
+		const tty = interactive();
+		const file = existingConfigFile(loaded, args.config);
+		if (!file) {
+			process.exitCode = 1;
+			return;
+		}
+		const forges = loaded.config.forges;
+		let key = typeof args.key === "string" ? args.key.trim() : "";
+		if (!key && tty) {
+			const answer = await promptSelect("Which forge should be edited?", Object.keys(forges));
+			if (answer === null) return abort$1();
+			key = answer;
+		}
+		if (!key) return fail$1("Missing forge key. Pass it as an argument.");
+		const current = forges[key];
+		if (!current) return fail$1(`No forge "${key}" in ${file}. Configured: ${Object.keys(forges).join(", ")}.`);
+		const currentProtocol = current.type === "git" ? current.protocol : void 0;
+		const patch = {};
+		if (typeof args.type === "string") {
+			if (!isForgeType(args.type)) return fail$1(invalidType(args.type));
+			patch.type = args.type;
+		} else if (tty) {
+			const answer = await promptSelect(`Type (current: ${current.type}):`, FORGE_TYPES);
+			if (answer === null) return abort$1();
+			if (isForgeType(answer)) patch.type = answer;
+		}
+		const resultType = patch.type ?? current.type;
+		if (typeof args.host === "string") patch.host = args.host.trim();
+		else if (tty) {
+			const answer = await promptText(`Host (current: ${current.host}):`, current.host);
+			if (answer === null) return abort$1();
+			if (answer.trim()) patch.host = answer.trim();
+		}
+		if (typeof args.dir === "string") patch.dir = args.dir.trim();
+		else if (tty) {
+			const answer = await promptText(`Directory (current: ${current.dir}):`, current.dir);
+			if (answer === null) return abort$1();
+			if (answer.trim()) patch.dir = answer.trim();
+		}
+		if (resultType === "git") {
+			if (typeof args.protocol === "string") {
+				if (!isGitProtocol(args.protocol)) return fail$1(invalidProtocol(args.protocol));
+				patch.protocol = args.protocol;
+			} else if (tty) {
+				const answer = await promptSelect("Clone protocol:", GIT_PROTOCOLS);
+				if (answer !== null && isGitProtocol(answer)) patch.protocol = answer;
+			}
+		}
+		if (!hasChanges(patch)) return fail$1("Nothing to change. Pass --type, --host, --dir or --protocol.");
+		consola.info(`Edit forge "${key}" in ${file}`);
+		if (tty && !args.yes && !await confirmChange("Apply this change?")) return abort$1();
+		const merged = mergeForge(current, currentProtocol, patch, resultType);
+		if (await applyChange(file, (c) => editForge(c, key, patch), () => {
+			consola.log(`Update the "${key}" entry to:`);
+			printManualForge(key, merged);
+		})) consola.success(`Edited forge "${key}" in ${file}`);
+		else process.exitCode = 1;
+	}
+});
+function hasChanges(patch) {
+	return patch.type !== void 0 || patch.host !== void 0 || patch.dir !== void 0 || patch.protocol !== void 0;
+}
+function mergeForge(current, currentProtocol, patch, resultType) {
+	const protocol = resultType === "git" ? patch.protocol ?? currentProtocol : void 0;
+	return {
+		type: resultType,
+		host: patch.host ?? current.host,
+		dir: patch.dir ?? current.dir,
+		...protocol ? { protocol } : {}
+	};
+}
+function fail$1(message) {
+	consola.error(message);
+	process.exitCode = 1;
+}
+function abort$1() {
+	consola.info("Aborted — nothing changed.");
+}
+function invalidType(value) {
+	return `Invalid type "${value}". Expected one of: ${FORGE_TYPES.join(", ")}.`;
+}
+function invalidProtocol(value) {
+	return `Invalid protocol "${value}". Expected one of: ${GIT_PROTOCOLS.join(", ")}.`;
+}
+//#endregion
+//#region src/commands/forge/remove.ts
+var LEAVE_UNSET = "— leave unset —";
+var forgeRemoveCommand = defineCommand({
+	meta: {
+		name: "remove",
+		description: "Remove a forge from the config"
+	},
+	args: {
+		key: {
+			type: "positional",
+			required: false,
+			description: "Forge key to remove"
+		},
+		default: {
+			type: "string",
+			description: "When removing the default forge, reassign the default to this"
+		},
+		config: {
+			type: "string",
+			description: "Path to the forgemap config file to modify"
+		},
+		yes: {
+			type: "boolean",
+			description: "Skip the confirmation prompt",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const loaded = await loadForgeMapConfig({ configFile: args.config });
+		const tty = interactive();
+		const file = existingConfigFile(loaded, args.config);
+		if (!file) {
+			process.exitCode = 1;
+			return;
+		}
+		const forges = loaded.config.forges;
+		let key = typeof args.key === "string" ? args.key.trim() : "";
+		if (!key && tty) {
+			const answer = await promptSelect("Which forge should be removed?", Object.keys(forges));
+			if (answer === null) return abort();
+			key = answer;
+		}
+		if (!key) return fail("Missing forge key. Pass it as an argument.");
+		if (!(key in forges)) return fail(`No forge "${key}" in ${file}. Configured: ${Object.keys(forges).join(", ")}.`);
+		const remaining = Object.keys(forges).filter((k) => k !== key);
+		let newDefault;
+		if (loaded.config.defaultForge === key && remaining.length > 0) if (typeof args.default === "string") {
+			if (!remaining.includes(args.default)) return fail(`Cannot set default to "${args.default}" — not a remaining forge (${remaining.join(", ")}).`);
+			newDefault = args.default;
+		} else if (tty) {
+			const answer = await promptSelect(`"${key}" is the default forge. Pick a new default:`, [...remaining, LEAVE_UNSET]);
+			if (answer === null) return abort();
+			if (answer !== LEAVE_UNSET) newDefault = answer;
+		} else consola.warn(`Removing the default forge "${key}"; defaultForge now points at a missing forge. Pass --default to reassign it.`);
+		consola.info(`Remove forge "${key}" from ${file}${newDefault ? ` (new default: "${newDefault}")` : ""}`);
+		if (tty && !args.yes && !await confirmChange("Apply this change?")) return abort();
+		if (await applyChange(file, (c) => {
+			removeForge(c, key);
+			if (newDefault) setDefaultForge(c, newDefault);
+		}, () => consola.log(`Remove the "${key}" entry from \`forges\` in ${file}.`))) consola.success(`Removed forge "${key}" from ${file}`);
+		else process.exitCode = 1;
+	}
+});
+function fail(message) {
+	consola.error(message);
+	process.exitCode = 1;
+}
+function abort() {
+	consola.info("Aborted — nothing changed.");
+}
+//#endregion
+//#region src/commands/forge/index.ts
+var forgeCommand = defineCommand({
+	meta: {
+		name: "forge",
+		description: "Add, remove or edit forges in the config"
+	},
+	subCommands: {
+		add: forgeAddCommand,
+		remove: forgeRemoveCommand,
+		edit: forgeEditCommand
+	}
+});
+//#endregion
+//#region src/repos/import.ts
+async function listDirs(path) {
+	try {
+		return (await readdir(path, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+/**
+* Structure-driven depth-3 walk of `<path>/<serverDir>/<owner>/<repo>`.
+* Unlike `scanRepos`, this is config-free: every top-level directory is a
+* candidate server dir, and the names are discovered rather than configured.
+*/
+async function discoverForgemapLayout(path) {
+	const repos = [];
+	for (const serverDir of await listDirs(path)) {
+		const serverPath = join(path, serverDir);
+		for (const owner of await listDirs(serverPath)) {
+			const ownerPath = join(serverPath, owner);
+			for (const repo of await listDirs(ownerPath)) repos.push({
+				serverDir,
+				owner,
+				repo,
+				localPath: join(ownerPath, repo)
+			});
+		}
+	}
+	return repos;
+}
+function forgeTypeForHost(host) {
+	return host === "github.com" ? "github" : "git";
+}
+/**
+* Derive a `root` + one forge per server dir from the analyzed reports.
+* Host (and therefore type) come from the dominant origin host of the repos
+* under each server dir.
+*/
+function deriveConfig(reports, path) {
+	const forges = {};
+	const counts = /* @__PURE__ */ new Map();
+	const byServer = /* @__PURE__ */ new Map();
+	for (const report of reports) {
+		const list = byServer.get(report.repo.serverDir);
+		if (list) list.push(report);
+		else byServer.set(report.repo.serverDir, [report]);
+	}
+	for (const [serverDir, group] of byServer) {
+		counts.set(serverDir, group.length);
+		const hostTally = /* @__PURE__ */ new Map();
+		for (const report of group) if (report.originHost) hostTally.set(report.originHost, (hostTally.get(report.originHost) ?? 0) + 1);
+		const host = [...hostTally.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
+		forges[serverDir] = {
+			type: host ? forgeTypeForHost(host) : "git",
+			host,
+			dir: serverDir
+		};
+	}
+	return {
+		root: path,
 		defaultForge: Object.keys(forges).slice().sort((a, b) => {
 			const aGh = forges[a].type === "github" ? 1 : 0;
 			const bGh = forges[b].type === "github" ? 1 : 0;
@@ -2419,7 +2935,7 @@ var infoCommand = defineCommand({
 	async run({ args }) {
 		const binary = resolveBinary(process.argv[1]);
 		const info = {
-			version: "0.5.0",
+			version: "0.6.0",
 			build: detectBuild(binary.resolved),
 			binary,
 			node: process.version,
@@ -2433,89 +2949,176 @@ var infoCommand = defineCommand({
 	}
 });
 //#endregion
-//#region src/repos/match.ts
+//#region src/repos/filter.ts
+var FLAG = "--filter";
 /**
-* The one Fuse configuration every fuzzy lookup shares — `search`, `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.
+* Shared `--filter` option for the commands that enumerate repos
+* (`status`, `sync`, `list`), so the flag reads identically everywhere.
 */
-var REPO_FUSE_OPTIONS = {
-	keys: [
-		"slug",
-		"owner",
-		"repo"
-	],
-	threshold: .3,
-	ignoreLocation: true
+var filterArg = {
+	type: "string",
+	description: "Restrict to repos whose owner or forge name matches. Repeatable; a repo passes if it matches any value."
 };
-function createRepoFuse(repos) {
-	return new Fuse(repos, REPO_FUSE_OPTIONS);
-}
-/** Fuzzy-match `query` against scanned repos, best match first. */
-function matchRepos(repos, query, limit) {
-	return createRepoFuse(repos).search(query, limit ? { limit } : void 0).map((r) => r.item);
-}
-//#endregion
-//#region src/repos/picker.ts
 /**
-* Show the interactive repo picker and return the chosen local path
-* (undefined when the user cancels).
-*
-* `$(forgemap pick)` / `$(forgemap path <q>)` captures stdout, so the
-* interactive TUI must not go there. consola/clack writes the UI to stdout AND
-* reads stdout.rows/columns for layout — but a captured stdout is a pipe (no
-* rows → nothing renders). So for the duration of the prompt: route stdout
-* writes to stderr (the real TTY) and borrow stderr's dimensions, then
-* restore. stdout stays clean for the chosen path only.
+* Recover every `--filter` occurrence from the raw argv.
 *
-* Callers must check {@link canPrompt} first — without a TTY on stdin there is
-* nobody to answer.
+* 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.
 */
-async function promptRepoChoice(candidates) {
-	const out = process.stdout;
-	const realWrite = out.write;
-	const saved = {
-		rows: Object.getOwnPropertyDescriptor(out, "rows"),
-		columns: Object.getOwnPropertyDescriptor(out, "columns"),
-		isTTY: Object.getOwnPropertyDescriptor(out, "isTTY")
-	};
-	const fake = (key, value) => {
-		Object.defineProperty(out, key, {
-			configurable: true,
-			value
-		});
-	};
-	const restore = (key) => {
-		if (saved[key]) Object.defineProperty(out, key, saved[key]);
-		else delete out[key];
-	};
-	out.write = process.stderr.write.bind(process.stderr);
-	fake("rows", process.stderr.rows ?? 24);
-	fake("columns", process.stderr.columns ?? 80);
-	fake("isTTY", true);
-	let choice;
-	try {
-		choice = await consola.prompt("Select a repo", {
-			type: "select",
-			options: candidates.map((r) => ({
-				label: `${colors.gray(`${r.forgeName}:`)}${r.slug}`,
-				value: r.localPath,
-				hint: r.localPath
-			}))
-		});
-	} finally {
-		out.write = realWrite;
-		restore("rows");
-		restore("columns");
-		restore("isTTY");
+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 typeof choice === "string" && choice ? choice : void 0;
+	return values;
 }
-/** Whether an interactive prompt can be shown at all. */
-function canPrompt() {
-	return Boolean(process.stdin.isTTY);
+/**
+* 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 — `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.
+*/
+var REPO_FUSE_OPTIONS = {
+	keys: [
+		"slug",
+		"owner",
+		"repo"
+	],
+	threshold: .3,
+	ignoreLocation: true
+};
+function createRepoFuse(repos) {
+	return new Fuse(repos, REPO_FUSE_OPTIONS);
+}
+/** Fuzzy-match `query` against scanned repos, best match first. */
+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/slug/locate.ts
 /**
 * Turn user input into a repo location.
@@ -2712,7 +3315,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 +3324,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 +3353,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 +3372,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 +3383,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 +3435,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 +3783,297 @@ 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],
+		["forge", forgeCommand]
+	].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",
+		version: "0.6.0",
 		description: "Manage a local repo layout of the form <root>/<forge.dir>/<owner>/<repo>"
 	},
 	subCommands: {
@@ -3342,50 +4084,16 @@ 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,
-		config: configCommand
+		config: configCommand,
+		forge: forgeCommand
 	}
 }));
 //#endregion