rvlib-shipkit 1.4.0 → 1.6.0

package/src/cli/cmd_Check.ts

@@ -14,14 +14,15 @@ export class CheckCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every check except the build steps. `shipkit ci` runs these too and is what you normally want. --fix applies check autofixes',
+        description: 'every check except the build steps: the slower health surface',
+        details: 'every check except the build steps. `shipkit ci` runs these too and is what you normally want. --fix applies check autofixes',
         examples: [
-            ['run (cached where valid)', 'shipkit check'],
-            ['bust every cache layer', 'shipkit check --fresh'],
-            ['apply every rule autofix, re-lint', 'shipkit check --fix'],
-            ['fix one rule', 'shipkit check --fix SK004'],
-            ['report-only: self-maintaining rules never write', 'shipkit check --frozen'],
-            ['machine-readable', 'shipkit check --json'],
+            ['run (cached where valid)', 'sk check'],
+            ['bust every cache layer', 'sk check --fresh'],
+            ['apply every rule autofix, re-lint', 'sk check --fix'],
+            ['fix one rule', 'sk check --fix SK004'],
+            ['report-only: self-maintaining rules never write', 'sk check --frozen'],
+            ['machine-readable', 'sk check --json'],
         ],
     })
 

package/src/cli/cmd_Checks.ts

@@ -21,13 +21,14 @@ export class ChecksCommand extends Command {
     // widened so the hidden alias below can drop it: no usage, no help entry
     static override usage: Usage | undefined = Command.Usage({
         category: 'Health',
-        description: 'every gate check on one table: where it comes from, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
+        description: 'every gate check on one table: source, blocking or warning, cache',
+        details: 'every gate check on one table: where it comes from, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
         examples: [
-            ['the whole inventory', 'shipkit checks'],
-            ['the big markdown table, written to a file', 'shipkit checks --out STATUS.full.md'],
-            ['only the ones the gate never runs', 'shipkit checks --proactive'],
-            ['everything that repairs itself, with its owner', 'shipkit checks --fixable'],
-            ['machine-readable', 'shipkit checks --json'],
+            ['the whole inventory', 'sk checks'],
+            ['the big markdown table, written to a file', 'sk checks --out STATUS.full.md'],
+            ['only the ones the gate never runs', 'sk checks --proactive'],
+            ['everything that repairs itself, with its owner', 'sk checks --fixable'],
+            ['machine-readable', 'sk checks --json'],
         ],
     })
 

package/src/cli/cmd_Ci.ts

@@ -13,18 +13,19 @@ export class CiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
+        description: 'THE gate: repairs what a machine can, then runs every check. Run this, not the parts',
+        details: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
-            ['full gate, mechanical fixes applied', 'shipkit ci'],
-            ['gate without the repair pass (checks can still write)', 'shipkit ci --no-fix'],
-            ['leave repo config files alone', 'shipkit ci --no-fix-rules'],
-            ['stop at the first failure', 'shipkit ci --bail'],
-            ['one check + its dep closure', 'shipkit ci --only typecheck'],
-            ['every check declaring one group', 'shipkit ci --only wiki'],
-            ['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'],
+            ['full gate, mechanical fixes applied', 'sk ci'],
+            ['gate without the repair pass (checks can still write)', 'sk ci --no-fix'],
+            ['leave repo config files alone', 'sk ci --no-fix-rules'],
+            ['stop at the first failure', 'sk ci --bail'],
+            ['one check + its dep closure', 'sk ci --only typecheck'],
+            ['every check declaring one group', 'sk ci --only wiki'],
+            ['run everything, take nothing from the cache', 'sk ci --fresh'],
+            ['include an opt in check', 'sk ci --with up:itch'],
+            ['in the background, read it back with shipkit status', 'sk ci --detach'],
+            ['every line, the ones nobody acts on included', 'sk ci --verbose'],
         ],
     })
 

package/src/cli/cmd_Commands.ts

@@ -23,6 +23,10 @@ export type Definition = {
     options?: { definition?: string; description?: string | null }[] | null
 }
 
+/** the longest description the index shows: one short line. The rest goes in
+ *  the command's `details`, which --help prints */
+export const DESCRIPTION_MAX = 100
+
 // clipanion renders a value placeholder as `#0`, which nobody can type
 const clean = (s: string | null | undefined): string => (s ?? '').trim().replace(/\s+/g, ' ').replace(/ #\d+\b/g, ' <value>')
 
@@ -34,9 +38,9 @@ const clean = (s: string | null | undefined): string => (s ?? '').trim().replace
 export function commandRows(plain: Definition[], detailed: Definition[] = []): CommandRow[] {
     const flagsByPath = new Map(detailed.map((d) => [d.path, d.options ?? []]))
     return plain
-        .filter((d) => !/^shipkit (--help|-h|--version|-v)$/.test(d.path))
+        .filter((d) => !/^(shipkit|sk) (--help|-h|--version|-v)$/.test(d.path))
         .map((d) => ({
-            path: d.path.replace(/^shipkit /, ''),
+            path: d.path.replace(/^(shipkit|sk) /, ''),
             category: clean(d.category) || 'Other',
             // verbatim from the CLI so the doc cannot say something it does not
             description: clean(d.description),
@@ -49,21 +53,19 @@ export function commandRows(plain: Definition[], detailed: Definition[] = []): C
         .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
 }
 
-/** the markdown block: per command, the real invocation with its arguments and
- *  flags, then a worked example. A name and a sentence are not enough to act
- *  on: an agent that cannot see the arguments either guesses them or runs
- *  `--help` first, and both are the waste this page exists to remove. */
+/** the markdown block, loaded into every agent's context at start: per
+ *  command its invocation with every flag, one line of description, then its
+ *  examples. What a flag does and the long text are `sk <command> --help`. */
 export function renderMarkdown(rows: CommandRow[]): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
         if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
-        const sig = r.usage.replace(/^\$0/, 'shipkit').trim() || `shipkit ${r.path}`
+        const sig = r.usage.replace(/^\$0/, 'sk').trim() || `sk ${r.path}`
         const flags = r.options.map((o) => `[${o.definition}]`).join(' ')
         // one line per bullet: a description on its own indented line reads as
         // hard-wrapped prose to the house lint
         out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}`)
-        for (const o of r.options) if (o.description !== '') out.push(`  - \`${o.definition}\` ${o.description}`)
         for (const [label, cmd] of r.examples) out.push(`  - ${label}: \`${cmd}\``)
     }
     return out.join('\n').trim()
@@ -82,12 +84,13 @@ export class CommandsCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every command this binary registers, as markdown or json — the source a docs page is generated FROM, never hand-copied',
+        description: 'every command this binary registers, as markdown or json',
+        details: 'every command this binary registers, as markdown or json — the source a docs page is generated FROM, never hand-copied',
         examples: [
-            ['markdown index', 'shipkit commands'],
-            ['machine-readable', 'shipkit commands --json'],
-            ['write into a docs page between the markers', 'shipkit commands --out wiki/build/shipkit-cli.md'],
-            ['fail if that page is stale (lint mode)', 'shipkit commands --out wiki/build/shipkit-cli.md --check'],
+            ['markdown index', 'sk commands'],
+            ['machine-readable', 'sk commands --json'],
+            ['write into a docs page between the markers', 'sk commands --out wiki/build/shipkit-cli.md'],
+            ['fail if that page is stale (lint mode)', 'sk commands --out wiki/build/shipkit-cli.md --check'],
         ],
     })
 

package/src/cli/cmd_ConfigKeys.ts

@@ -19,13 +19,14 @@ export class ConfigKeysCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every repo.config.ts key and every check field with its doc, read from the types — the source a config reference page is generated FROM',
+        description: 'every repo.config.ts key and check field with its doc, from the types',
+        details: 'every repo.config.ts key and every check field with its doc, read from the types — the source a config reference page is generated FROM',
         examples: [
-            ['markdown reference', 'shipkit config-keys'],
-            ['machine-readable', 'shipkit config-keys --json'],
-            ['write into a docs page between the markers', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md'],
-            ['fail if that page is stale (lint mode)', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md --check'],
-            ['name the keys carrying no doc comment', 'shipkit config-keys --undocumented'],
+            ['markdown reference', 'sk config-keys'],
+            ['machine-readable', 'sk config-keys --json'],
+            ['write into a docs page between the markers', 'sk config-keys --out wiki/build/shipkit/config-keys.md'],
+            ['fail if that page is stale (lint mode)', 'sk config-keys --out wiki/build/shipkit/config-keys.md --check'],
+            ['name the keys carrying no doc comment', 'sk config-keys --undocumented'],
         ],
     })
 

package/src/cli/cmd_Contracts.ts

@@ -10,9 +10,9 @@ export class ContractsCommand extends Command {
         category: 'Gate',
         description: 'release-contract fulfillness, fast and filesystem-only — deploy checks dep on it',
         examples: [
-            ['all applicable contracts', 'shipkit contracts'],
-            ['one venue', 'shipkit contracts --venue itch'],
-            ['machine-readable', 'shipkit contracts --json'],
+            ['all applicable contracts', 'sk contracts'],
+            ['one venue', 'sk contracts --venue itch'],
+            ['machine-readable', 'sk contracts --json'],
         ],
     })
 

package/src/cli/cmd_CrossRepoActivity.ts

@@ -8,7 +8,6 @@ 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 {
@@ -85,12 +84,13 @@ export class CrossRepoActivityCommand extends Command {
 
     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',
+        description: 'the activity page as text: every house repo, its git state and recent commits',
+        details: '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'],
+            ['the last 30 minutes, 3 commits per repo, as the page opens', 'sk cross-repo-activity'],
+            ['the same, by the page name', 'sk activity'],
+            ['the last 3 hours, up to 10 commits per repo', 'sk cross-repo-activity --max-age 3h --max-commit 10'],
+            ['the route\'s exact payload', 'sk cross-repo-activity --max-age 30m --json'],
         ],
     })
 
@@ -107,6 +107,8 @@ export class CrossRepoActivityCommand extends Command {
         const cap = clampCap(this.maxCommit ?? DEFAULT_CAP)
         const declared = await daemonDeclared()
         // HOME as the shell has it now: the house include names `~`
+        // the hub route module draws app icons, so it loads only when this runs
+        const { railRepos } = await import('../serve/project-gutter-route.ts')
         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`)

package/src/cli/cmd_Fleet.ts

@@ -14,11 +14,11 @@ export class FleetCommand extends Command {
         category: 'Health',
         description: 'every repo on this disk that installs the toolkit, and how far behind each one is',
         examples: [
-            ['what is stale out there', 'shipkit fleet'],
-            ['filesystem only, no registry', 'shipkit fleet --offline'],
-            ['bring every behind repo up, through its own gate', 'shipkit fleet --update'],
-            ['one repo only', 'shipkit fleet --update --only my-app'],
-            ['machine-readable', 'shipkit fleet --json'],
+            ['what is stale out there', 'sk fleet'],
+            ['filesystem only, no registry', 'sk fleet --offline'],
+            ['bring every behind repo up, through its own gate', 'sk fleet --update'],
+            ['one repo only', 'sk fleet --update --only my-app'],
+            ['machine-readable', 'sk fleet --json'],
         ],
     })
 
@@ -66,10 +66,12 @@ export class FleetCommand extends Command {
     private row(r: FleetRepo): string {
         const cells = r.deps.map((d) => {
             if (d.pin.startsWith('link:') || d.pin.startsWith('file:')) return `${short(d.name)}=source`
-            const at = d.installed ?? 'absent'
+            // a linked dep reads as its pin: the source it links is always newest
+            const at = d.linkedInstall ? `pin ${d.at ?? d.pin}` : (d.installed ?? 'absent')
+            const tag = d.linkedInstall ? ' (linked)' : ''
             const stale = r.behind.some((b) => b.name === d.name)
             const breaks = r.breaking.some((b) => b.name === d.name)
-            return stale ? `${short(d.name)} ${at} → ${d.latest}${breaks ? ' BREAKING' : ''}` : `${short(d.name)} ${at}`
+            return stale ? `${short(d.name)} ${at} → ${d.latest}${breaks ? ' BREAKING' : ''}${d.linkedInstall ? ' (linked, stale pin)' : ''}` : `${short(d.name)} ${at}${tag}`
         })
         const flag = r.linked ? 'source' : r.breaking.length > 0 ? `${r.breaking.length} BREAKING` : r.behind.length > 0 ? `${r.behind.length} behind` : 'current'
         return `  ${r.name.padEnd(24)} ${flag.padEnd(10)} ${cells.join(', ')}`

package/src/cli/cmd_GlobalProcesses.ts

@@ -9,10 +9,10 @@ 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 type { ResourceView } from '../home/resources.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 */
@@ -74,11 +74,13 @@ export async function askPm(url = pmUrl()): Promise<PmAnswer | 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'> {
+export async function localProcessDeps(cwd: string): Promise<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 {
+        // the hub route module draws app icons: loaded only when this runs
+        const { railRepos } = await import('../serve/project-gutter-route.ts')
         order = railRepos(cwd, home).map((r) => r.name)
     } catch {
         // no rail from here: the groups sort by name
@@ -133,18 +135,19 @@ export class GlobalProcessesCommand extends Command {
 
     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',
+        description: 'every process on the machine and its state, as the overview shows it',
+        details: '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'],
+            ['the table', 'sk global-processes'],
+            ['the same, short', 'sk gp'],
+            ['the rows the overview draws, as json', 'sk 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() })
+        const a = await globalProcessesAnswer({ ...(await 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
@@ -153,3 +156,113 @@ export class GlobalProcessesCommand extends Command {
         return 0
     }
 }
+
+export type SwitchAct = 'start' | 'stop' | 'restart'
+
+export type SwitchDeps = {
+    /** pm's answer to the switch: null when it took it, else why not */
+    post: (id: string, act: SwitchAct) => Promise<string | null>
+    /** the process as pm sees it now, null when pm does not answer */
+    view: (id: string) => Promise<ResourceView | null>
+    sleep: (ms: number) => Promise<void>
+    now: () => number
+    log: (line: string) => void
+}
+
+/** the longest a switch is followed: a bring-up polls its health for minutes */
+export const SWITCH_WAIT_MS = 10 * 60_000
+const SWITCH_POLL_MS = 1_000
+
+/** flip a global process through pm, then follow pm's state until its probe
+ *  settles it: 0 once it is up (or down for stop), 1 otherwise. The launcher's
+ *  exit code proves nothing, pm's probe does */
+export async function switchProcess(id: string, act: SwitchAct, d: SwitchDeps, waitMs = SWITCH_WAIT_MS): Promise<number> {
+    const refused = await d.post(id, act)
+    if (refused != null) {
+        d.log(`FAIL ${act} ${id}: ${refused}`)
+        return 1
+    }
+    const want = act === 'stop' ? 'down' : 'up'
+    const end = d.now() + waitMs
+    let said = ''
+    for (;;) {
+        const v = await d.view(id)
+        if (v == null) {
+            d.log(`FAIL pm stopped answering while ${id} was switched ${want}: shipkit gp`)
+            return 1
+        }
+        if (v.status !== said) {
+            said = v.status
+            d.log(`${id}: ${v.status}`)
+        }
+        const moving = v.status === 'starting' || v.status === 'stopping' || v.want !== want
+        if (!moving) {
+            if (v.status === want) return 0
+            d.log(`FAIL ${id} is ${v.status}, not ${want}${v.note == null ? '' : `: ${v.note}`}`)
+            for (const l of v.tail.slice(-10)) d.log(`  log: ${l}`)
+            return 1
+        }
+        if (d.now() >= end) {
+            d.log(`FAIL ${id} still ${v.status} after ${Math.round(waitMs / 1000)}s: shipkit gp shows where it stands`)
+            return 1
+        }
+        await d.sleep(SWITCH_POLL_MS)
+    }
+}
+
+/** the switch against the running pm */
+export const pmSwitchDeps = (log: (line: string) => void, url = pmUrl()): SwitchDeps => ({
+    post: async (id, act) => {
+        try {
+            const r = await fetch(`${url}/api/pm/resource`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id, act }), signal: AbortSignal.timeout(5_000) })
+            return r.ok ? null : await r.text()
+        } catch (e) {
+            return `pm does not answer on ${url} (${(e as Error).message}): shipkit pm install`
+        }
+    },
+    view: async (id) => (await askPm(url))?.resources.find((r) => r.id === id) ?? null,
+    sleep: (ms) => Bun.sleep(ms),
+    now: () => Date.now(),
+    log,
+})
+
+abstract class SwitchCommand extends Command {
+    abstract readonly act: SwitchAct
+    id = Option.String({ required: true, name: 'id' })
+
+    async execute(): Promise<number> {
+        return switchProcess(this.id, this.act, pmSwitchDeps((l) => this.context.stdout.write(`${l}\n`)))
+    }
+}
+
+export class GlobalProcessStartCommand extends SwitchCommand {
+    readonly act = 'start'
+    static override paths = [['global-processes', 'start'], ['gp', 'start']]
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'start a global process through pm, wait until its probe answers',
+        details: 'start a global process through pm, the same switch as the overview\'s play, and wait until its probe answers. Exit 0 once it is up, 1 when it crashed, stayed down or pm refused',
+        examples: [['start ComfyUI on the GPU box', 'sk gp start comfyui']],
+    })
+}
+
+export class GlobalProcessStopCommand extends SwitchCommand {
+    readonly act = 'stop'
+    static override paths = [['global-processes', 'stop'], ['gp', 'stop']]
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'stop a global process through pm, wait until it is down',
+        details: 'stop a global process through pm, the same switch as the overview\'s stop, and wait until its probe no longer answers. Exit 0 once it is down',
+        examples: [['stop ComfyUI', 'sk gp stop comfyui']],
+    })
+}
+
+export class GlobalProcessRestartCommand extends SwitchCommand {
+    readonly act = 'restart'
+    static override paths = [['global-processes', 'restart'], ['gp', 'restart']]
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'restart a global process through pm and wait until its probe answers again. Exit 0 once it is up',
+        examples: [['restart ComfyUI, so it rescans its models', 'sk gp restart comfyui']],
+    })
+}

package/src/cli/cmd_Home.ts

@@ -10,7 +10,6 @@ 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))
@@ -35,10 +34,11 @@ export class PmCommand extends Command {
 
     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',
+        description: 'the machine\'s process manager: runs the daemon, the web and every global process',
+        details: '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'],
+            ['run pm in this terminal', 'sk pm'],
+            ['on test ports', 'SHIPKIT_PM_PORT=4887 SHIPKIT_HOME_PORT=4889 SHIPKIT_DAEMON_PORT=4888 SHIPKIT_HOME_DIR=/tmp/home sk pm'],
         ],
     })
 
@@ -57,10 +57,11 @@ export class DaemonCommand extends Command {
 
     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',
+        description: 'the home daemon: every house repo\'s hub in one process',
+        details: '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'],
+            ['the daemon alone', 'sk daemon'],
+            ['on another port', 'sk daemon --port 4888'],
         ],
     })
 
@@ -69,6 +70,8 @@ export class DaemonCommand extends Command {
     async execute(): Promise<number> {
         const port = portOf(this, this.port)
         if (port === null) return 1
+        // the daemon hosts every hub, image tools included: loaded when it runs
+        const { runDaemon } = await import('../home/run-daemon.ts')
         return runDaemon(process.cwd(), io(this), { port })
     }
 }
@@ -78,10 +81,11 @@ export class WebCommand extends Command {
 
     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',
+        description: 'the home page server: serves the page, proxies the api to the daemon',
+        details: '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'],
+            ['the page alone', 'sk web'],
+            ['on another port', 'sk web --port 4889'],
         ],
     })
 
@@ -99,8 +103,9 @@ export class PmInstallCommand extends Command {
 
     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']],
+        description: 'keep pm running at every login through a macOS LaunchAgent',
+        details: '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', 'sk pm install']],
     })
 
     async execute(): Promise<number> {
@@ -114,8 +119,9 @@ export class PmUninstallCommand extends Command {
 
     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']],
+        description: 'stop pm, the daemon and the web, and remove the LaunchAgent',
+        details: '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', 'sk pm uninstall']],
     })
 
     async execute(): Promise<number> {
@@ -130,11 +136,12 @@ export class GuiCommand extends Command {
 
     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',
+        description: 'open the home in its own window',
+        details: '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 .'],
+            ['a window on the home', 'sk gui'],
+            ['a window on one repo', 'sk gui my-app'],
+            ['a window on the repo you stand in', 'sk gui .'],
         ],
     })
 
@@ -163,7 +170,7 @@ export class GuiCommand extends Command {
         // `.` = 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 })
+        const cmd = await 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_Hooks.ts

@@ -1,7 +1,7 @@
 // shipkit hooks, install the git hooks, run their gates, or list what
 // blocks a commit. Thin clipanion surface; logic in hooks/run-hooks.ts.
 import { Command, Option } from 'clipanion'
-import { hookBinInvocation, installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
+import { hookBinInvocation, installHooks, listGates, preCommitChecks, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
 const report = (out: GateOutcome[], write: (s: string) => void): number => {
@@ -13,8 +13,9 @@ export class HooksInstallCommand extends Command {
     static override paths = [['hooks', 'install']]
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'write .shipkit/hooks/pre-commit + .shipkit/hooks/commit-msg and point core.hooksPath at them (idempotent)',
-        examples: [['wire the hooks', 'shipkit hooks install']],
+        description: 'write the pre-commit and commit-msg hooks and point core.hooksPath at them',
+        details: 'write .shipkit/hooks/pre-commit + .shipkit/hooks/commit-msg and point core.hooksPath at them (idempotent)',
+        examples: [['wire the hooks', 'sk hooks install']],
     })
 
     bin = Option.String('--bin', { description: 'how the hook body invokes shipkit (default: the repo\'s own node_modules copy, else the running cli — in-repo consumers pass `bun <path to cli.ts>`)' })
@@ -56,12 +57,12 @@ export class HooksListCommand extends Command {
     static override usage = Command.Usage({
         category: 'Gate',
         description: 'what blocks a commit in this repo, built-ins and repo-declared',
-        examples: [['list the gates', 'shipkit hooks list']],
+        examples: [['list the gates', 'sk hooks list']],
     })
 
     async execute(): Promise<number> {
         const config = await loadRepoConfig(process.cwd())
-        for (const l of listGates(config, process.cwd())) this.context.stdout.write(`${l}\n`)
+        for (const l of listGates(config, process.cwd(), await preCommitChecks(process.cwd(), config))) this.context.stdout.write(`${l}\n`)
         return 0
     }
 }

package/src/cli/cmd_Init.ts

@@ -8,11 +8,12 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts + the create-only .vscode/ that starts the watchers and the hub on folder open, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
+        description: 'wire the current directory as a shipkit repo, like git init',
+        details: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts + the create-only .vscode/ that starts the watchers and the hub on folder open, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
         examples: [
-            ['wire the repo you are standing in', 'shipkit init'],
-            ['local git and the first commit, never touch github', 'shipkit init --no-github'],
-            ['in-repo-source consumer: scripts run the CLI by path', 'shipkit init --bin wiki/build/shipkit/rvlib-shipkit/src/cli.ts'],
+            ['wire the repo you are standing in', 'sk init'],
+            ['local git and the first commit, never touch github', 'sk init --no-github'],
+            ['in-repo-source consumer: scripts run the CLI by path', 'sk init --bin wiki/build/shipkit/rvlib-shipkit/src/cli.ts'],
         ],
     })