polyrepo-cli 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "polyrepo-cli",
+  "version": "1.0.0",
+  "description": "Interactive CLI for managing a folder of local npm package repos: version bumps through a PR, npm publish, GitHub releases, and cross-package dependency drift checks — all from one tool.",
+  "type": "module",
+  "bin": {
+    "polyrepo": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "cli",
+    "polyrepo",
+    "monorepo",
+    "multi-repo",
+    "npm",
+    "release",
+    "version-bump",
+    "github-release",
+    "changelog"
+  ],
+  "author": {
+    "name": "Danil Lisin Vladimirovich (Macrulez)",
+    "email": "macrulezru@gmail.com",
+    "url": "https://macrulez.ru/en"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/macrulezru/polyrepo-cli.git"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.1",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "semver": "^7.8.5"
+  }
+}

package/polyrepo.config.example.json

@@ -0,0 +1,4 @@
+{
+  "roots": ["/path/to/folder-of-repos"],
+  "packages": ["/path/to/a-single-repo"]
+}

package/src/changelog.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function changelogPath(repo) {
+  return path.join(repo.path, 'CHANGELOG.md')
+}
+
+export function hasChangelog(repo) {
+  return fs.existsSync(changelogPath(repo))
+}
+
+function todayISO() {
+  return new Date().toISOString().slice(0, 10)
+}
+
+// Inserts a "## [x.y.z] - YYYY-MM-DD" entry into an existing Keep a
+// Changelog-style CHANGELOG.md, as the new most-recent release:
+//   - right after "## [Unreleased]" if the file has one (so Unreleased
+//     stays in place, empty, at the top)
+//   - otherwise right before the first existing "## " version heading
+//   - otherwise (no version headings at all) appended at the end
+// `commitLines` (from changes.js's fullCommitLinesSince) seeds a "###
+// Changed" section as a draft — merge-commit noise filtered out, but this
+// is a starting point to review and edit, not a finished changelog. Only
+// ever called when hasChangelog() is already true — packages without one
+// are left alone rather than having a CHANGELOG.md invented for them.
+export function addChangelogEntry(repo, version, commitLines) {
+  const filePath = changelogPath(repo)
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n')
+
+  const bullets = commitLines
+    .map((l) => l.replace(/^[0-9a-f]+\s+/, '').trim())
+    .filter((l) => l && !/^Merge (pull request|branch)\b/i.test(l))
+    .map((l) => `- ${l}`)
+
+  const entry = [`## [${version}] - ${todayISO()}`, '']
+  if (bullets.length > 0) entry.push('### Changed', '', ...bullets, '')
+
+  const unreleasedIndex = lines.findIndex((l) => /^## \[Unreleased\]/i.test(l))
+  const searchStart = unreleasedIndex === -1 ? 0 : unreleasedIndex + 1
+
+  let insertAt = -1
+  for (let i = searchStart; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) {
+      insertAt = i
+      break
+    }
+  }
+
+  const before = insertAt === -1 ? lines : lines.slice(0, insertAt)
+  const after = insertAt === -1 ? [] : lines.slice(insertAt)
+  const updated = [...before, ...entry, ...after].join('\n')
+
+  fs.writeFileSync(filePath, updated.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n')
+}
+
+// Pulls just the body of one version's section back out — used by `polyrepo
+// release` to seed GitHub Release notes from the changelog instead of
+// gh's own --generate-notes when a CHANGELOG.md entry already exists for
+// that version. Returns null if there's no changelog, no matching heading,
+// or the section is empty.
+export function extractChangelogSection(repo, version) {
+  if (!hasChangelog(repo)) return null
+  const lines = fs.readFileSync(changelogPath(repo), 'utf8').split('\n')
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const headingIndex = lines.findIndex((l) => new RegExp(`^## \\[${escaped}\\]`).test(l))
+  if (headingIndex === -1) return null
+
+  let end = lines.length
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) {
+      end = i
+      break
+    }
+  }
+  const section = lines
+    .slice(headingIndex + 1, end)
+    .join('\n')
+    .trim()
+  return section || null
+}

package/src/changes.js

@@ -0,0 +1,55 @@
+import { MASTER_BRANCH } from './config.js'
+import { git, gitAsync } from './exec.js'
+import { pMap } from './pMap.js'
+
+const PREVIEW_LIMIT = 5
+
+// Summarizes what changed on local master since the last `v*` tag (or the
+// last few commits if there's no tag yet), so the bump checklist can show
+// whether a package actually has anything worth releasing. Reflects local
+// repo state — run `polyrepo switch-master` first if it might be stale. Run
+// through pMap across many repos at once (see describeRecentChangesForAll)
+// — this builds the bump checkbox's preview, and waiting on 3 sequential
+// git calls per repo, 17 times over, added up to a real pause before the
+// prompt even appeared.
+async function describeRecentChangesAsync(repo) {
+  const tagResult = await gitAsync(repo.path, ['describe', '--tags', '--abbrev=0', '--match', 'v*', MASTER_BRANCH])
+  const sinceTag = tagResult.ok ? tagResult.stdout : null
+  const range = sinceTag ? `${sinceTag}..${MASTER_BRANCH}` : MASTER_BRANCH
+
+  const [countResult, logResult] = await Promise.all([
+    gitAsync(repo.path, ['rev-list', '--count', range]),
+    gitAsync(repo.path, ['log', range, '--oneline', '--no-decorate', '-n', String(PREVIEW_LIMIT)]),
+  ])
+  const count = countResult.ok ? Number(countResult.stdout) : 0
+  const lines = logResult.ok && logResult.stdout ? logResult.stdout.split('\n') : []
+
+  return { sinceTag, count, lines, truncated: count > lines.length }
+}
+
+export function describeRecentChangesForAll(repos, concurrency) {
+  return pMap(repos, describeRecentChangesAsync, concurrency)
+}
+
+// Uncapped commit list from the last `v*` tag to HEAD — used right before
+// committing a version bump (see bump.js) to draft a CHANGELOG.md entry, so
+// unlike describeRecentChanges (capped for a preview) this needs the whole
+// list. Uses HEAD rather than MASTER_BRANCH because it's called from
+// exactly where that matters: after checking out the bump branch, whose
+// HEAD is master's tip at that point anyway.
+export function fullCommitLinesSince(repo) {
+  const tagResult = git(repo.path, ['describe', '--tags', '--abbrev=0', '--match', 'v*', 'HEAD'], { quiet: true })
+  const sinceTag = tagResult.ok ? tagResult.stdout : null
+  const range = sinceTag ? `${sinceTag}..HEAD` : 'HEAD'
+  const logResult = git(repo.path, ['log', range, '--oneline', '--no-decorate'], { quiet: true })
+  return logResult.ok && logResult.stdout ? logResult.stdout.split('\n').filter(Boolean) : []
+}
+
+export function formatRecentChanges({ sinceTag, count, lines, truncated }) {
+  const header = sinceTag
+    ? `${count} commit${count === 1 ? '' : 's'} since ${sinceTag}`
+    : `${count} commit${count === 1 ? '' : 's'} (no tags yet)`
+  if (count === 0) return header
+  const body = lines.map((l) => `  ${l}`).join('\n')
+  return `${header}:\n${body}${truncated ? '\n  …' : ''}`
+}

package/src/ciChecks.js

@@ -0,0 +1,26 @@
+import { gh } from './exec.js'
+
+// Blocks until a PR's CI checks finish, so `bump --wait-checks` doesn't
+// merge on top of a red build. Two steps rather than one:
+//   1. A quick, quiet probe (no --watch) to see whether the PR has any
+//      checks reported at all — most of these repos don't have CI wired up
+//      yet, and "no checks configured" isn't a reason to refuse merging.
+//   2. Only if checks exist: the real wait, using gh's own `--watch`
+//      (rather than hand-rolled polling) with a real terminal so its live
+//      updating table actually renders instead of arriving all at once
+//      when it's done.
+export function waitForChecks(repo, prNumber) {
+  const probe = gh(repo.path, ['pr', 'checks', String(prNumber), '--json', 'bucket'], { quiet: true })
+  if (!probe.ok || !probe.stdout || probe.stdout === '[]') {
+    return { ok: true, skipped: true }
+  }
+
+  const watched = gh(repo.path, ['pr', 'checks', String(prNumber), '--watch', '--interval', '10'], {
+    interactive: true,
+  })
+  if (watched.ok) return { ok: true, skipped: false }
+  return {
+    ok: false,
+    message: `CI checks failed for PR #${prNumber} — not merging. Run \`gh pr checks ${prNumber}\` for details.`,
+  }
+}

package/src/commands/bump.js

@@ -0,0 +1,245 @@
+import fs from 'node:fs'
+import { confirm } from '@inquirer/prompts'
+import pc from 'picocolors'
+import { discoverRepos, inspectRepos, readPackageJson } from '../repos.js'
+import { MASTER_BRANCH, bumpBranchName } from '../config.js'
+import { loadConfig } from '../loadConfig.js'
+import { bumpVersion, replaceVersionInText } from '../version.js'
+import { git } from '../exec.js'
+import { syncMaster } from '../masterSync.js'
+import { detectBumpState, createPr, mergePr } from '../github.js'
+import { tagName, tagExists, createAndPushTag } from '../tags.js'
+import { describeRecentChangesForAll, formatRecentChanges, fullCommitLinesSince } from '../changes.js'
+import { hasChangelog, addChangelogEntry } from '../changelog.js'
+import { waitForChecks } from '../ciChecks.js'
+import { findStaleLocalDeps } from '../crossDeps.js'
+import { heading, stepHeading, ok, fail, warn, columnWidths, formatRow } from '../ui.js'
+import { selectPackages } from '../selectPackages.js'
+import { startSpinner } from '../spinner.js'
+
+export async function bumpCommand({
+  dryRun = false,
+  configPath,
+  packages, // string[] of dir names — skips the checkbox when given
+  yes = false, // skip the "proceed?" confirmation
+  waitChecks = false, // wait for CI checks (if any) before merging each PR
+  bumpType = 'patch', // 'patch' | 'minor' | 'major'
+} = {}) {
+  const config = loadConfig({ configPath })
+  const discovered = discoverRepos(config)
+  if (discovered.length === 0) {
+    console.log(pc.yellow('No repos found.'))
+    return
+  }
+
+  heading(`Bump version (${bumpType})`)
+
+  const scanSpinner = startSpinner(`Checking ${discovered.length} package(s)...`)
+  const allRepos = await inspectRepos(discovered)
+  scanSpinner.stop()
+
+  const repos = allRepos.filter((r) => r.version)
+  if (repos.length === 0) {
+    console.log(pc.yellow('No repos found.'))
+    return
+  }
+
+  const withTarget = repos.map((r) => ({ ...r, newVersion: bumpVersion(r.version, bumpType) }))
+
+  // Only worth computing when the checkbox is actually going to be shown —
+  // a --packages run never displays it, so skip the (parallel, but still
+  // real) work of asking every repo for its git log.
+  let withPreview = withTarget
+  if (!packages) {
+    const previewSpinner = startSpinner(`Checking what changed since the last tag for ${withTarget.length} package(s)...`)
+    const changesList = await describeRecentChangesForAll(withTarget)
+    previewSpinner.stop()
+    withPreview = withTarget.map((r, i) => ({ ...r, changes: changesList[i] }))
+  }
+
+  const selected = await selectPackages({
+    items: withPreview,
+    packages,
+    message: `Pick packages to bump (${bumpType}):`,
+    buildChoice: (all) => {
+      const columns = [
+        { value: (r) => r.dir },
+        { value: (r) => r.version, style: (r, t) => pc.dim(t) },
+        { value: () => '→', style: (r, t) => pc.dim(t) },
+        { value: (r) => r.newVersion, style: (r, t) => pc.green(t) },
+      ]
+      const widths = columnWidths(all, columns)
+      return (r) => ({
+        name: formatRow(r, columns, widths) + (r.clean ? '' : pc.red('  (dirty, will be skipped)')),
+        description: formatRecentChanges(r.changes),
+        value: r,
+      })
+    },
+  })
+
+  if (selected.length === 0) {
+    console.log(pc.dim('Nothing selected.'))
+    return
+  }
+
+  if (!yes) {
+    const proceed = await confirm({
+      message: `Bump ${selected.length} package(s), open a PR, and merge each into ${MASTER_BRANCH}?${
+        dryRun ? ' (dry run — no changes will actually be pushed)' : ''
+      }`,
+      default: true,
+    })
+    if (!proceed) {
+      console.log(pc.dim('Cancelled.'))
+      return
+    }
+  }
+
+  let index = 0
+  for (const repo of selected) {
+    index += 1
+    stepHeading(index, selected.length, `${repo.dir}  ${repo.version} → ${repo.newVersion}`)
+    await bumpOne(repo, { dryRun, waitChecks })
+  }
+
+  if (!dryRun) await reportStaleLocalDeps(config)
+}
+
+async function bumpOne(repo, { dryRun, waitChecks }) {
+  if (!repo.clean) {
+    warn('Working tree is dirty — skipping to avoid committing unrelated changes.')
+    return
+  }
+
+  const syncResult = syncMaster(repo)
+  if (!syncResult.ok) return fail(syncResult.message)
+  ok(`${MASTER_BRANCH} is up to date.`)
+
+  const branchName = bumpBranchName(repo.newVersion)
+  const state = detectBumpState(repo, branchName)
+
+  if (dryRun) {
+    if (state.status === 'merged') {
+      ok(`[dry-run] Already merged as PR #${state.pr.number} — would only ensure the tag exists.`)
+    } else {
+      const verb = state.status === 'fresh' ? 'create' : 'reuse'
+      const prVerb = state.status === 'open' ? `merge existing PR #${state.pr.number}` : 'open + merge a PR'
+      const waitNote = waitChecks ? ', waiting for CI checks first' : ''
+      console.log(
+        pc.magenta(
+          `  [dry-run] would ${verb} branch ${branchName}, ensure version ${repo.newVersion} (+ a CHANGELOG.md entry if one exists), commit/push if needed, then ${prVerb}${waitNote}, then tag ${tagName(repo.newVersion)}.`,
+        ),
+      )
+    }
+    return
+  }
+
+  let prNumber = state.status === 'merged' || state.status === 'open' ? state.pr.number : null
+
+  if (state.status !== 'merged') {
+    if (state.status === 'open') ok(`Found existing open PR #${state.pr.number} for ${branchName} — reusing it.`)
+    if (state.status === 'branch') ok(`Found existing branch ${branchName} on origin without a PR — reusing it.`)
+
+    const checkoutResult = checkoutBumpBranch(repo, branchName)
+    if (!checkoutResult.ok) return fail(`Could not check out branch ${branchName}.`)
+    ok(checkoutResult.reused ? `Reusing branch ${branchName}.` : `Created branch ${branchName}.`)
+
+    const onDiskVersion = readPackageJson(repo).version
+    if (onDiskVersion !== repo.newVersion) {
+      const text = fs.readFileSync(repo.pkgPath, 'utf8')
+      fs.writeFileSync(repo.pkgPath, replaceVersionInText(text, repo.newVersion))
+      if (!git(repo.path, ['add', 'package.json']).ok) return fail('git add failed.')
+
+      if (hasChangelog(repo)) {
+        addChangelogEntry(repo, repo.newVersion, fullCommitLinesSince(repo))
+        if (git(repo.path, ['add', 'CHANGELOG.md']).ok) {
+          ok('Drafted a CHANGELOG.md entry — review it before merging if you want it polished.')
+        } else {
+          warn('Wrote a CHANGELOG.md entry but `git add` failed — it will stay as an uncommitted local change.')
+        }
+      }
+
+      if (!git(repo.path, ['commit', '-m', `chore: bump version to ${repo.newVersion}`]).ok) {
+        return fail('git commit failed.')
+      }
+      ok(`package.json version set to ${repo.newVersion} and committed.`)
+    } else {
+      ok(`package.json on ${branchName} is already at ${repo.newVersion} — nothing to commit.`)
+    }
+
+    if (!git(repo.path, ['push', '-u', 'origin', branchName]).ok) return fail('git push failed.')
+    ok('Branch pushed (or already up to date on origin).')
+
+    if (state.status !== 'open') {
+      const prResult = createPr(repo, {
+        base: MASTER_BRANCH,
+        branch: branchName,
+        title: `chore: bump version to ${repo.newVersion}`,
+        body: `Bump version: ${repo.version} → ${repo.newVersion}.`,
+      })
+      if (!prResult.ok) return fail(prResult.message ?? 'gh pr create failed.')
+      prNumber = prResult.number
+      ok(`Opened PR #${prNumber}.`)
+    }
+
+    if (waitChecks) {
+      const checksResult = waitForChecks(repo, prNumber)
+      if (!checksResult.ok) return fail(checksResult.message)
+      ok(checksResult.skipped ? 'No CI checks reported — nothing to wait for.' : 'CI checks passed.')
+    }
+
+    if (!mergePr(repo, prNumber).ok) {
+      return fail(`gh pr merge failed — PR #${prNumber} is still open, merge it manually.`)
+    }
+    ok(`Merged PR #${prNumber}.`)
+
+    const resyncResult = syncMaster(repo)
+    if (!resyncResult.ok) return fail(resyncResult.message)
+    ok(`Local ${MASTER_BRANCH} synced to origin at ${repo.newVersion}.`)
+  } else {
+    ok(`Already merged as PR #${state.pr.number} — ${MASTER_BRANCH} already has it.`)
+  }
+
+  const tag = tagName(repo.newVersion)
+  if (tagExists(repo, tag)) {
+    ok(`Tag ${tag} already exists on origin.`)
+  } else {
+    const tagResult = createAndPushTag(repo, tag)
+    if (!tagResult.ok) fail(tagResult.message)
+    else ok(`Tagged and pushed ${tag}.`)
+  }
+}
+
+// Reuse a local branch left over from a previous attempt if there is one,
+// otherwise track the remote branch if a previous attempt got as far as
+// pushing it, otherwise create it fresh from the current (just-synced)
+// master. Trying "reuse" first before falling back is what makes this safe
+// to call again after any partial failure without any state bookkeeping.
+function checkoutBumpBranch(repo, branchName) {
+  if (git(repo.path, ['checkout', branchName], { quiet: true }).ok) {
+    return { ok: true, reused: true }
+  }
+
+  git(repo.path, ['fetch', 'origin', branchName], { quiet: true })
+  if (git(repo.path, ['checkout', '-b', branchName, `origin/${branchName}`], { quiet: true }).ok) {
+    return { ok: true, reused: true }
+  }
+
+  return { ok: git(repo.path, ['checkout', '-b', branchName]).ok, reused: false }
+}
+
+// One last look across every package (not just the ones just bumped) once
+// the run is done — a bump can leave some other local package's
+// dependencies/peerDependencies/devDependencies pointing at a range that no
+// longer matches, and nothing else would surface that.
+async function reportStaleLocalDeps(config) {
+  const repos = (await inspectRepos(discoverRepos(config))).filter((r) => r.version)
+  const issues = findStaleLocalDeps(repos)
+  if (issues.length === 0) return
+  heading('Stale local dependency references')
+  for (const issue of issues) {
+    warn(
+      `${issue.repo.dir}: depends on "${issue.depName}" via "${issue.range}", which does not match the local version ${issue.localVersion}.`,
+    )
+  }
+}

package/src/commands/clone.js

@@ -0,0 +1,102 @@
+import path from 'node:path'
+import { confirm } from '@inquirer/prompts'
+import pc from 'picocolors'
+import { discoverRepos } from '../repos.js'
+import { loadConfig } from '../loadConfig.js'
+import { gh, git } from '../exec.js'
+import { selectPackages } from '../selectPackages.js'
+import { heading, stepHeading, ok, fail, columnWidths, formatRow } from '../ui.js'
+
+// Diffs a GitHub org/user's repo list against what's already present under
+// one root directory, then clones whatever's missing. `--org` is taken
+// per-invocation rather than stored in polyrepo.config.json — the config's
+// roots/packages are about *where local repos live*, not which GitHub
+// account they come from, and one root can plausibly mix repos from
+// several accounts.
+export async function cloneCommand({
+  configPath,
+  org,
+  root,
+  includeArchived = false,
+  packages,
+  yes = false,
+  dryRun = false,
+} = {}) {
+  const config = loadConfig({ configPath })
+  const targetRoot = root ? path.resolve(root) : config.roots[0]
+  if (!targetRoot) {
+    console.log(pc.red('No root to clone into — pass --root, or run `polyrepo setup` to add one first.'))
+    return
+  }
+
+  heading(`Clone missing repos from ${org}`)
+  console.log(pc.dim(`Target root: ${targetRoot}`))
+
+  const listResult = gh('.', ['repo', 'list', org, '--limit', '200', '--json', 'name,url,isArchived'], {
+    quiet: true,
+  })
+  if (!listResult.ok) {
+    fail(`Could not list repos for "${org}" — is \`gh\` authenticated and the name correct?`)
+    return
+  }
+
+  let remoteRepos
+  try {
+    remoteRepos = JSON.parse(listResult.stdout)
+  } catch {
+    fail('Could not parse `gh repo list` output.')
+    return
+  }
+
+  if (!includeArchived) remoteRepos = remoteRepos.filter((r) => !r.isArchived)
+
+  const existing = new Set(discoverRepos({ roots: [targetRoot], packages: [] }).map((r) => r.dir.toLowerCase()))
+  const missing = remoteRepos.filter((r) => !existing.has(r.name.toLowerCase()))
+
+  if (missing.length === 0) {
+    console.log(pc.green(`Nothing to clone — every repo in ${org} already exists under ${targetRoot}.`))
+    return
+  }
+
+  const selected = await selectPackages({
+    items: missing.map((r) => ({ dir: r.name, url: r.url })),
+    packages,
+    message: `Pick repos to clone into ${targetRoot}:`,
+    buildChoice: (all) => {
+      const columns = [{ value: (r) => r.dir }]
+      const widths = columnWidths(all, columns)
+      return (r) => ({ name: formatRow(r, columns, widths), value: r, checked: true })
+    },
+  })
+
+  if (selected.length === 0) {
+    console.log(pc.dim('Nothing selected.'))
+    return
+  }
+
+  if (!yes) {
+    const proceed = await confirm({
+      message: `Clone ${selected.length} repo(s) into ${targetRoot}?${dryRun ? ' (dry run — nothing will actually be cloned)' : ''}`,
+      default: true,
+    })
+    if (!proceed) {
+      console.log(pc.dim('Cancelled.'))
+      return
+    }
+  }
+
+  let index = 0
+  for (const repo of selected) {
+    index += 1
+    stepHeading(index, selected.length, repo.dir)
+    const dest = path.join(targetRoot, repo.dir)
+    const result = git('.', ['clone', repo.url, dest], { mutating: true, dryRun })
+    if (!result.ok) fail(`git clone failed (exit ${result.status}).`)
+    else ok(dryRun ? `Would clone into ${dest}.` : `Cloned into ${dest}.`)
+  }
+
+  if (!dryRun && !config.roots.some((r) => path.resolve(r).toLowerCase() === targetRoot.toLowerCase())) {
+    console.log('')
+    console.log(pc.yellow(`Tip: ${targetRoot} isn't in your config yet — run \`polyrepo setup\` to add it as a root.`))
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,100 @@
+import pc from 'picocolors'
+import { discoverRepos, inspectRepos } from '../repos.js'
+import { loadConfig } from '../loadConfig.js'
+import { run } from '../exec.js'
+import { findStaleLocalDeps } from '../crossDeps.js'
+import { heading, ok, fail, warn } from '../ui.js'
+import { startSpinner } from '../spinner.js'
+
+export async function doctorCommand({ configPath } = {}) {
+  heading('Environment')
+  checkNode()
+  checkGit()
+  checkGh()
+  checkNpm()
+
+  heading('Config')
+  const config = loadConfig({ configPath })
+  console.log(pc.dim(`Config file: ${config.configPath}`))
+  const discovered = discoverRepos(config)
+  const spinner = startSpinner(`Checking ${discovered.length} package(s)...`)
+  const repos = await inspectRepos(discovered)
+  spinner.stop()
+  if (repos.length === 0) {
+    fail('No packages discovered — check `polyrepo setup`.')
+  } else {
+    ok(`${repos.length} package(s) discovered.`)
+    const dirty = repos.filter((r) => !r.clean)
+    if (dirty.length > 0) {
+      warn(`${dirty.length} repo(s) have uncommitted changes: ${dirty.map((r) => r.dir).join(', ')}`)
+    }
+    const offMaster = repos.filter((r) => r.branch !== 'master')
+    if (offMaster.length > 0) {
+      warn(`${offMaster.length} repo(s) are not on master: ${offMaster.map((r) => r.dir).join(', ')}`)
+    }
+  }
+
+  heading('Cross-package dependencies')
+  if (repos.length > 0) {
+    const issues = findStaleLocalDeps(repos)
+    if (issues.length === 0) {
+      ok('No stale local dependency references found.')
+    } else {
+      for (const issue of issues) {
+        warn(
+          `${issue.repo.dir}: depends on "${issue.depName}" via "${issue.range}", which does not match the local version ${issue.localVersion}.`,
+        )
+      }
+    }
+  } else {
+    console.log(pc.dim('Skipped — no packages discovered.'))
+  }
+}
+
+function checkNode() {
+  const [major] = process.versions.node.split('.').map(Number)
+  if (major >= 20) {
+    ok(`Node.js ${process.version} (>= 20 required).`)
+  } else {
+    fail(`Node.js ${process.version} — this CLI needs 20 or newer.`)
+  }
+}
+
+function checkGit() {
+  const result = run('.', 'git', ['--version'], { quiet: true })
+  if (result.ok) {
+    ok(`${result.stdout}.`)
+  } else {
+    fail('git not found in PATH — required for every command, including this one.')
+  }
+}
+
+function checkGh() {
+  const version = run('.', 'gh', ['--version'], { quiet: true })
+  if (!version.ok) {
+    fail('gh (GitHub CLI) not found in PATH — required for `bump`, `release`, and PR merges. https://cli.github.com/')
+    return
+  }
+  const versionLine = version.stdout.split('\n')[0]
+  const auth = run('.', 'gh', ['auth', 'status'], { quiet: true })
+  if (auth.ok) {
+    const who = (auth.stdout + auth.stderr).match(/Logged in to [^\s]+ account (\S+)/)
+    ok(`${versionLine}${who ? ` — authenticated as ${who[1]}` : ' — authenticated'}.`)
+  } else {
+    fail(`${versionLine} — not authenticated. Run \`gh auth login\`.`)
+  }
+}
+
+function checkNpm() {
+  const version = run('.', 'npm', ['--version'], { quiet: true })
+  if (!version.ok) {
+    fail('npm not found in PATH — required only for `polyrepo publish`.')
+    return
+  }
+  const who = run('.', 'npm', ['whoami'], { quiet: true })
+  if (who.ok) {
+    ok(`npm ${version.stdout} — authenticated as ${who.stdout}.`)
+  } else {
+    warn(`npm ${version.stdout} — not authenticated (only needed for \`polyrepo publish\`). Run \`npm login\`.`)
+  }
+}