rvlib-shipkit 1.3.0 → 1.5.0

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,6 +9,7 @@ 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'
@@ -133,11 +134,12 @@ 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'],
         ],
     })
 
@@ -153,3 +155,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

@@ -35,10 +35,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 +58,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'],
         ],
     })
 
@@ -78,10 +80,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 +102,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 +118,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 +135,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 .'],
         ],
     })
 

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'],
         ],
     })
 

package/src/cli/cmd_Keys.ts

@@ -19,14 +19,15 @@ export class KeysCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'the cache key of every gate check, and the reason the undeclared ones have none. Reports, never gates',
+        description: 'the cache key of every gate check, and why the others have none',
+        details: 'the cache key of every gate check, and the reason the undeclared ones have none. Reports, never gates',
         examples: [
-            ['every check and its key', 'shipkit keys'],
-            ['only the ones nothing can cache yet', 'shipkit keys --burn-down'],
-            ['why this key is what it is', 'shipkit keys --why typecheck'],
-            ['re-hash after the fact and report drift', 'shipkit keys --rescan'],
-            ['the keys a --full gate asks for', 'shipkit keys --full'],
-            ['machine-readable', 'shipkit keys --json'],
+            ['every check and its key', 'sk keys'],
+            ['only the ones nothing can cache yet', 'sk keys --burn-down'],
+            ['why this key is what it is', 'sk keys --why typecheck'],
+            ['re-hash after the fact and report drift', 'sk keys --rescan'],
+            ['the keys a --full gate asks for', 'sk keys --full'],
+            ['machine-readable', 'sk keys --json'],
         ],
     })
 

package/src/cli/cmd_Mv.ts

@@ -12,13 +12,14 @@ export class MvCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Refactor',
-        description: 'rename anything and sweep every reference: an md page (plus its sibling dir and its check file) or a code file or folder. Dry run by default. Renames must be CHEAP',
+        description: 'rename a file, folder or md page and rewrite every reference (dry run by default)',
+        details: 'rename anything and sweep every reference: an md page (plus its sibling dir and its check file) or a code file or folder. Dry run by default. Renames must be CHEAP',
         examples: [
-            ['dry run, the default, shows what changes', 'shipkit mv docs/old-name.md docs/new-name.md'],
-            ['apply it', 'shipkit mv docs/old-name.md docs/new-name.md --write'],
-            ['apply + one conventional commit', 'shipkit mv docs/old-name.md docs/new-name.md --commit'],
-            ['a code file, every import rewritten', 'shipkit mv src/old-mod.ts src/new-mod.ts --write'],
-            ['a whole folder', 'shipkit mv src/old-dir src/new-dir --write'],
+            ['dry run, the default, shows what changes', 'sk mv docs/old-name.md docs/new-name.md'],
+            ['apply it', 'sk mv docs/old-name.md docs/new-name.md --write'],
+            ['apply + one conventional commit', 'sk mv docs/old-name.md docs/new-name.md --commit'],
+            ['a code file, every import rewritten', 'sk mv src/old-mod.ts src/new-mod.ts --write'],
+            ['a whole folder', 'sk mv src/old-dir src/new-dir --write'],
         ],
     })
 

package/src/cli/cmd_Needs.ts

@@ -12,10 +12,11 @@ export class NeedsCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'everything blocked on a human, red/yellow by collection — report-only, exit 0 always (check/ci are the gates)',
+        description: 'everything blocked on a human, by collection. Report only',
+        details: 'everything blocked on a human, red/yellow by collection — report-only, exit 0 always (check/ci are the gates)',
         examples: [
-            ['what needs me', 'shipkit needs'],
-            ['machine-readable (agents, drills, cross-repo rollups)', 'shipkit needs --json'],
+            ['what needs me', 'sk needs'],
+            ['machine-readable (agents, drills, cross-repo rollups)', 'sk needs --json'],
         ],
     })
 

package/src/cli/cmd_Overview.ts

@@ -77,10 +77,11 @@ export class OverviewCommand extends Command {
 
     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',
+        description: 'the overview page as text: the widgets, then every process',
+        details: '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'],
+            ['the overview', 'sk overview'],
+            ['the answers the page reads, as json', 'sk overview --json'],
         ],
     })
 

package/src/cli/cmd_Pb.ts

@@ -10,8 +10,8 @@ export class PbCollectionCommand extends Command {
         category: 'Scaffold',
         description: "a collection's CRUD UI folder from the app's generated pb types: columns, card, grid, form, index",
         examples: [
-            ['see the whole folder before it exists', 'shipkit pb collection orders --dry-run'],
-            ['write src/collections/orders/', 'shipkit pb collection orders'],
+            ['see the whole folder before it exists', 'sk pb collection orders --dry-run'],
+            ['write src/collections/orders/', 'sk pb collection orders'],
         ],
     })
 

package/src/cli/cmd_Planned.ts

@@ -78,12 +78,13 @@ export class PlannedCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Home',
-        description: 'the planned page in the console: every check the machine runs on its own time, running now, then next, each with its repo, check and title, when, the rule that planned it and its last result. Asks the daemon, which holds the plan. With the daemon down it says so and exits 0',
+        description: 'the plan as text: every check the machine runs on its own time',
+        details: 'the planned page in the console: every check the machine runs on its own time, running now, then next, each with its repo, check and title, when, the rule that planned it and its last result. Asks the daemon, which holds the plan. With the daemon down it says so and exits 0',
         examples: [
-            ['the plan, as the page lists it', 'shipkit planned'],
-            ['one repo only', 'shipkit planned --repo my-app'],
-            ['also the checks that only a save runs', 'shipkit planned --all'],
-            ['the route\'s exact payload', 'shipkit planned --json'],
+            ['the plan, as the page lists it', 'sk planned'],
+            ['one repo only', 'sk planned --repo my-app'],
+            ['also the checks that only a save runs', 'sk planned --all'],
+            ['the route\'s exact payload', 'sk planned --json'],
         ],
     })
 

package/src/cli/cmd_Prose.ts

@@ -13,11 +13,11 @@ export class ProseCommand extends Command {
         category: 'Health',
         description: 'STE prose check (identity/writing-voice.md): mechanical fixes, hard violations, soft warnings',
         examples: [
-            ['every file this repo declares as prose', 'shipkit prose'],
-            ['one file while drafting', 'shipkit prose wiki/build/shipkit.md'],
-            ['apply every mechanical rewrite', 'shipkit prose --fix'],
-            ['the procedural 20-word limit', 'shipkit prose --strict'],
-            ['machine-readable', 'shipkit prose --json'],
+            ['every file this repo declares as prose', 'sk prose'],
+            ['one file while drafting', 'sk prose wiki/build/shipkit.md'],
+            ['apply every mechanical rewrite', 'sk prose --fix'],
+            ['the procedural 20-word limit', 'sk prose --strict'],
+            ['machine-readable', 'sk prose --json'],
         ],
     })
 

package/src/cli/cmd_Reflect.ts

@@ -17,14 +17,14 @@ export class ReflectCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description:
-            "the user's typed prompts across every Claude Code session of a repo — chronological md corpus for retrospectives",
+        description: "the user's prompts across every Claude Code session of a repo, as a corpus",
+        details: "the user's typed prompts across every Claude Code session of a repo — chronological md corpus for retrospectives",
         examples: [
-            ['corpus for the current repo', 'shipkit reflect'],
-            ['corpus for other repos', 'shipkit reflect ~/dev/one-repo ~/dev/another-repo'],
-            ['drop the long pastes', 'shipkit reflect --short'],
-            ['batch to files instead of stdout', 'shipkit reflect ~/dev/a ~/dev/b --out stats'],
-            ['machine-readable', 'shipkit reflect --json'],
+            ['corpus for the current repo', 'sk reflect'],
+            ['corpus for other repos', 'sk reflect ~/dev/one-repo ~/dev/another-repo'],
+            ['drop the long pastes', 'sk reflect --short'],
+            ['batch to files instead of stdout', 'sk reflect ~/dev/a ~/dev/b --out stats'],
+            ['machine-readable', 'sk reflect --json'],
         ],
     })
 

package/src/cli/cmd_Release.ts

@@ -9,12 +9,13 @@ export class ReleaseCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'cut a release for ONE unit (default the repo root): ci gate → npm publish (non-private only) → git tag → push → GitHub release, notes from that unit CHANGELOG section. Resumable after a partial failure, which is why it takes no --all.',
+        description: 'cut a release of one unit: gate, npm publish, tag, push, GitHub release',
+        details: 'cut a release for ONE unit (default the repo root): ci gate → npm publish (non-private only) → git tag → push → GitHub release, notes from that unit CHANGELOG section. Resumable after a partial failure, which is why it takes no --all.',
         examples: [
-            ['rehearse — touches nothing', 'shipkit release --dry-run'],
-            ['release the version in package.json', 'shipkit release'],
-            ['finish a sub-unit bump stopped part way (ids: shipkit releases)', 'shipkit release rvlib-shipkit'],
-            ['release with dirt elsewhere in the worktree', 'shipkit release --allow-dirty'],
+            ['rehearse — touches nothing', 'sk release --dry-run'],
+            ['release the version in package.json', 'sk release'],
+            ['finish a sub-unit bump stopped part way (ids: shipkit releases)', 'sk release rvlib-shipkit'],
+            ['release with dirt elsewhere in the worktree', 'sk release --allow-dirty'],
         ],
     })
 

package/src/cli/cmd_Releases.ts

@@ -9,11 +9,12 @@ export class ReleasesCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'every unit that releases and where it stands: version, npm, tag local and remote, GitHub release, drift. Reports, never gates (only an unresolvable config exits non-zero)',
+        description: 'every release unit and where it stands: version, npm, tags, GitHub',
+        details: 'every unit that releases and where it stands: version, npm, tag local and remote, GitHub release, drift. Reports, never gates (only an unresolvable config exits non-zero)',
         examples: [
-            ['what is published and what is not', 'shipkit releases'],
-            ['filesystem + local git only, no network', 'shipkit releases --offline'],
-            ['machine-readable', 'shipkit releases --json'],
+            ['what is published and what is not', 'sk releases'],
+            ['filesystem + local git only, no network', 'sk releases --offline'],
+            ['machine-readable', 'sk releases --json'],
         ],
     })
 

package/src/cli/cmd_Serve.ts

@@ -8,10 +8,11 @@ export class ServeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Serve',
-        description: 'ONE server, ONE page: media studio + asks + creds + posts + health + wikis, each wiki a link graph page',
+        description: 'the repo hub: one server, one page (assets, asks, creds, posts, health, wikis)',
+        details: 'ONE server, ONE page: media studio + asks + creds + posts + health + wikis, each wiki a link graph page',
         examples: [
-            ['serve the repo toolbox', 'shipkit serve'],
-            ['pin the port for this launch', 'shipkit serve --port 4804'],
+            ['serve the repo toolbox', 'sk serve'],
+            ['pin the port for this launch', 'sk serve --port 4804'],
         ],
     })
 

package/src/cli/cmd_Smoke.ts

@@ -10,11 +10,12 @@ export class SmokeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'browser smoke pass over a deployed web app: login through the app, visit every declared route, read only, screenshots + console/network problems + host quota. Exit code = failed routes',
+        description: 'browser smoke pass over a deployed web app, every declared route',
+        details: 'browser smoke pass over a deployed web app: login through the app, visit every declared route, read only, screenshots + console/network problems + host quota. Exit code = failed routes',
         examples: [
-            ['every route in repo.config smoke, against its base url', 'shipkit smoke'],
-            ['a preview deploy', 'shipkit smoke --base https://abc123.my-app.pages.dev'],
-            ['two routes only', 'shipkit smoke --routes /orders,/clients'],
+            ['every route in repo.config smoke, against its base url', 'sk smoke'],
+            ['a preview deploy', 'sk smoke --base https://abc123.my-app.pages.dev'],
+            ['two routes only', 'sk smoke --routes /orders,/clients'],
         ],
     })
 

package/src/cli/cmd_Start.ts

@@ -9,13 +9,14 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create or enter ~/dev/<name> from anywhere, ready to work in',
+        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
-            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'shipkit start pong'],
-            ['another house: replace the include lines', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
-            ['adopt a pre-existing repo from anywhere', 'shipkit start my-old-project'],
-            ['force the private github repo for a folder that was already there', 'shipkit start old-notes --github'],
-            ['local git and the first commit, never touch github', 'shipkit start pong --no-github'],
+            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],
+            ['another house: replace the include lines', "sk start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
+            ['adopt a pre-existing repo from anywhere', 'sk start my-old-project'],
+            ['force the private github repo for a folder that was already there', 'sk start old-notes --github'],
+            ['local git and the first commit, never touch github', 'sk start pong --no-github'],
         ],
     })
 

package/src/cli/cmd_Status.ts

@@ -8,10 +8,11 @@ export class StatusCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: `a gate started with \`shipkit ci --detach\`: its wire lines so far, then its verdict. Exit code = the gate's own once it finished, ${STILL_RUNNING} while it still runs, 1 when it died without one`,
+        description: 'the output and verdict of a gate started with `sk ci --detach`',
+        details: `a gate started with \`shipkit ci --detach\`: its wire lines so far, then its verdict. Exit code = the gate's own once it finished, ${STILL_RUNNING} while it still runs, 1 when it died without one`,
         examples: [
-            ['the latest detached run of this checkout', 'shipkit status'],
-            ['one run by id', 'shipkit status ci-mf3k2a-1x2y'],
+            ['the latest detached run of this checkout', 'sk status'],
+            ['one run by id', 'sk status ci-mf3k2a-1x2y'],
         ],
     })
 

package/src/cli/cmd_Tui.ts

@@ -11,8 +11,9 @@ export class TuiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'live dashboard: the gate build steps + every other check, plus panels the repo injects via repo.config tui.panels',
-        examples: [['open the dashboard', 'shipkit tui']],
+        description: 'live dashboard: the gate steps, every other check, the repo\'s panels',
+        details: 'live dashboard: the gate build steps + every other check, plus panels the repo injects via repo.config tui.panels',
+        examples: [['open the dashboard', 'sk tui']],
     })
 
     async execute(): Promise<number> {