rvlib-shipkit 1.0.1 → 1.1.0

package/src/core/package-manager.ts

@@ -70,9 +70,11 @@ export function trackedLocks(root: string): string[] {
 }
 
 /** the manager this repo installs with, read off its lock files */
-export function detectPackageManager(root: string, tracked: string[] = trackedLocks(root)): PackageManagerPick {
+export function detectPackageManager(root: string, tracked?: string[]): PackageManagerPick {
     const present = LOCK_FILES.filter((f) => existsSync(join(root, f)))
-    const owned = present.filter((f) => tracked.includes(f))
+    // git is asked which locks it tracks only when there is a lock to ask about
+    const known = present.length === 0 ? [] : (tracked ?? trackedLocks(root))
+    const owned = present.filter((f) => known.includes(f))
     const locks = owned.length > 0 ? owned : present
     const managers = [
         ...(locks.some((f) => BUN_LOCKS.includes(f)) ? [bun] : []),

package/src/core/raw-access.ts

@@ -72,17 +72,25 @@ function scanSource(src: string, o: ClosureKind): { line: number; what: string }
  *  scanned, and neither is `skip`, the toolkit's own tree when it sits inside
  *  the repo: the toolchain id covers it exactly as it covers an install.
  *  Throws when the closure cannot be walked, which the caller counts as a hit */
-export function rawAccessInClosure(root: string, file: string, o: { skip?: string; configs?: Map<string, RvtConfig> } & ClosureKind = {}): RawAccess | null {
+export function rawAccessInClosure(root: string, file: string, o: { skip?: string; configs?: Map<string, RvtConfig>; texts?: Map<string, string> } & ClosureKind = {}): RawAccess | null {
     // one pass over many checks under one root hands in `configs`, so the
     // root's config (a walk of its source tree) is read once for all of them
     let loaded = o.configs?.get(root)
     if (loaded == null) { loaded = loadConfig(root); o.configs?.set(root, loaded) }
     const cfg = { ...loaded, root }
     const skipped = (f: string): boolean => f.split('/').includes('node_modules') || (o.skip != null && join(root, f).startsWith(`${o.skip}/`))
-    const files = importClosure(cfg, [relative(root, file).replace(/\\/g, '/')], o).filter((f) => !skipped(f))
+    // one pass over many checks hands in `texts` too: their closures share
+    // most of their files, and each is read once for the whole pass
+    const read = (rel: string): string => {
+        const p = join(root, rel)
+        let text = o.texts?.get(p)
+        if (text == null) { text = readFileSync(p, 'utf8'); o.texts?.set(p, text) }
+        return text
+    }
+    const files = importClosure(cfg, [relative(root, file).replace(/\\/g, '/')], { ...o, read }).filter((f) => !skipped(f))
     for (const f of files) {
         let src: string
-        try { src = readFileSync(join(root, f), 'utf8') } catch { continue }
+        try { src = read(f) } catch { continue }
         const hit = rawAccessInSource(src, o)
         if (hit != null) return { file: f, ...hit }
     }

package/src/core/reexec.ts

@@ -0,0 +1,26 @@
+// run this exact invocation again, on whatever code is on disk now. execve
+// replaces the image in place: same pid, same terminal, same argv (so the
+// same flags and the same port), and a `--watch` flag stays in execArgv. A
+// runtime without execve runs the invocation as a child and exits with its
+// code, which keeps the terminal but leaves this process waiting under it.
+import { existsSync } from 'fs'
+
+const argvOf = (): string[] => [process.execPath, ...process.execArgv, ...process.argv.slice(1)]
+
+/** why this invocation cannot run again, null when it can. Asked BEFORE a
+ *  caller tears anything down, so a refusal leaves the process serving */
+export function reexecBlocker(): string | null {
+    const entry = process.argv[1]
+    if (entry != null && entry !== '' && !entry.startsWith('-') && /\.[cm]?[jt]sx?$/.test(entry) && !existsSync(entry)) return `its entry file ${entry} is gone`
+    return null
+}
+
+/** never returns. `env` defaults to this process's own */
+export function reexecSelf(env: Record<string, string | undefined> = process.env): never {
+    const argv = argvOf()
+    const clean = Object.fromEntries(Object.entries(env).filter((e): e is [string, string] => e[1] != null))
+    const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
+    if (typeof execve === 'function') execve.call(process, process.execPath, argv, clean)
+    const child = Bun.spawnSync(argv, { cwd: process.cwd(), stdout: 'inherit', stderr: 'inherit', stdin: 'inherit', env: clean })
+    process.exit(child.exitCode ?? 1)
+}

package/src/core/run-check.ts

@@ -14,10 +14,11 @@ import { Ledger } from '../ledger/ledger.ts'
 import { RunLog, type InvokedBy } from '../ledger/run-log.ts'
 import { storeRoot } from '../ledger/store.ts'
 import { gateBinary } from '../ledger/toolchain-identity.ts'
-import { runChecks, type Audience, type CheckEvent, type CheckResult } from './check-runner.ts'
+import { runChecks, selectChecks, type Audience, type CheckEvent, type CheckResult, type RunnableCheck } from './check-runner.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { unknownWhenIds } from './when.ts'
+import { unknownBudgetIds } from './budget.ts'
 import { formatLine, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
 import { CHECK_TABLE_FILE, writeCheckTable } from '../ledger/check-table.ts'
@@ -106,12 +107,37 @@ export type CheckRun = {
     /** `when` entries naming no check of this repo — a toggle that does
      *  nothing is worse than none, so it is fatal too */
     unknownWhen: string[]
+    /** `budgets` entries naming no check of this repo, fatal for the same reason */
+    unknownBudgets: string[]
     /** what every asked-for check did, in declaration order */
     results: CheckResult[]
     /** the run was interrupted or bailed out */
     interrupted: boolean
 }
 
+/** what the runner selects from, built from the pass options in ONE place: the
+ *  ledger is scoped on the same selection the runner then makes */
+function selectionOf(checks: RunnableCheck[], o: CheckOpts, tier: TestTier) {
+    return {
+        checks,
+        audience: o.audience ?? 'health',
+        fullTier: tier === 'full',
+        skipGroups: o.skipGroups,
+        onlyIds: o.only,
+        withIds: o.withIds,
+        onlyBlocking: o.onlyBlocking,
+        buildOnly: o.buildOnly,
+        includeProactive: o.includeProactive,
+        exclude: o.exclude,
+    } satisfies Parameters<typeof selectChecks>[0]
+}
+
+/** the ids a pass with these options executes: the scope its ledger scans for */
+export function passScope(composed: GateCheck[], o: CheckOpts): Set<string> {
+    const tier: TestTier = o.tier ?? envTier()
+    return new Set(selectChecks(selectionOf(composed.map((g) => g.runnable), o, tier)).selected.map((u) => u.id))
+}
+
 /** THE run body: compose this repo's checks, run the set the audience asks
  *  for, and classify the outcome by what each check declared. `shipkit check`
  *  and `shipkit ci` both come through here, and nothing else decides
@@ -135,7 +161,7 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     let ledger: Ledger | null = o.ledger ?? null
     if (ledger === null && o.ledger === undefined) {
         try {
-            ledger = Ledger.open(root, composed.map((g) => g.row.decl), { cliEntry: o.cliEntry ?? gateBinary(), fresh: o.fresh })
+            ledger = Ledger.open(root, composed.map((g) => g.row.decl), { cliEntry: o.cliEntry ?? gateBinary(), fresh: o.fresh, scope: passScope(composed, o) })
         } catch { ledger = null }
     }
     // the caller's log, or this run's own: `shipkit check` measures checks too,
@@ -157,24 +183,15 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     const collected: Line[] = []
     const sink = (l: string): void => print(l)
     const summary = await runChecks({
-        checks,
+        ...selectionOf(checks, o, tier),
         root,
         config: c,
-        audience,
-        fullTier: tier === 'full',
         logDir: c.logDir ?? join(root, CI_LOG_DIR),
         cache: { storeDir: storeRoot(root), ns: c.name, now: Date.now },
         ledger,
         log,
         childEnv: { [SHARE_ENV]: sharePath, ...(o.fresh === true ? { SHIPKIT_FRESH: '1' } : {}) },
         bail: o.bail,
-        skipGroups: o.skipGroups,
-        onlyIds: o.only,
-        withIds: o.withIds,
-        onlyBlocking: o.onlyBlocking,
-        buildOnly: o.buildOnly,
-        includeProactive: o.includeProactive,
-        exclude: o.exclude,
         print: sink,
         onCheck: (e) => { collected.push(...e.lines); o.onCheck?.(e) },
     })
@@ -205,13 +222,16 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     if (o.runLog === undefined && log != null) for (const l of log.flush()) say(l)
     // a `when` id naming nothing is a switch wired to no check: the id is read
     // against the WHOLE inventory this run composed, never its narrowed list
-    const unknownWhen = unknownWhenIds(composed.map((g) => g.row), c)
+    const rows = composed.map((g) => g.row)
+    const unknownWhen = unknownWhenIds(rows, c)
+    const unknownBudgets = unknownBudgetIds(rows.map((r) => r.decl.id), c.budgets)
     return {
         lines: [...collected, ...lines],
         blocked: !summary.ok,
         advisoryFailures: summary.advisoryFailures,
         undeclared: summary.undeclared,
         unknownWhen,
+        unknownBudgets,
         results: summary.results,
         interrupted: summary.interrupted,
     }
@@ -222,14 +242,14 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
     const print = o.print ?? ((l: string) => console.log(l))
     const c = o.config ?? (await loadRepoConfig(root))
     const run = await runCheckPass(root, { ...o, config: c })
-    const code = run.blocked || run.undeclared.length > 0 || run.unknownWhen.length > 0 ? 1 : 0
+    const code = run.blocked || run.undeclared.length > 0 || run.unknownWhen.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     if (o.json === true) { print(JSON.stringify(run)); return code }
     for (const u of run.undeclared) {
         print(`FAIL: ${u} does not declare whether it blocks`)
         print(`      fix: add \`blocking: true\` (about this repo) or \`false\` (about the world) to that check`)
     }
-    for (const id of run.unknownWhen) {
-        print(`FAIL: when.${id} names no check of this repo`)
+    for (const key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+        print(`FAIL: ${key} names no check of this repo`)
         print(`      fix: \`shipkit checks\` lists every id; drop the entry or correct it`)
     }
     if (o.status !== false) {

package/src/core/run-ci.ts

@@ -8,7 +8,7 @@
 // --no-fix is passed.
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
-import { runCheckPass, type CheckOpts } from './run-check.ts'
+import { passScope, runCheckPass, type CheckOpts } from './run-check.ts'
 import { poolLines } from './slots.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
@@ -169,11 +169,34 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // ONE walk for the whole gate: the ledger is keyed on it and the run
     // measures it, and two walks can disagree about what exists
     const composed = await composeChecks(root, c, { tier })
+    // `gate = false` opts a check out of the everyday gate, and failOnAdvisory
+    // (release.requireHealthy) re-arms the world probes, because a repo asking
+    // for exactly those must not have them silently dropped by the opt-out
+    const passOpts: CheckOpts = {
+        status: false,
+        config: c,
+        composed,
+        audience: 'gate',
+        includeProactive: o.failOnAdvisory === true,
+        frozen: o.frozen,
+        onlyBlocking: o.onlyBlockingChecks,
+        only: o.onlyIds,
+        withIds: o.withIds,
+        skipGroups: o.skipGroups,
+        exclude: o.skipTaskIds,
+        buildOnly: o.buildOnly,
+        bail: o.bail,
+        fresh: o.fresh,
+        tier,
+    }
     try {
         ledger = Ledger.open(root, composed.map((g) => g.row.decl), {
             cliEntry: o.cliEntry ?? gateBinary(),
             read: o.ledgerRead,
             fresh: o.fresh,
+            // only what this run executes is scanned: an `--only` run pays for
+            // its own checks, never for the whole inventory
+            scope: passScope(composed, passOpts),
         })
         const reg = ledger.layer.registration
         for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
@@ -191,27 +214,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         ledger = null
         sink(`WARN cache unavailable (${String(e).slice(0, 160)}) — every check runs this time, so the gate is correct and slower`)
     }
-    // THE RUN. One engine, one DAG, one pass over everything this gate asks
-    // for: `gate = false` opts a check out of the everyday gate, and
-    // failOnAdvisory (release.requireHealthy) re-arms the world probes,
-    // because a repo asking for exactly those must not have them silently
-    // dropped by the opt-out.
+    // THE RUN. One engine, one DAG, one pass over everything this gate asks for
     const run = await runCheckPass(root, {
-        status: false,
-        config: c,
-        composed,
-        audience: 'gate',
-        includeProactive: o.failOnAdvisory === true,
-        frozen: o.frozen,
-        onlyBlocking: o.onlyBlockingChecks,
-        only: o.onlyIds,
-        withIds: o.withIds,
-        skipGroups: o.skipGroups,
-        exclude: o.skipTaskIds,
-        buildOnly: o.buildOnly,
-        bail: o.bail,
-        fresh: o.fresh,
-        tier,
+        ...passOpts,
         ledger,
         runLog,
         onCheck: o.onCheck,
@@ -230,8 +235,8 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     }
     // a switch wired to no check does nothing, silently, which is the one thing
     // a toggle must never do
-    for (const id of run.unknownWhen) {
-        sink(`FAIL: when.${id} names no check of this repo`)
+    for (const key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+        sink(`FAIL: ${key} names no check of this repo`)
         sink(`      fix: \`shipkit checks\` lists every id; drop the entry or correct it`)
     }
     let advisoryFatal = false
@@ -249,7 +254,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
     // one write for the whole gate, after everything has finished
     for (const l of runLog.flush()) sink(formatLine(l, false))
-    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 ? 1 : 0
+    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     // motherhome row (docsBase wiki on this disk) — never affects the gate,
     // and never fires under frozen: a bump/release gate must not re-dirty the
     // tree it just proved clean

package/src/core/self-update.ts

@@ -10,12 +10,16 @@
 // re-exec guard set, dirty package.json/lockfile (a tool must not mix its
 // writes into human-staged work), registry unreachable (offline is not a
 // defect). every skip is silent except the actionable ones, which WARN.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
-import { dirname, join } from 'path'
+import { basename, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { detectPackageManager, isRefusal } from './package-manager.ts'
 import { gitBin } from './git-bin.ts'
+import { reexecSelf } from './reexec.ts'
+import { LIB_ROOT } from './lib-root.ts'
+import { FRESH_ENV } from '../ledger/store.ts'
+import { allowMajor, breakingAdvice, isBreaking } from './update-policy.ts'
 
 const PKG = 'rvlib-shipkit'
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000
@@ -34,6 +38,10 @@ export function planSelfUpdate(o: {
     ci: boolean
     frozen: boolean
     manifestDirty: boolean
+    /** `fleet --update --major` asked for this jump on purpose */
+    allowMajor: boolean
+    /** the repo dir name, for the advice a breaking jump prints */
+    repo: string
 }): SelfUpdatePlan {
     if (o.reexecGuard) return { action: 'skip', reason: 'already re-executed once' }
     if (o.ci) return { action: 'skip', reason: 'CI env' }
@@ -43,6 +51,7 @@ export function planSelfUpdate(o: {
     if (o.latest == null) return { action: 'skip', reason: 'registry unreachable' }
     if (o.installed === o.latest) return { action: 'skip', reason: 'current' }
     if (newerThan(o.installed, o.latest)) return { action: 'skip', reason: 'ahead of the registry' }
+    if (isBreaking(o.installed, o.latest) && !o.allowMajor) return { action: 'warn', reason: breakingAdvice(PKG, o.latest, o.repo) }
     if (o.manifestDirty) return { action: 'warn', reason: `rvlib-shipkit ${o.installed} is behind ${o.latest}, package.json or lockfile dirty, not touching — commit, then rerun` }
     return { action: 'update', installed: o.installed, latest: o.latest }
 }
@@ -58,23 +67,40 @@ const newerThan = (a: string, b: string): boolean => {
     return false
 }
 
-const cachePath = (): string => join(homedir(), '.cache', 'shipkit', 'self-update.json')
+/** overrides the per-machine cache file (tests) */
+export const SELF_UPDATE_CACHE_ENV = 'SHIPKIT_SELF_UPDATE_CACHE'
 
-/** npm latest with a per-machine 24h cache, null when unreachable */
-async function latestCached(): Promise<string | null> {
+const cachePath = (): string => {
+    const env = process.env[SELF_UPDATE_CACHE_ENV]
+    return env != null && env !== '' ? env : join(homedir(), '.cache', 'shipkit', 'self-update.json')
+}
+
+/** store a registry answer another path measured, so the next startup
+ *  decides on it instead of on an older cached one */
+export function rememberLatest(version: string): void {
     const p = cachePath()
-    try {
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, JSON.stringify({ at: Date.now(), version }))
+}
+
+const npmLatest = async (): Promise<string | null> => {
+    const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(5000) })
+    if (!res.ok) return null
+    return ((await res.json()) as { version?: string }).version ?? null
+}
+
+/** npm latest with a per-machine 24h cache, null when unreachable. A fresh
+ *  run skips the cache: it decides the one update that restarts the run, and
+ *  a stale answer here leaves that update to SK005, mid run */
+export async function latestCached(o: { fresh: boolean; fetchLatest?: () => Promise<string | null> }): Promise<string | null> {
+    const p = cachePath()
+    if (!o.fresh) try {
         const c = JSON.parse(readFileSync(p, 'utf8')) as { at: number; version: string }
         if (Date.now() - c.at < CACHE_TTL_MS) return c.version
     } catch { /* no cache yet */ }
     try {
-        const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(5000) })
-        if (!res.ok) return null
-        const v = ((await res.json()) as { version?: string }).version ?? null
-        if (v != null) {
-            mkdirSync(dirname(p), { recursive: true })
-            writeFileSync(p, JSON.stringify({ at: Date.now(), version: v }))
-        }
+        const v = await (o.fetchLatest ?? npmLatest)()
+        if (v != null) rememberLatest(v)
         return v
     } catch {
         return null
@@ -87,10 +113,22 @@ const manifestDirty = (root: string): boolean => {
     return p.stdout.toString().trim() !== ''
 }
 
-/** run before dispatching an interactive ci/check. On update: re-exec the
- *  SAME argv with a loop guard and exit with the child's code (never
- *  returns). Otherwise returns after at most one cached registry probe. */
-export async function maybeSelfUpdateAndRestart(root: string): Promise<void> {
+/** true when `root`'s installed rvlib-shipkit is the code of THIS process.
+ *  Updating that tree in process would leave the rest of the run importing
+ *  modules of two versions, so only the startup path below may update it */
+export function isRunningCopy(root: string): boolean {
+    try {
+        return realpathSync(join(root, 'node_modules', PKG)) === realpathSync(LIB_ROOT)
+    } catch {
+        return false
+    }
+}
+
+/** run before dispatching an interactive ci/check, so no check has loaded
+ *  yet. On update: re-exec the SAME argv with a loop guard and exit with the
+ *  child's code (never returns). Otherwise returns after at most one registry
+ *  probe, cached unless the run is fresh (`--fresh` or SHIPKIT_FRESH=1). */
+export async function maybeSelfUpdateAndRestart(root: string, o: { fresh?: boolean } = {}): Promise<void> {
     const here = fileURLToPath(import.meta.url)
     const base = {
         installed: installedVersion(root),
@@ -98,10 +136,12 @@ export async function maybeSelfUpdateAndRestart(root: string): Promise<void> {
         reexecGuard: process.env.SHIPKIT_SELF_UPDATED === '1',
         ci: process.env.CI != null && process.env.CI !== '',
         frozen: process.env.SHIPKIT_FROZEN === '1',
+        allowMajor: allowMajor(),
+        repo: basename(root),
     }
     // cheap gates first: no network unless an update is even possible
     if (base.reexecGuard || base.ci || base.frozen || !base.runningFromNodeModules || base.installed == null) return
-    const plan = planSelfUpdate({ ...base, latest: await latestCached(), manifestDirty: manifestDirty(root) })
+    const plan = planSelfUpdate({ ...base, latest: await latestCached({ fresh: o.fresh === true || process.env[FRESH_ENV] === '1' }), manifestDirty: manifestDirty(root) })
     if (plan.action === 'warn') { console.error(`WARN self-update: ${plan.reason}`); return }
     if (plan.action !== 'update') return
     const pm = detectPackageManager(root)
@@ -111,12 +151,7 @@ export async function maybeSelfUpdateAndRestart(root: string): Promise<void> {
     const up = Bun.spawnSync(cmd, { cwd: root, stdout: 'inherit', stderr: 'inherit' })
     if (up.exitCode !== 0) { console.error(`WARN self-update failed (exit ${up.exitCode}), continuing on ${plan.installed}`) ; return }
     console.error(`ok: restarting on ${plan.latest} — commit package.json + lockfile with your work`)
-    const child = Bun.spawnSync([process.execPath, ...process.argv.slice(1)], {
-        cwd: process.cwd(),
-        stdout: 'inherit', stderr: 'inherit', stdin: 'inherit',
-        env: { ...process.env, SHIPKIT_SELF_UPDATED: '1' },
-    })
-    process.exit(child.exitCode ?? 1)
+    reexecSelf({ ...process.env, SHIPKIT_SELF_UPDATED: '1' })
 }
 
 const installedVersion = (root: string): string | null => {

package/src/core/update-policy.ts

@@ -0,0 +1,25 @@
+// the ONE update policy every automatic update path asks: rule SK005, the
+// startup self-update and `shipkit fleet --update`. An automatic update never
+// crosses a breaking boundary. It reports the jump and names the one command
+// that takes it on purpose.
+
+/** set by `shipkit fleet --update --major` on the repo run it spawns */
+export const ALLOW_MAJOR_ENV = 'SHIPKIT_ALLOW_MAJOR'
+
+export const allowMajor = (): boolean => process.env[ALLOW_MAJOR_ENV] === '1'
+
+/** a jump across the boundary npm's caret draws: a changed major, or on a
+ *  `0.x` package a changed minor (`^0.2.0` means `<0.3.0`). A porting job
+ *  rather than a bump, so no automatic path takes it. */
+export function isBreaking(installed: string, latest: string): boolean {
+    const parts = (v: string) => v.split('-')[0]!.split('.').map((n) => Number(n) || 0)
+    const [aMajor = 0, aMinor = 0] = parts(installed)
+    const [bMajor = 0, bMinor = 0] = parts(latest)
+    if (aMajor !== bMajor) return true
+    return aMajor === 0 && aMinor !== bMinor
+}
+
+/** the WARN text for a jump no automatic path takes. `repo` is the directory
+ *  name, which is what `fleet --only` matches */
+export const breakingAdvice = (name: string, latest: string, repo: string): string =>
+    `${name} ${latest} available (breaking): run \`shipkit fleet --update --major --only ${repo}\``

package/src/fleet/scan-fleet.ts

@@ -8,11 +8,12 @@
 //
 // This module DISCOVERS and REPORTS. It never updates: rule SK005 owns the
 // update, with the lease, the dirty-tree guard and the frozen guard that took
-// three bugs to get right. `--update` runs each repo's own `shipkit check`,
-// so the fix travels through that one code path.
+// three bugs to get right. `--update` (update-fleet.ts) runs each repo's own
+// `shipkit check`, so the fix travels through that one code path.
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
+import { isBreaking } from '../core/update-policy.ts'
 
 export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
 
@@ -26,18 +27,6 @@ export type FleetDep = {
     latest: string | null
 }
 
-/** a jump that changes the MAJOR, which is a porting job rather than a bump.
- *
- *  Deliberately NOT the semver rule. On a `0.x` package npm treats every
- *  minor as breaking, and by that rule every repo here is breaking, including
- *  the `0.24 → 0.35` shipkit jumps that rule SK005 already performs by itself
- *  every day. A flag that fires on everything is a flag nobody reads. What
- *  survives is the case a human has to own: `rvlib-pb-mobx 0.2.0 → 2.0.0`. */
-export function isBreaking(installed: string, latest: string): boolean {
-    const major = (v: string) => Number(v.split('-')[0]!.split('.')[0]) || 0
-    return major(installed) !== major(latest)
-}
-
 export type FleetRepo = {
     name: string
     dir: string
@@ -62,7 +51,7 @@ const readPkg = (dir: string): Pkg | null => {
     }
 }
 
-const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
+export const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
 
 /** semver-ish compare, enough to answer "is this one behind that one". A
  *  prerelease tag sorts before its release, which is the safe direction: it

package/src/fleet/update-fleet.ts

@@ -0,0 +1,85 @@
+// `shipkit fleet --update`: hand each behind repo its own update. The update
+// is NOT performed here. Each repo runs its own binary, which is the only copy
+// whose SK005 matches the rules that repo is pinned to, and the only one
+// holding that repo's mutate lease.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { spawnWithTimeout } from '../core/spawn-timeout.ts'
+import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
+import { ALLOW_MAJOR_ENV, breakingAdvice } from '../core/update-policy.ts'
+import { installedVersion, isBehind, updateRefusal, type FleetRepo } from './scan-fleet.ts'
+
+
+export const short = (name: string): string => name.replace(/^rvlib-/, '')
+
+// the hand-run fallback speaks the manager THAT repo installs with: telling
+// an npm consumer to run bun leaves its package-lock.json behind
+const manualUpdate = (r: FleetRepo): string => {
+    const pm = detectPackageManager(r.dir)
+    return isRefusal(pm) ? `<its package manager> update ${r.behind.map((d) => d.name).join(' ')} (${pm.refused})` : pm.update(r.behind.map((d) => d.name)).join(' ')
+}
+
+export type FleetUpdateOpts = {
+    /** cross a breaking boundary too (`--major`) */
+    major: boolean
+    print: (line: string) => void
+    /** per repo run (default 10 minutes: a fresh health pass probes the world) */
+    timeoutMs?: number
+}
+
+/** returns how many repos did not update. A repo whose gate refused (dirty
+ *  tree, frozen, a lease held elsewhere) is a REPORT, not a failure of the
+ *  command: SK005 defers on purpose */
+export async function updateFleet(behind: FleetRepo[], o: FleetUpdateOpts): Promise<number> {
+    const w = o.print
+    let failed = 0
+    for (const r of behind) {
+        // the same policy SK005 applies inside the repo: a breaking jump is reported,
+        // never taken, and a safe jump beside it still moves
+        const held = o.major ? [] : r.breaking
+        for (const d of held) w(`WARN ${r.name}: ${breakingAdvice(d.name, d.latest!, r.name)}`)
+        const wanted = r.behind.filter((d) => !held.includes(d))
+        if (wanted.length === 0) {
+            failed++
+            continue
+        }
+        const refused = updateRefusal(r)
+        if (refused != null) {
+            w(`WARN ${r.name}: not updating: ${refused}`)
+            failed++
+            continue
+        }
+        const cli = join(r.dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')
+        if (!existsSync(cli)) {
+            w(`WARN ${r.name}: no shipkit installed, so it cannot update itself — run: cd ${r.dir} && ${manualUpdate(r)}`)
+            failed++
+            continue
+        }
+        // `--fresh` because SK005 caches a clean pass for 24h: a plain `check`
+        // replays the answer it gave before this release existed, and the run
+        // meant to update never asks the registry. `check --fix SK005` is no
+        // way around it: SK005 has no autofix, so the binary refuses the id.
+        // The re-exec guard is dropped so the repo's own startup self-update
+        // can still fire, and --major travels as the one env the policy reads.
+        const env: Record<string, string> = Object.fromEntries(Object.entries(process.env).filter((e): e is [string, string] => e[1] != null && e[0] !== 'SHIPKIT_SELF_UPDATED' && e[0] !== ALLOW_MAJOR_ENV))
+        if (o.major) env[ALLOW_MAJOR_ENV] = '1'
+        const res = await spawnWithTimeout(['bun', cli, 'check', '--fresh'], { cwd: r.dir, env, timeoutMs: o.timeoutMs ?? 600_000 })
+        // judge by what node_modules carries now, never by the exit code or a
+        // printed line: the code covers every rule in that repo, and the line
+        // format belongs to whatever version that repo runs
+        const stuck = wanted.filter((d) => {
+            const now = installedVersion(r.dir, d.name)
+            return now == null || isBehind(now, d.latest!)
+        })
+        if (stuck.length === 0) {
+            w(`ok: ${r.name} — ${wanted.map((d) => `${short(d.name)} ${d.installed} → ${installedVersion(r.dir, d.name)}`).join(', ')}`)
+            continue
+        }
+        failed++
+        const said = res.out.split('\n').find((l) => /\brvlib-/.test(l) && (l.startsWith('WARN') || l.startsWith('FAIL')))
+        w(`WARN ${r.name} did not move ${stuck.map((d) => short(d.name)).join(', ')} — ${said ?? `check exited ${res.code}${res.timedOut ? ', timed out' : ''} with no rvlib line`}`)
+        w(`      fix: cd ${r.dir} && ${manualUpdate(r)}`)
+    }
+    w(failed === 0 ? `ok: ${behind.length} repo(s) updated through their own gate` : `WARN ${failed}/${behind.length} repo(s) did not update — each line above says why`)
+    return failed
+}