forgemap 0.1.0-dev.22-d31fc67 → 0.1.0-dev.23-9e4d2ae

package/dist/bin/forgemap.mjs

@@ -2,10 +2,11 @@
 import { defineCommand, runMain } from "citty";
 import consola from "consola";
 import { existsSync } from "node:fs";
-import { mkdir, writeFile, readdir } from "node:fs/promises";
+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";
@@ -55,16 +56,12 @@ async function loadForgeMapConfig(options = {}) {
     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
-    }
+    forges: config.forges && Object.keys(config.forges).length > 0 ? config.forges : DEFAULT_CONFIG.forges
   };
   return {
     config: merged,
@@ -81,6 +78,26 @@ function execInherit(command, args) {
     });
   });
 }
+function execCapture(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", rejectPromise);
+    child.on("close", (code) => {
+      resolvePromise({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}
 function hasCommand(command) {
   return new Promise((resolvePromise) => {
     const child = spawn(
@@ -94,6 +111,28 @@ function hasCommand(command) {
     child.on("close", (code) => resolvePromise(code === 0));
   });
 }
+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}`);
+    }
+  }
+};
 const githubAdapter = {
   async clone({ owner, repo, dest }) {
     if (!await hasCommand("gh")) {
@@ -116,11 +155,13 @@ 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 +169,159 @@ 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) {
+  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 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]
+  });
+}
 const SHORT_RE = /^([\w.-]+)\/([\w.-]+)$/;
 const NAMED_RE = /^([\w.-]+):([\w.-]+)\/([\w.-]+)$/;
 const SSH_RE = /^git@([\w.-]+):([\w.-]+)\/([\w.-]+?)(?:\.git)?$/;
@@ -181,16 +375,6 @@ 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()) {
@@ -252,12 +436,27 @@ const cloneCommand = defineCommand({
       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;
@@ -265,6 +464,15 @@ const cloneCommand = defineCommand({
       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;
@@ -275,13 +483,146 @@ 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 SUPPORTED$1 = ["zsh", "bash", "fish"];
+const SUBCOMMANDS = [
+  "clone",
+  "cd",
+  "path",
+  "open",
+  "search",
+  "pick",
+  "status",
+  "sync",
+  "validate",
+  "shell-init",
+  "completion",
+  "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)"
+_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$1.join(", ")}). Auto-detected from $SHELL if omitted.`,
+      required: false
+    }
+  },
+  async run({ args }) {
+    const requested = args.shell ?? detectShell$1();
+    if (!SUPPORTED$1.includes(requested)) {
+      consola.error(
+        `Unsupported shell "${requested}". Supported: ${SUPPORTED$1.join(", ")}.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const out = requested === "fish" ? renderFish$1() : requested === "zsh" ? renderZsh() : renderBash();
+    process.stdout.write(out);
+  }
+});
 const TEMPLATE = `/**
  * forgemap configuration.
  *
@@ -459,39 +800,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",
@@ -556,7 +864,7 @@ const pickCommand = defineCommand({
     }
   }
 });
-function renderTree(repos) {
+function renderTree$1(repos) {
   const groups = /* @__PURE__ */ new Map();
   for (const r of repos) {
     const list = groups.get(r.forgeName);
@@ -625,7 +933,7 @@ const searchCommand = defineCommand({
       return;
     }
     if (format === "pretty") {
-      process.stdout.write(`${renderTree(items)}
+      process.stdout.write(`${renderTree$1(items)}
 `);
       return;
     }
@@ -738,6 +1046,448 @@ const shellInitCommand = defineCommand({
     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"}`)}`;
+  }
+  const s = row.status;
+  const parts = [colors.cyan(row.repo.slug)];
+  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 groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const list = groups.get(row.repo.forgeName);
+    if (list) list.push(row);
+    else groups.set(row.repo.forgeName, [row]);
+  }
+  return formatTree(
+    Array.from(groups, ([forge, items]) => ({
+      text: colors.bold(forge),
+      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 {
+          outcomes.push({
+            repo,
+            status: "failed",
+            message: (result.stderr || result.stdout).trim().split("\n")[0]
+          });
+          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",
@@ -750,6 +1500,10 @@ const rootCommand = defineCommand({
     open: openCommand,
     search: searchCommand,
     pick: pickCommand,
+    status: statusCommand,
+    sync: syncCommand,
+    validate: validateCommand,
+    completion: completionCommand,
     "shell-init": shellInitCommand,
     config: configCommand
   }