@ajaykumarnpm/talea 0.1.0

package/src/commands/where.js

@@ -0,0 +1,67 @@
+import { existsSync } from 'node:fs';
+
+import { repoDir } from '../config.js';
+import { c, fail, plain } from '../log.js';
+import { requireWorkspace } from '../workspace.js';
+
+export const help = `
+${c.bold('talea where')} — print a repo's path
+
+  ${c.dim('talea where eklavya')}             the absolute path, one line, nothing else
+  ${c.dim('cd $(talea where eklavya)')}       what it is actually for
+  ${c.dim('talea where')}                     the workspace root
+
+The whole point of a fixed structure is never having to remember it. This is
+the command that keeps that promise — the path goes to stdout on its own so it
+composes with ${c.dim('cd')}, ${c.dim('code')}, ${c.dim('open')} and anything else that takes a directory.
+
+Exits non-zero if the repo is not in the catalogue, so ${c.dim('cd $(talea where typo)')}
+fails loudly instead of landing you in your home directory.
+`;
+
+export function run(opts, positionals = []) {
+  const { root, manifest } = requireWorkspace();
+  const name = positionals[0];
+
+  if (!name) {
+    // stdout, not through the logger: this is data, and it is going to be
+    // consumed by $( ).
+    process.stdout.write(root + '\n');
+    return;
+  }
+
+  const wanted = name.toLowerCase();
+  const matches = manifest.repos.filter(
+    (r) => r.name.toLowerCase() === wanted || `${r.owner}/${r.name}`.toLowerCase() === wanted,
+  );
+
+  if (!matches.length) {
+    // Everything diagnostic goes to stderr, so a failed lookup never puts a
+    // stray word on stdout where a shell would try to cd into it.
+    fail(`No repo called "${name}" in the catalogue.`);
+    const near = manifest.repos
+      .filter((r) => r.name.toLowerCase().includes(wanted))
+      .slice(0, 5);
+    if (near.length) {
+      console.error(`\n  Did you mean: ${near.map((r) => c.bold(r.name)).join(', ')}`);
+    }
+    process.exit(1);
+  }
+
+  // Two owners can have a repo of the same name, and picking one silently would
+  // be the wrong kind of convenient.
+  if (matches.length > 1) {
+    fail(`"${name}" is ambiguous — ${matches.length} repos have that name.`);
+    for (const r of matches) console.error(`    ${c.bold(`${r.owner}/${r.name}`)}`);
+    console.error(`\n  Name the owner too: ${c.dim(`talea where ${matches[0].owner}/${matches[0].name}`)}`);
+    process.exit(1);
+  }
+
+  const dir = repoDir(manifest, root, matches[0]);
+  process.stdout.write(dir + '\n');
+
+  if (!existsSync(dir)) {
+    console.error(c.dim(`\n  Not cloned yet — \`talea sync -r ${matches[0].name}\` will fetch it.`));
+    process.exit(1);
+  }
+}

package/src/config.js

@@ -0,0 +1,155 @@
+// Configuration comes from three places, nearest wins:
+//
+//   <workspace>/talea.repos.json   a catalogue that belongs to this tree only
+//   ~/.talea/talea.repos.json      your catalogue — what `talea discover` writes
+//   manifest/talea.repos.json      the packaged one, which ships EMPTY
+//
+// The packaged manifest is empty on purpose. talea is not a catalogue of
+// anybody's repositories; it is the machinery for keeping your own in one
+// shape on every machine. Shipping a repo list in the package would make the
+// tool personal to whoever published it.
+//
+//   <workspace>/.talea.json        per-machine state — which repos this machine
+//                                  wants, which protocol, where it has looked
+//                                  for strays, what it has already moved.
+//
+// State is never shared. The catalogue is the thing that travels (see
+// `talea manifest push`); the selection is the thing that does not.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export const MANIFEST_NAME = 'talea.repos.json';
+export const STATE_FILE = '.talea.json';
+
+export const PACKAGED_MANIFEST = path.join(here, '..', 'manifest', MANIFEST_NAME);
+export const USER_DIR = path.join(os.homedir(), '.talea');
+export const USER_MANIFEST = path.join(USER_DIR, MANIFEST_NAME);
+export const USER_STATE = path.join(USER_DIR, 'state.json');
+
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8'));
+
+/** Machine-wide state: the update-check stamp, the gist id. Not per workspace. */
+export function readUserState() {
+  try {
+    return readJson(USER_STATE);
+  } catch {
+    return {};
+  }
+}
+
+export function writeUserState(state) {
+  try {
+    mkdirSync(USER_DIR, { recursive: true });
+    writeFileSync(USER_STATE, JSON.stringify(state, null, 2) + '\n');
+  } catch {
+    // A read-only home directory must not break the actual command. The only
+    // things kept here are a cache stamp and a gist id.
+  }
+}
+
+/** The catalogue files in precedence order, nearest first. */
+export function manifestCandidates(workspaceRoot) {
+  return [
+    workspaceRoot ? path.join(workspaceRoot, MANIFEST_NAME) : null,
+    USER_MANIFEST,
+    PACKAGED_MANIFEST,
+  ].filter(Boolean);
+}
+
+export function loadManifest(workspaceRoot) {
+  const file = manifestCandidates(workspaceRoot).find((f) => existsSync(f));
+  const manifest = file ? readJson(file) : readJson(PACKAGED_MANIFEST);
+  manifest.__source = file ?? PACKAGED_MANIFEST;
+  manifest.repos ??= [];
+  manifest.groups ??= {};
+  return manifest;
+}
+
+/** Write the catalogue back to wherever it was loaded from, or to the user one. */
+export function saveManifest(manifest, file) {
+  const dest =
+    file ?? (manifest.__source === PACKAGED_MANIFEST ? USER_MANIFEST : manifest.__source) ?? USER_MANIFEST;
+  const { __source, ...body } = manifest;
+  mkdirSync(path.dirname(dest), { recursive: true });
+  writeFileSync(dest, JSON.stringify(body, null, 2) + '\n');
+  return dest;
+}
+
+/**
+ * Find the workspace root by walking up from `start` looking for .talea.json.
+ * Mirrors how git finds .git, so commands work from anywhere inside the tree —
+ * including from inside one of the repos it manages.
+ */
+export function findWorkspace(start = process.cwd()) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (existsSync(path.join(dir, STATE_FILE))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function loadState(workspaceRoot) {
+  const file = path.join(workspaceRoot, STATE_FILE);
+  return existsSync(file) ? readJson(file) : {};
+}
+
+export function saveState(workspaceRoot, state) {
+  const file = path.join(workspaceRoot, STATE_FILE);
+  writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+}
+
+/** Expand `~` so `talea init ~/Workspace` behaves the same on every shell. */
+export function expandHome(p) {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * The clone URL for a repo: an explicit override, else the host template with
+ * the repo's own owner filled in.
+ *
+ * `{owner}` is per repo rather than per manifest, which is the whole reason one
+ * catalogue can hold your personal repos and three orgs' repos at once.
+ */
+export function repoUrl(manifest, repo, protocol = 'ssh') {
+  if (repo.url) return repo.url;
+  const template = manifest.remotes?.[protocol];
+  if (!template) {
+    throw new Error(
+      `Unknown remote protocol "${protocol}". Known: ${Object.keys(manifest.remotes ?? {}).join(', ')}`,
+    );
+  }
+  return template.replace('{owner}', repo.owner ?? '').replace('{repo}', repo.name);
+}
+
+/**
+ * The folder a group lives in. Equal to the catalogue key until a group is
+ * nested (`work/backend`), at which point printing the key names no real folder.
+ */
+export const groupDir = (manifest, group) => manifest.groups?.[group]?.dir ?? group;
+
+/** A repo's group: explicit, else its owner — so a fresh catalogue needs no curation. */
+export const repoGroup = (repo) => repo.group ?? repo.owner ?? 'repos';
+
+export const repoDir = (manifest, workspaceRoot, repo) =>
+  path.join(workspaceRoot, groupDir(manifest, repoGroup(repo)), repo.dir ?? repo.name);
+
+/**
+ * The branch this repo is cloned on and fast-forwarded against.
+ *
+ * Recorded per repo by `talea discover`, because GitHub is the only thing that
+ * knows — assuming `main` is wrong for every repo cut before 2020 and for
+ * anyone whose default is `master`, `develop` or `trunk`. Never guessed: a repo
+ * with nothing recorded is cloned on whatever the server hands over.
+ */
+export const defaultBranch = (repo) => repo.defaultBranch ?? null;

package/src/docs.js

@@ -0,0 +1,122 @@
+// The CLAUDE.md files that describe a *folder of repos* rather than a repo.
+//
+// `ProjectAJ14/`, `nonstopio/`, `work/backend/` — the folders repos get cloned
+// into — are not git repositories. So nothing can version the doc that says what
+// lives in one, and every machine would have to be handed the file. The
+// templates therefore ship with this package and `talea clone` drops them into
+// place, keyed by group name: `templates/<GROUP>.CLAUDE.md`, plus
+// `templates/root.CLAUDE.md` for the workspace root.
+//
+// talea ships NO templates. The mechanism is here so that adding a doc is
+// adding a file; until one exists this writes nothing.
+//
+// Repo-level CLAUDE.md files are not our business: a committed one arrives with
+// the clone, and a gitignored one belongs to whoever wrote it.
+
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { groupDir } from './config.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES = path.join(here, '..', 'templates');
+
+/** The template for a group, or for the workspace root when group is null. */
+export const templateFor = (group) =>
+  path.join(TEMPLATES, `${group ?? 'root'}.CLAUDE.md`);
+
+/**
+ * Every folder a group's docs belong in, innermost last: `work/backend` is the
+ * group, but `work/` above it is a real folder that no group owns and nothing
+ * else would ever document. Keyed by folder name, so `work.CLAUDE.md` is the
+ * only wiring a parent folder needs.
+ *
+ * A group's `dir` is catalogue data, and a typo in it used to be silent in two
+ * different ways — both of which cost the workspace-root doc, which is outside
+ * git and therefore unrecoverable:
+ *
+ *   dir: "./work/api"    `path.join(root, ".")` is `root`, so the group's own
+ *                        key displaced the root's entry in `targets`;
+ *                        `templateFor(".")` names no file, the write was
+ *                        skipped, and the root CLAUDE.md was never written.
+ *   dir: "" or "."       same collapse, except the key that lands on `root` is
+ *                        the GROUP's — so the workspace root was handed the
+ *                        group's doc. Never overwritten afterwards, so the
+ *                        wrong file at the root became permanent.
+ *
+ * Both are a malformed catalogue, so they are an error now. "Fail loudly on
+ * typos" is rule 5 for exactly this: a bulk command that quietly does the wrong
+ * thing is worse than one that stops.
+ */
+function docFolders(dir, group) {
+  // Split on '/' only: catalogue dirs are authored with forward slashes on
+  // every platform. Quietly accepting a backslash here would be papering over a
+  // different typo, and this function's job is to refuse them.
+  const raw = String(dir ?? '');
+  const segs = raw.split('/');
+  const usable =
+    segs.every((seg) => seg !== '' && seg !== '.' && seg !== '..') && !path.isAbsolute(raw);
+
+  if (!usable) {
+    throw new Error(
+      `Group "${group}" has an unusable dir ${JSON.stringify(dir)}.\n` +
+        '  A group dir must be a relative path below the workspace root, like "work/api".\n' +
+        '  Fix it in the catalogue (manifest/talea.repos.json).',
+    );
+  }
+
+  return segs.map((seg, i) => [
+    i === segs.length - 1 ? group : seg,
+    segs.slice(0, i + 1),
+  ]);
+}
+
+/**
+ * Write the workspace-root, parent-folder and per-group CLAUDE.md files that
+ * have a template.
+ *
+ * **Never overwrites.** These files are outside git by design, so an overwrite
+ * cannot be recovered — a developer's own edits to their own untracked doc
+ * outrank the packaged copy every time. A group with no template is skipped,
+ * which is how a group opts out — though for a nested group that means deleting
+ * the parent's template too (`PORTAL.CLAUDE.md` is reached through V1's and
+ * V2's `dir`, not through either group's own name).
+ *
+ * Throws on a group whose `dir` cannot name a folder below the root. See
+ * `docFolders`.
+ */
+export function dropDocs(manifest, root, groups) {
+  // Keyed by folder so a parent shared by two groups (`PORTAL/` under both V1
+  // and V2) is considered once.
+  const targets = new Map([[root, null]]);
+  for (const g of [...groups].sort()) {
+    for (const [key, segs] of docFolders(groupDir(manifest, g), g)) {
+      // `docFolders` guarantees at least one segment that is not '', '.' or
+      // '..', so this can never join back to `root` and displace its entry —
+      // which is how the root doc used to go missing. The guarantee lives
+      // there, with a test, rather than as an unreachable guard here.
+      targets.set(path.join(root, ...segs), key);
+    }
+  }
+
+  const written = [];
+  const kept = [];
+
+  for (const [dir, group] of targets) {
+    const src = templateFor(group);
+    if (!existsSync(src)) continue;
+
+    const dst = path.join(dir, 'CLAUDE.md');
+    if (existsSync(dst)) {
+      kept.push(dst);
+      continue;
+    }
+
+    mkdirSync(dir, { recursive: true });
+    copyFileSync(src, dst);
+    written.push(dst);
+  }
+
+  return { written, kept };
+}

package/src/git.js

@@ -0,0 +1,291 @@
+// Git plumbing. Everything shells out to the `git` binary with shell:false so
+// that repo names, branch names and Windows paths containing spaces are passed
+// through verbatim — no quoting rules to get wrong on cmd.exe vs bash.
+
+import { spawn } from 'node:child_process';
+import { existsSync, statSync, unlinkSync } from 'node:fs';
+import { availableParallelism } from 'node:os';
+import path from 'node:path';
+
+// Environment variables that point git at a specific repository, overriding
+// `cwd` completely. Git exports several of them into hooks, so a `talea`
+// command run from inside one — or from any wrapper that exports them — would
+// otherwise run every operation against the wrong repository. `adopt` decides
+// what to move from `git remote get-url origin`, so a leaked GIT_DIR makes 47
+// separate checkouts all report one remote and look like copies of each other.
+//
+// Cleared rather than trusted: `cwd` is the only thing that should select the
+// repository here.
+const REPO_SCOPING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+  'GIT_CEILING_DIRECTORIES',
+];
+
+/** process.env with anything that would redirect git away from `cwd` removed. */
+export function cleanGitEnv(base = process.env) {
+  const env = { ...base };
+  // Node omits a variable whose value is undefined when spawning.
+  for (const name of REPO_SCOPING_VARS) env[name] = undefined;
+  return env;
+}
+
+/**
+ * Run git and capture output. Never throws on a non-zero exit; callers decide
+ * what a failure means, which keeps "branch missing" from looking like a crash.
+ */
+export function git(args, { cwd, env, input } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('git', args, {
+      cwd,
+      shell: false,
+      env: {
+        ...cleanGitEnv(),
+        // Never let git stop mid-run waiting for credentials — a hung prompt
+        // across 47 repos is far worse than a clean per-repo failure.
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_ASKPASS: '',
+        ...env,
+      },
+      stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+    });
+
+    if (input != null) {
+      // A git that exits before reading all of stdin (or is missing) gives an
+      // EPIPE here; the exit code and stderr are the real signal, so swallow it.
+      child.stdin.on('error', () => {});
+      child.stdin.end(input);
+    }
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (err) =>
+      resolve({ code: -1, stdout: '', stderr: err.message }),
+    );
+    child.on('close', (code) =>
+      resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() }),
+    );
+  });
+}
+
+// Git writes `<ref>.lock` while it updates a ref and removes it when it is done.
+// A fetch that dies mid-write — Ctrl-C, a closed laptop, a killed pool worker —
+// leaves the lock behind, and every fetch afterwards fails with
+// "cannot lock ref … File exists" until a human deletes the file. Across 47
+// repos that is a permanent, self-inflicted failure, so clear the locks git
+// itself named in the error and run the command again.
+//
+// Age is the only safe test for "nobody owns this": a lock a live git holds is
+// at most seconds old, whether it is ours or another terminal's. Anything older
+// than a minute is debris. This never touches anything but a `.lock` file —
+// git forbids a ref name ending in `.lock`, so there is no repo content behind
+// that suffix.
+const STALE_LOCK_MS = 60_000;
+
+/** Absolute paths of the `*.lock` files quoted in a git error message. */
+function lockPathsIn(stderr, cwd) {
+  const quoted = String(stderr).matchAll(/'([^']*\.lock)'/g);
+  return [...new Set([...quoted].map((m) => path.resolve(cwd ?? process.cwd(), m[1])))];
+}
+
+/** Remove the locks git named that are too old to belong to a running git. */
+function clearStaleLocks(stderr, cwd) {
+  let cleared = 0;
+  for (const lock of lockPathsIn(stderr, cwd)) {
+    try {
+      if (Date.now() - statSync(lock).mtimeMs < STALE_LOCK_MS) continue;
+      unlinkSync(lock);
+      cleared++;
+    } catch {
+      // Already gone, or not ours to remove. The retry decides either way.
+    }
+  }
+  return cleared;
+}
+
+// The other way "cannot lock ref … File exists" happens, and no lock file on
+// disk explains it: macOS and Windows filesystems are case-insensitive, so two
+// branches on origin whose names differ only in case —
+// `INT-1203-on-UAT` and `INT-1203-on-Uat`, `optimize-CICD` and `optimize-cicd`
+// — are one path locally. `fetch --prune` locks the first, collides on the
+// second, and fails. Nothing is stale and waiting does not help: the pair can
+// never both exist as files, so every fetch fails until one of them is gone.
+//
+// Dropping the ref git named is the recovery, and this is the only place it is
+// safe: a `refs/remotes/` ref is a cache of origin that the same fetch rebuilds.
+// Nothing under `refs/heads/` or `refs/stash` is ever touched here.
+const CANNOT_LOCK = /cannot lock ref '(refs\/remotes\/[^']+)'/g;
+
+async function dropCollidingRefs(stderr, opts) {
+  // A lock file that is still on disk means a live git owns it — the age check
+  // above already declined to remove it, so do not go behind its back either.
+  if (lockPathsIn(stderr, opts?.cwd).some(existsSync)) return 0;
+
+  const named = new Set([...String(stderr).matchAll(CANNOT_LOCK)].map((m) => m[1]));
+  let dropped = 0;
+  for (const ref of named) {
+    const { code: exists } = await git(['show-ref', '--verify', '--quiet', ref], opts);
+    if (exists !== 0) continue; // already gone; not progress, so do not loop on it
+    const { code } = await git(['update-ref', '-d', ref], opts);
+    if (code === 0) dropped++;
+  }
+  return dropped;
+}
+
+/**
+ * Run git, healing the two ref-lock failures that a retry alone cannot fix:
+ * debris from a killed git, and a case-collision between two remote branches.
+ * Retries only while it is actually clearing something, so a genuine failure
+ * returns after the first run and a lock a live git holds is reported rather
+ * than stolen.
+ */
+async function unlocking(args, opts) {
+  let res = await git(args, opts);
+  // Git reports one collision per run, and a repo with years of branches can
+  // have several, so the cap is per-repo patience rather than per-failure.
+  for (let i = 0; i < 10 && res.code !== 0; i++) {
+    const healed =
+      clearStaleLocks(res.stderr, opts?.cwd) || (await dropCollidingRefs(res.stderr, opts));
+    if (!healed) break;
+    res = await git(args, opts);
+  }
+  return res;
+}
+
+/**
+ * Origin is gone, renamed, or this account was never granted it. Neither a
+ * retry nor anything the developer can do at their keyboard fixes it, so bulk
+ * commands report it and move on instead of failing the whole run.
+ */
+export const isMissingRemote = (stderr) =>
+  /TF401019|repository not found|does not exist or you do not have permission/i.test(
+    String(stderr),
+  );
+
+export const isRepo = (dir) => existsSync(path.join(dir, '.git'));
+
+export async function gitVersion() {
+  const { code, stdout } = await git(['--version']);
+  return code === 0 ? stdout.replace('git version ', '') : null;
+}
+
+export async function currentBranch(dir) {
+  const { code, stdout } = await git(['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: dir,
+  });
+  return code === 0 ? stdout : null;
+}
+
+/** True when the working tree has uncommitted changes (tracked or untracked). */
+export async function isDirty(dir) {
+  const { code, stdout } = await git(['status', '--porcelain'], { cwd: dir });
+  return code === 0 && stdout.length > 0;
+}
+
+/** Commits ahead of / behind the upstream, or null when there is no upstream. */
+export async function aheadBehind(dir) {
+  const { code, stdout } = await git(
+    ['rev-list', '--left-right', '--count', '@{upstream}...HEAD'],
+    { cwd: dir },
+  );
+  if (code !== 0) return null;
+  const [behind, ahead] = stdout.split(/\s+/).map(Number);
+  return { ahead, behind };
+}
+
+/** Does `branch` exist on the remote? Uses the local remote-tracking refs. */
+export async function remoteHasBranch(dir, branch) {
+  const { code } = await git(
+    ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${branch}`],
+    { cwd: dir },
+  );
+  return code === 0;
+}
+
+export async function localHasBranch(dir, branch) {
+  const { code } = await git(
+    ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`],
+    { cwd: dir },
+  );
+  return code === 0;
+}
+
+export const fetch = (dir) => unlocking(['fetch', '--prune', 'origin'], { cwd: dir });
+
+/**
+ * Check out `branch`, creating it from origin/<branch> on first use.
+ * Assumes the caller has already fetched and confirmed the branch exists.
+ */
+export async function checkout(dir, branch) {
+  if (await localHasBranch(dir, branch)) {
+    return unlocking(['checkout', branch], { cwd: dir });
+  }
+  return unlocking(['checkout', '-b', branch, '--track', `origin/${branch}`], {
+    cwd: dir,
+  });
+}
+
+/**
+ * Fast-forward the current branch onto its already-fetched upstream.
+ *
+ * Fast-forward only: a merge commit invented across 47 repos is the kind of
+ * history nobody can unpick afterwards, so a diverged branch fails loudly.
+ *
+ * This is deliberately `merge`, not `pull`. Every caller fetches first, and
+ * `git pull` fetches *again* — one extra network round-trip per repo, which
+ * over 47 repos on a VPN was most of the wall-clock time `talea sync` spent.
+ * Merging the ref that fetch just updated does the same work with one.
+ */
+export const ffMerge = (dir) =>
+  unlocking(['merge', '--ff-only', '@{upstream}'], { cwd: dir });
+
+/** Does the current branch track anything? `ffMerge` has nothing to do if not. */
+export async function hasUpstream(dir) {
+  const { code } = await git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
+    cwd: dir,
+  });
+  return code === 0;
+}
+
+export const stashPush = (dir, message) =>
+  git(['stash', 'push', '--include-untracked', '-m', message], { cwd: dir });
+
+export const clone = (url, dest, branch) =>
+  git(['clone', ...(branch ? ['--branch', branch] : []), '--', url, dest]);
+
+/**
+ * How many git operations run at once when `-j` is not given.
+ *
+ * This work is network-bound, not CPU-bound, so the core count is a proxy for
+ * "how big is this machine" rather than a real limit — but it beats the flat 6
+ * this used to be, which left a modern laptop idle for most of a clone. Capped
+ * at 12 because the far end is one SSH server and 47 simultaneous sessions is
+ * how you get throttled; floored at 6 so it never runs slower than it used to.
+ */
+export const defaultJobs = () => Math.min(12, Math.max(6, availableParallelism()));
+
+/**
+ * Run `tasks` with a bounded number in flight. Cloning 47 repos serially is
+ * slow; cloning them all at once saturates the network and the SSH server.
+ */
+export async function pooled(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await worker(items[i], i);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}