rvlib-shipkit 1.1.0 → 1.2.0

package/src/home/gui-app/ShipkitGui.swift

@@ -0,0 +1,159 @@
+// the shipkit window on macOS: its own app, so the dock and cmd-tab show the
+// house icon, never a second browser. One WKWebView per window on the home's
+// page; every `open -a <app> <url>` opens one more window, cmd-n too. A link
+// to another site opens in the default browser. Built once by `shipkit gui`
+// (home/gui-app.ts) with swiftc, no Xcode project.
+import AppKit
+import WebKit
+
+let homeFallback = "http://127.0.0.1:4799/"
+
+final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKUIDelegate, NSWindowDelegate {
+    var windows: [NSWindow] = []
+    var opened = false
+
+    func applicationDidFinishLaunching(_ note: Notification) {
+        buildMenu()
+        // an open event may deliver the url right after launch: wait for it
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
+            if !self.opened {
+                let arg = CommandLine.arguments.dropFirst().first { $0.hasPrefix("http") }
+                self.open(URL(string: arg ?? homeFallback)!)
+            }
+        }
+    }
+
+    func application(_ app: NSApplication, open urls: [URL]) {
+        for u in urls { open(u) }
+    }
+
+    func applicationShouldTerminateAfterLastWindowClosed(_ app: NSApplication) -> Bool { true }
+
+    func applicationShouldHandleReopen(_ app: NSApplication, hasVisibleWindows: Bool) -> Bool {
+        if !hasVisibleWindows { open(URL(string: homeFallback)!) }
+        return true
+    }
+
+    @objc func newWindow(_ sender: Any?) {
+        let current = (NSApp.keyWindow?.contentView as? WKWebView)?.url
+        open(current ?? URL(string: homeFallback)!)
+    }
+
+    @objc func reload(_ sender: Any?) {
+        (NSApp.keyWindow?.contentView as? WKWebView)?.reload()
+    }
+
+    // the zoom is one value for every window, kept across restarts
+    var zoom: CGFloat {
+        get { let z = UserDefaults.standard.double(forKey: "pageZoom"); return z > 0 ? CGFloat(z) : 1 }
+        set {
+            let z = min(3, max(0.3, newValue))
+            UserDefaults.standard.set(Double(z), forKey: "pageZoom")
+            for w in windows { (w.contentView as? WKWebView)?.pageZoom = z }
+        }
+    }
+
+    @objc func zoomIn(_ sender: Any?) { zoom = zoom * 1.1 }
+    @objc func zoomOut(_ sender: Any?) { zoom = zoom / 1.1 }
+    @objc func zoomReset(_ sender: Any?) { zoom = 1 }
+
+    func open(_ url: URL) {
+        opened = true
+        let config = WKWebViewConfiguration()
+        config.preferences.setValue(true, forKey: "developerExtrasEnabled")
+        let web = WKWebView(frame: .zero, configuration: config)
+        web.navigationDelegate = self
+        web.uiDelegate = self
+        web.allowsBackForwardNavigationGestures = true
+        web.pageZoom = zoom
+        let frame = NSRect(x: 0, y: 0, width: 1400, height: 900)
+        let win = NSWindow(contentRect: frame, styleMask: [.titled, .closable, .miniaturizable, .resizable], backing: .buffered, defer: false)
+        win.contentView = web
+        win.title = "shipkit"
+        win.delegate = self
+        win.isReleasedWhenClosed = false
+        win.setFrameAutosaveName("shipkit-window")
+        if let last = windows.last { win.setFrameTopLeftPoint(NSPoint(x: last.frame.minX + 28, y: last.frame.maxY - 28)) } else { win.center() }
+        windows.append(win)
+        web.load(URLRequest(url: url))
+        win.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+
+    func windowWillClose(_ note: Notification) {
+        windows.removeAll { $0 === note.object as? NSWindow }
+    }
+
+    // the page title names the window, so cmd-tab and the window menu tell repos apart
+    func webView(_ web: WKWebView, didFinish nav: WKNavigation!) {
+        web.window?.title = (web.title?.isEmpty == false) ? web.title! : "shipkit"
+    }
+
+    // same host: stay in the window; anything else: the default browser
+    func webView(_ web: WKWebView, decidePolicyFor action: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
+        guard let url = action.request.url, action.navigationType == .linkActivated else { return decisionHandler(.allow) }
+        let local = url.host == "127.0.0.1" || url.host == "localhost"
+        if local { return decisionHandler(.allow) }
+        NSWorkspace.shared.open(url)
+        decisionHandler(.cancel)
+    }
+
+    // window.open and target=_blank: one more shipkit window for a local page
+    func webView(_ web: WKWebView, createWebViewWith config: WKWebViewConfiguration, for action: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        if let url = action.request.url {
+            if url.host == "127.0.0.1" || url.host == "localhost" { open(url) } else { NSWorkspace.shared.open(url) }
+        }
+        return nil
+    }
+
+    func buildMenu() {
+        let main = NSMenu()
+        let appItem = NSMenuItem()
+        main.addItem(appItem)
+        let appMenu = NSMenu()
+        appMenu.addItem(withTitle: "Hide shipkit", action: #selector(NSApplication.hide(_:)), keyEquivalent: "h")
+        appMenu.addItem(withTitle: "Quit shipkit", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+        appItem.submenu = appMenu
+        let fileItem = NSMenuItem()
+        main.addItem(fileItem)
+        let file = NSMenu(title: "File")
+        file.addItem(withTitle: "New Window", action: #selector(newWindow(_:)), keyEquivalent: "n")
+        file.addItem(withTitle: "Reload", action: #selector(reload(_:)), keyEquivalent: "r")
+        file.addItem(withTitle: "Close Window", action: #selector(NSWindow.performClose(_:)), keyEquivalent: "w")
+        fileItem.submenu = file
+        let editItem = NSMenuItem()
+        main.addItem(editItem)
+        let edit = NSMenu(title: "Edit")
+        edit.addItem(withTitle: "Undo", action: Selector(("undo:")), keyEquivalent: "z")
+        edit.addItem(withTitle: "Redo", action: Selector(("redo:")), keyEquivalent: "Z")
+        edit.addItem(withTitle: "Cut", action: #selector(NSText.cut(_:)), keyEquivalent: "x")
+        edit.addItem(withTitle: "Copy", action: #selector(NSText.copy(_:)), keyEquivalent: "c")
+        edit.addItem(withTitle: "Paste", action: #selector(NSText.paste(_:)), keyEquivalent: "v")
+        edit.addItem(withTitle: "Select All", action: #selector(NSText.selectAll(_:)), keyEquivalent: "a")
+        editItem.submenu = edit
+        let viewItem = NSMenuItem()
+        main.addItem(viewItem)
+        let view = NSMenu(title: "View")
+        view.addItem(withTitle: "Actual Size", action: #selector(zoomReset(_:)), keyEquivalent: "0")
+        view.addItem(withTitle: "Zoom In", action: #selector(zoomIn(_:)), keyEquivalent: "+")
+        // cmd-= zooms in too: the + sits behind shift on most layouts
+        let alsoIn = view.addItem(withTitle: "Zoom In", action: #selector(zoomIn(_:)), keyEquivalent: "=")
+        alsoIn.isAlternate = true
+        alsoIn.keyEquivalentModifierMask = [.command]
+        view.addItem(withTitle: "Zoom Out", action: #selector(zoomOut(_:)), keyEquivalent: "-")
+        viewItem.submenu = view
+        let winItem = NSMenuItem()
+        main.addItem(winItem)
+        let win = NSMenu(title: "Window")
+        win.addItem(withTitle: "Minimize", action: #selector(NSWindow.performMiniaturize(_:)), keyEquivalent: "m")
+        winItem.submenu = win
+        NSApp.windowsMenu = win
+        NSApp.mainMenu = main
+    }
+}
+
+let app = NSApplication.shared
+let delegate = Delegate()
+app.delegate = delegate
+app.setActivationPolicy(.regular)
+app.run()

package/src/home/gui-app.ts

@@ -0,0 +1,99 @@
+// the macOS app `shipkit gui` opens windows through: a bundle built once from
+// ShipkitGui.swift with swiftc, carrying the house repo's own icon, so the
+// dock and cmd-tab show it and never a second Chrome. Rebuilt only when the
+// source or the icon changed (a stamp in the bundle). No compiler, or not
+// macOS: the caller falls back to a Chrome app window.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.url))
+
+export const BUNDLE_ID = 'dev.shipkit.gui'
+export const guiAppPath = (): string => process.env.SHIPKIT_GUI_APP ?? join(homedir(), 'Applications', 'Shipkit.app')
+
+/** the icon the app wears: the house repo's own mark, largest first. Only a
+ *  png can become an icns */
+export const APP_ICON_FILES = ['.shipkit/identity/icon.png', 'public/logo.png', 'public/favicon.png']
+
+export function appIconOf(root: string): string | null {
+    for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
+    return null
+}
+
+export function infoPlist(o: { version: string }): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>CFBundleName</key><string>shipkit</string>
+\t<key>CFBundleDisplayName</key><string>shipkit</string>
+\t<key>CFBundleIdentifier</key><string>${BUNDLE_ID}</string>
+\t<key>CFBundleExecutable</key><string>shipkit-gui</string>
+\t<key>CFBundleIconFile</key><string>AppIcon</string>
+\t<key>CFBundlePackageType</key><string>APPL</string>
+\t<key>CFBundleShortVersionString</key><string>${o.version}</string>
+\t<key>CFBundleVersion</key><string>${o.version}</string>
+\t<key>LSMinimumSystemVersion</key><string>12.0</string>
+\t<key>NSHighResolutionCapable</key><true/>
+\t<key>NSAppTransportSecurity</key><dict><key>NSAllowsLocalNetworking</key><true/></dict>
+</dict>
+</plist>
+`
+}
+
+type Run = (cmd: string[]) => { code: number; err: string }
+const runSync: Run = (cmd) => {
+    const p = Bun.spawnSync(cmd, { stdout: 'ignore', stderr: 'pipe' })
+    return { code: p.exitCode ?? 1, err: p.stderr.toString().trim() }
+}
+
+/** the stamp a built bundle carries: what it was built from */
+export function stampOf(source: string, icon: string | null): string {
+    const h = new Bun.CryptoHasher('sha256').update(source)
+    if (icon != null) h.update(readFileSync(icon))
+    return h.digest('hex').slice(0, 16)
+}
+
+/** the app, built or rebuilt when stale. Throws with the step that failed.
+ *  `rebuilt` tells the caller a running copy is now the old one */
+export function ensureGuiApp(o: { root: string; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
+    const app = o.app ?? guiAppPath()
+    const run = o.run ?? runSync
+    const icon = appIconOf(o.root)
+    const stamp = stampOf(readFileSync(SOURCE, 'utf8'), icon)
+    const stampFile = join(app, 'Contents', 'Resources', 'stamp')
+    if (existsSync(stampFile) && readFileSync(stampFile, 'utf8') === stamp) return { app, rebuilt: false }
+    const tmp = `${app}.building-${process.pid}`
+    rmSync(tmp, { recursive: true, force: true })
+    const res = join(tmp, 'Contents', 'Resources')
+    mkdirSync(join(tmp, 'Contents', 'MacOS'), { recursive: true })
+    mkdirSync(res, { recursive: true })
+    writeFileSync(join(tmp, 'Contents', 'Info.plist'), infoPlist({ version: o.version }))
+    const built = run(['swiftc', '-O', '-o', join(tmp, 'Contents', 'MacOS', 'shipkit-gui'), SOURCE])
+    if (built.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`swiftc could not build the gui app: ${built.err.slice(0, 400)}`) }
+    if (icon != null) {
+        const set = join(res, 'AppIcon.iconset')
+        mkdirSync(set, { recursive: true })
+        for (const n of [16, 32, 128, 256, 512]) {
+            for (const [scale, px] of [['', n], ['@2x', n * 2]] as const) {
+                const r = run(['sips', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
+                if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`) }
+            }
+        }
+        const r = run(['iconutil', '-c', 'icns', set, '-o', join(res, 'AppIcon.icns')])
+        rmSync(set, { recursive: true, force: true })
+        if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`iconutil could not build the icon: ${r.err.slice(0, 200)}`) }
+    }
+    writeFileSync(join(res, 'stamp'), stamp)
+    mkdirSync(dirname(app), { recursive: true })
+    rmSync(app, { recursive: true, force: true })
+    run(['mv', tmp, app])
+    // launch services caches icons by bundle: tell it this one changed
+    run(['/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister', '-f', app])
+    return { app, rebuilt: true }
+}
+
+/** true when this machine can build the app */
+export const canBuildGui = (platform = process.platform): boolean => platform === 'darwin' && Bun.which('swiftc') != null && Bun.which('iconutil') != null

package/src/home/handoff.ts

@@ -0,0 +1,51 @@
+// a repo's own install of this lib (node_modules/.bin/shipkit, the .shipkit
+// hooks) runs its cli.ts directly, past the machine launcher. On a machine
+// with a house that copy hands the command to the house source, the one
+// `~/.local/bin/shipkit` runs, so every repo runs one version.
+//
+// the one constraint a reader breaks first: only an INSTALLED copy hands off.
+// A house checkout (a worktree on a branch) runs its own source, since an
+// agent there verifies that branch, never the main checkout.
+import { existsSync, realpathSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { houseCli, houseRootOf } from './home-start.ts'
+
+type Env = Record<string, string | undefined>
+const set = (v: string | undefined): boolean => v != null && v !== ''
+
+/** set on the process a handoff starts, so it never hands off again */
+export const HANDED_OFF_ENV = 'SHIPKIT_HANDED_OFF'
+
+const real = (p: string): string => {
+    try {
+        return realpathSync(p)
+    } catch {
+        return p
+    }
+}
+
+/** the house cli this command should run instead, or null to run here */
+export function handoffTarget(o: { own: string; env: Env; house: () => string | null; cliOf: (root: string) => string; exists?: (p: string) => boolean }): string | null {
+    if (!o.own.split(/[\\/]/).includes('node_modules')) return null
+    if (set(o.env.CI) || set(o.env.SHIPKIT_NO_HOME) || set(o.env[HANDED_OFF_ENV])) return null
+    const root = o.house()
+    if (root == null) return null
+    const target = o.cliOf(root)
+    if (!(o.exists ?? existsSync)(target)) return null
+    return real(target) === real(o.own) ? null : target
+}
+
+const OWN_CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+
+/** the cli's very first step. Returns when this copy runs the command; else
+ *  the process becomes the house cli (same pid, same argv) and never returns */
+export function handoff(argv: string[], env: Env = process.env, cwd = process.cwd()): void {
+    const target = handoffTarget({ own: OWN_CLI, env, house: () => houseRootOf(cwd), cliOf: (root) => houseCli(root, '') })
+    if (target == null) return
+    const clean = Object.fromEntries(Object.entries({ ...env, [HANDED_OFF_ENV]: '1' }).filter((e): e is [string, string] => e[1] != null))
+    const args = [process.execPath, target, ...argv]
+    const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
+    if (typeof execve === 'function') execve.call(process, process.execPath, args, clean)
+    const child = Bun.spawnSync(args, { cwd, stdout: 'inherit', stderr: 'inherit', stdin: 'inherit', env: clean })
+    process.exit(child.exitCode ?? 1)
+}

package/src/home/home-launchd.ts

@@ -0,0 +1,104 @@
+// the LaunchAgent that keeps pm alive: started at login, restarted when it
+// dies. macOS only; launchd is the one supervisor of the one process that must
+// always run, and pm supervises everything else (the daemon, the web, the
+// machine resources).
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { homeDir, pmLog } from './home-paths.ts'
+
+export const LABEL = 'com.shipkit.pm'
+/** the agent that ran `shipkit home` before pm: an install replaces it */
+export const LEGACY_LABEL = 'com.shipkit.home'
+/** where launchd reads user agents. SHIPKIT_LAUNCH_AGENTS_DIR moves it, so a
+ *  live smoke installs into a scratch dir and never the real one */
+export const agentsDir = (home = homedir()): string => process.env.SHIPKIT_LAUNCH_AGENTS_DIR ?? join(home, 'Library', 'LaunchAgents')
+export const plistPath = (home = homedir(), label = LABEL): string => join(agentsDir(home), `${label}.plist`)
+
+const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/** the agent: `bun <cli> pm` from the house repo, which replaces its image
+ *  with run-pm.ts (execPm). No bun watch: through cli.ts it would follow
+ *  every command, so any edit would restart pm. pm,
+ *  the daemon and the web each watch their own code and restart in place on
+ *  it (lib-watch.ts). PATH is the installing shell's, since launchd starts
+ *  with almost none and the daemon needs bun, git, ps, lsof and ssh */
+export function renderPlist(o: { bun: string; cli: string; root: string; path: string; log: string }): string {
+    const args = [o.bun, o.cli, 'pm'].map((a) => `\t\t<string>${esc(a)}</string>`).join('\n')
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${args}
+\t</array>
+\t<key>WorkingDirectory</key>
+\t<string>${esc(o.root)}</string>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+\t\t<key>PATH</key>
+\t\t<string>${esc(o.path)}</string>
+\t</dict>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<true/>
+\t<key>StandardOutPath</key>
+\t<string>${esc(o.log)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${esc(o.log)}</string>
+</dict>
+</plist>
+`
+}
+
+type Launchctl = (args: string[]) => Promise<{ code: number; out: string }>
+
+const launchctl: Launchctl = async (args) => {
+    const p = Bun.spawn(['launchctl', ...args], { stdout: 'pipe', stderr: 'pipe' })
+    const out = `${await new Response(p.stdout).text()}${await new Response(p.stderr).text()}`.trim()
+    return { code: await p.exited, out }
+}
+
+const domain = (): string => `gui/${process.getuid?.() ?? 501}`
+
+export async function installHome(o: { root: string; cli: string; print: (l: string) => void; run?: Launchctl }): Promise<number> {
+    if (process.platform !== 'darwin') {
+        o.print(`FAIL: the pm LaunchAgent is macOS only. Run \`shipkit pm\` under your own supervisor on ${process.platform}`)
+        return 1
+    }
+    const run = o.run ?? launchctl
+    const bun = Bun.which('bun') ?? process.execPath
+    const file = plistPath()
+    mkdirSync(agentsDir(), { recursive: true })
+    mkdirSync(homeDir(), { recursive: true })
+    const log = pmLog()
+    writeFileSync(file, renderPlist({ bun, cli: o.cli, root: o.root, path: process.env.PATH ?? '/usr/bin:/bin', log }))
+    // a loaded copy holds the old arguments: out first, then in
+    await run(['bootout', `${domain()}/${LABEL}`])
+    await run(['bootout', `${domain()}/${LEGACY_LABEL}`])
+    rmSync(plistPath(homedir(), LEGACY_LABEL), { force: true })
+    const r = await run(['bootstrap', domain(), file])
+    if (r.code !== 0) {
+        o.print(`FAIL: launchctl bootstrap refused ${file} (exit ${r.code}): ${r.out}`)
+        return 1
+    }
+    o.print(`ok: pm runs now and at every login, from ${o.root}, and runs the daemon and the web`)
+    o.print(`  agent: ${file}`)
+    o.print(`  log:   ${log}`)
+    return 0
+}
+
+export async function uninstallHome(o: { print: (l: string) => void; run?: Launchctl }): Promise<number> {
+    const run = o.run ?? launchctl
+    const file = plistPath()
+    const r = await run(['bootout', `${domain()}/${LABEL}`])
+    await run(['bootout', `${domain()}/${LEGACY_LABEL}`])
+    rmSync(plistPath(homedir(), LEGACY_LABEL), { force: true })
+    if (existsSync(file)) rmSync(file)
+    o.print(r.code === 0 ? `ok: pm, the daemon and the web are stopped and will not start at login. The resources and repo processes keep running` : `ok: no pm agent was loaded; ${file} is gone`)
+    return 0
+}

package/src/home/home-paths.ts

@@ -0,0 +1,88 @@
+// where the home keeps its machine-local files, and the one port it serves on.
+// Nothing here lives in a repo: the home is per machine, and a repo that is
+// cloned elsewhere carries none of it.
+import { homedir } from 'os'
+import { join } from 'path'
+
+/** just below the hashed hub range (4800-4979), so no repo hub can hash onto it */
+export const DEFAULT_HOME_PORT = 4799
+
+export const homePort = (): number => {
+    const env = Number(process.env.SHIPKIT_HOME_PORT)
+    return Number.isInteger(env) && env > 0 ? env : DEFAULT_HOME_PORT
+}
+
+/** the daemon's internal port: every repo runtime and every api answer
+ *  here, and the web on the home port is the one door a browser uses */
+export const DEFAULT_DAEMON_PORT = 4798
+
+export const daemonPort = (): number => {
+    const env = Number(process.env.SHIPKIT_DAEMON_PORT)
+    return Number.isInteger(env) && env > 0 ? env : DEFAULT_DAEMON_PORT
+}
+
+/** pm's port: its api (children, resources), which the web proxies at /api/pm/* */
+export const DEFAULT_PM_PORT = 4797
+
+export const pmPort = (): number => {
+    const env = Number(process.env.SHIPKIT_PM_PORT)
+    return Number.isInteger(env) && env > 0 ? env : DEFAULT_PM_PORT
+}
+
+export const pmUrl = (port = pmPort()): string => `http://127.0.0.1:${port}`
+
+/** true when pm answers on this port */
+export async function pmUp(port = pmPort(), timeoutMs = 400): Promise<boolean> {
+    try {
+        const r = await fetch(`${pmUrl(port)}/api/pm/status.json`, { signal: AbortSignal.timeout(timeoutMs) })
+        return ((await r.json()) as { pm?: string }).pm === 'shipkit-pm'
+    } catch {
+        return false
+    }
+}
+
+/** beside the rail order file (project-gutter-route.ts ORDER_FILE) */
+export const homeDir = (): string => process.env.SHIPKIT_HOME_DIR ?? join(homedir(), '.config', 'shipkit', 'home')
+
+/** set in the home process, so every process it starts (a check's child, a
+ *  repo's declared process) runs its gate and its hub in process, never back
+ *  through the home (run-serve.ts serveMode, via-hub.ts runsHere) */
+export const WORKER_ENV = 'SHIPKIT_HOME_WORKER'
+
+/** one repo's hub lines as the home prints them: its banner and its problem
+ *  frames, what `shipkit serve` streams to VS Code (attach.ts) */
+export const hubLog = (dir: string, repo: string): string => join(dir, 'hubs', `${repo}.log`)
+/** pm's own output, where launchd writes it */
+export const pmLog = (dir = homeDir()): string => join(dir, 'pm.log')
+/** pm's children: the daemon and the web, each with its log and the key of
+ *  the pid record the next pm adopts (supervise.ts pidKey) */
+export const childLog = (dir: string, role: string): string => join(dir, `${role}.log`)
+export const childPid = (dir: string, role: string): string => join(dir, `${role}.pid`)
+export const resourceLog = (dir: string, id: string): string => join(dir, 'resources', `${id}.log`)
+export const resourcePid = (dir: string, id: string): string => join(dir, 'resources', `${id}.pid`)
+export const stateFile = (dir: string): string => join(dir, 'state.json')
+
+/** the url prefix of a repo's hub on the home */
+export const hubBase = (name: string): string => `/r/${encodeURIComponent(name)}`
+
+/** the home page's url as a local client reaches it (the web) */
+export const homeUrl = (port = homePort()): string => `http://127.0.0.1:${port}`
+
+/** the daemon's url: a terminal client talks to it directly, so a gate
+ *  never depends on the web being up */
+export const daemonUrl = (port = daemonPort()): string => `http://127.0.0.1:${port}`
+
+/** true when the daemon answers on this machine */
+export const daemonUp = (timeoutMs = 400): Promise<boolean> => homeUp(daemonPort(), timeoutMs)
+
+/** true when a shipkit home answers on this port: the daemon itself, or the
+ *  web, which asks the daemon */
+export async function homeUp(port = homePort(), timeoutMs = 400): Promise<boolean> {
+    try {
+        const r = await fetch(`${homeUrl(port)}/hub.json`, { signal: AbortSignal.timeout(timeoutMs) })
+        const j = (await r.json()) as { hub?: string }
+        return j.hub === 'shipkit-home'
+    } catch {
+        return false
+    }
+}