forgemap 0.1.0-dev.23-9e4d2ae → 0.1.0-dev.26-b896caf

package/dist/bin/forgemap.mjs

@@ -1,14 +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 { readdir, readFile, mkdir, writeFile, stat, access } from "node:fs/promises";
-import { dirname, isAbsolute, resolve, join } from "pathe";
 import { loadConfig } from "c12";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { colors, formatTree } from "consola/utils";
 import Fuse from "fuse.js";
 const cdCommand = defineCommand({
   meta: {
@@ -35,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: {
@@ -48,8 +88,9 @@ 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,
@@ -59,9 +100,9 @@ async function loadForgeMapConfig(options = {}) {
     dotenv: false
   });
   const merged = {
-    root: config.root ?? DEFAULT_CONFIG.root,
-    defaultForge: config.defaultForge ?? DEFAULT_CONFIG.defaultForge,
-    forges: config.forges && Object.keys(config.forges).length > 0 ? config.forges : DEFAULT_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,
@@ -82,19 +123,50 @@ 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", rejectPromise);
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      if (killer) clearTimeout(killer);
+      if (!settled) {
+        settled = true;
+        rejectPromise(error);
+      }
+    });
     child.on("close", (code) => {
-      resolvePromise({ code: code ?? 0, stdout, stderr });
+      if (timer) clearTimeout(timer);
+      if (killer) clearTimeout(killer);
+      if (!settled) {
+        settled = true;
+        resolvePromise({
+          code: code ?? (timedOut ? 124 : 0),
+          stdout,
+          stderr,
+          timedOut
+        });
+      }
     });
   });
 }
@@ -111,6 +183,7 @@ 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";
@@ -131,8 +204,94 @@ const gitAdapter = {
     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")) {
@@ -149,6 +308,68 @@ 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) {
@@ -169,17 +390,7 @@ function getForgeAdapter(type) {
     }
   }
 }
-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);
-}
-async function listDirs(path) {
+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);
@@ -194,10 +405,10 @@ async function scanRepos(options) {
   const repos = [];
   for (const [forgeName, forge] of Object.entries(config.forges)) {
     const forgeRoot = join(root, forge.dir);
-    const owners = await listDirs(forgeRoot);
+    const owners = await listDirs$1(forgeRoot);
     for (const owner of owners) {
       const ownerPath = join(forgeRoot, owner);
-      const repoNames = await listDirs(ownerPath);
+      const repoNames = await listDirs$1(ownerPath);
       for (const repo of repoNames) {
         repos.push({
           forgeName,
@@ -322,6 +533,132 @@ async function appendCachedRepo(options, repo) {
     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)?$/;
@@ -375,75 +712,129 @@ function parseSlug(input) {
   }
   throw new Error(`Unrecognized slug format: ${input}`);
 }
-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"
     },
-    ssh: {
+    forge: {
+      type: "string",
+      description: "Restrict to a single forge alias"
+    },
+    "dry-run": {
       type: "boolean",
-      description: "Force the SSH URL form (git-type forges only)",
+      description: "Only list candidates; never prompt or delete",
       default: false
     },
-    https: {
+    yes: {
       type: "boolean",
-      description: "Force the HTTPS URL form (git-type forges only)",
+      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: {
@@ -452,27 +843,275 @@ const cloneCommand = defineCommand({
     }
   },
   async run({ args }) {
-    if (args.ssh && args.https) {
-      consola.error("--ssh and --https are mutually exclusive.");
+    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 parsed = parseSlug(args.slug);
     const configDir = loaded.configFile ? dirname(loaded.configFile) : loaded.cwd;
-    const resolved = resolveSlug(parsed, {
+    let repos = await scanReposCached({
       config: loaded.config,
-      configDir
+      configDir,
+      useCache: !args["no-cache"]
     });
-    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 (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;
@@ -502,9 +1141,64 @@ const cloneCommand = defineCommand({
     );
   }
 });
-const SUPPORTED$1 = ["zsh", "bash", "fish"];
+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",
@@ -518,12 +1212,6 @@ const SUBCOMMANDS = [
   "config"
 ];
 const SLUG_COMMANDS = ["clone", "cd", "path", "open", "search", "pick"];
-function detectShell$1() {
-  const env = process.env.SHELL ?? "";
-  if (env.endsWith("/fish")) return "fish";
-  if (env.endsWith("/bash")) return "bash";
-  return "zsh";
-}
 function renderBash() {
   return `# forgemap bash completion — drop into your ~/.bashrc:
 #   eval "$(forgemap completion bash)"
@@ -606,24 +1294,45 @@ const completionCommand = defineCommand({
   args: {
     shell: {
       type: "positional",
-      description: `Shell flavor (${SUPPORTED$1.join(", ")}). Auto-detected from $SHELL if omitted.`,
+      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$1();
-    if (!SUPPORTED$1.includes(requested)) {
+    const requested = args.shell ?? detectShell();
+    if (!SUPPORTED_SHELLS.includes(requested)) {
       consola.error(
-        `Unsupported shell "${requested}". Supported: ${SUPPORTED$1.join(", ")}.`
+        `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 TEMPLATE = `/**
+const HEADER = `/**
  * forgemap configuration.
  *
  * For type-safe authoring, install forgemap and switch to:
@@ -631,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",
@@ -662,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({
@@ -717,6 +1467,558 @@ const configCommand = defineCommand({
     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) {
   const distro = process.env.WSL_DISTRO_NAME;
   if (distro) {
@@ -850,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$1(repos) {
-  const groups = /* @__PURE__ */ new Map();
+  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)}`
+        }))
       }))
     }))
   );
@@ -945,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:
@@ -1018,89 +2371,49 @@ 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);
   }
 });
-async function gitIn(cwd, args) {
-  return execCapture("git", args, { cwd });
-}
-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 gitIn(localPath, ["fetch", "--all", "--prune"]);
-}
-async function pullRepo(localPath) {
-  return gitIn(localPath, ["pull", "--ff-only"]);
-}
-async function isClean(localPath) {
-  const result = await gitIn(localPath, ["status", "--porcelain"]);
-  return result.code === 0 && result.stdout.trim().length === 0;
-}
 function statusLine(row) {
   if (row.error || !row.status) {
-    return `${colors.cyan(row.repo.slug)}  ${colors.red(`error: ${row.error ?? "unknown"}`)}`;
+    return `${colors.cyan(row.repo.repo)}  ${colors.red(`error: ${row.error ?? "unknown"}`)}`;
   }
   const s = row.status;
-  const parts = [colors.cyan(row.repo.slug)];
+  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}`));
@@ -1113,16 +2426,24 @@ function statusLine(row) {
   return parts.join("  ");
 }
 function renderTree(rows) {
-  const groups = /* @__PURE__ */ new Map();
+  const byForge = /* @__PURE__ */ new Map();
   for (const row of rows) {
-    const list = groups.get(row.repo.forgeName);
+    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 groups.set(row.repo.forgeName, [row]);
+    else owners.set(row.repo.owner, [row]);
   }
   return formatTree(
-    Array.from(groups, ([forge, items]) => ({
+    Array.from(byForge, ([forge, owners]) => ({
       text: colors.bold(forge),
-      children: items.map((row) => ({ text: statusLine(row) }))
+      children: Array.from(owners, ([owner, items]) => ({
+        text: owner,
+        children: items.map((row) => ({ text: statusLine(row) }))
+      }))
     }))
   );
 }
@@ -1313,10 +2634,11 @@ const syncCommand = defineCommand({
           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: (result.stderr || result.stdout).trim().split("\n")[0]
+            message
           });
           consola.fail(
             `${colors.dim(repo.slug)} — ${outcomes.at(-1)?.message}`
@@ -1495,6 +2817,8 @@ const rootCommand = defineCommand({
   },
   subCommands: {
     clone: cloneCommand,
+    import: importCommand,
+    cleanup: cleanupCommand,
     cd: cdCommand,
     path: pathCommand,
     open: openCommand,