forgemap 0.1.0-dev.22-d31fc67 → 0.1.0-dev.26-b896caf

package/dist/bin/forgemap.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
 import consola from "consola";
+import { readdir, readFile, mkdir, writeFile, stat, rm, rmdir, rename, access } from "node:fs/promises";
+import { colors, formatTree } from "consola/utils";
+import { isAbsolute, resolve, dirname, join } from "pathe";
+import { homedir } from "node:os";
 import { existsSync } from "node:fs";
-import { mkdir, writeFile, readdir } from "node:fs/promises";
-import { dirname, isAbsolute, resolve, join } from "pathe";
 import { loadConfig } from "c12";
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { colors, formatTree } from "consola/utils";
+import { createHash } from "node:crypto";
 import Fuse from "fuse.js";
 const cdCommand = defineCommand({
   meta: {
@@ -34,7 +35,47 @@ const cdCommand = defineCommand({
     process.exitCode = 1;
   }
 });
-const DEFAULT_CONFIG = {
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return resolve(homedir(), p.slice(2));
+  return p;
+}
+function resolveRoot(root, configDir) {
+  const expanded = expandTilde(root);
+  if (isAbsolute(expanded)) return expanded;
+  return resolve(configDir, expanded);
+}
+const CONFIG_BASENAMES = [
+  "forgemap.config.ts",
+  "forgemap.config.mts",
+  "forgemap.config.cts",
+  "forgemap.config.js",
+  "forgemap.config.mjs",
+  "forgemap.config.cjs",
+  "forgemap.config.json"
+];
+function findConfigUp(start) {
+  let dir = resolve(start);
+  for (; ; ) {
+    for (const base of CONFIG_BASENAMES) {
+      const candidate = join(dir, base);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function findGlobalConfig() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  const dir = join(base, "forgemap");
+  for (const baseName of CONFIG_BASENAMES) {
+    const candidate = join(dir, baseName);
+    if (existsSync(candidate)) return candidate;
+  }
+  return void 0;
+}
+const DEFAULT_CONFIG$1 = {
   root: ".",
   defaultForge: "github",
   forges: {
@@ -47,24 +88,21 @@ const DEFAULT_CONFIG = {
 };
 async function loadForgeMapConfig(options = {}) {
   const envConfig = process.env.FORGEMAP_CONFIG;
-  const explicit = options.configFile ?? envConfig;
-  const cwd = explicit ? dirname(explicit) : options.cwd ?? process.cwd();
+  const startDir = options.cwd ?? process.cwd();
+  const explicit = options.configFile ?? envConfig ?? findConfigUp(startDir) ?? findGlobalConfig();
+  const cwd = explicit ? dirname(explicit) : startDir;
   const { config, configFile } = await loadConfig({
     name: "forgemap",
     cwd,
     configFile: explicit ? explicit : "forgemap.config",
     rcFile: false,
     globalRc: false,
-    dotenv: false,
-    defaults: DEFAULT_CONFIG
+    dotenv: false
   });
   const merged = {
-    root: config.root ?? DEFAULT_CONFIG.root,
-    defaultForge: config.defaultForge ?? DEFAULT_CONFIG.defaultForge,
-    forges: {
-      ...DEFAULT_CONFIG.forges,
-      ...config.forges
-    }
+    root: config.root ?? DEFAULT_CONFIG$1.root,
+    defaultForge: config.defaultForge ?? DEFAULT_CONFIG$1.defaultForge,
+    forges: config.forges && Object.keys(config.forges).length > 0 ? config.forges : DEFAULT_CONFIG$1.forges
   };
   return {
     config: merged,
@@ -81,6 +119,57 @@ function execInherit(command, args) {
     });
   });
 }
+function execCapture(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env ? { ...process.env, ...options.env } : void 0,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let timer;
+    let killer;
+    if (options.timeoutMs && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        killer = setTimeout(() => child.kill("SIGKILL"), 2e3);
+        killer.unref();
+      }, options.timeoutMs);
+      timer.unref();
+    }
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      if (killer) clearTimeout(killer);
+      if (!settled) {
+        settled = true;
+        rejectPromise(error);
+      }
+    });
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (killer) clearTimeout(killer);
+      if (!settled) {
+        settled = true;
+        resolvePromise({
+          code: code ?? (timedOut ? 124 : 0),
+          stdout,
+          stderr,
+          timedOut
+        });
+      }
+    });
+  });
+}
 function hasCommand(command) {
   return new Promise((resolvePromise) => {
     const child = spawn(
@@ -94,6 +183,115 @@ function hasCommand(command) {
     child.on("close", (code) => resolvePromise(code === 0));
   });
 }
+const REMOTE_TIMEOUT_MS = 1e4;
+function buildCloneUrl(opts) {
+  const forge = opts.forge;
+  const protocol = opts.protocol ?? forge.protocol ?? "ssh";
+  if (protocol === "https") {
+    return `https://${forge.host}/${opts.owner}/${opts.repo}.git`;
+  }
+  return `git@${forge.host}:${opts.owner}/${opts.repo}.git`;
+}
+const gitAdapter = {
+  async clone(options) {
+    if (!await hasCommand("git")) {
+      throw new Error(
+        "`git` is not installed. Install it from https://git-scm.com/ and try again."
+      );
+    }
+    const url = buildCloneUrl(options);
+    const { code } = await execInherit("git", ["clone", url, options.dest]);
+    if (code !== 0) {
+      throw new Error(`git clone exited with code ${code}`);
+    }
+  },
+  async checkRemote(input) {
+    if (!await hasCommand("git")) {
+      return { state: "unknown", reason: "git not installed" };
+    }
+    const url = input.originUrl ?? buildCloneUrl(input);
+    const result = await execCapture("git", ["ls-remote", url], {
+      timeoutMs: REMOTE_TIMEOUT_MS,
+      env: {
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_SSH_COMMAND: "ssh -oBatchMode=yes -oConnectTimeout=5"
+      }
+    });
+    if (result.timedOut) {
+      return { state: "unknown", reason: "ls-remote timed out" };
+    }
+    if (result.code === 0) {
+      return {
+        state: "exists",
+        canonical: { owner: input.owner, repo: input.repo }
+      };
+    }
+    if (isRepoMissing(result.stderr)) {
+      return { state: "gone" };
+    }
+    const reason = result.stderr.split("\n").map((line) => line.trim()).find(Boolean) ?? `git ls-remote exited with code ${result.code}`;
+    return { state: "unknown", reason };
+  }
+};
+function isRepoMissing(stderr) {
+  const s = stderr.toLowerCase();
+  return /repository not found/.test(s) || /remote:.*not found/.test(s) || /\b404\b/.test(s) || /could not find repository/.test(s);
+}
+async function mapLimit(items, limit, fn) {
+  const results = Array.from({ length: items.length });
+  const max = Math.max(1, Math.min(limit, items.length));
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: max }, () => worker()));
+  return results;
+}
+const GRAPHQL_CHUNK = 100;
+const FALLBACK_CONCURRENCY = 8;
+const GH_TIMEOUT_MS = 2e4;
+async function checkOne(owner, repo) {
+  const result = await execCapture(
+    "gh",
+    ["api", `repos/${owner}/${repo}`, "--jq", ".full_name"],
+    { timeoutMs: GH_TIMEOUT_MS }
+  );
+  if (result.timedOut) {
+    return { state: "unknown", reason: "gh api timed out" };
+  }
+  if (result.code !== 0) {
+    if (/404|not found/i.test(result.stderr)) return { state: "gone" };
+    return {
+      state: "unknown",
+      reason: result.stderr.trim() || `gh api exited with code ${result.code}`
+    };
+  }
+  const fullName = result.stdout.trim();
+  const [canonicalOwner, canonicalRepo] = fullName.split("/");
+  if (!canonicalOwner || !canonicalRepo) {
+    return { state: "unknown", reason: "could not parse gh api full_name" };
+  }
+  const canonical = { owner: canonicalOwner, repo: canonicalRepo };
+  if (canonicalOwner === owner && canonicalRepo === repo) {
+    return { state: "exists", canonical };
+  }
+  return {
+    state: "moved",
+    canonical,
+    canonicalUrl: `https://github.com/${canonicalOwner}/${canonicalRepo}.git`
+  };
+}
+function buildQuery(chunk) {
+  const fields = chunk.map(
+    (input, i) => `  r${i}: repository(owner: ${JSON.stringify(input.owner)}, name: ${JSON.stringify(input.repo)}) { nameWithOwner }`
+  ).join("\n");
+  return `query {
+${fields}
+}`;
+}
 const githubAdapter = {
   async clone({ owner, repo, dest }) {
     if (!await hasCommand("gh")) {
@@ -110,17 +308,81 @@ const githubAdapter = {
     if (code !== 0) {
       throw new Error(`gh repo clone exited with code ${code}`);
     }
+  },
+  async checkRemote({
+    owner,
+    repo
+  }) {
+    if (!await hasCommand("gh")) {
+      return { state: "unknown", reason: "gh not installed" };
+    }
+    return checkOne(owner, repo);
+  },
+  /**
+   * One GraphQL request resolves up to GRAPHQL_CHUNK repos at once. GraphQL
+   * does not follow rename redirects, so a hit means `exists`; a null/miss
+   * could be either `gone` or `moved` and is disambiguated with a single
+   * (redirect-following) REST call, run concurrency-limited.
+   */
+  async checkRemotes(inputs) {
+    if (inputs.length === 0) return [];
+    if (!await hasCommand("gh")) {
+      return inputs.map(() => ({
+        state: "unknown",
+        reason: "gh not installed"
+      }));
+    }
+    const results = Array.from(
+      { length: inputs.length },
+      () => null
+    );
+    for (let start = 0; start < inputs.length; start += GRAPHQL_CHUNK) {
+      const chunk = inputs.slice(start, start + GRAPHQL_CHUNK);
+      const res = await execCapture(
+        "gh",
+        ["api", "graphql", "-f", `query=${buildQuery(chunk)}`],
+        { timeoutMs: GH_TIMEOUT_MS }
+      );
+      let data = null;
+      try {
+        data = JSON.parse(res.stdout).data ?? null;
+      } catch {
+        data = null;
+      }
+      for (let i = 0; i < chunk.length; i++) {
+        const node = data?.[`r${i}`];
+        if (node?.nameWithOwner) {
+          const [owner, repo] = node.nameWithOwner.split("/");
+          if (owner && repo) {
+            results[start + i] = {
+              state: "exists",
+              canonical: { owner, repo }
+            };
+          }
+        }
+      }
+    }
+    const pending = results.flatMap((r, i) => r === null ? [i] : []);
+    await mapLimit(pending, FALLBACK_CONCURRENCY, async (index) => {
+      results[index] = await checkOne(
+        inputs[index].owner,
+        inputs[index].repo
+      );
+    });
+    return results;
   }
 };
 function getForgeAdapter(type) {
   switch (type) {
     case "github":
       return githubAdapter;
+    case "git":
+      return gitAdapter;
     case "gitlab":
     case "gitea":
     case "codeberg":
       throw new Error(
-        `Forge type "${type}" is not implemented yet. Only "github" is supported in this release.`
+        `Forge type "${type}" is not implemented yet. Use type: 'git' for a vanilla git-clone fallback.`
       );
     default: {
       const exhaustive = type;
@@ -128,6 +390,275 @@ function getForgeAdapter(type) {
     }
   }
 }
+async function listDirs$1(path) {
+  try {
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+async function scanRepos(options) {
+  const { config, configDir } = options;
+  const root = resolveRoot(config.root, configDir);
+  const repos = [];
+  for (const [forgeName, forge] of Object.entries(config.forges)) {
+    const forgeRoot = join(root, forge.dir);
+    const owners = await listDirs$1(forgeRoot);
+    for (const owner of owners) {
+      const ownerPath = join(forgeRoot, owner);
+      const repoNames = await listDirs$1(ownerPath);
+      for (const repo of repoNames) {
+        repos.push({
+          forgeName,
+          forge,
+          owner,
+          repo,
+          localPath: join(ownerPath, repo),
+          slug: `${owner}/${repo}`
+        });
+      }
+    }
+  }
+  return repos;
+}
+const DEFAULT_TTL_MS = 6e4;
+function ttl() {
+  const env = process.env.FORGEMAP_CACHE_TTL_MS;
+  if (!env) return DEFAULT_TTL_MS;
+  const parsed = Number.parseInt(env, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_TTL_MS;
+}
+function cacheDir() {
+  const xdg = process.env.XDG_CACHE_HOME;
+  return xdg ? join(xdg, "forgemap") : join(homedir(), ".cache", "forgemap");
+}
+function cachePath(root) {
+  const hash = createHash("sha1").update(root).digest("hex").slice(0, 16);
+  return join(cacheDir(), `scan-${hash}.json`);
+}
+async function safeStat(path) {
+  try {
+    const s = await stat(path);
+    return Math.trunc(s.mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+async function safeListDirs(path) {
+  try {
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+async function computeFingerprint(config, configDir) {
+  const root = resolveRoot(config.root, configDir);
+  const perForge = await Promise.all(
+    Object.values(config.forges).map(async (forge) => {
+      const forgeRoot = join(root, forge.dir);
+      const [forgeMtime, owners] = await Promise.all([
+        safeStat(forgeRoot),
+        safeListDirs(forgeRoot)
+      ]);
+      const ownerEntries = await Promise.all(
+        owners.map(async (owner) => {
+          const ownerPath = join(forgeRoot, owner);
+          return [ownerPath, await safeStat(ownerPath)];
+        })
+      );
+      return [[forgeRoot, forgeMtime], ...ownerEntries];
+    })
+  );
+  const entries = [[root, await safeStat(root)]];
+  for (const group of perForge) entries.push(...group);
+  entries.sort((a, b) => a[0].localeCompare(b[0]));
+  return createHash("sha1").update(entries.map(([p, m]) => `${p}:${m}`).join("\n")).digest("hex");
+}
+async function readCacheFile(file) {
+  try {
+    const raw = await readFile(file, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeCacheFile(file, payload) {
+  await mkdir(cacheDir(), { recursive: true });
+  await writeFile(file, JSON.stringify(payload), "utf8");
+}
+async function scanReposCached(options) {
+  const { config, configDir, useCache = true, trustTtl = true } = options;
+  const root = resolveRoot(config.root, configDir);
+  const file = cachePath(root);
+  if (useCache) {
+    const cached = await readCacheFile(file);
+    if (cached) {
+      const age = Date.now() - cached.writtenAt;
+      if (trustTtl && age < ttl()) {
+        return cached.repos;
+      }
+      const fingerprint2 = await computeFingerprint(config, configDir);
+      if (cached.fingerprint === fingerprint2) {
+        await writeCacheFile(file, { ...cached, writtenAt: Date.now() });
+        return cached.repos;
+      }
+    }
+  }
+  const repos = await scanRepos({ config, configDir });
+  const fingerprint = await computeFingerprint(config, configDir);
+  await writeCacheFile(file, {
+    fingerprint,
+    writtenAt: Date.now(),
+    repos
+  });
+  return repos;
+}
+async function appendCachedRepo(options, repo) {
+  const { config, configDir } = options;
+  const root = resolveRoot(config.root, configDir);
+  const file = cachePath(root);
+  const cached = await readCacheFile(file);
+  if (!cached) {
+    return;
+  }
+  if (cached.repos.some((r) => r.localPath === repo.localPath)) {
+    return;
+  }
+  await writeCacheFile(file, {
+    fingerprint: await computeFingerprint(config, configDir),
+    writtenAt: Date.now(),
+    repos: [...cached.repos, repo]
+  });
+}
+async function removeCachedRepo(options, localPath) {
+  const { config, configDir } = options;
+  const root = resolveRoot(config.root, configDir);
+  const file = cachePath(root);
+  const cached = await readCacheFile(file);
+  if (!cached) return;
+  const next = cached.repos.filter((r) => r.localPath !== localPath);
+  if (next.length === cached.repos.length) return;
+  await writeCacheFile(file, {
+    fingerprint: await computeFingerprint(config, configDir),
+    writtenAt: Date.now(),
+    repos: next
+  });
+}
+async function gitIn(cwd, args) {
+  return execCapture("git", args, { cwd });
+}
+const NETWORK_TIMEOUT_MS = 3e4;
+async function gitNetwork(cwd, args) {
+  return execCapture("git", args, {
+    cwd,
+    timeoutMs: NETWORK_TIMEOUT_MS,
+    env: {
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_SSH_COMMAND: "ssh -oBatchMode=yes -oConnectTimeout=5"
+    }
+  });
+}
+async function getRepoStatus(localPath) {
+  const status = {
+    branch: "HEAD",
+    detached: false,
+    dirty: false,
+    ahead: 0,
+    behind: 0,
+    lastCommit: null
+  };
+  const branchResult = await gitIn(localPath, ["branch", "--show-current"]);
+  status.branch = branchResult.stdout.trim() || "HEAD";
+  status.detached = !status.branch || status.branch === "HEAD";
+  const porcelain = await gitIn(localPath, ["status", "--porcelain"]);
+  status.dirty = porcelain.stdout.trim().length > 0;
+  const aheadBehind = await gitIn(localPath, [
+    "rev-list",
+    "--left-right",
+    "--count",
+    "@{u}...HEAD"
+  ]);
+  if (aheadBehind.code === 0) {
+    const match = aheadBehind.stdout.trim().match(/^(\d+)\s+(\d+)$/);
+    if (match) {
+      status.behind = Number(match[1]);
+      status.ahead = Number(match[2]);
+    }
+  }
+  const lastCommit = await gitIn(localPath, ["log", "-1", "--format=%h|%cr"]);
+  if (lastCommit.code === 0) {
+    const [sha, relativeDate] = lastCommit.stdout.trim().split("|");
+    if (sha && relativeDate) {
+      status.lastCommit = { sha, relativeDate };
+    }
+  }
+  return status;
+}
+async function fetchRepo(localPath) {
+  return gitNetwork(localPath, ["fetch", "--all", "--prune"]);
+}
+async function pullRepo(localPath) {
+  return gitNetwork(localPath, ["pull", "--ff-only"]);
+}
+async function isClean(localPath) {
+  const result = await gitIn(localPath, ["status", "--porcelain"]);
+  return result.code === 0 && result.stdout.trim().length === 0;
+}
+async function isGitRepo(localPath) {
+  const result = await gitIn(localPath, ["rev-parse", "--is-inside-work-tree"]);
+  return result.code === 0 && result.stdout.trim() === "true";
+}
+async function getOriginUrl(localPath) {
+  const result = await gitIn(localPath, ["remote", "get-url", "origin"]);
+  if (result.code !== 0) return null;
+  const url = result.stdout.trim();
+  return url.length > 0 ? url : null;
+}
+async function getRemotes(localPath) {
+  const result = await gitIn(localPath, [
+    "config",
+    "--get-regexp",
+    "^remote\\..*\\.url$"
+  ]);
+  if (result.code !== 0) return [];
+  const remotes = [];
+  for (const line of result.stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^remote\.(.+)\.url\s+(.+)$/);
+    if (match) remotes.push({ name: match[1], url: match[2] });
+  }
+  return remotes;
+}
+async function setOriginUrl(localPath, url) {
+  return gitIn(localPath, ["remote", "set-url", "origin", url]);
+}
+async function getLastCommitUnix(localPath) {
+  const result = await gitIn(localPath, [
+    "log",
+    "--branches",
+    "-1",
+    "--format=%ct"
+  ]);
+  if (result.code !== 0) return null;
+  const ts = Number.parseInt(result.stdout.trim(), 10);
+  return Number.isFinite(ts) ? ts : null;
+}
+async function hasUnpushedCommits(localPath) {
+  const result = await gitIn(localPath, [
+    "log",
+    "--branches",
+    "--not",
+    "--remotes",
+    "--format=%H",
+    "-1"
+  ]);
+  if (result.code !== 0) return true;
+  return result.stdout.trim().length > 0;
+}
 const SHORT_RE = /^([\w.-]+)\/([\w.-]+)$/;
 const NAMED_RE = /^([\w.-]+):([\w.-]+)\/([\w.-]+)$/;
 const SSH_RE = /^git@([\w.-]+):([\w.-]+)\/([\w.-]+?)(?:\.git)?$/;
@@ -181,93 +712,409 @@ function parseSlug(input) {
   }
   throw new Error(`Unrecognized slug format: ${input}`);
 }
-function expandTilde(p) {
-  if (p === "~") return homedir();
-  if (p.startsWith("~/")) return resolve(homedir(), p.slice(2));
-  return p;
-}
-function resolveRoot(root, configDir) {
-  const expanded = expandTilde(root);
-  if (isAbsolute(expanded)) return expanded;
-  return resolve(configDir, expanded);
-}
-function findForgeByHost(forges, host) {
-  for (const [name, forge] of Object.entries(forges)) {
-    if (forge.host.toLowerCase() === host.toLowerCase()) {
-      return { name, forge };
-    }
+const DAY_SECONDS = 86400;
+const LOCAL_CONCURRENCY$1 = 16;
+const REMOTE_CONCURRENCY$1 = 10;
+async function evaluate(repo, cutoffUnix) {
+  if (!await isGitRepo(repo.localPath)) return null;
+  const origin = await getOriginUrl(repo.localPath);
+  if (!origin) return null;
+  const lastCommitUnix = await getLastCommitUnix(repo.localPath);
+  if (lastCommitUnix === null || lastCommitUnix > cutoffUnix) return null;
+  const status = await getRepoStatus(repo.localPath);
+  const dirty = status.dirty;
+  const unpushed = await hasUnpushedCommits(repo.localPath);
+  let owner = repo.owner;
+  let name = repo.repo;
+  try {
+    const parsed = parseSlug(origin);
+    owner = parsed.owner;
+    name = parsed.repo;
+  } catch {
   }
-  return void 0;
+  return { repo, origin, owner, name, lastCommitUnix, dirty, unpushed };
 }
-function resolveSlug(parsed, options) {
-  const { config, configDir } = options;
-  let forgeName;
-  let forge;
-  if (parsed.forgeName) {
-    const candidate = config.forges[parsed.forgeName];
-    if (!candidate) {
-      throw new Error(
-        `Forge "${parsed.forgeName}" is not defined in forgemap.config`
-      );
-    }
-    forgeName = parsed.forgeName;
-    forge = candidate;
-  } else if (parsed.host) {
-    const match = findForgeByHost(config.forges, parsed.host);
-    if (!match) {
-      throw new Error(
-        `No forge configured for host "${parsed.host}". Add it to forgemap.config.ts.`
-      );
-    }
-    forgeName = match.name;
-    forge = match.forge;
-  } else {
-    const candidate = config.forges[config.defaultForge];
-    if (!candidate) {
-      throw new Error(
-        `Default forge "${config.defaultForge}" is not defined in forgemap.config`
-      );
-    }
-    forgeName = config.defaultForge;
-    forge = candidate;
+async function classifyRemotes(candidates) {
+  const byType = /* @__PURE__ */ new Map();
+  for (const c of candidates) {
+    const list = byType.get(c.repo.forge.type);
+    if (list) list.push(c);
+    else byType.set(c.repo.forge.type, [c]);
   }
-  const root = resolveRoot(config.root, configDir);
-  const localPath = join(root, forge.dir, parsed.owner, parsed.repo);
-  return {
-    forgeName,
-    forge,
-    owner: parsed.owner,
-    repo: parsed.repo,
-    localPath
-  };
+  const results = /* @__PURE__ */ new Map();
+  await Promise.all(
+    Array.from(byType, async ([type, items]) => {
+      const inputs = items.map((c) => ({
+        forge: c.repo.forge,
+        owner: c.owner,
+        repo: c.name,
+        originUrl: c.origin
+      }));
+      let adapter;
+      try {
+        adapter = getForgeAdapter(type);
+      } catch (error) {
+        for (const c of items) {
+          results.set(c.repo.localPath, {
+            state: "unknown",
+            reason: error.message
+          });
+        }
+        return;
+      }
+      let res;
+      if (adapter.checkRemotes) {
+        try {
+          res = await adapter.checkRemotes(inputs);
+        } catch (error) {
+          res = inputs.map(() => ({
+            state: "unknown",
+            reason: error.message
+          }));
+        }
+      } else if (adapter.checkRemote) {
+        const check = adapter.checkRemote;
+        res = await mapLimit(inputs, REMOTE_CONCURRENCY$1, async (inp) => {
+          try {
+            return await check(inp);
+          } catch (error) {
+            return { state: "unknown", reason: error.message };
+          }
+        });
+      } else {
+        res = inputs.map(() => ({
+          state: "unknown",
+          reason: `${type} has no remote check`
+        }));
+      }
+      items.forEach((c, i) => results.set(c.repo.localPath, res[i]));
+    })
+  );
+  return results;
 }
-const cloneCommand = defineCommand({
+function ageDays(lastCommitUnix) {
+  return Math.floor(
+    Date.now() / 1e3 / DAY_SECONDS - lastCommitUnix / DAY_SECONDS
+  );
+}
+const cleanupCommand = defineCommand({
   meta: {
-    name: "clone",
-    description: "Clone a repo into the configured local layout"
+    name: "cleanup",
+    description: "List stale, clean, fully-pushed repos whose remote still exists, then delete them locally after confirmation"
   },
   args: {
-    slug: {
-      type: "positional",
-      description: "owner/repo, forge:owner/repo, or full URL",
-      required: true
+    days: {
+      type: "string",
+      description: "Minimum age in days since the last commit (default 365)",
+      default: "365"
     },
-    config: {
+    forge: {
       type: "string",
-      description: "Path to forgemap.config.ts (overrides walk-up discovery)"
-    }
-  },
-  async run({ args }) {
-    const loaded = await loadForgeMapConfig({ configFile: args.config });
-    const parsed = parseSlug(args.slug);
-    const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
-    const resolved = resolveSlug(parsed, {
-      config: loaded.config,
-      configDir
-    });
-    if (existsSync(resolved.localPath)) {
-      consola.info(`Already cloned at ${resolved.localPath}`);
-      return;
+      description: "Restrict to a single forge alias"
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Only list candidates; never prompt or delete",
+      default: false
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation (deletes immediately)",
+      default: false
+    },
+    "include-dirty": {
+      type: "boolean",
+      description: "Also delete repos with uncommitted changes (those changes are lost)",
+      default: false
+    },
+    "include-unpushed": {
+      type: "boolean",
+      description: "Also delete repos with unpushed commits (those commits are lost)",
+      default: false
+    },
+    "no-cache": {
+      type: "boolean",
+      description: "Skip the scanned-repos cache",
+      default: false
+    },
+    config: {
+      type: "string",
+      description: "Path to forgemap.config.ts (overrides walk-up discovery)"
+    }
+  },
+  async run({ args }) {
+    const days = Number.parseInt(args.days, 10);
+    if (!Number.isFinite(days) || days < 0) {
+      consola.error(`Invalid --days value "${args.days}".`);
+      process.exitCode = 1;
+      return;
+    }
+    const loaded = await loadForgeMapConfig({ configFile: args.config });
+    const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
+    let repos = await scanReposCached({
+      config: loaded.config,
+      configDir,
+      useCache: !args["no-cache"]
+    });
+    if (args.forge) repos = repos.filter((r) => r.forgeName === args.forge);
+    const cutoffUnix = Math.floor(Date.now() / 1e3) - days * DAY_SECONDS;
+    const stale = (await mapLimit(
+      repos,
+      LOCAL_CONCURRENCY$1,
+      (repo) => evaluate(repo, cutoffUnix)
+    )).filter((c) => c !== null);
+    const includeDirty = Boolean(args["include-dirty"]);
+    const includeUnpushed = Boolean(args["include-unpushed"]);
+    const localOk = (c) => (!c.dirty || includeDirty) && (!c.unpushed || includeUnpushed);
+    const remoteStates = await classifyRemotes(stale.filter(localOk));
+    const candidates = [];
+    const kept = [];
+    for (const c of stale) {
+      if (c.dirty && !includeDirty) {
+        kept.push({ repo: c, reason: "uncommitted changes" });
+      } else if (c.unpushed && !includeUnpushed) {
+        kept.push({ repo: c, reason: "unpushed commits" });
+      } else {
+        const state = remoteStates.get(c.repo.localPath)?.state;
+        if (state === "exists" || state === "moved") candidates.push(c);
+        else {
+          kept.push({
+            repo: c,
+            reason: state === "gone" ? "remote no longer exists" : "remote unreachable"
+          });
+        }
+      }
+    }
+    candidates.sort((a, b) => a.lastCommitUnix - b.lastCommitUnix);
+    kept.sort((a, b) => a.repo.lastCommitUnix - b.repo.lastCommitUnix);
+    if (candidates.length > 0) {
+      process.stdout.write(
+        `${colors.bold(`${candidates.length} repo(s) eligible for cleanup`)} ${colors.dim(`(idle ${days}+ days, remote exists)`)}
+
+`
+      );
+      for (const c of candidates) {
+        const flags = [
+          c.dirty ? colors.red("dirty") : "",
+          c.unpushed ? colors.red("unpushed") : ""
+        ].filter(Boolean).join(" ");
+        process.stdout.write(
+          `  ${colors.cyan(`${c.repo.forgeName}:${c.repo.slug}`)}  ${colors.dim(`${ageDays(c.lastCommitUnix)}d idle`)}${flags ? `  ${flags}` : ""}  ${colors.dim(c.repo.localPath)}
+`
+        );
+      }
+      process.stdout.write("\n");
+    }
+    if (kept.length > 0) {
+      process.stdout.write(
+        `${colors.dim(`${kept.length} idle repo(s) kept (not safe to delete):`)}
+`
+      );
+      for (const k of kept) {
+        process.stdout.write(
+          `  ${colors.dim(`${k.repo.repo.forgeName}:${k.repo.repo.slug}  ${ageDays(k.repo.lastCommitUnix)}d idle — ${k.reason}`)}
+`
+        );
+      }
+      process.stdout.write("\n");
+    }
+    const root = resolveRoot(loaded.config.root, configDir);
+    if (args["dry-run"]) {
+      const empties = await findEmptyDirs(root, loaded.config);
+      if (empties.length > 0) {
+        process.stdout.write(
+          `${colors.dim(`${empties.length} empty folder(s) would be removed:`)}
+`
+        );
+        for (const e of empties) {
+          process.stdout.write(`  ${colors.dim(e)}
+`);
+        }
+        process.stdout.write("\n");
+      }
+      consola.info(
+        candidates.length > 0 ? "Dry run — nothing deleted." : "Nothing to delete."
+      );
+      return;
+    }
+    if (candidates.length > 0) {
+      const losing = candidates.filter((c) => c.dirty || c.unpushed).length;
+      if (losing > 0) {
+        consola.warn(
+          `${losing} of these have uncommitted/unpushed work that will be permanently lost.`
+        );
+      }
+      let confirmed = args.yes;
+      if (!confirmed) {
+        const answer = await consola.prompt(
+          `Type "yes" to delete these ${candidates.length} repo(s) locally:`,
+          { type: "text", cancel: "null" }
+        );
+        confirmed = typeof answer === "string" && answer.trim() === "yes";
+      }
+      if (!confirmed) {
+        consola.info("Aborted — nothing deleted.");
+        return;
+      }
+      for (const c of candidates) {
+        await rm(c.repo.localPath, { recursive: true, force: true });
+        await removeCachedRepo(
+          { config: loaded.config, configDir },
+          c.repo.localPath
+        );
+        consola.success(`Deleted ${c.repo.localPath}`);
+      }
+      consola.success(`Removed ${candidates.length} repo(s).`);
+    }
+    const emptied = await pruneEmptyDirs(root, loaded.config);
+    if (emptied > 0) {
+      consola.success(`Removed ${emptied} empty folder(s).`);
+    } else if (candidates.length === 0) {
+      consola.info("Nothing to clean up.");
+    }
+  }
+});
+async function safeReaddir(path) {
+  try {
+    return await readdir(path);
+  } catch {
+    return null;
+  }
+}
+async function findEmptyDirs(root, config) {
+  const empties = [];
+  for (const forge of Object.values(config.forges)) {
+    const serverPath = join(root, forge.dir);
+    const owners = await safeReaddir(serverPath);
+    if (owners === null) continue;
+    let emptyCount = 0;
+    for (const owner of owners) {
+      const ownerPath = join(serverPath, owner);
+      const inner = await safeReaddir(ownerPath);
+      if (inner !== null && inner.length === 0) {
+        empties.push(ownerPath);
+        emptyCount++;
+      }
+    }
+    if (owners.length === 0 || emptyCount === owners.length) {
+      empties.push(serverPath);
+    }
+  }
+  return empties;
+}
+async function pruneEmptyDirs(root, config) {
+  const empties = await findEmptyDirs(root, config);
+  let removed = 0;
+  for (const dir of empties) {
+    try {
+      await rmdir(dir);
+      removed++;
+    } catch {
+    }
+  }
+  return removed;
+}
+function findForgeByHost(forges, host) {
+  for (const [name, forge] of Object.entries(forges)) {
+    if (forge.host.toLowerCase() === host.toLowerCase()) {
+      return { name, forge };
+    }
+  }
+  return void 0;
+}
+function resolveSlug(parsed, options) {
+  const { config, configDir } = options;
+  let forgeName;
+  let forge;
+  if (parsed.forgeName) {
+    const candidate = config.forges[parsed.forgeName];
+    if (!candidate) {
+      throw new Error(
+        `Forge "${parsed.forgeName}" is not defined in forgemap.config`
+      );
+    }
+    forgeName = parsed.forgeName;
+    forge = candidate;
+  } else if (parsed.host) {
+    const match = findForgeByHost(config.forges, parsed.host);
+    if (!match) {
+      throw new Error(
+        `No forge configured for host "${parsed.host}". Add it to forgemap.config.ts.`
+      );
+    }
+    forgeName = match.name;
+    forge = match.forge;
+  } else {
+    const candidate = config.forges[config.defaultForge];
+    if (!candidate) {
+      throw new Error(
+        `Default forge "${config.defaultForge}" is not defined in forgemap.config`
+      );
+    }
+    forgeName = config.defaultForge;
+    forge = candidate;
+  }
+  const root = resolveRoot(config.root, configDir);
+  const localPath = join(root, forge.dir, parsed.owner, parsed.repo);
+  return {
+    forgeName,
+    forge,
+    owner: parsed.owner,
+    repo: parsed.repo,
+    localPath
+  };
+}
+const cloneCommand = defineCommand({
+  meta: {
+    name: "clone",
+    description: "Clone a repo into the configured local layout"
+  },
+  args: {
+    slug: {
+      type: "positional",
+      description: "owner/repo, forge:owner/repo, or full URL",
+      required: true
+    },
+    ssh: {
+      type: "boolean",
+      description: "Force the SSH URL form (git-type forges only)",
+      default: false
+    },
+    https: {
+      type: "boolean",
+      description: "Force the HTTPS URL form (git-type forges only)",
+      default: false
+    },
+    config: {
+      type: "string",
+      description: "Path to forgemap.config.ts (overrides walk-up discovery)"
+    }
+  },
+  async run({ args }) {
+    if (args.ssh && args.https) {
+      consola.error("--ssh and --https are mutually exclusive.");
+      process.exitCode = 1;
+      return;
+    }
+    const loaded = await loadForgeMapConfig({ configFile: args.config });
+    const parsed = parseSlug(args.slug);
+    const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
+    const resolved = resolveSlug(parsed, {
+      config: loaded.config,
+      configDir
+    });
+    let protocol;
+    if (args.ssh) protocol = "ssh";
+    else if (args.https) protocol = "https";
+    if (protocol && resolved.forge.type !== "git") {
+      consola.warn(
+        `--${protocol} is ignored for type "${resolved.forge.type}" — the adapter selects the URL itself.`
+      );
+      protocol = void 0;
+    }
+    if (existsSync(resolved.localPath)) {
+      consola.info(`Already cloned at ${resolved.localPath}`);
+      return;
     }
     await mkdir(dirname(resolved.localPath), { recursive: true });
     const adapter = getForgeAdapter(resolved.forge.type);
@@ -275,14 +1122,217 @@ const cloneCommand = defineCommand({
       forge: resolved.forge,
       owner: resolved.owner,
       repo: resolved.repo,
-      dest: resolved.localPath
+      dest: resolved.localPath,
+      protocol
     });
+    await appendCachedRepo(
+      { config: loaded.config, configDir },
+      {
+        forgeName: resolved.forgeName,
+        forge: resolved.forge,
+        owner: resolved.owner,
+        repo: resolved.repo,
+        localPath: resolved.localPath,
+        slug: `${resolved.owner}/${resolved.repo}`
+      }
+    );
     consola.success(
       `Cloned ${resolved.owner}/${resolved.repo} → ${resolved.localPath}`
     );
   }
 });
-const TEMPLATE = `/**
+const SUPPORTED_SHELLS = ["zsh", "bash", "fish"];
+function detectShell() {
+  const env = process.env.SHELL ?? "";
+  if (env.endsWith("/fish")) return "fish";
+  if (env.endsWith("/bash")) return "bash";
+  return "zsh";
+}
+function rcFileFor(shell) {
+  const home = homedir();
+  if (shell === "fish") return join(home, ".config", "fish", "config.fish");
+  if (shell === "bash") return join(home, ".bashrc");
+  return join(home, ".zshrc");
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stripBlocks(content, labels) {
+  let out = content;
+  for (const label of labels) {
+    const l = escapeRegExp(label);
+    const re = new RegExp(
+      `\\n*# >>> forgemap ${l} >>>[\\s\\S]*?# <<< forgemap ${l} <<<\\n?`,
+      "g"
+    );
+    out = out.replace(re, "");
+  }
+  return out;
+}
+async function installRcBlock(shell, label, lines, legacyLabels = []) {
+  const rcFile = rcFileFor(shell);
+  let existing = "";
+  try {
+    existing = await readFile(rcFile, "utf8");
+  } catch {
+  }
+  const allLabels = [label, ...legacyLabels];
+  const hadAny = allLabels.some(
+    (l) => existing.includes(`# >>> forgemap ${l} >>>`)
+  );
+  const block = `# >>> forgemap ${label} >>>
+${lines.join("\n")}
+# <<< forgemap ${label} <<<
+`;
+  const cleaned = stripBlocks(existing, allLabels).replace(/\s*$/, "");
+  const next = cleaned.length > 0 ? `${cleaned}
+
+${block}` : block;
+  if (next === existing) {
+    return { status: "present", rcFile };
+  }
+  await mkdir(dirname(rcFile), { recursive: true });
+  await writeFile(rcFile, next, "utf8");
+  return { status: hadAny ? "updated" : "installed", rcFile };
+}
+const SUBCOMMANDS = [
+  "clone",
+  "import",
+  "cleanup",
+  "cd",
+  "path",
+  "open",
+  "search",
+  "pick",
+  "status",
+  "sync",
+  "validate",
+  "shell-init",
+  "completion",
+  "config"
+];
+const SLUG_COMMANDS = ["clone", "cd", "path", "open", "search", "pick"];
+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)'
+`;
+}
+const 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 loader = requested === "fish" ? "forgemap completion fish | source" : `eval "$(forgemap completion ${requested})"`;
+      const { status, rcFile } = await installRcBlock(requested, "completion", [
+        loader
+      ]);
+      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);
+  }
+});
+const HEADER = `/**
  * forgemap configuration.
  *
  * For type-safe authoring, install forgemap and switch to:
@@ -290,19 +1340,63 @@ const TEMPLATE = `/**
  *   export default defineForgeMapConfig({ ... });
  *
  * @type {import('forgemap').ForgeMapUserConfig}
- */
+ */`;
+function quoteKey(name) {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`;
+}
+function renderForge(forge) {
+  const lines = [
+    `      type: '${forge.type}',`,
+    `      host: '${forge.host}',`,
+    `      dir: '${forge.dir}'`
+  ];
+  if (forge.type === "git" && forge.protocol) {
+    lines.splice(1, 0, `      protocol: '${forge.protocol}',`);
+  }
+  return `{
+${lines.join("\n")}
+    }`;
+}
+function renderConfigModule(config) {
+  const forgeEntries = Object.entries(config.forges).map(([name, forge]) => `    ${quoteKey(name)}: ${renderForge(forge)}`).join(",\n");
+  return `${HEADER}
 export default {
-  root: '.',
-  defaultForge: 'github',
+  root: '${config.root}',
+  defaultForge: '${config.defaultForge}',
+  forges: {
+${forgeEntries}
+  }
+};
+`;
+}
+async function writeConfigFile(config, options) {
+  const outDir = resolve(process.cwd(), options.outDir);
+  const target = join(outDir, "forgemap.config.ts");
+  await mkdir(dirname(target), { recursive: true });
+  try {
+    await writeFile(target, renderConfigModule(config), {
+      encoding: "utf8",
+      flag: options.force ? "w" : "wx"
+    });
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      return null;
+    }
+    throw error;
+  }
+  return { path: target };
+}
+const DEFAULT_CONFIG = {
+  root: ".",
+  defaultForge: "github",
   forges: {
     github: {
-      type: 'github',
-      host: 'github.com',
-      dir: 'comGithub'
+      type: "github",
+      host: "github.com",
+      dir: "comGithub"
     }
   }
 };
-`;
 const configInitCommand = defineCommand({
   meta: {
     name: "init",
@@ -321,23 +1415,20 @@ const configInitCommand = defineCommand({
     }
   },
   async run({ args }) {
-    const outDir = resolve(process.cwd(), args.out);
-    const target = join(outDir, "forgemap.config.ts");
-    await mkdir(dirname(target), { recursive: true });
-    try {
-      await writeFile(target, TEMPLATE, {
-        encoding: "utf8",
-        flag: args.force ? "w" : "wx"
-      });
-    } catch (error) {
-      if (error.code === "EEXIST") {
-        consola.error(`${target} already exists. Use --force to overwrite.`);
-        process.exitCode = 1;
-        return;
-      }
-      throw error;
+    const result = await writeConfigFile(DEFAULT_CONFIG, {
+      outDir: args.out,
+      force: args.force
+    });
+    if (!result) {
+      const target = join(
+        resolve(process.cwd(), args.out),
+        "forgemap.config.ts"
+      );
+      consola.error(`${target} already exists. Use --force to overwrite.`);
+      process.exitCode = 1;
+      return;
     }
-    consola.success(`Wrote ${target}`);
+    consola.success(`Wrote ${result.path}`);
   }
 });
 const configShowCommand = defineCommand({
@@ -350,30 +1441,582 @@ const configShowCommand = defineCommand({
       type: "string",
       description: "Path to forgemap.config.ts (overrides walk-up discovery)"
     }
-  },
-  async run({ args }) {
-    const loaded = await loadForgeMapConfig({ configFile: args.config });
-    process.stdout.write(
-      JSON.stringify(
-        {
-          configFile: loaded.configFile ?? null,
-          cwd: loaded.cwd,
-          config: loaded.config
-        },
-        null,
-        2
-      ) + "\n"
-    );
-  }
-});
-const configCommand = defineCommand({
-  meta: {
-    name: "config",
-    description: "Manage the forgemap config file"
-  },
-  subCommands: {
-    init: configInitCommand,
-    show: configShowCommand
+  },
+  async run({ args }) {
+    const loaded = await loadForgeMapConfig({ configFile: args.config });
+    process.stdout.write(
+      JSON.stringify(
+        {
+          configFile: loaded.configFile ?? null,
+          cwd: loaded.cwd,
+          config: loaded.config
+        },
+        null,
+        2
+      ) + "\n"
+    );
+  }
+});
+const configCommand = defineCommand({
+  meta: {
+    name: "config",
+    description: "Manage the forgemap config file"
+  },
+  subCommands: {
+    init: configInitCommand,
+    show: configShowCommand
+  }
+});
+async function listDirs(path) {
+  try {
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+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";
+}
+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] ?? "";
+    const type = host ? forgeTypeForHost(host) : "git";
+    forges[serverDir] = { type, host, dir: serverDir };
+  }
+  const names = Object.keys(forges);
+  const defaultForge = names.slice().sort((a, b) => {
+    const aGh = forges[a].type === "github" ? 1 : 0;
+    const bGh = forges[b].type === "github" ? 1 : 0;
+    if (aGh !== bGh) return bGh - aGh;
+    return (counts.get(b) ?? 0) - (counts.get(a) ?? 0);
+  })[0] ?? "";
+  return { root: path, defaultForge, forges };
+}
+async function analyzeLocal(repo, options) {
+  const report = {
+    repo,
+    originUrl: null,
+    originHost: null,
+    remotes: [],
+    findings: []
+  };
+  if (!await isGitRepo(repo.localPath)) {
+    report.findings.push({
+      kind: "not-a-git-repo",
+      severity: "warn",
+      message: "not a git repository"
+    });
+    return { report, parsed: null };
+  }
+  report.remotes = await getRemotes(repo.localPath);
+  report.originUrl = await getOriginUrl(repo.localPath);
+  if (!report.originUrl) {
+    const names = report.remotes.map((r) => r.name).filter((n) => n !== "origin");
+    report.findings.push({
+      kind: "no-origin",
+      severity: "warn",
+      message: names.length > 0 ? `no origin remote (other remotes: ${names.join(", ")})` : "no origin remote"
+    });
+    return { report, parsed: null };
+  }
+  if (report.remotes.length > 1) {
+    report.findings.push({
+      kind: "multiple-remotes",
+      severity: "warn",
+      message: `${report.remotes.length} remotes configured; comparing origin`
+    });
+  }
+  let parsed = null;
+  try {
+    parsed = parseSlug(report.originUrl);
+    report.originHost = parsed.host ?? null;
+  } catch {
+    report.findings.push({
+      kind: "origin-mismatch",
+      severity: "warn",
+      message: `could not parse origin URL: ${report.originUrl}`
+    });
+  }
+  if (parsed && (parsed.owner !== repo.owner || parsed.repo !== repo.repo)) {
+    const to = join(options.path, repo.serverDir, parsed.owner, parsed.repo);
+    report.findings.push({
+      kind: "origin-mismatch",
+      severity: "warn",
+      message: `folder ${repo.owner}/${repo.repo} != origin ${parsed.owner}/${parsed.repo}`,
+      fix: { action: "move-folder", from: repo.localPath, to }
+    });
+  }
+  return { report, parsed };
+}
+function pushRemoteFinding(report, parsed, result, path) {
+  const { repo } = report;
+  switch (result.state) {
+    case "exists":
+      break;
+    case "moved": {
+      const to = join(
+        path,
+        repo.serverDir,
+        result.canonical.owner,
+        result.canonical.repo
+      );
+      const fix = result.canonicalUrl ? {
+        action: "set-origin-url",
+        localPath: repo.localPath,
+        url: result.canonicalUrl
+      } : to !== repo.localPath ? { action: "move-folder", from: repo.localPath, to } : void 0;
+      report.findings.push({
+        kind: "remote-moved",
+        severity: "warn",
+        message: `remote moved to ${result.canonical.owner}/${result.canonical.repo}`,
+        fix
+      });
+      break;
+    }
+    case "gone":
+      report.findings.push({
+        kind: "remote-gone",
+        severity: "warn",
+        message: `remote ${parsed.owner}/${parsed.repo} no longer exists`
+      });
+      break;
+    case "unknown":
+      report.findings.push({
+        kind: "remote-check-unknown",
+        severity: "warn",
+        message: `remote check inconclusive: ${result.reason}`
+      });
+      break;
+  }
+}
+async function checkForgeGroup(forge, items, options, bump) {
+  const inputs = items.map((it) => ({
+    forge,
+    owner: it.parsed.owner,
+    repo: it.parsed.repo,
+    originUrl: it.report.originUrl ?? void 0
+  }));
+  let adapter;
+  try {
+    adapter = getForgeAdapter(forge.type);
+  } catch (error) {
+    for (const it of items) {
+      it.report.findings.push({
+        kind: "remote-check-unknown",
+        severity: "warn",
+        message: `remote check inconclusive: ${error.message}`
+      });
+      bump();
+    }
+    return;
+  }
+  if (adapter.checkRemotes) {
+    let results;
+    try {
+      results = await adapter.checkRemotes(inputs);
+    } catch (error) {
+      results = inputs.map(() => ({
+        state: "unknown",
+        reason: error.message
+      }));
+    }
+    items.forEach((it, i) => {
+      pushRemoteFinding(it.report, it.parsed, results[i], options.path);
+      bump();
+    });
+    return;
+  }
+  const check = adapter.checkRemote;
+  await mapLimit(items, REMOTE_CONCURRENCY, async (it, i) => {
+    let result;
+    try {
+      result = check ? await check(inputs[i]) : { state: "unknown", reason: `${forge.type} has no remote check` };
+    } catch (error) {
+      result = { state: "unknown", reason: error.message };
+    }
+    pushRemoteFinding(it.report, it.parsed, result, options.path);
+    bump();
+  });
+}
+const LOCAL_CONCURRENCY = 16;
+const REMOTE_CONCURRENCY = 10;
+async function analyzeImport(options) {
+  const discovered = await discoverForgemapLayout(options.path);
+  const locals = await mapLimit(
+    discovered,
+    LOCAL_CONCURRENCY,
+    (repo) => analyzeLocal(repo, options)
+  );
+  const reports = locals.map((l) => l.report);
+  const derived = deriveConfig(reports, options.path);
+  for (const { report, parsed } of locals) {
+    const forge = derived.forges[report.repo.serverDir];
+    if (parsed?.host && forge?.host && parsed.host !== forge.host) {
+      report.findings.push({
+        kind: "host-unmatched",
+        severity: "warn",
+        message: `origin host ${parsed.host} differs from forge host ${forge.host}`
+      });
+    }
+  }
+  const checkable = locals.flatMap(
+    (l) => l.report.originUrl && l.parsed ? [{ report: l.report, parsed: l.parsed }] : []
+  );
+  if (!options.remoteCheck) {
+    for (const { report } of checkable) {
+      report.findings.push({
+        kind: "remote-check-skipped",
+        severity: "ok",
+        message: "remote check skipped (--no-remote-check)"
+      });
+    }
+    return { root: options.path, derived, reports };
+  }
+  const total = checkable.length;
+  let done = 0;
+  const bump = () => {
+    done++;
+    options.onProgress?.(done, total);
+  };
+  options.onProgress?.(0, total);
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of checkable) {
+    const key = item.report.repo.serverDir;
+    const list = groups.get(key);
+    if (list) list.push(item);
+    else groups.set(key, [item]);
+  }
+  await Promise.all(
+    Array.from(groups, ([serverDir, items]) => {
+      const forge = derived.forges[serverDir];
+      if (!forge) {
+        for (const it of items) {
+          it.report.findings.push({
+            kind: "remote-check-unknown",
+            severity: "warn",
+            message: "no forge derived for this server dir"
+          });
+          bump();
+        }
+        return Promise.resolve();
+      }
+      return checkForgeGroup(forge, items, options, bump);
+    })
+  );
+  return { root: options.path, derived, reports };
+}
+const ALLOWED_TYPES = ["forgemap"];
+const ALLOWED_FORMATS$1 = ["pretty", "json"];
+function isImportType(value) {
+  return ALLOWED_TYPES.includes(value);
+}
+function severitySymbol$1(severity) {
+  if (severity === "fail") return colors.red("✗");
+  if (severity === "warn") return colors.yellow("!");
+  return colors.green("✓");
+}
+function worstSeverity(findings) {
+  if (findings.some((f) => f.severity === "fail")) return "fail";
+  if (findings.some((f) => f.severity === "warn")) return "warn";
+  return "ok";
+}
+function hasIssues(report) {
+  return report.findings.some((f) => f.severity !== "ok");
+}
+function repoLine(report) {
+  const symbol = severitySymbol$1(worstSeverity(report.findings));
+  const name = colors.cyan(report.repo.repo);
+  const issues = report.findings.filter((f) => f.severity !== "ok");
+  if (issues.length === 0) return `${symbol} ${name}`;
+  const summary = issues.map((f) => f.message).join("; ");
+  return `${symbol} ${name}  ${colors.dim(summary)}`;
+}
+function renderReports(reports) {
+  const byServer = /* @__PURE__ */ new Map();
+  for (const report of reports) {
+    let owners = byServer.get(report.repo.serverDir);
+    if (!owners) {
+      owners = /* @__PURE__ */ new Map();
+      byServer.set(report.repo.serverDir, owners);
+    }
+    const list = owners.get(report.repo.owner);
+    if (list) list.push(report);
+    else owners.set(report.repo.owner, [report]);
+  }
+  return formatTree(
+    Array.from(byServer, ([serverDir, owners]) => ({
+      text: colors.bold(serverDir),
+      children: Array.from(owners, ([owner, items]) => ({
+        text: owner,
+        children: items.map((report) => ({ text: repoLine(report) }))
+      }))
+    }))
+  );
+}
+function renderDerived(config) {
+  return formatTree([
+    {
+      text: colors.bold("Derived config"),
+      children: Object.entries(config.forges).map(([name, forge]) => ({
+        text: `${colors.cyan(name)}  ${colors.dim(
+          `${forge.type} @ ${forge.host || "(unknown host)"} → ${forge.dir}`
+        )}`
+      }))
+    }
+  ]);
+}
+async function applyFixes(reports) {
+  const applied = [];
+  const fixes = reports.flatMap(
+    (r) => r.findings.flatMap((f) => f.fix ? [f.fix] : [])
+  );
+  for (const fix of fixes) {
+    if (fix.action !== "set-origin-url") continue;
+    const result = await setOriginUrl(fix.localPath, fix.url);
+    if (result.code === 0) {
+      applied.push(fix);
+      consola.success(`origin → ${fix.url}`);
+    } else {
+      consola.warn(
+        `failed to set origin for ${fix.localPath}: ${result.stderr.trim()}`
+      );
+    }
+  }
+  for (const fix of fixes) {
+    if (fix.action !== "move-folder") continue;
+    if (existsSync(fix.to)) {
+      consola.warn(`skip move: target exists ${fix.to}`);
+      continue;
+    }
+    await mkdir(dirname(fix.to), { recursive: true });
+    await rename(fix.from, fix.to);
+    applied.push(fix);
+    consola.success(`moved ${fix.from} → ${fix.to}`);
+  }
+  return applied;
+}
+function augmentConfig(existing, derived) {
+  const forges = { ...existing.forges };
+  const conflicts = [];
+  for (const [name, forge] of Object.entries(derived.forges)) {
+    const current = existing.forges[name];
+    if (!current) {
+      forges[name] = forge;
+    } else if (current.host !== forge.host) {
+      conflicts.push(name);
+    }
+  }
+  return { merged: { ...existing, forges }, conflicts };
+}
+const importCommand = defineCommand({
+  meta: {
+    name: "import",
+    description: "Adopt an existing repo tree: reconcile folders against git remotes and derive a config"
+  },
+  args: {
+    path: {
+      type: "positional",
+      description: "Directory laid out as <server>/<owner>/<repo>",
+      required: true
+    },
+    type: {
+      type: "string",
+      description: 'Layout type (currently only "forgemap")',
+      default: "forgemap"
+    },
+    format: {
+      type: "string",
+      description: "Output format: pretty (default) or json",
+      default: "pretty"
+    },
+    "remote-check": {
+      type: "boolean",
+      description: "Check each remote for existence/moves (default true)",
+      default: true
+    },
+    fix: {
+      type: "boolean",
+      description: "Apply corrections (move folders, repoint origin URLs)",
+      default: false
+    },
+    "write-config": {
+      type: "boolean",
+      description: "Write/augment forgemap.config.ts from the derived structure",
+      default: true
+    },
+    out: {
+      type: "string",
+      description: "Directory to write the derived config into (defaults to <path>)"
+    },
+    force: {
+      type: "boolean",
+      description: "Overwrite an existing config instead of augmenting it",
+      default: false
+    }
+  },
+  async run({ args }) {
+    if (!isImportType(args.type)) {
+      consola.error(
+        `Invalid --type value "${args.type}". Allowed: ${ALLOWED_TYPES.join(", ")}.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (!ALLOWED_FORMATS$1.includes(args.format)) {
+      consola.error(
+        `Invalid --format value "${args.format}". Allowed: ${ALLOWED_FORMATS$1.join(", ")}.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const path = resolve(process.cwd(), args.path);
+    try {
+      const s = await stat(path);
+      if (!s.isDirectory()) {
+        consola.error(`${path} is not a directory.`);
+        process.exitCode = 1;
+        return;
+      }
+    } catch {
+      consola.error(`${path} does not exist.`);
+      process.exitCode = 1;
+      return;
+    }
+    const showProgress = args["remote-check"] && Boolean(process.stderr.isTTY);
+    let clearLen = 0;
+    const onProgress = showProgress ? (done, total) => {
+      const msg = `⏳ Checking remotes ${done}/${total}`;
+      process.stderr.write(`\r${msg} `);
+      clearLen = msg.length + 1;
+    } : void 0;
+    const result = await analyzeImport({
+      path,
+      type: args.type,
+      remoteCheck: args["remote-check"],
+      onProgress
+    });
+    if (clearLen > 0) {
+      process.stderr.write(`\r${" ".repeat(clearLen)}\r`);
+    }
+    const applied = args.fix ? await applyFixes(result.reports) : [];
+    const withFindings = result.reports.filter(hasIssues).length;
+    const fixable = result.reports.reduce(
+      (n, r) => n + r.findings.filter((f) => f.fix).length,
+      0
+    );
+    if (args.format === "json") {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            path,
+            type: args.type,
+            derived: result.derived,
+            repos: result.reports.map((r) => ({
+              serverDir: r.repo.serverDir,
+              owner: r.repo.owner,
+              repo: r.repo.repo,
+              localPath: r.repo.localPath,
+              originUrl: r.originUrl,
+              remotes: r.remotes,
+              findings: r.findings
+            })),
+            ...args.fix ? { applied } : {},
+            summary: { repos: result.reports.length, withFindings, fixable }
+          },
+          null,
+          2
+        )}
+`
+      );
+    } else {
+      process.stdout.write(
+        `${colors.dim(`Scanned ${path} (${args.type})`)}
+
+`
+      );
+      if (result.reports.length === 0) {
+        consola.info("No repos found.");
+      } else {
+        process.stdout.write(`${renderReports(result.reports)}
+
+`);
+      }
+      process.stdout.write(`${renderDerived(result.derived)}
+
+`);
+      process.stdout.write(
+        `${colors.bold(`${result.reports.length} repos`)}, ${withFindings} with findings, ${fixable} fixable${args.fix ? `, ${applied.length} fixed` : ""}
+`
+      );
+    }
+    if (!args["write-config"]) return;
+    if (result.reports.length === 0 && !args.force) return;
+    const outDir = args.out ? resolve(process.cwd(), args.out) : path;
+    const writableRoot = outDir === path ? "." : path;
+    const target = join(outDir, "forgemap.config.ts");
+    if (existsSync(target) && !args.force) {
+      const loaded = await loadForgeMapConfig({ configFile: target });
+      const { merged, conflicts } = augmentConfig(
+        loaded.config,
+        result.derived
+      );
+      for (const name of conflicts) {
+        consola.warn(
+          `forge "${name}" already exists with a different host — left untouched`
+        );
+      }
+      await writeConfigFile(merged, { outDir, force: true });
+      consola.success(`Augmented ${target}`);
+    } else {
+      const written = await writeConfigFile(
+        { ...result.derived, root: writableRoot },
+        { outDir, force: args.force }
+      );
+      if (written) consola.success(`Wrote ${written.path}`);
+    }
+    await scanReposCached({
+      config: result.derived,
+      configDir: path,
+      useCache: false
+    });
   }
 });
 function platformOpen(localPath) {
@@ -459,39 +2102,6 @@ const pathCommand = defineCommand({
 `);
   }
 });
-async function listDirs(path) {
-  try {
-    const entries = await readdir(path, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
-  } catch (error) {
-    if (error.code === "ENOENT") return [];
-    throw error;
-  }
-}
-async function scanRepos(options) {
-  const { config, configDir } = options;
-  const root = resolveRoot(config.root, configDir);
-  const repos = [];
-  for (const [forgeName, forge] of Object.entries(config.forges)) {
-    const forgeRoot = join(root, forge.dir);
-    const owners = await listDirs(forgeRoot);
-    for (const owner of owners) {
-      const ownerPath = join(forgeRoot, owner);
-      const repoNames = await listDirs(ownerPath);
-      for (const repo of repoNames) {
-        repos.push({
-          forgeName,
-          forge,
-          owner,
-          repo,
-          localPath: join(ownerPath, repo),
-          slug: `${owner}/${repo}`
-        });
-      }
-    }
-  }
-  return repos;
-}
 const pickCommand = defineCommand({
   meta: {
     name: "pick",
@@ -542,32 +2152,66 @@ const pickCommand = defineCommand({
       process.exitCode = 1;
       return;
     }
-    const 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
-      }))
-    });
+    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");
+    }
     if (typeof choice === "string" && choice) {
-      process.stdout.write(`${choice}
+      realWrite.call(out, `${choice}
 `);
     }
   }
 });
-function renderTree(repos) {
-  const groups = /* @__PURE__ */ new Map();
+function renderTree$1(repos) {
+  const byForge = /* @__PURE__ */ new Map();
   for (const r of repos) {
-    const list = groups.get(r.forgeName);
+    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 groups.set(r.forgeName, [r]);
+    else owners.set(r.owner, [r]);
   }
   return formatTree(
-    Array.from(groups, ([forge, items]) => ({
+    Array.from(byForge, ([forge, owners]) => ({
       text: colors.bold(forge),
-      children: items.map((r) => ({
-        text: `${colors.cyan(r.slug)}  ${colors.dim(r.localPath)}`
+      children: Array.from(owners, ([owner, items]) => ({
+        text: owner,
+        children: items.map((r) => ({
+          text: `${colors.cyan(r.repo)}  ${colors.dim(r.localPath)}`
+        }))
       }))
     }))
   );
@@ -625,7 +2269,7 @@ const searchCommand = defineCommand({
       return;
     }
     if (format === "pretty") {
-      process.stdout.write(`${renderTree(items)}
+      process.stdout.write(`${renderTree$1(items)}
 `);
       return;
     }
@@ -637,12 +2281,29 @@ const searchCommand = defineCommand({
     }
   }
 });
-const SUPPORTED = ["zsh", "bash", "fish"];
-function detectShell() {
-  const env = process.env.SHELL ?? "";
-  if (env.endsWith("/fish")) return "fish";
-  if (env.endsWith("/bash")) return "bash";
-  return "zsh";
+async function install(shell, name) {
+  const nameArg = name !== "forgemap" ? ` --name ${name}` : "";
+  const loaders = shell === "fish" ? [
+    `forgemap shell-init fish${nameArg} | source`,
+    "forgemap completion fish | source"
+  ] : [
+    `eval "$(forgemap shell-init ${shell}${nameArg})"`,
+    `eval "$(forgemap completion ${shell})"`
+  ];
+  const { status, rcFile } = await installRcBlock(shell, "shell", loaders, [
+    "shell-init"
+  ]);
+  if (status === "present") {
+    consola.info(`forgemap shell integration already present in ${rcFile}.`);
+    return;
+  }
+  const verb = status === "updated" ? "Updated" : "Added";
+  consola.success(
+    `${verb} forgemap shell integration (cd + completion) in ${rcFile}.`
+  );
+  consola.info(
+    `Run \`source ${rcFile}\` or restart your shell to activate it.`
+  );
 }
 function renderPosix(name) {
   return `# forgemap shell integration — drop into your ~/.zshrc / ~/.bashrc:
@@ -710,34 +2371,445 @@ end
 const shellInitCommand = defineCommand({
   meta: {
     name: "shell-init",
-    description: 'Print a shell wrapper that adds `forgemap cd <slug>` as a real cd. Source it via `eval "$(forgemap shell-init)"`.'
+    description: 'Print (or --install) a shell wrapper that adds `forgemap cd <slug>` as a real cd. Source it via `eval "$(forgemap shell-init)"`.'
   },
   args: {
     shell: {
       type: "positional",
-      description: `Shell flavor (${SUPPORTED.join(", ")}). Auto-detected from $SHELL if omitted.`,
+      description: `Shell flavor (${SUPPORTED_SHELLS.join(", ")}). Auto-detected from $SHELL if omitted.`,
       required: false
     },
     name: {
       type: "string",
       description: "Name of the generated wrapper function (default: forgemap)",
       default: "forgemap"
+    },
+    install: {
+      type: "boolean",
+      description: "Append the loader to your shell's rc file (idempotent) instead of printing",
+      default: false
     }
   },
   async run({ args }) {
     const requested = args.shell ?? detectShell();
-    if (!SUPPORTED.includes(requested)) {
+    if (!SUPPORTED_SHELLS.includes(requested)) {
       consola.error(
-        `Unsupported shell "${requested}". Supported: ${SUPPORTED.join(", ")}.`
+        `Unsupported shell "${requested}". Supported: ${SUPPORTED_SHELLS.join(", ")}.`
       );
       process.exitCode = 1;
       return;
     }
     const name = args.name || "forgemap";
+    if (args.install) {
+      await install(requested, name);
+      return;
+    }
     const out = requested === "fish" ? renderFish(name) : renderPosix(name);
     process.stdout.write(out);
   }
 });
+function statusLine(row) {
+  if (row.error || !row.status) {
+    return `${colors.cyan(row.repo.repo)}  ${colors.red(`error: ${row.error ?? "unknown"}`)}`;
+  }
+  const s = row.status;
+  const parts = [colors.cyan(row.repo.repo)];
+  const aheadBehind = [];
+  if (s.ahead > 0) aheadBehind.push(colors.green(`↑${s.ahead}`));
+  if (s.behind > 0) aheadBehind.push(colors.yellow(`↓${s.behind}`));
+  if (aheadBehind.length > 0) parts.push(aheadBehind.join(" "));
+  parts.push(s.dirty ? colors.red("●") : colors.green("✓"));
+  parts.push(colors.gray(s.branch));
+  if (s.lastCommit) {
+    parts.push(colors.dim(`${s.lastCommit.sha} ${s.lastCommit.relativeDate}`));
+  }
+  return parts.join("  ");
+}
+function renderTree(rows) {
+  const byForge = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    let owners = byForge.get(row.repo.forgeName);
+    if (!owners) {
+      owners = /* @__PURE__ */ new Map();
+      byForge.set(row.repo.forgeName, owners);
+    }
+    const list = owners.get(row.repo.owner);
+    if (list) list.push(row);
+    else owners.set(row.repo.owner, [row]);
+  }
+  return formatTree(
+    Array.from(byForge, ([forge, owners]) => ({
+      text: colors.bold(forge),
+      children: Array.from(owners, ([owner, items]) => ({
+        text: owner,
+        children: items.map((row) => ({ text: statusLine(row) }))
+      }))
+    }))
+  );
+}
+const ALLOWED_FORMATS = ["pretty", "json"];
+const statusCommand = defineCommand({
+  meta: {
+    name: "status",
+    description: "Show branch, dirty, ahead/behind, and last commit per repo"
+  },
+  args: {
+    format: {
+      type: "string",
+      description: "Output format: pretty (default) or json",
+      default: "pretty"
+    },
+    forge: {
+      type: "string",
+      description: "Restrict to a single forge alias"
+    },
+    query: {
+      type: "string",
+      description: "Fuzzy filter against <owner>/<repo>"
+    },
+    "no-cache": {
+      type: "boolean",
+      description: "Skip the scanned-repos cache",
+      default: false
+    },
+    config: {
+      type: "string",
+      description: "Path to forgemap.config.ts (overrides walk-up discovery)"
+    }
+  },
+  async run({ args }) {
+    if (!ALLOWED_FORMATS.includes(args.format)) {
+      consola.error(
+        `Invalid --format value "${args.format}". Allowed: ${ALLOWED_FORMATS.join(", ")}.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const loaded = await loadForgeMapConfig({ configFile: args.config });
+    const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
+    let repos = await scanReposCached({
+      config: loaded.config,
+      configDir,
+      useCache: !args["no-cache"]
+    });
+    if (args.forge) {
+      repos = repos.filter((r) => r.forgeName === args.forge);
+    }
+    if (args.query) {
+      const fuse = new Fuse(repos, {
+        keys: ["slug", "owner", "repo"],
+        threshold: 0.3,
+        ignoreLocation: true
+      });
+      repos = fuse.search(args.query).map((r) => r.item);
+    }
+    const rows = await Promise.all(
+      repos.map(async (repo) => {
+        try {
+          return { repo, status: await getRepoStatus(repo.localPath) };
+        } catch (error) {
+          return { repo, status: null, error: error.message };
+        }
+      })
+    );
+    if (args.format === "json") {
+      process.stdout.write(
+        `${JSON.stringify(
+          rows.map((r) => ({
+            forge: r.repo.forgeName,
+            owner: r.repo.owner,
+            repo: r.repo.repo,
+            localPath: r.repo.localPath,
+            status: r.status,
+            error: r.error ?? null
+          })),
+          null,
+          2
+        )}
+`
+      );
+      return;
+    }
+    if (rows.length === 0) {
+      consola.info("No repos to report on.");
+      return;
+    }
+    process.stdout.write(`${renderTree(rows)}
+`);
+  }
+});
+async function runWithConcurrency(items, limit, task) {
+  const queue = [...items];
+  const workers = Array.from(
+    { length: Math.min(limit, queue.length) },
+    async () => {
+      while (queue.length > 0) {
+        const next = queue.shift();
+        if (!next) return;
+        await task(next);
+      }
+    }
+  );
+  await Promise.all(workers);
+}
+const syncCommand = defineCommand({
+  meta: {
+    name: "sync",
+    description: "Run git fetch (or --pull) across every cloned repo, in parallel"
+  },
+  args: {
+    pull: {
+      type: "boolean",
+      description: "Pull --ff-only instead of fetch. Dirty working trees are skipped.",
+      default: false
+    },
+    concurrency: {
+      type: "string",
+      description: "Number of parallel workers (default: 4)"
+    },
+    sequential: {
+      type: "boolean",
+      description: "Run one repo at a time (overrides --concurrency)",
+      default: false
+    },
+    forge: {
+      type: "string",
+      description: "Restrict to a single forge alias"
+    },
+    query: {
+      type: "string",
+      description: "Fuzzy filter against <owner>/<repo>"
+    },
+    "no-cache": {
+      type: "boolean",
+      description: "Skip the scanned-repos cache",
+      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;
+    let repos = await scanReposCached({
+      config: loaded.config,
+      configDir,
+      useCache: !args["no-cache"]
+    });
+    if (args.forge) {
+      repos = repos.filter((r) => r.forgeName === args.forge);
+    }
+    if (args.query) {
+      const fuse = new Fuse(repos, {
+        keys: ["slug", "owner", "repo"],
+        threshold: 0.3,
+        ignoreLocation: true
+      });
+      repos = fuse.search(args.query).map((r) => r.item);
+    }
+    if (repos.length === 0) {
+      consola.info("Nothing to sync.");
+      return;
+    }
+    const concurrency = args.sequential ? 1 : args.concurrency ? Math.max(1, Number.parseInt(args.concurrency, 10)) : 4;
+    consola.info(
+      `Syncing ${repos.length} repo(s) — ${args.pull ? "pull" : "fetch"}, concurrency ${concurrency}`
+    );
+    const outcomes = [];
+    await runWithConcurrency(repos, concurrency, async (repo) => {
+      try {
+        if (args.pull && !await isClean(repo.localPath)) {
+          outcomes.push({
+            repo,
+            status: "skipped",
+            message: "dirty working tree"
+          });
+          consola.warn(`${colors.dim(repo.slug)} — skipped (dirty)`);
+          return;
+        }
+        const result = args.pull ? await pullRepo(repo.localPath) : await fetchRepo(repo.localPath);
+        if (result.code === 0) {
+          outcomes.push({ repo, status: "synced" });
+          consola.success(colors.dim(repo.slug));
+        } else {
+          const message = result.timedOut ? "timed out (remote unreachable)" : (result.stderr || result.stdout).trim().split("\n")[0] || `git exited with code ${result.code}`;
+          outcomes.push({
+            repo,
+            status: "failed",
+            message
+          });
+          consola.fail(
+            `${colors.dim(repo.slug)} — ${outcomes.at(-1)?.message}`
+          );
+        }
+      } catch (error) {
+        outcomes.push({
+          repo,
+          status: "failed",
+          message: error.message
+        });
+        consola.fail(`${colors.dim(repo.slug)} — ${error.message}`);
+      }
+    });
+    const synced = outcomes.filter((o) => o.status === "synced").length;
+    const skipped = outcomes.filter((o) => o.status === "skipped").length;
+    const failed = outcomes.filter((o) => o.status === "failed").length;
+    consola.info(
+      `Done — ${colors.green(`${synced} synced`)}, ${colors.yellow(`${skipped} skipped`)}, ${colors.red(`${failed} failed`)}`
+    );
+    if (failed > 0) {
+      process.exitCode = 1;
+    }
+  }
+});
+const KNOWN_TYPES = /* @__PURE__ */ new Set(["github", "gitlab", "gitea", "codeberg", "git"]);
+function validateForge(name, forge) {
+  if (!KNOWN_TYPES.has(forge.type)) {
+    return {
+      name: `forge "${name}"`,
+      severity: "fail",
+      message: `unknown type "${forge.type}"`
+    };
+  }
+  if (!forge.host?.trim()) {
+    return {
+      name: `forge "${name}"`,
+      severity: "fail",
+      message: "host is empty"
+    };
+  }
+  if (!forge.dir?.trim()) {
+    return {
+      name: `forge "${name}"`,
+      severity: "fail",
+      message: "dir is empty"
+    };
+  }
+  return {
+    name: `forge "${name}"`,
+    severity: "ok",
+    message: `${forge.type} at ${forge.host}`
+  };
+}
+async function runChecks(config, configDir) {
+  const checks = [];
+  for (const [name, forge] of Object.entries(config.forges)) {
+    checks.push(validateForge(name, forge));
+  }
+  checks.push(
+    config.forges[config.defaultForge] ? {
+      name: "defaultForge",
+      severity: "ok",
+      message: `→ ${config.defaultForge}`
+    } : {
+      name: "defaultForge",
+      severity: "fail",
+      message: `"${config.defaultForge}" is not in forges`
+    }
+  );
+  const root = resolveRoot(config.root, configDir);
+  try {
+    await access(root);
+    checks.push({
+      name: "root directory",
+      severity: "ok",
+      message: root
+    });
+  } catch {
+    checks.push({
+      name: "root directory",
+      severity: "fail",
+      message: `${root} does not exist (mkdir -p it or fix root in config)`
+    });
+  }
+  const types = new Set(Object.values(config.forges).map((f) => f.type));
+  const needsGit = types.has("git") || types.size > 0;
+  const needsGh = types.has("github");
+  if (needsGit) {
+    checks.push(
+      await hasCommand("git") ? { name: "git CLI", severity: "ok", message: "on PATH" } : {
+        name: "git CLI",
+        severity: "fail",
+        message: "install from https://git-scm.com/"
+      }
+    );
+  }
+  if (needsGh) {
+    if (await hasCommand("gh")) {
+      checks.push({ name: "gh CLI", severity: "ok", message: "on PATH" });
+      const auth = await execCapture("gh", ["auth", "status"]);
+      checks.push(
+        auth.code === 0 ? { name: "gh auth", severity: "ok", message: "authenticated" } : {
+          name: "gh auth",
+          severity: "warn",
+          message: "not logged in — run `gh auth login`"
+        }
+      );
+    } else {
+      checks.push({
+        name: "gh CLI",
+        severity: "fail",
+        message: "install from https://cli.github.com/"
+      });
+    }
+  }
+  return checks;
+}
+function severitySymbol(severity) {
+  if (severity === "ok") return colors.green("✓");
+  if (severity === "warn") return colors.yellow("!");
+  return colors.red("✗");
+}
+const 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)}
+`);
+    } else {
+      for (const c of checks) {
+        process.stdout.write(
+          `${severitySymbol(c.severity)} ${c.name.padEnd(22)} ${colors.dim(c.message)}
+`
+        );
+      }
+      process.stdout.write(
+        `
+${ok ? colors.green("All checks passed.") : colors.red("Validation failed.")}
+`
+      );
+    }
+    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."
+      );
+    }
+  }
+});
 const rootCommand = defineCommand({
   meta: {
     name: "forgemap",
@@ -745,11 +2817,17 @@ const rootCommand = defineCommand({
   },
   subCommands: {
     clone: cloneCommand,
+    import: importCommand,
+    cleanup: cleanupCommand,
     cd: cdCommand,
     path: pathCommand,
     open: openCommand,
     search: searchCommand,
     pick: pickCommand,
+    status: statusCommand,
+    sync: syncCommand,
+    validate: validateCommand,
+    completion: completionCommand,
     "shell-init": shellInitCommand,
     config: configCommand
   }