@ajaykumarnpm/talea 0.1.0

package/src/commands/adopt.js

@@ -0,0 +1,441 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { expandHome, loadState, saveState } from '../config.js';
+import { c, fail, glyph, heading, icon, info, ok, plain, skip, summary, warn } from '../log.js';
+import { requireCatalogue, requireWorkspace, selectRepos } from '../workspace.js';
+import {
+  DUPLICATES_DIR,
+  claudeMaybeRunning,
+  executeMove,
+  parkingSpot,
+  findConfigHits,
+  findGitDirs,
+  moveClaudeSessions,
+  planAdoptions,
+  readOrigins,
+  rekeyClaudeJson,
+  rewriteConfigFile,
+  unfixablePaths,
+} from '../adopt.js';
+import { git } from '../git.js';
+
+export const help = `
+${c.bold('talea adopt')} — move repos you already have into the right place
+
+  ${c.dim('talea adopt')}                        show what would move
+  ${c.dim('talea adopt --apply')}                actually move it
+  ${c.dim('talea adopt --from ~/Desktop')}       also look there for checkouts
+  ${c.dim('talea adopt -r eklavya --apply')}
+
+Repos are matched by their ${c.bold('git remote')}, never by folder name, so a checkout
+called ${c.dim('~/tmp/clone2')} is still recognised as the repo it holds. A matched repo in the wrong place is
+${c.bold('moved')}, never re-cloned — the move keeps every branch, stash, reflog entry
+and uncommitted change exactly as it is.
+
+A repo that cannot be moved safely (a linked worktree, extra worktrees, an
+occupied destination, another filesystem) is left alone and the reason is
+printed.
+
+When the same repo is found twice, the copy at the catalogue path wins and the
+other moves into ${c.bold(DUPLICATES_DIR)}/ — never deleted, never left outside the tree.
+Whatever it holds (branches, stashes, uncommitted work) comes with it, and is
+listed so you can decide what to do with it.
+
+After a move, absolute paths that pointed at the old location are repaired:
+Claude Code session history and memory, its per-project settings, and config
+files in the workspace and the repo (.idea, .vscode, .claude, CLAUDE.md).
+
+Options
+  -g, --group <names>   restrict to groups
+  -r, --repo <names>    restrict to repos
+      --from <path>     extra folder to search (repeatable, remembered)
+      --apply           perform the moves (default is a dry run)
+      --fix-paths       re-repair config for repos already adopted, moving nothing
+  -j, --jobs <n>        parallel git calls (default 8)
+`;
+
+/**
+ * Scan, match, and optionally move. Exported so `clone` can adopt before it
+ * clones — a repo the developer already has must never be cloned twice.
+ */
+export async function planFor({ manifest, root, repos, scanRoots, jobs = 8 }) {
+  const dirs = findGitDirs(scanRoots, 3);
+  const candidates = await readOrigins(dirs, jobs);
+  const plans = await planAdoptions(manifest, root, repos, candidates);
+
+  return {
+    plans,
+    moves: plans.filter((p) => p.action === 'move'),
+    parks: plans.filter((p) => p.action === 'park'),
+    refused: plans.filter((p) => p.action === 'refuse'),
+    inPlace: plans.filter((p) => p.action === 'in-place'),
+  };
+}
+
+/**
+ * Perform the moves and repair the paths that pointed at the old locations.
+ *
+ * Every successful move is appended to `.talea.json`, both as an audit trail
+ * and so `--fix-paths` can repair the config again later. That matters because
+ * a running Claude Code process rewrites ~/.claude.json when it exits and can
+ * revert the repair — and by then the repo is in place, so a plain re-run would
+ * find nothing to do.
+ */
+export async function applyMoves(root, moves, parks = [], manifest) {
+  const results = [];
+  const warnedAboutClaude = moves.length > 0 && claudeMaybeRunning();
+
+  for (const plan of moves) {
+    const res = executeMove(plan);
+    if (!res.ok) {
+      fail(`${c.bold(plan.repo.name)}\n    ${c.dim(res.message)}`);
+      results.push({ plan, ok: false });
+      continue;
+    }
+    ok(
+      `${c.bold(plan.repo.name)} ${c.dim(shorten(plan.from))} ${icon.arrow} ${c.dim(path.relative(root, plan.to))}`,
+    );
+    const repairs = repairPaths(root, plan);
+    results.push({ plan, ok: true, repairs });
+  }
+
+  // Second copies move only once the winner is actually in place. Ordering
+  // alone does not achieve that — a move that failed leaves the catalogue path
+  // empty, and parking on top of that strands one copy and hides the other, so
+  // the winner's arrival is checked rather than assumed.
+  const parked = [];
+  const failedMoves = new Set(
+    results.filter((r) => !r.ok).map((r) => path.resolve(r.plan.to)),
+  );
+
+  for (const plan of parks) {
+    const winner = path.resolve(plan.keeping);
+    if (failedMoves.has(winner) || !existsSync(winner)) {
+      warn(
+        `${c.bold(plan.repo.name)} second copy left where it is — ` +
+          `${path.relative(root, plan.keeping) || plan.keeping} is not in place\n    ${c.dim(shorten(plan.from))}`,
+      );
+      continue;
+    }
+
+    // The spot is chosen now, not at plan time: two copies of one repo planned
+    // in the same run would otherwise be handed the identical path, and the
+    // -2 suffixing would never fire.
+    const res = executeMove({ ...plan, to: parkingSpot(root, plan.repo, manifest) });
+    if (!res.ok) {
+      fail(`${c.bold(plan.repo.name)} second copy\n    ${c.dim(res.message)}`);
+      continue;
+    }
+    parked.push({ ...plan, to: res.to ?? plan.to });
+    const landed = parked[parked.length - 1];
+    ok(
+      `${c.bold(plan.repo.name)} ${c.dim(shorten(plan.from))} ${icon.arrow} ${c.dim(path.relative(root, landed.to))}`,
+    );
+    plain(
+      `    ${c.dim(glyph.pending)} second copy — ${c.bold(path.relative(root, plan.keeping) || plan.keeping)} is the one in use`,
+    );
+    plain(
+      `    ${c.dim(glyph.pending)} ${
+        plan.holds.length
+          ? c.yellow(`holds ${plan.holds.join(' and ')}`)
+          : c.dim('fully redundant — every commit is in the copy above')
+      }`,
+    );
+  }
+
+  const done = results.filter((r) => r.ok);
+  if (done.length) {
+    const state = loadState(root);
+    const at = new Date().toISOString();
+    saveState(root, {
+      ...state,
+      adopted: [
+        ...(state.adopted ?? []),
+        ...done.map((r) => ({ repo: r.plan.repo.name, from: r.plan.from, to: r.plan.to, at })),
+      ],
+    });
+  }
+
+  return { results, parked, warnedAboutClaude };
+}
+
+/** Which of the rewritten files are tracked by git, and so now show a diff. */
+async function trackedAmong(files) {
+  const tracked = [];
+  for (const file of files) {
+    const { code } = await git(['ls-files', '--error-unmatch', '--', path.basename(file)], {
+      cwd: path.dirname(file),
+    });
+    if (code === 0) tracked.push(file);
+  }
+  return tracked;
+}
+
+/**
+ * Report the places that still name the old location and that this tool will
+ * not touch, so "nothing was missed" is a statement the developer can check
+ * rather than take on trust.
+ */
+async function reportLeftovers(root, applied) {
+  const rewritten = applied.results
+    .filter((r) => r.ok)
+    .flatMap((r) => r.repairs?.rewritten?.map((h) => h.file) ?? []);
+
+  const tracked = await trackedAmong(rewritten);
+  if (tracked.length) {
+    plain('');
+    warn(
+      `${tracked.length} rewritten file${tracked.length > 1 ? 's are' : ' is'} tracked by git — you now have a diff to review:`,
+    );
+    for (const file of tracked) plain(c.dim(`    ${path.relative(root, file)}`));
+  }
+
+  const moved = applied.results.filter((r) => r.ok).map((r) => r.plan);
+  const leftovers = moved.flatMap((plan) => unfixablePaths(plan.from));
+  if (!leftovers.length) return;
+
+  const needsYou = leftovers.filter((l) => l.actionable);
+  const informational = leftovers.filter((l) => !l.actionable);
+
+  if (needsYou.length) {
+    plain('');
+    heading('Still pointing at the old location — these need you');
+    for (const l of needsYou) {
+      plain(`  ${c.yellow('!')} ${c.bold(l.what)} ${c.dim(l.detail ?? '')}`);
+      plain(`      ${c.dim(l.why)}`);
+    }
+  }
+
+  if (informational.length) {
+    plain('');
+    plain(c.dim('  Left alone on purpose:'));
+    for (const l of informational) plain(c.dim(`    ${l.what} — ${l.why}`));
+  }
+}
+
+/**
+ * Re-apply the path repair for moves already recorded, moving nothing.
+ * The escape hatch for a repair that was reverted underneath us.
+ */
+export function refixPaths(root) {
+  const history = loadState(root).adopted ?? [];
+  if (!history.length) return { count: 0 };
+  for (const entry of history) {
+    plain(`  ${c.bold(entry.repo)} ${c.dim(`${shorten(entry.from)} ${glyph.arrow} ${path.relative(root, entry.to)}`)}`);
+    repairPaths(root, { repo: { name: entry.repo }, from: entry.from, to: entry.to });
+    for (const l of unfixablePaths(entry.from)) {
+      plain(
+        `    ${l.actionable ? c.yellow('!') : c.dim('·')} ${l.what} ${c.dim(l.detail ?? '')} ${c.dim(`— ${l.why}`)}`,
+      );
+    }
+  }
+  return { count: history.length };
+}
+
+/** Fix the absolute paths that pointed at the repo's old home. */
+function repairPaths(root, plan) {
+  const done = [];
+
+  const sessions = moveClaudeSessions(plan.from, plan.to);
+  if (sessions.changed) {
+    done.push(
+      sessions.merged
+        ? `Claude history merged (${sessions.moved} moved, ${sessions.kept} already there)`
+        : 'Claude session history and memory',
+    );
+  } else if (sessions.error) {
+    done.push(c.yellow(`Claude history not moved: ${sessions.error}`));
+  }
+
+  const settings = rekeyClaudeJson(plan.from, plan.to);
+  if (settings.changed) {
+    done.push(`~/.claude.json project entry${settings.note ? ` ${c.dim(`(${settings.note})`)}` : ''}`);
+  } else if (settings.error) {
+    done.push(c.yellow(`~/.claude.json not updated: ${settings.error}`));
+  }
+
+  const rewritten = [];
+  for (const hit of findConfigHits([root, plan.to], plan.from)) {
+    const res = rewriteConfigFile(hit.file, plan.from, plan.to);
+    if (res.changed) {
+      rewritten.push(hit);
+      done.push(`${path.relative(root, hit.file)} ${c.dim(`(${hit.count} path${hit.count > 1 ? 's' : ''})`)}`);
+    }
+  }
+
+  for (const line of done) plain(`    ${c.dim(glyph.pending)} ${line}`);
+
+  // Some of those config files are committed. Say so — the developer now has a
+  // diff to review, and finding it by surprise later is worse.
+  return { done, rewritten };
+}
+
+// os.homedir(), not process.env.HOME: HOME is unset on Windows, and
+// String.replace(undefined, '~') would replace the literal text "undefined".
+const shorten = (p) => {
+  const home = os.homedir();
+  return home && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+};
+
+/**
+ * Turn `--from a,b` into absolute paths.
+ *
+ * Empty segments are dropped BEFORE resolving: `path.resolve('')` is the
+ * current directory, so a trailing comma or `--from ""` would otherwise add
+ * cwd to the remembered scan paths and quietly hunt for repos to relocate
+ * there on every later run.
+ */
+export function parseFromPaths(from) {
+  return (Array.isArray(from) ? from : [from])
+    .filter(Boolean)
+    .flatMap((s) => String(s).split(','))
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => path.resolve(expandHome(s)));
+}
+
+export async function run(opts) {
+  const { root, manifest, state } = requireWorkspace();
+
+  if (opts['fix-paths']) {
+    heading('Repairing paths for repos already adopted');
+    const { count } = refixPaths(root);
+    if (!count) {
+      plain(c.dim('  Nothing recorded — no repo has been adopted in this workspace.'));
+    }
+    return;
+  }
+
+  requireCatalogue(manifest);
+
+  // The whole catalogue, not this machine's selection: a stray checkout is
+  // worth moving into place whether or not this machine had signed up for it.
+  const repos = selectRepos(manifest, opts, manifest.repos);
+
+  const extra = parseFromPaths(opts.from);
+
+  const remembered = state.scanPaths ?? [];
+  const scanRoots = [...new Set([root, ...remembered, ...extra])];
+
+  heading(opts.apply ? 'Adopting existing checkouts' : 'Adopting existing checkouts (dry run)');
+  info(
+    `searching ${scanRoots.length} location${scanRoots.length > 1 ? 's' : ''}, ` +
+      `${repos.length} repo${repos.length > 1 ? 's' : ''} in scope`,
+  );
+  for (const dir of scanRoots) plain(`    ${c.dim(shorten(dir))}`);
+
+  const { moves, parks, refused, inPlace } = await planFor({
+    manifest,
+    root,
+    repos,
+    scanRoots,
+    jobs: opts.jobs ?? 8,
+  });
+
+  if (inPlace.length) {
+    plain('');
+    skip(`${inPlace.length} already in the right place`);
+  }
+
+  if (!moves.length && !parks.length && !refused.length) {
+    plain(`\n${c.dim('Nothing to adopt.')}`);
+    return;
+  }
+
+  if (moves.length && !opts.apply) {
+    plain('');
+    for (const p of moves) {
+      const mark = p.confidence === 'name' ? c.yellow(glyph.maybe) : c.green(glyph.arrow);
+      plain(
+        `  ${mark} ${c.bold(p.repo.name)}\n` +
+          `      from  ${c.dim(shorten(p.from))}\n` +
+          `      to    ${c.dim(path.relative(root, p.to))}`,
+      );
+    }
+    if (moves.some((p) => p.confidence === 'name')) {
+      plain('');
+      warn(
+        `${c.yellow('~')} matched on repo name only — the remote host is not one the catalogue lists.\n` +
+          `  Check those remotes before applying.`,
+      );
+    }
+  }
+
+  if (parks.length && !opts.apply) {
+    plain('');
+    for (const p of parks) {
+      plain(
+        `  ${c.yellow('⇉')} ${c.bold(p.repo.name)} ${c.dim('— second copy')}\n` +
+          `      from  ${c.dim(shorten(p.from))}\n` +
+          `      to    ${c.dim(path.relative(root, p.to))}\n` +
+          `      keep  ${c.dim(path.relative(root, p.keeping) || p.keeping)}` +
+          (p.holds.length ? `\n      ${c.yellow(`holds ${p.holds.join(' and ')}`)}` : ''),
+      );
+    }
+    plain('');
+    info(
+      c.dim(`Second copies move into ${DUPLICATES_DIR}/ rather than being deleted — everything\n` +
+        '    in them is kept, and nothing outside the tree is left behind.'),
+    );
+  }
+
+  if (refused.length) {
+    plain('');
+    for (const p of refused) {
+      warn(`${c.bold(p.repo.name)} left alone — ${p.reason}\n    ${c.dim(shorten(p.from))}`);
+    }
+  }
+
+  if (!opts.apply) {
+    const bits = [];
+    if (moves.length) bits.push(`move ${moves.length} into place`);
+    if (parks.length) bits.push(`park ${parks.length} second cop${parks.length === 1 ? 'y' : 'ies'}`);
+    plain(`\n${c.dim(bits.length ? `Re-run with --apply to ${bits.join(' and ')}.` : 'Nothing to apply.')}`);
+    return;
+  }
+
+  if (extra.length) {
+    saveState(root, { ...state, scanPaths: [...new Set([...remembered, ...extra])] });
+  }
+
+  plain('');
+  const applied = await applyMoves(root, moves, parks, manifest);
+  const okCount = applied.results.filter((r) => r.ok).length;
+  summary({
+    ok: okCount + applied.parked.length,
+    skipped: inPlace.length,
+    failed: applied.results.length - okCount + (parks.length - applied.parked.length),
+    okLabel: 'relocated',
+  });
+
+  if (applied.parked.length) {
+    plain('');
+    info(
+      `${applied.parked.length} second cop${applied.parked.length === 1 ? 'y' : 'ies'} parked in ` +
+        `${c.bold(DUPLICATES_DIR)}/ ${c.dim('— nothing was deleted.')}`,
+    );
+    plain(c.dim(`  Review them, then remove the folder yourself when you are happy:`));
+    plain(c.dim(`    rm -rf ${path.join(root, DUPLICATES_DIR)}`));
+  }
+
+  await reportLeftovers(root, applied);
+
+  if (applied.warnedAboutClaude) {
+    plain('');
+    warn(
+      'A Claude Code process is running. It rewrites ~/.claude.json when it exits,\n' +
+        '  which can revert the settings fix above. Re-run `talea adopt` after quitting it\n' +
+        '  if the project entry looks wrong.',
+    );
+  }
+
+  if (okCount) {
+    plain(`\n${c.dim('To sweep anything this did not cover:')}`);
+    for (const r of applied.results.filter((x) => x.ok)) {
+      plain(c.dim(`  grep -rl "${r.plan.from}" ${root} ~ 2>/dev/null`));
+      break;
+    }
+  }
+}

package/src/commands/clone.js

@@ -0,0 +1,233 @@
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+import { defaultBranch, groupDir, repoGroup, repoUrl, saveState } from '../config.js';
+import { dropDocs } from '../docs.js';
+import { clone, defaultJobs, isMissingRemote, pooled } from '../git.js';
+import { board } from '../live.js';
+import { c, heading, icon, ok, plain, summary, warn } from '../log.js';
+import { chooseRepos } from '../select.js';
+import { requireCatalogue, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+import { applyMoves, parseFromPaths, planFor } from './adopt.js';
+
+export const help = `
+${c.bold('talea clone')} — clone what is missing, and nothing else
+
+  ${c.dim('talea clone')}                     clone every repo this machine keeps
+  ${c.dim('talea clone -g nonstopio')}        only that owner
+  ${c.dim('talea clone -r eklavya')}          a single repo, whether or not it is selected
+  ${c.dim('talea clone --pick')}              re-open the checklist first
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --pick            choose what this machine keeps before cloning
+      --protocol <p>    ssh (default) or https
+      --from <path>     also search here for existing checkouts (repeatable)
+      --no-adopt        skip the existing-checkout check and only clone
+  -j, --jobs <n>        parallel clones (default: one per core, 6-12)
+
+Before cloning anything, the workspace is checked for repos that are already on
+disk in the wrong place — cloned by hand, or moved by a catalogue change. Those
+are ${c.bold('moved')} into place, keeping every branch and uncommitted change, instead of
+being cloned again. Pass ${c.dim('--from ~/Desktop')} to look outside the workspace too;
+folders you name are remembered.
+
+Already-cloned repos are left completely alone, so re-running is safe. A repo
+the server will not hand over — renamed, deleted, or never granted to your
+account — is reported and skipped, not failed.
+
+${c.dim('talea sync')} does this and then fast-forwards. This command is the half you want
+when you are on a slow connection and do not care about merging yet.
+`;
+
+/**
+ * Relocate checkouts that are already on disk but in the wrong place.
+ *
+ * The workspace itself is always searched — that is how a catalogue change that
+ * moves a repo between groups reaches everyone who already cloned it. Anywhere
+ * else is only searched when it has been named explicitly, because moving
+ * repositories found by guesswork is not ours to do.
+ *
+ * Returns the repos to keep OUT of the clone set. Anything left where it is
+ * must not be cloned as well, or a fresh copy lands beside the developer's
+ * existing checkout — the one outcome this whole module exists to prevent.
+ */
+export async function adoptInPlace({ manifest, root, state, repos, opts }) {
+  const extra = parseFromPaths(opts.from);
+  const scanRoots = [...new Set([root, ...(state.scanPaths ?? []), ...extra])];
+
+  // Remembered before anything moves. `applyMoves` appends to the same state
+  // file, so writing this afterwards from a stale snapshot would wipe the
+  // `adopted` move log — the exact record `talea adopt --fix-paths` replays.
+  if (extra.length) {
+    saveState(root, { ...state, scanPaths: [...new Set([...(state.scanPaths ?? []), ...extra])] });
+  }
+
+  const { moves, parks, refused } = await planFor({ manifest, root, repos, scanRoots, jobs: opts.jobs });
+
+  // A name-only match means the remote host is not one the catalogue lists, so
+  // it is probably right but not certainly. This runs unattended, so it only
+  // relocates certain matches; the rest are named and left for `talea adopt`,
+  // where they are shown before anything moves.
+  const certain = moves.filter((m) => m.confidence === 'exact');
+  const unsure = moves.filter((m) => m.confidence !== 'exact');
+
+  const skip = new Map();
+  for (const m of unsure) skip.set(m.repo.name, 'its remote host is not one the catalogue lists');
+  for (const r of refused) skip.set(r.repo.name, r.reason);
+
+  if (certain.length || parks.length) {
+    const bits = [];
+    if (certain.length) bits.push(`${certain.length} to move into place`);
+    if (parks.length) bits.push(`${parks.length} second cop${parks.length === 1 ? 'y' : 'ies'} to park`);
+    heading(`Existing checkouts: ${bits.join(', ')}`);
+
+    const applied = await applyMoves(root, certain, parks, manifest);
+    for (const r of applied.results.filter((x) => !x.ok)) skip.set(r.plan.repo.name, 'its move failed');
+  }
+
+  if (skip.size) {
+    plain('');
+    for (const [name, reason] of skip) warn(`${c.bold(name)} left alone — ${reason}`);
+    plain(c.dim('  Not cloned either, so nothing lands beside it. Run `talea adopt` to sort it out.'));
+  }
+
+  return { skip };
+}
+
+/**
+ * Clone the entries that are not on disk. Shared with `sync`, which clones the
+ * missing before fast-forwarding the rest — one command for "make this machine
+ * match the list".
+ *
+ * Mutates and returns `counts` so a caller can fold cloning and syncing into a
+ * single summary.
+ */
+export async function cloneMissing({ manifest, root, entries, protocol, jobs, counts }) {
+  const view = board(
+    entries.map(({ repo }) => ({
+      id: repo.name,
+      group: groupDir(manifest, repoGroup(repo)),
+      label: repo.name,
+    })),
+  );
+
+  await pooled(entries, jobs, async ({ repo, dir }) => {
+    const url = repoUrl(manifest, repo, protocol);
+    const branch = defaultBranch(repo);
+    view.set(repo.name, 'busy', branch ? `cloning ${branch} …` : 'cloning …');
+
+    // Anything already sitting at the destination belongs to the developer, not
+    // to us. A folder with no .git could be hand-made notes, a half-finished
+    // checkout, or a repo whose .git was moved — none of which we may delete.
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+      counts.skipped++;
+      view.set(
+        repo.name,
+        'warn',
+        `${path.relative(root, dir)} already exists and is not a git repo, leaving it untouched`,
+      );
+      return;
+    }
+
+    mkdirSync(path.dirname(dir), { recursive: true });
+    const res = await clone(url, dir, branch ?? undefined);
+
+    // Only retry on the specific failure this fallback is for: the catalogue
+    // naming a branch the remote no longer has, which happens whenever a repo
+    // is renamed from master to main after the last discover. Any other failure
+    // (auth, network, disk) must be reported as itself.
+    const branchMissing =
+      branch && /remote branch .* not found|could not find remote branch/i.test(res.stderr);
+
+    if (res.code !== 0 && branchMissing) {
+      // Safe to clear: we got here having confirmed the path was empty, so the
+      // only thing here is the partial directory this failed clone just made.
+      rmSync(dir, { recursive: true, force: true });
+      const retry = await clone(url, dir, undefined);
+      if (retry.code === 0) {
+        counts.ok++;
+        view.set(repo.name, 'skip', `cloned on the default branch (no ${branch} on origin)`);
+        return;
+      }
+      counts.failed++;
+      view.set(repo.name, 'fail', 'clone failed');
+      view.note(repo.name, retry.stderr.split('\n')[0] ?? 'clone failed');
+      return;
+    }
+
+    if (res.code !== 0 && isMissingRemote(res.stderr)) {
+      // The catalogue lists it, the server does not hand it over. Not a broken
+      // workspace and not something a retry mends — skip it, clone the rest.
+      counts.skipped++;
+      view.set(repo.name, 'skip', 'origin is gone or not granted to you, not cloned');
+      return;
+    }
+
+    if (res.code !== 0) {
+      counts.failed++;
+      view.set(repo.name, 'fail', 'clone failed');
+      view.note(repo.name, res.stderr.split('\n')[0] ?? 'clone failed');
+      return;
+    }
+
+    counts.ok++;
+    view.set(
+      repo.name,
+      'ok',
+      `${icon.arrow} ${branch ? c.cyan(branch) : c.dim('default')} ${c.dim(path.relative(root, dir))}`,
+    );
+  });
+
+  view.stop();
+  return counts;
+}
+
+/** Group docs, for the folders repos live in. Shared by `clone` and `sync`. */
+export function writeDocs(manifest, root, repos) {
+  const docs = dropDocs(manifest, root, new Set(repos.map((r) => repoGroup(r))));
+  if (!docs.written.length) return;
+  heading('Workspace docs');
+  for (const file of docs.written) ok(`CLAUDE.md ${c.dim(`→ ${path.relative(root, file)}`)}`);
+}
+
+export async function run(opts) {
+  const { root, manifest, state } = requireWorkspace();
+  requireCatalogue(manifest);
+
+  const protocol = opts.protocol ?? state.protocol ?? 'ssh';
+  const jobs = opts.jobs ?? defaultJobs();
+
+  const { repos: chosen } = await chooseRepos({ manifest, root, state, opts });
+  const repos = selectRepos(manifest, opts, chosen);
+
+  const adoption =
+    opts.adopt === false
+      ? { skip: new Map() }
+      : await adoptInPlace({ manifest, root, state, repos, opts });
+
+  writeDocs(manifest, root, repos);
+
+  const entries = withPaths(manifest, root, repos);
+  const todo = entries.filter((e) => !e.cloned && !adoption.skip.has(e.repo.name));
+  const already = entries.filter((e) => e.cloned).length;
+
+  heading(`Cloning into ${root}`);
+  // A repo left alone counts against the run: without this, a clone that
+  // quietly skipped a stranded repo would still exit 0.
+  const counts = { ok: 0, skipped: already, failed: adoption.skip.size, okLabel: 'cloned' };
+
+  if (!todo.length) {
+    summary(counts);
+    return;
+  }
+
+  plain('');
+  await cloneMissing({ manifest, root, entries: todo, protocol, jobs, counts });
+  summary(counts);
+
+  if (counts.failed) {
+    plain(c.dim('\nFailed clones are usually SSH access. Run `talea doctor` to check.'));
+  }
+}