rvlib-shipkit 1.1.1 → 1.3.0

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
+    }
+}

package/src/cli/cmd_Home.ts

@@ -0,0 +1,170 @@
+// shipkit pm, daemon, web and gui: the machine's one app. Thin clipanion surface; logic in home/.
+import { Command, Option } from 'clipanion'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { fileURLToPath } from 'url'
+import { basename } from 'path'
+import { markAutostart } from '../home/autostart.ts'
+import { installHome, uninstallHome } from '../home/home-launchd.ts'
+import { homeInstalled, houseCli, houseRootOf, openWindow, startHome } from '../home/home-start.ts'
+import { homeUp, homeUrl, hubBase } from '../home/home-paths.ts'
+import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
+import { homedir } from 'os'
+import { execPm, runPm } from '../home/run-pm.ts'
+import { runDaemon } from '../home/run-daemon.ts'
+import { runWeb } from '../home/run-web.ts'
+
+const OWN_CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+
+const io = (c: Command) => ({
+    print: (l: string) => c.context.stdout.write(`${l}\n`),
+    printErr: (l: string) => c.context.stderr.write(`${l}\n`),
+})
+
+/** the --port value, undefined when absent, null when it is not a port */
+function portOf(c: Command, raw: string | undefined): number | undefined | null {
+    if (raw == null) return undefined
+    const port = Number(raw)
+    if (Number.isInteger(port) && port > 0) return port
+    c.context.stderr.write(`FAIL --port '${raw}' is not a port number\n`)
+    return null
+}
+
+export class PmCommand extends Command {
+    // `home` is the name agents installed before pm still run
+    static override paths = [['pm'], ['home']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the machine\'s process manager: runs `shipkit daemon` and `shipkit web` as detached children, starts one again when it dies, owns the global processes every house repo declares in its .shipkit.ts files, and serves its api on port 4797 (SHIPKIT_PM_PORT). A pm restarted or killed leaves its children running and the next one adopts them. Run from the repo that hosts the house wiki',
+        examples: [
+            ['run pm in this terminal', 'shipkit pm'],
+            ['on test ports', 'SHIPKIT_PM_PORT=4887 SHIPKIT_HOME_PORT=4889 SHIPKIT_DAEMON_PORT=4888 SHIPKIT_HOME_DIR=/tmp/home shipkit pm'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'pm port (default 4797, or SHIPKIT_PM_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        if (execPm({ port })) return 0
+        return runPm(process.cwd(), io(this), { port })
+    }
+}
+
+export class DaemonCommand extends Command {
+    static override paths = [['daemon']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the home\'s daemon: loads every house repo hub in this one process and serves their api, their run streams and the home api under /r/<repo>/ on an internal port. No page: `shipkit web` serves it. Run from the repo that hosts the house wiki',
+        examples: [
+            ['the daemon alone', 'shipkit daemon'],
+            ['on another port', 'shipkit daemon --port 4888'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'daemon port (default 4798, or SHIPKIT_DAEMON_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        return runDaemon(process.cwd(), io(this), { port })
+    }
+}
+
+export class WebCommand extends Command {
+    static override paths = [['web']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the home\'s page: one server on the home port that serves the page and proxies every api request to the daemon, so a browser only sees this origin. It loads no repo',
+        examples: [
+            ['the page alone', 'shipkit web'],
+            ['on another port', 'shipkit web --port 4889'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'home port (default 4799, or SHIPKIT_HOME_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        return runWeb(io(this), { port })
+    }
+}
+
+export class PmInstallCommand extends Command {
+    static override paths = [['pm', 'install'], ['home', 'install']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'keep pm running, and through it the daemon and the web: a macOS LaunchAgent starts it now and at every login, and restarts it when it dies. Idempotent',
+        examples: [['install from the house repo', 'shipkit pm install']],
+    })
+
+    async execute(): Promise<number> {
+        markAutostart(true)
+        return installHome({ root: process.cwd(), cli: houseCli(process.cwd(), OWN_CLI), print: io(this).print })
+    }
+}
+
+export class PmUninstallCommand extends Command {
+    static override paths = [['pm', 'uninstall'], ['home', 'uninstall']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'stop pm, the daemon and the web, and remove the LaunchAgent. The resources and repo processes keep running. No later command starts pm on its own until `shipkit pm install`',
+        examples: [['remove the agent', 'shipkit pm uninstall']],
+    })
+
+    async execute(): Promise<number> {
+        // a machine that said no: no later command starts pm again on its own
+        markAutostart(false)
+        return uninstallHome({ print: io(this).print })
+    }
+}
+
+export class GuiCommand extends Command {
+    static override paths = [['gui']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'open the home in its own window, outside VS Code and the browser, starting pm first when the web does not answer (and installing its LaunchAgent the first time). Every call opens one more window',
+        examples: [
+            ['a window on the home', 'shipkit gui'],
+            ['a window on one repo', 'shipkit gui my-app'],
+            ['a window on the repo you stand in', 'shipkit gui .'],
+        ],
+    })
+
+    repo = Option.String({ required: false, name: 'repo' })
+
+    async execute(): Promise<number> {
+        const out = io(this)
+        if (!(await homeUp())) {
+            // pm runs the web: ensure pm, then wait for the web
+            try {
+                if (!homeInstalled()) {
+                    const root = houseRootOf(process.cwd())
+                    if (root == null) {
+                        out.printErr(`FAIL: no pm runs, and ${process.cwd()} is not a house repo, so there is none to install it from. Run \`shipkit gui\` once from any repo whose CLAUDE.md includes the house wiki`)
+                        return 1
+                    }
+                    const code = await installHome({ root, cli: houseCli(root, OWN_CLI), print: out.print })
+                    if (code !== 0) return code
+                }
+                await startHome({ need: 'web' })
+            } catch (e) {
+                out.printErr(`FAIL: ${(e as Error).message}`)
+                return 1
+            }
+        }
+        // `.` = the repo you stand in, named the way the rail names it
+        const name = this.repo === '.' && houseIndex(homeRepo(process.cwd()), homedir()) != null ? basename(homeRepo(process.cwd())) : this.repo
+        const url = `${homeUrl()}${name != null && name !== '.' ? `${hubBase(name)}/` : '/'}`
+        const cmd = openWindow(url, { version: LIB_VERSION, warn: out.printErr })
+        out.print(`ok: a home window on ${url}${cmd[0] === 'open' ? ' (the shipkit app)' : ''}`)
+        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

package/src/cli/cmd_Overview.ts

@@ -0,0 +1,98 @@
+// shipkit overview: the overview page in the console, top to bottom as the
+// page: the monitor widgets as the daemon last rendered them, their html read
+// as text by widget-text.ts, then the processes through
+// globalProcessesAnswer (the rows `shipkit gp` prints: pm, the daemon and the
+// web first, then the global processes). Nothing renders a widget here: the
+// daemon holds the render, and while it is down the monitor is unknown.
+import { Command, Option } from 'clipanion'
+import { daemonUrl } from '../home/home-paths.ts'
+import type { WidgetsAnswer } from '../home/home-routes.ts'
+import type { ChildView, PmAnswer } from '../home/pm.ts'
+import { splitWidgetHead, widgetText } from '../home/widget-text.ts'
+import { askDaemon, askPm, globalProcessesAnswer, localProcessDeps, renderGlobalProcesses, type GlobalProcessesAnswer, type GlobalProcessesDeps } from './cmd_GlobalProcesses.ts'
+
+export type OverviewAnswer = {
+    now: number
+    /** pm as it answered: its own pid and version, its children; null when it did not */
+    pm: { pid: number; since: number | null; version: string; children: ChildView[] } | null
+    /** the daemon's identity, asked of the daemon itself; null when it does not answer */
+    daemon: { version: string } | null
+    /** the global processes, exactly as `shipkit global-processes --json` */
+    processes: GlobalProcessesAnswer
+    /** the daemon's widgets route payload; null when the daemon does not answer */
+    widgets: WidgetsAnswer | null
+}
+
+export type OverviewDeps = Pick<GlobalProcessesDeps, 'declared' | 'order'> & {
+    pm: () => Promise<PmAnswer | null>
+    daemon: () => Promise<{ version: string } | null>
+    widgets: () => Promise<WidgetsAnswer | null>
+    now: number
+}
+
+async function getJson<T>(url: string): Promise<T | null> {
+    try {
+        const r = await fetch(url, { signal: AbortSignal.timeout(3_000) })
+        return r.ok ? ((await r.json()) as T) : null
+    } catch {
+        return null
+    }
+}
+
+/** the daemon's widgets route payload, or null */
+export const askWidgets = (url = daemonUrl()): Promise<WidgetsAnswer | null> => getJson<WidgetsAnswer>(`${url}/api/home/widgets.json`)
+
+export async function overviewAnswer(d: OverviewDeps): Promise<OverviewAnswer> {
+    const [pm, daemon, widgets] = await Promise.all([d.pm(), d.daemon(), d.widgets()])
+    const processes = await globalProcessesAnswer({ pm: async () => pm, daemon: async () => daemon, declared: d.declared, order: d.order, now: d.now })
+    return { now: d.now, pm: pm == null ? null : { pid: pm.pid, since: pm.since ?? null, version: pm.version, children: pm.children }, daemon, processes, widgets }
+}
+
+const indent = (lines: string[], by = '  '): string[] => lines.map((l) => by + l)
+
+/** the page as text: the monitor, then the processes (shipkit's own first),
+ *  each section saying what is unknown and why when pm or the daemon does not
+ *  answer */
+export function renderOverview(a: OverviewAnswer): string[] {
+    const out: string[] = ['monitor']
+    if (a.widgets == null) out.push(`  the daemon does not answer on ${daemonUrl()}, and it renders the widgets: the monitor is unknown`)
+    else {
+        if (a.widgets.widgets.length === 0 && a.widgets.errors.length === 0) out.push('  no widget declared: a repo declares one in a <name>.shipkit.ts file, as export default widget({...})')
+        for (const x of a.widgets.widgets) {
+            const { head, body } = splitWidgetHead(x.html ?? '')
+            out.push(`  ${x.title}${head == null ? '' : ` · ${widgetText(head).join(' ')}`}`)
+            if (x.error != null) out.push(`    WARN ${x.error}`)
+            if (x.html == null) out.push('    not rendered yet')
+            else out.push(...indent(widgetText(body), '    '))
+        }
+        for (const e of a.widgets.errors) out.push(`  WARN ${e}`)
+    }
+    out.push('processes', ...indent(renderGlobalProcesses(a.processes)))
+    if (a.daemon == null) out.push(`  the daemon does not answer on ${daemonUrl()}`)
+    return out
+}
+
+export class OverviewCommand extends Command {
+    static override paths = [['overview']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the overview page in the console: every monitor widget as text, from the html the daemon last rendered, then the processes as `shipkit gp` prints them (pm, the daemon and the web with pid, uptime and version, then every global process). When pm or the daemon does not answer, it says which and prints what is still known. Always exits 0',
+        examples: [
+            ['the overview', 'shipkit overview'],
+            ['the answers the page reads, as json', 'shipkit overview --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'the answers as json: { now, pm, daemon, processes, widgets }, processes as `shipkit gp --json`, widgets the daemon route\'s payload' })
+
+    async execute(): Promise<number> {
+        const a = await overviewAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        for (const l of renderOverview(a)) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}