rvlib-shipkit 0.1.0

package/src/contracts/contracts-engine.ts

@@ -0,0 +1,186 @@
+// Contract fulfillness engine — evaluates ContractManifests against a repo,
+// emitting wire-protocol lines. Enforcement is BOTH ways:
+// - declared venue with an incomplete folder → FAIL per missing artifact
+// - undeclared venue whose detectors fire → FAIL (config can't lie,
+//   folders can't rot)
+// - exempt venues skip VISIBLY with their reason; never silence
+// - 'always' contracts with gate 'public-surface': full severity once the
+//   repo has a public surface, everything demoted to WARN before.
+// Every FAIL carries a fix: pointer = docsBase + manifest.owner.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import type { ArtifactRule, ContractEnv, ContractManifest } from './contract-types.ts'
+import type { Line } from '../core/wire.ts'
+
+export type ContractsConfig = {
+    root: string
+    /** venue ids the repo declares it ships on (config side of both-ways drift) */
+    declared: string[]
+    /** social channel list — handed to custom rules via ContractEnv */
+    social: string[]
+    /** repo has a public surface (deploy script or any declared venue) — gates 'always' contracts */
+    publicSurface: boolean
+    /** venue → reason; skips the venue VISIBLY */
+    exempt?: Record<string, string>
+    /** prefix for fix: pointers, e.g. a docs checkout path or URL */
+    docsBase?: string
+}
+
+export type ContractOutcome = { venue: string; status: 'ok' | 'fail' | 'warn' | 'exempt' | 'not-applicable'; problems: number }
+export type ContractsResult = { lines: Line[]; exitCode: 0 | 1; outcomes: ContractOutcome[] }
+
+// PNG dims from the IHDR header — bytes 16..23 big-endian, after the
+// 8-byte signature + IHDR length/type. No image dependency.
+export function pngDims(path: string): { width: number; height: number } | null {
+    try {
+        const fd = readFileSync(path)
+        if (fd.length < 24) return null
+        const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+        for (let i = 0; i < sig.length; i++) if (fd[i] !== sig[i]) return null
+        return { width: fd.readUInt32BE(16), height: fd.readUInt32BE(20) }
+    } catch {
+        return null
+    }
+}
+
+const abs = (root: string, rel: string): string => join(root, rel)
+
+async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]> {
+    const problems: string[] = []
+    switch (rule.kind) {
+        case 'file': {
+            const p = abs(env.root, rule.path)
+            if (!existsSync(p)) problems.push(`${rule.path} missing`)
+            else if (!statSync(p).isFile()) problems.push(`${rule.path} is not a file`)
+            else if (rule.nonEmpty && statSync(p).size === 0) problems.push(`${rule.path} is empty`)
+            break
+        }
+        case 'png': {
+            const p = abs(env.root, rule.path)
+            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${rule.width}x${rule.height}`); break }
+            const dims = pngDims(p)
+            if (dims == null) problems.push(`${rule.path} is not a readable png`)
+            else if (dims.width !== rule.width || dims.height !== rule.height)
+                problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${rule.width}x${rule.height}`)
+            break
+        }
+        case 'glob': {
+            const matches = [...new Bun.Glob(rule.pattern).scanSync({ cwd: env.root, onlyFiles: true })]
+            if (matches.length < rule.min) { problems.push(`${rule.pattern}: ${matches.length} file(s) — need >= ${rule.min}`); break }
+            if (rule.width != null && rule.height != null)
+                for (const m of matches) {
+                    const dims = pngDims(abs(env.root, m))
+                    if (dims == null || dims.width !== rule.width || dims.height !== rule.height)
+                        problems.push(`${m} is ${dims == null ? 'not a readable png' : `${dims.width}x${dims.height}`} — need ${rule.width}x${rule.height}`)
+                }
+            break
+        }
+        case 'md': {
+            const p = abs(env.root, rule.path)
+            if (!existsSync(p)) { problems.push(`${rule.path} missing`); break }
+            const text = readFileSync(p, 'utf8')
+            if (text.trim() === '') { problems.push(`${rule.path} is empty`); break }
+            for (const needle of rule.mustContain) if (!text.includes(needle)) problems.push(`${rule.path} lacks required '${needle}'`)
+            break
+        }
+        case 'dir': {
+            const p = abs(env.root, rule.path)
+            if (!existsSync(p) || !statSync(p).isDirectory()) problems.push(`${rule.path}/ missing`)
+            break
+        }
+        case 'custom': {
+            problems.push(...(await rule.probe(env)))
+            break
+        }
+    }
+    return problems
+}
+
+function detectorFires(m: ContractManifest, cfg: ContractsConfig): string | null {
+    for (const d of m.detect) {
+        if (d.kind === 'dirExists') {
+            if (existsSync(abs(cfg.root, d.path))) return `${d.path}/ exists`
+        } else if (d.kind === 'fileContains') {
+            const p = abs(cfg.root, d.path)
+            if (existsSync(p) && new RegExp(d.pattern).test(readFileSync(p, 'utf8'))) return `${d.path} matches /${d.pattern}/`
+        } else {
+            const pkgPath = abs(cfg.root, 'package.json')
+            if (!existsSync(pkgPath)) continue
+            try {
+                const scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}
+                const re = new RegExp(d.pattern)
+                const hit = Object.keys(scripts).find((k) => re.test(k))
+                if (hit != null) return `package.json script '${hit}'`
+            } catch { /* unparseable package.json is another tool's FAIL */ }
+        }
+    }
+    return null
+}
+
+export async function evaluateContracts(manifests: ContractManifest[], cfg: ContractsConfig): Promise<ContractsResult> {
+    const lines: Line[] = []
+    const outcomes: ContractOutcome[] = []
+    let anyFail = false
+    const env: ContractEnv = {
+        root: cfg.root,
+        venues: cfg.declared,
+        social: cfg.social,
+        exists: (rel) => existsSync(abs(cfg.root, rel)),
+    }
+    const fix = (m: ContractManifest, text: string): Line[] => [
+        { kind: 'fix-fail', text: `${text} — ${(cfg.docsBase ?? '') + m.owner}` },
+    ]
+
+    for (const m of manifests) {
+        const exemptReason = cfg.exempt?.[m.venue]
+        if (exemptReason != null) {
+            lines.push({ kind: 'skip', text: `${m.venue}  exempt: "${exemptReason}"` })
+            outcomes.push({ venue: m.venue, status: 'exempt', problems: 0 })
+            continue
+        }
+        const declared = cfg.declared.includes(m.venue)
+        if (m.appliesTo === 'declared' && !declared) {
+            const signal = detectorFires(m, cfg)
+            if (signal != null) {
+                anyFail = true
+                lines.push({ kind: 'fail', text: `${m.venue}  ships (${signal}) but venue is not declared — declare it or remove the signal` })
+                lines.push(...fix(m, 'declare + fill the contract'))
+                outcomes.push({ venue: m.venue, status: 'fail', problems: 1 })
+            } else {
+                outcomes.push({ venue: m.venue, status: 'not-applicable', problems: 0 })
+            }
+            continue
+        }
+        // demote everything to WARN on ungated 'always' contracts (no public surface yet)
+        const warnAll = m.appliesTo === 'always' && m.gate === 'public-surface' && !cfg.publicSurface
+        let problems = 0
+        let warned = 0
+        for (const rule of m.artifacts) {
+            const found = await checkRule(rule, env)
+            const asWarn = warnAll || rule.warnOnly === true
+            for (const p of found) {
+                if (asWarn) {
+                    warned++
+                    lines.push({ kind: 'warn', text: `${m.venue}  ${p}${warnAll ? ' (no public surface yet — WARN not FAIL)' : ''}` })
+                } else {
+                    problems++
+                    lines.push({ kind: 'fail', text: `${m.venue}  ${p}` })
+                }
+            }
+        }
+        // ONE fix pointer per contract per severity — ten missing capsules
+        // must not print ten identical fix lines
+        if (problems > 0) lines.push(...fix(m, 'contract'))
+        if (warned > 0) lines.push({ kind: 'fix-warn', text: (cfg.docsBase ?? '') + m.owner })
+        if (problems > 0) {
+            anyFail = true
+            outcomes.push({ venue: m.venue, status: 'fail', problems })
+        } else if (warned > 0) {
+            outcomes.push({ venue: m.venue, status: 'warn', problems: warned })
+        } else {
+            lines.push({ kind: 'ok', text: `${m.venue}  ${m.dir}/ complete (${m.artifacts.length} rule(s))` })
+            outcomes.push({ venue: m.venue, status: 'ok', problems: 0 })
+        }
+    }
+    return { lines, exitCode: anyFail ? 1 : 0, outcomes }
+}

package/src/contracts/manifests/discord.contract.ts

@@ -0,0 +1,15 @@
+// normative WHAT for .rv-discord/ — a project's public Discord server
+// contract (promoted out of .rv-social/discord/ 2026-07-21; posts stay there).
+import { defineContract, dirExists, md, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+
+export default defineContract({
+    venue: 'discord',
+    dir: '.rv-discord',
+    owner: 'distribute/social.md',
+    appliesTo: 'declared',
+    detect: [dirExists('.rv-discord')],
+    artifacts: [
+        md('.rv-discord/server.md', { mustContain: ['invite'] }),
+        png('.rv-discord/icon.png', 512, 512),
+    ],
+})

package/src/contracts/manifests/identity.contract.ts

@@ -0,0 +1,19 @@
+// normative WHAT for .rv-identity/ — every repo with a public surface owns
+// its brand source + committed favicon/logo/OG outputs. gate: FAIL once a
+// public surface exists (deploy.sh or any declared venue), WARN before.
+import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+
+export default defineContract({
+    venue: 'identity',
+    dir: '.rv-identity',
+    owner: 'build/assets.md',
+    appliesTo: 'always',
+    gate: 'public-surface',
+    detect: [],
+    artifacts: [
+        file('.rv-identity/brand.ts'),
+        png('public/favicon.png', 512, 512),
+        png('public/og.png', 1200, 630),
+        glob('public/logo.*', { min: 1 }),
+    ],
+})

package/src/contracts/manifests/itch.contract.ts

@@ -0,0 +1,16 @@
+// normative WHAT for .rv-itch/ — the WHY + workflow live in the sibling page.
+import { defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+
+export default defineContract({
+    venue: 'itch',
+    dir: '.rv-itch',
+    owner: 'distribute/itch.md',
+    appliesTo: 'declared',
+    detect: [script('^(up|push):itch$'), fileContains('deploy.sh', 'butler push'), dirExists('.rv-itch')],
+    artifacts: [
+        // one AI-disclosure wording everywhere — page.md is its canonical home
+        md('.rv-itch/page.md', { mustContain: ['## AI disclosure'] }),
+        png('.rv-itch/cover.png', 630, 500),
+        glob('.rv-itch/screenshots/*.png', { min: 3 }),
+    ],
+})

package/src/contracts/manifests/social.contract.ts

@@ -0,0 +1,18 @@
+// normative WHAT for .rv-social/ (posts ONLY — the Discord server contract is
+// discord.contract.ts). Declared = the repo config lists social channels.
+import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+
+export default defineContract({
+    venue: 'social',
+    dir: '.rv-social',
+    owner: 'distribute/social.md',
+    appliesTo: 'declared',
+    detect: [dirExists('.rv-social')],
+    artifacts: [
+        custom('declared-channel-dirs', (env) =>
+            env.social
+                .filter((ch) => !env.exists(`.rv-social/${ch}`))
+                .map((ch) => `.rv-social/${ch}/ missing — declared social channel '${ch}' has no post folder`),
+        ),
+    ],
+})

package/src/contracts/manifests/steam.contract.ts

@@ -0,0 +1,28 @@
+// normative WHAT for .rv-steam/ — the WHY + workflow live in the sibling page.
+// Capsule sizes as of 2026-07 — Valve churns them: re-verify at use, bump here.
+import { defineContract, dir, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+
+export default defineContract({
+    venue: 'steam',
+    dir: '.rv-steam',
+    owner: 'distribute/steam.md',
+    appliesTo: 'declared',
+    detect: [script('^(up|push):steam$'), fileContains('deploy.sh', 'run_app_build'), dirExists('.rv-steam')],
+    artifacts: [
+        // store.md carries the same AI-disclosure wording as .rv-itch/page.md
+        md('.rv-steam/store.md', { mustContain: ['## AI disclosure'] }),
+        png('.rv-steam/capsules/main.png', 1232, 706),
+        png('.rv-steam/capsules/header.png', 920, 430),
+        png('.rv-steam/capsules/small.png', 462, 174),
+        png('.rv-steam/capsules/vertical.png', 748, 896),
+        png('.rv-steam/capsules/library.png', 600, 900),
+        png('.rv-steam/capsules/library-hero.png', 3840, 1240),
+        png('.rv-steam/capsules/library-logo.png', 1280, 720),
+        png('.rv-steam/capsules/community-icon.png', 184, 184),
+        // .ico, dims not png-parseable — presence-checked only
+        file('.rv-steam/capsules/client-icon.ico'),
+        glob('.rv-steam/screenshots/*.png', { min: 5, width: 1920, height: 1080 }),
+        // vdf scripts only exist once the appid does — nag, don't block
+        dir('.rv-steam/vdf', { warnOnly: true }),
+    ],
+})

package/src/core/check-ctx.ts

@@ -0,0 +1,63 @@
+// CheckCtx — the per-check handle a probe's logic receives: outcome lines
+// (wire.ts kinds), guarded fetch/exec helpers, resolved-tool lookup.
+import { existsSync } from 'fs'
+import type { Line } from './wire.ts'
+
+// thrown by t.fetch on 429 — the suite converts it to WARN, never FAIL
+export class RateLimited extends Error {}
+// thrown by t.tool when its defineRequiredTool check failed — that check
+// already FAILed the run; the dependent check notes it skipped, no double FAIL
+export class ToolUnresolved extends Error {}
+
+export class CheckCtx {
+    lines: Line[] = []
+    failed = false
+    warned = false
+    constructor(private toolPaths: Map<string, string>) {}
+
+    ok(msg: string): void { this.lines.push({ kind: 'ok', text: msg }) }
+    note(msg: string): void { this.lines.push({ kind: 'note', text: msg }) }
+    warn(msg: string, fix?: string): void {
+        this.warned = true
+        this.lines.push({ kind: 'warn', text: msg })
+        if (fix != null) this.lines.push({ kind: 'fix-warn', text: fix })
+    }
+    fail(msg: string, fix?: string): void {
+        this.failed = true
+        this.lines.push({ kind: 'fail', text: msg })
+        if (fix != null) this.lines.push({ kind: 'fix-fail', text: fix })
+    }
+
+    // path resolved by an earlier defineRequiredTool check (declaration order)
+    tool(name: string): string {
+        const p = this.toolPaths.get(name)
+        if (p == null) throw new ToolUnresolved(`tool '${name}' unresolved — its defineRequiredTool check failed or is declared after this check`)
+        return p
+    }
+
+    // fetch with a default timeout; 429 → RateLimited → WARN upstream
+    async fetch(url: string, init?: RequestInit & { timeoutMs?: number }): Promise<Response> {
+        const res = await fetch(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(init?.timeoutMs ?? 10_000) })
+        if (res.status === 429) throw new RateLimited(`${new URL(url).host} → 429 rate-limited`)
+        return res
+    }
+
+    // spawn without the Bun.spawn throw-on-missing-binary gotcha; SIGTERM at
+    // timeoutMs, SIGKILL 2s later (a child ignoring SIGTERM must not hang us)
+    async exec(cmd: string[], opts?: { env?: Record<string, string | undefined>; cwd?: string; timeoutMs?: number }): Promise<{ code: number; out: string; timedOut: boolean }> {
+        const head = cmd[0]
+        if (head == null) return { code: -1, out: 'empty command', timedOut: false }
+        const bin = head.includes('/') ? head : Bun.which(head)
+        if (bin == null || !existsSync(bin)) return { code: -1, out: `${head}: not found`, timedOut: false }
+        const p = Bun.spawn([bin, ...cmd.slice(1)], { stdout: 'pipe', stderr: 'pipe', env: opts?.env as Record<string, string>, cwd: opts?.cwd })
+        let timedOut = false
+        const ms = opts?.timeoutMs ?? 15_000
+        const timer = setTimeout(() => { timedOut = true; p.kill() }, ms)
+        const killer = setTimeout(() => p.kill('SIGKILL'), ms + 2000)
+        const out = (await new Response(p.stdout).text()) + (await new Response(p.stderr).text())
+        const code = await p.exited
+        clearTimeout(timer)
+        clearTimeout(killer)
+        return { code, out, timedOut }
+    }
+}

package/src/core/check-suite.ts

@@ -0,0 +1,179 @@
+// CheckSuite — declare tools / secrets / checks, then `await suite.run()`;
+// renders the v0 wire contract (wire.ts) with exit code.
+//
+// The TTL cache is the API-spam guard: a passing check with `remainValidFor`
+// replays from `<cacheDir>/<name>.json` without touching the network. Only
+// clean passes are cached; WARN/FAIL evict. Busts: version bump, secret
+// rotation (key hashes the secret value), `<freshEnv>=1`.
+//
+// Secret VALUES never enter this module's state beyond the injected
+// getSecret call + a truncated hash for cache-busting.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
+import { fmtAge, formatLine, parseDuration, type Line } from './wire.ts'
+
+type Logic = (t: CheckCtx) => unknown
+type Prep = { skip?: string; cacheExtra?: string }
+type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic }
+type CacheFile = Record<string, { version: number; key: string; at: number; lines: Line[] }>
+
+export type GetSecret = (name: string, field: 'get' | 'account') => string | null
+
+export type SecretSpec = {
+    remainValidFor?: string | number
+    version?: number
+    /** appended to the unstored skip message — a POINTER to where to mint (URL, file, or doc section), never inline mint steps */
+    skipHint: string
+}
+
+export type CheckSuiteOpts = {
+    name: string
+    cacheDir: string
+    now?: () => number
+    /** secret backend — consumers inject their own store; default = nothing stored, every secret check skips */
+    getSecret?: GetSecret
+    /** env var that busts the cache when set (consumer names it) */
+    freshEnv?: string
+}
+
+export class CheckSuite {
+    readonly name: string
+    private runners: Runner[] = []
+    private toolPaths = new Map<string, string>()
+    private cacheDir: string
+    private now: () => number
+    private getSecret: GetSecret
+    private freshEnv: string
+
+    constructor(opts: CheckSuiteOpts) {
+        this.name = opts.name
+        this.cacheDir = opts.cacheDir
+        this.now = opts.now ?? Date.now
+        this.getSecret = opts.getSecret ?? (() => null)
+        this.freshEnv = opts.freshEnv ?? 'SHIPKIT_FRESH'
+    }
+
+    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; logic: Logic }): void {
+        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, logic: spec.logic })
+    }
+
+    defineRequiredTool(name: string, opts: { candidates?: string[]; probe?: { args: string[]; expect?: RegExp }; fix: string }): void {
+        this.addCheck({
+            name,
+            logic: async (t) => {
+                // explicit candidate paths beat ambient PATH — a stale global (e.g. tsc 4.x) must not shadow the pinned one
+                const bin = opts.candidates?.find((c) => existsSync(c)) ?? Bun.which(name)
+                if (bin == null) return t.fail(`${name} not installed`, opts.fix)
+                this.toolPaths.set(name, bin)
+                if (opts.probe == null) return t.ok(`${name} present`)
+                const p = await t.exec([bin, ...opts.probe.args])
+                const first = p.out.trim().split('\n')[0] ?? ''
+                if (p.code !== 0 || (opts.probe.expect != null && !opts.probe.expect.test(p.out.trim())))
+                    return t.fail(`${name} present but broken (${first.slice(0, 120)})`, opts.fix)
+                // version-ish summary, not the whole banner (some CLIs append build date + ref)
+                t.ok(`${name} ${(first.split(',')[0] ?? first).slice(0, 80)}`)
+            },
+        })
+    }
+
+    defineRequiredSecret(spec: SecretSpec & { name: string; account?: false; validate: (value: string, t: CheckCtx) => unknown }): void
+    defineRequiredSecret(spec: SecretSpec & { name: string; account: true; validate: (cred: { value: string; account: string }, t: CheckCtx) => unknown }): void
+    defineRequiredSecret(spec: SecretSpec & { name: string[]; validate: (values: string[], t: CheckCtx) => unknown }): void
+    defineRequiredSecret(spec: SecretSpec & { name: string | string[]; account?: boolean; validate: (v: never, t: CheckCtx) => unknown }): void {
+        const names = [spec.name].flat()
+        const primary = names[0]
+        if (primary == null) throw new Error('defineRequiredSecret: name must be non-empty')
+        // probes may run without typechecking — enforce the required pointer at define time too
+        if (typeof spec.skipHint !== 'string' || spec.skipHint.length === 0)
+            throw new Error(`defineRequiredSecret(${primary}): skipHint is required — a pointer to where to mint (URL, file, or doc section)`)
+        const validate = spec.validate as (v: unknown, t: CheckCtx) => unknown
+        let payload: unknown
+        this.runners.push({
+            // bare secret name — this shows up in human-facing WARN/FAIL lines
+            name: names.length === 1 ? primary : primary.split('/').slice(0, 2).join('/') + '/*',
+            ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0,
+            version: spec.version ?? 1,
+            prep: () => {
+                const values = names.map((n) => this.getSecret(n, 'get'))
+                const account = spec.account === true ? this.getSecret(primary, 'account') : undefined
+                const missing = names.filter((_, i) => values[i] == null)
+                if (spec.account === true && account == null) missing.push(`${primary} (account field)`)
+                if (missing.length > 0)
+                    return { skip: `${missing.join(', ')} unstored — ${spec.skipHint}` }
+                payload = spec.account === true ? { value: values[0], account } : Array.isArray(spec.name) ? values : values[0]
+                // secret rotation busts the cache: key = hash of the value(s)
+                const material = [...(values as string[]), account ?? ''].join('\0')
+                return { cacheExtra: new Bun.CryptoHasher('sha256').update(material).digest('hex').slice(0, 16) }
+            },
+            logic: (t) => validate(payload, t),
+        })
+    }
+
+    // test seam — run() prints + exits; execute() returns the structured result
+    async execute(): Promise<{ lines: Line[]; exitCode: number }> {
+        const cachePath = join(this.cacheDir, `${this.name}.json`)
+        let cache: CacheFile = {}
+        try { cache = JSON.parse(readFileSync(cachePath, 'utf8')) } catch {}
+        let cacheDirty = false
+
+        const out: Line[] = []
+        const skipped: string[] = []
+        let ran = 0
+        let anyFail = false
+
+        for (const r of this.runners) {
+            const prep = r.prep?.() ?? {}
+            if (prep.skip != null) { skipped.push(prep.skip); continue }
+            ran++
+            const key = prep.cacheExtra ?? ''
+            const entry = cache[r.name]
+            const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
+                && entry != null && entry.version === r.version && entry.key === key
+                && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
+            if (fresh) {
+                const age = fmtAge(this.now() - entry.at)
+                out.push(...entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${age} ago)` } : l)))
+                continue
+            }
+            const t = new CheckCtx(this.toolPaths)
+            try {
+                await r.logic(t)
+            } catch (e) {
+                if (e instanceof RateLimited) t.warn(`${r.name} not validated this run (${e.message}) — retry later`)
+                else if (e instanceof ToolUnresolved) t.note(`${r.name} skipped (${e.message})`)
+                else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
+            }
+            out.push(...t.lines)
+            if (t.failed) anyFail = true
+            if (r.ttlMs > 0) {
+                if (!t.failed && !t.warned) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }
+                // a WARN/FAIL evicts the stale pass — a later run must re-probe,
+                // not replay an ok recorded before the breakage
+                else if (entry != null) { delete cache[r.name]; cacheDirty = true }
+            }
+        }
+
+        // contract: `skip:` lines ONLY when no check ran at all (whole probe is
+        // moot without the creds); otherwise a neutral note so passing probes
+        // are not relabeled 'check skip'
+        if (ran === 0) out.push(...skipped.map((s): Line => ({ kind: 'skip', text: `${s} (creds gate reports it)` })))
+        else out.push(...skipped.map((s): Line => ({ kind: 'note', text: `${s} — validation skipped (creds gate reports it)` })))
+
+        if (cacheDirty) {
+            // prune entries for renamed/removed checks — the file must not accrete
+            const known = new Set(this.runners.map((r) => r.name))
+            for (const k of Object.keys(cache)) if (!known.has(k)) delete cache[k]
+            mkdirSync(this.cacheDir, { recursive: true })
+            writeFileSync(cachePath, JSON.stringify(cache))
+        }
+        return { lines: out, exitCode: anyFail ? 1 : 0 }
+    }
+
+    async run(): Promise<never> {
+        const { lines, exitCode } = await this.execute()
+        const color = process.stdout.isTTY && process.env.NO_COLOR == null
+        for (const l of lines) console.log(formatLine(l, color))
+        process.exit(exitCode)
+    }
+}