rvlib-shipkit 1.2.0 → 1.4.0

package/src/checks/SK025-release-drift.check.ts

@@ -0,0 +1,58 @@
+// SK025 release drift (build/shipkit/built-in-checks.md): every unit this repo
+// releases matches what npm serves and what its push remote holds, the same
+// survey `shipkit releases` prints. It replaces a drift copy per page. A repo
+// that releases nothing (a private root with no release config and no units)
+// skips it. A world probe: the registry and the remote move on a publish this
+// tree cannot see, so a clean answer keeps for a day, keyed on every unit's
+// version so a local bump asks again at once.
+import { check, type CheckCtx } from '../check.ts'
+import { parseWireOutput } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { attentionLines, collectReports, type UnitReport } from '../release/run-releases.ts'
+import { resolveUnits, type ReleaseUnit } from '../release/units.ts'
+
+/** the units this repo releases: every declared one, and the root only when
+ *  it publishes to npm or the repo declares a release config */
+export function releasedUnits(root: string, config: RepoConfig): ReleaseUnit[] {
+    return resolveUnits(root, config).units.filter((u) => u.id !== 'root' || u.targets.npm || config.release != null)
+}
+
+/** the survey as check lines: one ok per unit in step, else its attention lines */
+export function reportDrift(c: CheckCtx, reports: UnitReport[]): void {
+    for (const r of reports) {
+        const lines = attentionLines(r)
+        if (lines.length === 0) {
+            // "in sync with npm" only for a unit that HAS an npm target and whose
+            // registry read succeeded (attentionLines warns when it did not)
+            c.ok(r.npmTarget ? `${r.name}@${r.version} in sync with npm` : `${r.name}@${r.version}, no npm target, tag state only`)
+            continue
+        }
+        for (const l of parseWireOutput(lines.join('\n'))) {
+            if (l.kind === 'warn' || l.kind === 'fail') c.warn(l.text)
+            else if (l.kind === 'ok') c.ok(l.text)
+            else c.note(l.text)
+        }
+    }
+}
+
+export const releaseDrift = check({
+    id: 'SK025',
+    blocking: false,
+    title: 'release drift',
+    description: 'every unit this repo releases matches npm and its push remote',
+    owner: 'build/shipkit/built-in-checks.md',
+    when: 'health',
+    ttl: '20h',
+    every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'),
+    planOff: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
+    cacheKey: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(','),
+    run: async (c) => {
+        const ids = new Set(releasedUnits(c.root, c.config).map((u) => u.id))
+        if (ids.size === 0) return void c.lines.push({ kind: 'skip', text: 'this repo releases nothing: no npm root, no release config, no units' })
+        const { reports, errors } = await collectReports(c.root, c.config)
+        for (const e of errors) c.warn(e)
+        reportDrift(c, reports.filter((r) => ids.has(r.id)))
+    },
+})
+
+export default releaseDrift

package/src/checks/SK026-asks-autoclose.check.ts

@@ -0,0 +1,44 @@
+// SK026 asks auto close (build/shipkit/built-in-checks.md): probe every open
+// ask's own `check:` and archive the ones that pass, so an act done in the
+// world leaves the queue without anyone editing a file. An open queue is no
+// warning: the hub and `shipkit needs` show it. A repo with no queue skips.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { checkAsks, listAsks } from '../asks/asks-queue.ts'
+import { check } from '../check.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export const asksAutoclose = check({
+    id: 'SK026',
+    blocking: false,
+    title: 'asks auto close',
+    description: 'no open ask whose own probe passes stays in the queue',
+    owner: 'build/shipkit/built-in-checks.md',
+    when: 'health',
+    never: "runs each open ask's own probe, a shell command that reads the world",
+    every: ['20h', '28h'],
+    // it only probes an ask that carries one, and archives one marked done
+    planOff: (env) => {
+        const dir = join(env.root, env.config.asks?.dir ?? LAYOUT.asks)
+        if (!existsSync(dir)) return 'no asks queue'
+        return listAsks(dir).some((a) => a.check != null || a.status === 'done') ? null : 'no open ask carries a probe'
+    },
+    run: async (c) => {
+        const dir = join(c.root, c.config.asks?.dir ?? LAYOUT.asks)
+        if (!existsSync(dir)) return void c.lines.push({ kind: 'skip', text: 'no asks queue in this repo' })
+        // archiving RENAMES files, and the release path runs the checks between
+        // its clean tree guard and `npm publish`: frozen means report only
+        if (c.frozen) return void c.lines.push({ kind: 'skip', text: 'asks not probed: a frozen run archives nothing' })
+        const events: string[] = []
+        await checkAsks(c.root, dir, (l) => events.push(l))
+        // `closed + archived <file>` / `archived <file>` are the queue's frozen stdout contract
+        for (const l of events) {
+            if (l.startsWith('closed') || l.startsWith('archived')) c.ok(`ask ${l}`)
+            // the queue could not run (another agent holds the write lease)
+            else if (l.startsWith('WARN')) c.warn(l.replace(/^WARN\s*/, ''))
+        }
+        if (!c.lines.some((l) => l.kind === 'ok')) c.ok('no open ask has a probe that passes')
+    },
+})
+
+export default asksAutoclose

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -0,0 +1,50 @@
+// SK027 agent wiki links (build/shipkit/built-in-checks.md): a repo's agent/
+// IS an md wiki (entry index.md, the CLAUDE.md include), so an orphan page or
+// a dangling ref there fails. A link that leaves agent/ but stays in the repo
+// is checked on disk; a pointer out of the repo (a house wiki) is backticked,
+// never a bare → or @. A repo without agent/index.md skips.
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
+import { check } from '../check.ts'
+import { lintMd } from '../wiki/lint-md.ts'
+
+export const agentWikiLinks = check({
+    id: 'SK027',
+    blocking: true,
+    title: 'agent wiki links',
+    description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
+    owner: 'meta/agent-folder.md',
+    // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
+    inputs: ['agent'],
+    run: (c) => {
+        if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
+        const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
+        const linked = lint.pages.filter((p) => !lint.orphans.includes(p))
+        for (const f of lint.orphans) {
+            const by = namingPage(c.root, f, linked)
+            const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
+            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)
+        }
+        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`)
+        if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
+    },
+})
+
+/** the linked page whose text already names an orphan (its path, its file
+ *  name, or a glob its file name matches), the one to turn into a link */
+function namingPage(root: string, orphan: string, pages: string[]): string | null {
+    const name = basename(orphan)
+    const stem = name.replace(/\.md$/, '')
+    for (const p of pages) {
+        const text = readFileSync(join(root, 'agent', p), 'utf8')
+        if (text.includes(orphan) || text.includes(name) || text.includes(`${stem}.`) || text.includes(`${stem} `)) return `agent/${p}`
+        for (const m of text.matchAll(/[\w.-]*\*[\w.*-]*/g)) {
+            const g = m[0]
+            if (g.replace(/[*.]/g, '').length < 3) continue
+            if (new Bun.Glob(g).match(name) || new Bun.Glob(`${g}.md`).match(name)) return `agent/${p}`
+        }
+    }
+    return null
+}
+
+export default agentWikiLinks

package/src/checks/SK028-readme.check.ts

@@ -0,0 +1,83 @@
+// SK028 readme (build/shipkit/built-in-checks.md): the README.md a repo's hub
+// page shows exists and carries what makes the repo recognizable at a glance.
+// A list of named requirements, each reporting its own line, so a new
+// mandatory item is one more entry. Read through `c` only, so the answer is
+// keyed on README.md and the images it points to, never on a clock.
+import { posix } from 'path'
+import { check } from '../check.ts'
+import type { CheckCtx } from '../core/check-ctx.ts'
+
+const README = 'README.md'
+
+/** every image source the README shows: markdown `![..](src)` and html
+ *  `<img src>`, code fences and inline code left out, since a sample there
+ *  shows nothing */
+export const imageRefs = (md: string): string[] => {
+    const prose = md.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, '').replace(/`[^`\n]*`/g, '')
+    const refs: { at: number; src: string }[] = []
+    for (const m of prose.matchAll(/!\[[^\]]*\]\(\s*<?([^\s)>]+)>?(?:\s+["'(][^)]*)?\)/g)) refs.push({ at: m.index, src: m[1]! })
+    for (const m of prose.matchAll(/<img\b[^>]*?\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) refs.push({ at: m.index, src: (m[1] ?? m[2] ?? m[3])! })
+    return refs.sort((a, b) => a.at - b.at).map((r) => r.src)
+}
+
+/** a status badge (ci, version, license) shows the repo's state, never what it looks like */
+const isBadge = (src: string): boolean => /(^|[/.])(shields\.io|badgen\.net)\//i.test(src) || /badge[^/]*\.svg([?#]|$)/i.test(src)
+
+/** where an image source lands: an https url, a repo file, or nowhere with why */
+const resolveImage = (c: CheckCtx, src: string): { ok: string } | { bad: string } => {
+    if (isBadge(src)) return { bad: `${src.slice(0, 60)} is a badge` }
+    if (/^https:\/\//i.test(src)) return { ok: src }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith('//')) return { bad: `${src.slice(0, 60)} is neither an https url nor a repo file` }
+    let rel: string
+    try {
+        rel = posix.normalize(decodeURI(src.replace(/[?#].*$/, '')).replace(/^\/+/, ''))
+    } catch {
+        return { bad: `${src} is not a readable path` }
+    }
+    if (rel === '.' || rel.startsWith('../')) return { bad: `${src} points out of the repo` }
+    return c.exists(rel, 'file') ? { ok: rel } : { bad: `${rel} is missing` }
+}
+
+type Finding = { ok: string } | { warn: string; fix: string }
+type Requirement = { name: string; test: (c: CheckCtx, md: string) => Finding }
+
+/** what every README carries, in order. Add an entry to make one more item mandatory */
+const REQUIREMENTS: Requirement[] = [
+    {
+        name: 'screenshot',
+        test: (c, md) => {
+            const found = imageRefs(md).map((src) => resolveImage(c, src))
+            const shown = found.find((f): f is { ok: string } => 'ok' in f)
+            if (shown != null) return { ok: `${README} shows a screenshot: ${shown.ok}` }
+            const why = found.map((f) => (f as { bad: string }).bad)
+            return {
+                warn: `${README}: screenshot: ${why.length === 0 ? 'no image at all' : `no image resolves (${why.join(', ')})`}`,
+                fix: `add a screenshot to README.md: ![what it looks like](docs/screenshot.png), a file in the repo, or an https url; ${OFF}`,
+            }
+        },
+    },
+]
+
+/** the other way out, for a repo that cannot show one: the rule off, with the
+ *  reason `defineRepo` requires (core/when.ts) */
+const OFF = `or, when this repo cannot show one, turn the rule off with the reason: when: { SK028: 'off:<why this repo shows no screenshot>' } in repo.config.ts, inside its shipkit gate block`
+
+export const readme = check({
+    id: 'SK028',
+    blocking: false,
+    title: 'readme',
+    description: 'README.md exists and shows at least one screenshot',
+    owner: 'build/shipkit/built-in-checks.md',
+    run: (c) => {
+        const md = c.read(README)
+        if (md == null) return c.warn(`${README}: exists: no ${README} at the repo root`, `write README.md: what the repo is, and a screenshot of it; ${OFF}`)
+        c.ok(`${README} exists`)
+        for (const r of REQUIREMENTS) {
+            const f = r.test(c, md)
+            if ('ok' in f) c.ok(f.ok)
+            else c.warn(f.warn, f.fix)
+        }
+    },
+})
+
+export default readme

package/src/cli/cmd_Assets.ts

@@ -99,7 +99,7 @@ export class AssetsCheckCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Assets',
-        description: 'kit loads, kinds valid, cflow workflows load, drafts present, backend reachable, identity outputs present',
+        description: 'kit loads, kinds valid, cflow workflows load, drafts present, identity outputs present',
         examples: [['health-check the asset pipeline', 'shipkit assets check']],
     })
 

package/src/cli/cmd_Ci.ts

@@ -24,6 +24,7 @@ export class CiCommand extends Command {
             ['run everything, take nothing from the cache', 'shipkit ci --fresh'],
             ['include an opt in check', 'shipkit ci --with up:itch'],
             ['in the background, read it back with shipkit status', 'shipkit ci --detach'],
+            ['every line, the ones nobody acts on included', 'shipkit ci --verbose'],
         ],
     })
 
@@ -38,6 +39,8 @@ export class CiCommand extends Command {
     fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
+    verbose = Option.Boolean('--verbose', false, { description: 'print every line, the ones nobody acts on included: a clean fix pass, the machine pool, the test tier, the cache declarations, the checks not in this run, the cache counts' })
+
     detach = Option.Boolean('--detach', false, { description: 'start this gate in the background and return at once with a run id. `shipkit status <id>` prints it. The gate is an ordinary one: same cache, same run record' })
     job = Option.String('--job', { hidden: true })
 
@@ -72,6 +75,7 @@ export class CiCommand extends Command {
             ...this.only.flatMap((v) => ['--only', v]),
             ...(this.fresh ? ['--fresh'] : []),
             ...(this.full ? ['--full'] : []),
+            ...(this.verbose ? ['--verbose'] : []),
         ]
     }
 
@@ -92,6 +96,7 @@ export class CiCommand extends Command {
                 onlyIds: this.only,
                 fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
+                ...(this.verbose ? { verbose: true } : {}),
             }
             const print = (l: string): void => { this.context.stdout.write(`${l}\n`) }
             // on a machine with the home, the repo's hub runs it (home/via-hub.ts)

package/src/cli/cmd_CrossRepoActivity.ts

@@ -0,0 +1,119 @@
+// shipkit cross-repo-activity: the activity page in the console. The rows come
+// from activityOf, the one computation the daemon's route serves the page, so
+// the two can never disagree; this file only renders them as text. It reads
+// local git and each repo's run record directly and needs no daemon: when one
+// answers, its plan says which checks each repo declares today, as the page's
+// status dot counts them.
+import { homedir } from 'os'
+import { Command, Option } from 'clipanion'
+import { activityOf, type Declared } from '../home/activity.ts'
+import { ageShort, clampCap, DEFAULT_CAP, DEFAULT_MINUTES, dirtWords, idleRow, upstreamWords, type ActivityAnswer, type ActivityCommit, type ActivityRow } from '../home/activity-shape.ts'
+import { railRepos } from '../serve/project-gutter-route.ts'
+
+/** a span as typed: `10m`, `1h`, `3d`, `90` (minutes); null when it is none */
+export function spanMinutes(v: string): number | null {
+    const m = /^(\d+(?:\.\d+)?)\s*(m|min|h|d)?$/.exec(v.trim())
+    if (m == null) return null
+    const n = Number(m[1]) * (m[2] === 'h' ? 60 : m[2] === 'd' ? 1440 : 1)
+    return n > 0 ? Math.round(n) : null
+}
+
+/** single dash spellings of the long options, as typed: `-max-commit 3` */
+export function aliasArgs(argv: string[]): string[] {
+    return argv.map((a) => (/^-max-(commit|age)(=|$)/.test(a) ? `-${a}` : a))
+}
+
+/** the declared check ids from a running daemon's plan; null when none answers */
+export async function daemonDeclared(port = Number(process.env.SHIPKIT_DAEMON_PORT ?? 4798)): Promise<Declared | null> {
+    try {
+        const r = await fetch(`http://127.0.0.1:${port}/api/home/planned.json`, { signal: AbortSignal.timeout(1_500) })
+        if (!r.ok) return null
+        const j = (await r.json()) as { rows: { repo: string; check: string }[] }
+        const by = new Map<string, Set<string>>()
+        for (const row of j.rows) {
+            if (!by.has(row.repo)) by.set(row.repo, new Set())
+            by.get(row.repo)!.add(row.check)
+        }
+        return (name) => by.get(name) ?? null
+    } catch {
+        return null
+    }
+}
+
+const dot = (r: ActivityRow): string => {
+    const c = r.status
+    if (c == null) return '·'
+    if (c.state === 'red') return `● ${c.reds.length} red`
+    if (c.state === 'orange') return `● ${c.warns.length} warn`
+    return '● green'
+}
+
+const commitLine = (c: ActivityCommit, now: number, old: boolean): string =>
+    `    ${ageShort(c.at, now).padStart(3)}  ${c.sha}  ${c.pushed ? '✓' : '↑'} ${c.branch == null ? '' : `[${c.branch}] `}${c.title}${old ? '  (last commit, before the window)' : ''}`
+
+/** the page's rows as text: busy repos first, then the quiet ones, each with
+ *  its status, branch, upstream, uncommitted line and commits */
+export function renderActivity(a: ActivityAnswer, cap: number): string[] {
+    const out: string[] = []
+    const busy = a.rows.filter((r) => !idleRow(r))
+    const quiet = a.rows.filter(idleRow)
+    for (const r of [...busy, ...quiet]) {
+        const branch = r.branch ?? (r.detached == null ? '' : `detached ${r.detached}`)
+        out.push(`${r.name}  ${dot(r)}  ${branch}  (${upstreamWords(r)})`)
+        for (const c of r.failing ?? []) {
+            out.push(`    ${c.status === 'fail' ? '✗' : '!'} ${c.id}${c.at == null ? '' : ` (${ageShort(c.at, a.now)})`}`)
+            for (const l of c.lines) out.push(`        ${l}`)
+        }
+        if (r.error != null) out.push(`    git failed: ${r.error}`)
+        const dirt = r.error == null ? dirtWords(r) : ''
+        if (dirt !== '') {
+            out.push(`    uncommitted: ${dirt}`)
+            const mark = { staged: 'S', modified: 'M', untracked: '?' } as const
+            for (const f of r.files) out.push(`      ${mark[f.kind]} ${f.path}`)
+        }
+        for (const c of r.commits.slice(0, cap)) out.push(commitLine(c, a.now, false))
+        if (r.commits.length > cap) out.push(`    … ${r.commits.length - cap} more`)
+        if (r.last != null) out.push(commitLine(r.last, a.now, true))
+        if (r.commits.length === 0 && r.last == null && r.error == null) out.push('    no commit yet')
+    }
+    out.push(`${busy.length} busy, ${quiet.length} quiet, read in ${a.ms}ms`)
+    return out
+}
+
+export class CrossRepoActivityCommand extends Command {
+    static override paths = [['cross-repo-activity'], ['activity']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the activity page in the console: every house repo (archived ones left out), its checks, branch, upstream, uncommitted work and commits in a window. The same computation the page reads, local git only, no daemon needed',
+        examples: [
+            ['the last 30 minutes, 3 commits per repo, as the page opens', 'shipkit cross-repo-activity'],
+            ['the same, by the page name', 'shipkit activity'],
+            ['the last 3 hours, up to 10 commits per repo', 'shipkit cross-repo-activity --max-age 3h --max-commit 10'],
+            ['the route\'s exact payload', 'shipkit cross-repo-activity --max-age 30m --json'],
+        ],
+    })
+
+    maxAge = Option.String('--max-age', { required: false, description: `how far back: 10m, 1h, 3d, or minutes (default ${DEFAULT_MINUTES}m)` })
+    maxCommit = Option.String('--max-commit', { required: false, description: `commits shown per repo, 1 to 15 (default ${DEFAULT_CAP}). -max-commit works too` })
+    json = Option.Boolean('--json', false, { description: 'the daemon route\'s exact payload: { now, minutes, rows, ms }' })
+
+    async execute(): Promise<number> {
+        const minutes = this.maxAge == null ? DEFAULT_MINUTES : spanMinutes(this.maxAge)
+        if (minutes == null) {
+            this.context.stderr.write(`--max-age must be a span like 10m, 1h or 3d, got ${JSON.stringify(this.maxAge)}\n`)
+            return 2
+        }
+        const cap = clampCap(this.maxCommit ?? DEFAULT_CAP)
+        const declared = await daemonDeclared()
+        // HOME as the shell has it now: the house include names `~`
+        const a = await activityOf(railRepos(process.cwd(), process.env.HOME || homedir()), minutes, Date.now(), declared)
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        for (const l of renderActivity(a, cap)) this.context.stdout.write(`${l}\n`)
+        if (declared == null) this.context.stdout.write('note: no daemon answered, so every check a run record holds counts, declared today or not\n')
+        return 0
+    }
+}

package/src/cli/cmd_GlobalProcesses.ts

@@ -0,0 +1,155 @@
+// shipkit global-processes: the overview's processes table in the console,
+// shipkit's own (pm, the daemon, the web) first. The rows come from pm's own
+// answer through process-rows.ts, the one model the page draws, so the two can
+// never disagree; this file only asks pm and the daemon and renders them as
+// text. With pm down it reads the declared units the way pm does
+// (pm-config.ts) and marks each one unknown.
+import { homedir } from 'os'
+import { Command, Option } from 'clipanion'
+import { daemonPort, daemonUrl, homePort, pmPort, pmUrl } from '../home/home-paths.ts'
+import { houseRootOf } from '../home/home-start.ts'
+import type { PmAnswer } from '../home/pm.ts'
+import { coreGroup, declaredRow, groupRows, processGroups, stateWords, type ProcessGroup } from '../home/process-rows.ts'
+import type { PmConfig } from '../home/pm-config.ts'
+import { readPmConfig } from '../home/run-pm.ts'
+import { railRepos } from '../serve/project-gutter-route.ts'
+
+export type GlobalProcessesAnswer = {
+    /** pm as it answered, null when it did not */
+    pm: { pid: number; version: string } | null
+    now: number
+    groups: ProcessGroup[]
+    /** the unit files that would not load */
+    errors: string[]
+    /** with pm down: whether a house was found to read the declared units from */
+    house: boolean
+}
+
+export type GlobalProcessesDeps = {
+    pm: () => Promise<PmAnswer | null>
+    /** the daemon's identity, for its version; null when it does not answer */
+    daemon?: () => Promise<{ version: string } | null>
+    /** the declared units, read like pm reads them; null when no house is found */
+    declared: () => Promise<Pick<PmConfig, 'processes' | 'errors'> | null>
+    /** the project list's order */
+    order: string[]
+    now: number
+}
+
+/** the ports this shell would find pm and its children on */
+const localPorts = () => ({ pm: pmPort(), daemon: daemonPort(), web: homePort() })
+
+/** pm's answer, shipkit's own rows first; the declared units as unknown when
+ *  pm does not answer */
+export async function globalProcessesAnswer(d: GlobalProcessesDeps): Promise<GlobalProcessesAnswer> {
+    const [pm, daemon] = await Promise.all([d.pm(), d.daemon?.() ?? null])
+    const core = { daemonVersion: daemon?.version ?? null, ports: localPorts() }
+    if (pm != null) return { pm: { pid: pm.pid, version: pm.version }, now: d.now, groups: processGroups(pm, d.order, core), errors: pm.unitErrors, house: true }
+    const c = await d.declared()
+    return { pm: null, now: d.now, groups: [coreGroup(null, core), ...groupRows((c?.processes ?? []).map(declaredRow), d.order)], errors: c?.errors ?? [], house: c != null }
+}
+
+/** the daemon's identity at /hub.json, or null */
+export async function askDaemon(url = daemonUrl()): Promise<{ version: string } | null> {
+    try {
+        const r = await fetch(`${url}/hub.json`, { signal: AbortSignal.timeout(3_000) })
+        const j = r.ok ? ((await r.json()) as { hub?: string; version?: string }) : null
+        return j?.hub === 'shipkit-home' && typeof j.version === 'string' ? { version: j.version } : null
+    } catch {
+        return null
+    }
+}
+
+/** pm's status answer, or null when it does not answer */
+export async function askPm(url = pmUrl()): Promise<PmAnswer | null> {
+    try {
+        const r = await fetch(`${url}/api/pm/status.json`, { signal: AbortSignal.timeout(1_500) })
+        if (!r.ok) return null
+        const j = (await r.json()) as PmAnswer
+        return j.pm === 'shipkit-pm' ? j : null
+    } catch {
+        return null
+    }
+}
+
+/** the project list's order and the declared units, read from disk the way
+ *  pm reads them: what the table falls back on while pm does not answer */
+export function localProcessDeps(cwd: string): Pick<GlobalProcessesDeps, 'declared' | 'order'> {
+    // HOME as the shell has it now: the house include names `~`
+    const home = process.env.HOME || homedir()
+    let order: string[] = []
+    try {
+        order = railRepos(cwd, home).map((r) => r.name)
+    } catch {
+        // no rail from here: the groups sort by name
+    }
+    return {
+        order,
+        declared: async () => {
+            const root = houseRootOf(cwd)
+            if (root == null) return null
+            try {
+                return await readPmConfig(root)
+            } catch (e) {
+                return { processes: [], errors: [(e as Error).message] }
+            }
+        },
+    }
+}
+
+const pad = (s: string, n: number): string => (s.length >= n ? s : s + ' '.repeat(n - s.length))
+
+/** the table as text: shipkit's own, then per repo, one line per process,
+ *  its note and last log line under it */
+export function renderGlobalProcesses(a: GlobalProcessesAnswer): string[] {
+    const out: string[] = []
+    const n = a.groups.reduce((k, g) => k + (g.core ? 0 : g.rows.length), 0)
+    if (a.pm != null) out.push(`pm pid ${a.pm.pid}, shipkit ${a.pm.version}: ${n} global process${n === 1 ? '' : 'es'}`)
+    else if (!a.house) out.push(`pm does not answer on ${pmUrl()}, and no house wiki is found from ${process.cwd()}, so no declared process is known`)
+    else out.push(`pm does not answer on ${pmUrl()}: the ${n} declared process${n === 1 ? '' : 'es'} below, each state unknown`)
+    const rows = a.groups.flatMap((g) => g.rows)
+    const w = {
+        state: Math.max(0, ...rows.map((r) => stateWords(r, a.now).length)),
+        label: Math.max(0, ...rows.map((r) => r.label.length)),
+        host: Math.max(0, ...rows.map((r) => (r.host ?? '').length)),
+    }
+    for (const g of a.groups) {
+        out.push(g.repo)
+        for (const r of g.rows) {
+            const cells = [`  ● ${pad(stateWords(r, a.now), w.state)}`, pad(r.label, w.label), pad(r.host ?? '', w.host), pad(r.pid == null ? '' : `pid ${r.pid}`, 10), r.version == null ? '' : `shipkit ${r.version}`]
+            out.push(cells.join('  ').trimEnd())
+            if (r.note != null) out.push(`      ${r.note}`)
+            // shipkit's own logs only matter while one is not up
+            if (r.lastLog != null && !(r.core && r.status === 'up')) out.push(`      log: ${r.lastLog}`)
+        }
+    }
+    if (a.pm != null && n === 0) out.push('none declared: a repo declares one in a <name>.shipkit.ts file, as export default globalProcess({...})')
+    for (const e of a.errors) out.push(`WARN ${e}`)
+    return out
+}
+
+export class GlobalProcessesCommand extends Command {
+    static override paths = [['global-processes'], ['gp']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'every process on the machine and its state, as the overview shows them: shipkit\'s own (pm, the daemon, the web, with their version) first, then per repo, one line per global process with its state, url, pid and last log line. When pm is down, the declared ones with their state unknown. Always exits 0',
+        examples: [
+            ['the table', 'shipkit global-processes'],
+            ['the same, short', 'shipkit gp'],
+            ['the rows the overview draws, as json', 'shipkit global-processes --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'the rows as json: { pm, now, groups, errors, house }, groups exactly as the overview draws them' })
+
+    async execute(): Promise<number> {
+        const a = await globalProcessesAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), now: Date.now() })
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        for (const l of renderGlobalProcesses(a)) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Keys.ts

@@ -8,7 +8,8 @@
 import { createHash } from 'crypto'
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
-import { envTier, FULL_TESTS_ENV, gateChecks } from '../ledger/gate-checks.ts'
+import { envTier, FULL_TESTS_ENV, gateInventory } from '../ledger/gate-checks.ts'
+import { planGap, plannable } from '../plan/repo-source.ts'
 import { KeyLayer } from '../ledger/git-key.ts'
 import { Ledger } from '../ledger/ledger.ts'
 import { gateBinary } from '../ledger/toolchain-identity.ts'
@@ -42,14 +43,22 @@ export class KeysCommand extends Command {
         // every task's env, which is in the key, so a surface that renders keys
         // without it renders a tier nobody asked for
         const tier = this.full ? 'full' : envTier()
-        const decls = await gateChecks(root, c, { tier })
+        const rows = await gateInventory(root, c, { tier })
+        const decls = rows.map((r) => r.decl)
+        // the plan's side of the burn-down: a check nothing keys and that
+        // declares no cadence is re-asked on a guess. A built-in there is a
+        // toolkit bug, a repo check rides the default range until it declares
+        const planGaps = rows.filter(plannable).flatMap((r) => {
+            const gap = planGap(r)
+            return gap == null ? [] : [{ id: r.decl.id, from: r.from, gap }]
+        })
         const layer = KeyLayer.open(root, decls, { cliEntry: gateBinary() })
         const keys = layer.keys()
         const out = (l: string): void => { this.context.stdout.write(`${l}\n`) }
 
         if (this.json) {
             const drift = this.rescan ? layer.rescan() : null
-            out(JSON.stringify({ tier, checks: keys, burnDown: layer.registration.burnDown, errors: layer.registration.errors, layerMs: Math.round(layer.openMs), scanMs: Math.round(layer.scanMs), failure: layer.failure, drift }))
+            out(JSON.stringify({ tier, checks: keys, burnDown: layer.registration.burnDown, planGaps, errors: layer.registration.errors, layerMs: Math.round(layer.openMs), scanMs: Math.round(layer.scanMs), failure: layer.failure, drift }))
             return layer.registration.errors.length > 0 || layer.failure != null ? 1 : 0
         }
 
@@ -115,6 +124,11 @@ export class KeysCommand extends Command {
         const decided = new Set(layer.decls.filter((d) => d.never != null && d.never !== '').map((d) => d.id))
         const shown = this.burnDown ? keys.filter((k) => k.population === 'none' && !decided.has(k.id)) : keys
         for (const k of shown) out(`${k.population.padEnd(7)} ${k.id.padEnd(28)} ${k.key ?? `— ${k.reason ?? ''}`}`)
+        if (planGaps.length > 0) out('')
+        for (const g of planGaps)
+            out(g.from === 'repo'
+                ? `WARN ${g.id}: ${g.gap}, so the plan runs it every 20h..28h. Declare inputs, a cacheKey, ttl or every`
+                : `FAIL: built-in ${g.id}: ${g.gap}. A toolkit bug: the plan waits for a save until it declares one`)
 
         const content = keys.filter((k) => k.population === 'content').length
         const reads = keys.filter((k) => k.population === 'reads').length