rvlib-shipkit 1.2.0 → 1.3.0

package/src/checks/SK015-nested-repo.check.ts

@@ -3,6 +3,7 @@
 // sites that write history refuse on the disk fact either way (core/nesting.ts),
 // so this rule is about the declaration telling the truth to the next reader.
 import { nestedIn } from '../core/nesting.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
 import { check } from '../check.ts'
 
 export const nestedRepo = check({
@@ -11,7 +12,10 @@ export const nestedRepo = check({
     title: 'nested repo',
     description: 'a config inside a larger work tree declares `nested: true`, and only there',
     owner: 'build/shipkit/config-keys.md',
-    never: 'reads where the git work tree root sits, which no content inside the repo describes',
+    // the declaration, and where the git work tree root sits, which no tree
+    // id describes, so its path is the rest of the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `nested=${env.config.nested === true}|top=${nestedIn(env.root) ?? 'root'}`,
     run: (c) => {
         const top = nestedIn(c.root)
         const declared = c.config.nested === true

package/src/checks/SK017-vscode-hub-task.check.ts

@@ -11,6 +11,7 @@ import { basename } from 'path'
 import { check } from '../check.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { whenOfTask } from '../core/when.ts'
 import { hubProblemMatcher } from '../problems/problem-line.ts'
 import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
@@ -165,6 +166,10 @@ function ownTasks(c: CheckCtx): { text: string } | 'none' | 'linked' {
     return text == null ? 'none' : { text }
 }
 
+/** a package published to npm is worked on by strangers, whose editor
+ *  runs these tasks */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${TASKS} belongs to every contributor, so it is never rewritten`
+
 export const vscodeHubTask = check({
     id: 'SK017',
     // a stale editor file is behind, not broken: it warns, and the fix pass
@@ -174,6 +179,7 @@ export const vscodeHubTask = check({
     description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
     owner: 'build/vscode-tasks.md',
     run: (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const own = ownTasks(c)
         if (own === 'none') return c.ok(`no ${TASKS}, so there is no hub task to wire`)
         if (own === 'linked') return c.ok(`.vscode/ is a link to a shared dir, left alone`)
@@ -185,6 +191,7 @@ export const vscodeHubTask = check({
         for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
     },
     fix: (c) => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const own = ownTasks(c)
         if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }
         const r = repairTasks(own.text, { typecheckOn: typecheckOn(c) })

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -3,7 +3,9 @@
 // rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
 // newer than the one this process runs: a rule or an api that pin relies on
 // is absent here until the house copy catches up.
+import { join } from 'path'
 import { LIB_VERSION } from '../core/lib-version.ts'
+import { fileStamp } from '../core/file-stamp.ts'
 import { check } from '../check.ts'
 
 type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -23,8 +25,10 @@ export const machineRunsThePin = check({
     title: 'machine runs the pin',
     description: 'the shipkit this machine runs is at least the version this repo pins',
     owner: 'build/shipkit.md',
-    // the running version is no file of the repo
-    cacheKey: () => LIB_VERSION,
+    // the pin, the install (gitignored) and the version this machine runs,
+    // which is no file of the repo
+    inputs: ['package.json'],
+    cacheKey: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}`,
     run: (c) => {
         const pkg = c.json<Pkg>('package.json')
         const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]

package/src/checks/SK024-identity-colors.check.ts

@@ -3,7 +3,9 @@
 // surface that shows the repo (the home page header, its rail tile) draws it
 // in its own colour. The fix derives them from the repo icon, or from a hue
 // hashed from the name, and writes that one key, every other byte kept.
+import { join } from 'path'
 import { check } from '../check.ts'
+import { fileStamp } from '../core/file-stamp.ts'
 import { configName, CONFIG_FILE, deriveIdentity, identityRefusal, INSTALLED_CONFIG_SRC } from '../core/identity.ts'
 import { declaresIdentity, identityOfText, identityProblem, setIdentityText } from '../core/identity-color.ts'
 
@@ -16,6 +18,9 @@ export const identityColors = check({
     title: 'identity colors',
     description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
     owner: 'build/shipkit/built-in-checks.md',
+    // the config, and the installed lib that says whether it knows the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}`,
     run: (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return c.note(`no ${CONFIG_FILE}`)

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,28 @@
+// 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 cross wiki pointer (into a house wiki) is
+// backticked, never a bare → or @, which reads as an agent local link and
+// dangles. A repo without agent/index.md skips.
+import { existsSync } from 'fs'
+import { 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' })
+        for (const f of lint.orphans) c.fail(`agent/${f}: orphan, unreachable from agent/index.md: link it from a page or delete it`)
+        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found (backtick a cross wiki ref; fix or delete the pointer)`)
+        if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
+    },
+})
+
+export default agentWikiLinks

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

@@ -0,0 +1,79 @@
+// 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',
+            }
+        },
+    },
+]
+
+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')
+        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,116 @@
+// 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)})`)
+        if (r.status != null && r.status.reds.length > 0) out.push(`    failing: ${r.status.reds.map((id) => (r.status!.since[id] == null ? id : `${id} (${ageShort(r.status!.since[id]!, a.now)})`)).join(', ')}`)
+        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
+    }
+}