rvlib-shipkit 1.3.0 → 1.4.0

package/src/core/discover-checks.ts

@@ -56,20 +56,23 @@ export type DiscoveredCheck = {
     from: CheckFrom
 }
 
-function walk(dir: string, out: string[], suffix = SUFFIX): void {
+function walk(dir: string, out: string[], suffix = SUFFIX, dirs?: string[]): void {
+    dirs?.push(dir)
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
     for (const e of entries) {
         if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix)
+            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix, dirs)
         } else if (e.name.endsWith(suffix)) out.push(join(dir, e.name))
     }
 }
 
-/** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted */
-export function repoUnitFiles(root: string): string[] {
+/** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted.
+ *  `dirs` collects every dir the walk read: a file added to one moves its
+ *  mtime, which is how a reader tells the list moved without walking again */
+export function repoUnitFiles(root: string, dirs?: string[]): string[] {
     const out: string[] = []
-    walk(root, out, UNIT_SUFFIX)
+    walk(root, out, UNIT_SUFFIX, dirs)
     return out.sort()
 }
 

package/src/core/layout.ts

@@ -32,6 +32,8 @@ export const LAYOUT = {
     reviews: sk('reviews'),
     // scratch: plans, logs, leases, detached runs, screenshots
     tmp: sk('tmp'),
+    // built app bundles, one per global process opened as an app (home/gui-app.ts)
+    wrapper: sk('wrapper'),
     // generated on every run
     status: sk('STATUS.md'),
     statusFull: sk('STATUS.full.md'),

package/src/core/motherhome.ts

@@ -1,15 +1,20 @@
-// Report to the motherhome — upsert this repo's row into the docsBase
-// wiki's `build/shipkit/local-projects.md`, when that page ALREADY EXISTS
-// on this disk. The lib NEVER creates the page and never writes into a
-// relative or URL docsBase: the page is a tracked wiki file, so a real
-// docs checkout has it, and a consumer that merely set docsBase as a
-// fix-pointer prefix must never find surprise files in its docs tree.
-// The whole read-modify-write runs under the shared file lock
-// (core/locked-write) — concurrent reporters never lose rows or tear the
-// file; the loser skips and self-heals on its next run. Rows whose repo
-// path no longer exists are pruned on every write. Churn control: a row
-// rewrites only when its DATA changes or its last-seen day is older than
-// 7 days. Never fails the calling command.
+// Report to the motherhome: a repo's row in the docsBase wiki's
+// `build/shipkit/local-projects.md`, in two halves.
+//
+// - `reportToMotherhome` (every ci/check/init) files the row in the MACHINE
+//   DB and nothing else. A gate answers about its own repo, so it never
+//   writes, let alone commits, in the docs repo.
+// - `landMotherhome` (the daemon's hourly sweep) renders every filed row into
+//   its page and lands the page as ONE commit, at most once per LAND_GAP_MS
+//   per page, only when a row's data changed or its last-seen day is older
+//   than STALE_DAYS.
+//
+// The lib NEVER creates the page and never reads a relative or URL docsBase:
+// the page is a tracked wiki file, so a real docs checkout has it, and a
+// consumer that merely set docsBase as a fix-pointer prefix must never find
+// surprise files in its docs tree. The page's read-modify-write runs under
+// the shared file lock (core/locked-write). Rows whose repo path no longer
+// exists are pruned from the page and from the machine db.
 import { existsSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
@@ -17,46 +22,31 @@ import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
 import { isLinkedWorktree } from './git-root.ts'
 import { machineCommit } from './machine-commit.ts'
+import { machineDelete, machineGet, machineList, machineSet } from './machine-db.ts'
 import { LIB_VERSION } from './lib-version.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
 const END = '<!-- <<< shipkit local-projects -->'
 const STALE_DAYS = 7
+/** the longest the page waits for a changed row: one commit a day at most */
+export const LAND_GAP_MS = 24 * 60 * 60 * 1000
+/** a row filed in the machine db, by its repo's path */
+const ROW = 'motherhome:'
+/** when a page last landed, by its path */
+const LANDED = 'motherhome-landed:'
 
 type Row = { name: string; root: string; version: string; mode: string; seen: string }
+type Filed = Row & { page: string }
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
-/**
- * Commit the row we just wrote, and ONLY that file.
- *
- * This page is machine written and rewrites whenever a repo's shipkit version
- * or consumption mode changes, so left alone it dirties the docs repo from a
- * gate run nobody associates with it, and the dirt then rides into an unrelated
- * commit or blocks a release. The row is not worth a human's attention in
- * either direction, so the machine that writes it also lands it.
- *
- * The scoping, the refusals and the escape hatch live in `core/machine-commit`,
- * which every machine written path commits through. This one fires only when
- * the row's DATA changed, not on every gate, so the hooks it runs are affordable.
- */
-function autoCommitRow(page: string, name: string): string {
-    const landed = machineCommit({
-        anchor: resolve(page, '..'),
-        message: `chore(machine): refresh local-projects row (${name})`,
-        paths: [page],
-    })
-    return landed ? ' + committed' : ''
-}
-
 const parseRow = (line: string): Row | null => {
     const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
 }
 
-
-// how this repo consumes the lib — `?` on an unreadable package.json (a
-// read failure must never be rendered as the fact 'path')
+// how this repo consumes the lib: `?` on an unreadable package.json (a read
+// failure must never be rendered as the fact 'path')
 function consumptionMode(root: string): string {
     try {
         const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -70,47 +60,79 @@ function consumptionMode(root: string): string {
 
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
+/** file this repo's row in the machine db. `wrote` says the filed row changed */
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
     try {
         if (config.docsBase == null) return { wrote: false }
         const base = config.docsBase.startsWith('~/') ? join(homedir(), config.docsBase.slice(2)) : config.docsBase
-        // absolute local paths only — a relative docsBase would resolve
+        // absolute local paths only: a relative docsBase would resolve
         // against CWD, a URL is a display prefix
         if (!base.startsWith('/')) return { wrote: false }
         const page = join(base, 'build/shipkit/local-projects.md')
         if (!existsSync(page)) return { wrote: false }
-        // a gate run inside a linked worktree must not write the MAIN
-        // checkout's tracked page: the row it would add describes a temporary
-        // side checkout, and the write lands as unexplained dirt in a tree
-        // somebody else is working in. The worktree's own runs are covered
-        // when its branch merges.
+        // a linked worktree is a temporary side checkout: its runs are
+        // covered when its branch merges
         if (isLinkedWorktree(root)) return { wrote: false, note: `motherhome: skipped (${config.name} is a linked worktree — its row belongs to the main checkout)` }
-
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version
-        // string names — disclose it
+        // string names: disclose it
         const version = mode === 'npm' ? LIB_VERSION : `${LIB_VERSION}+src`
-        const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
-
-        const r = withFileLock(page, (): MotherhomeOutcome => {
-            const lines = readFileSync(page, 'utf8').split('\n')
-            const b = lines.indexOf(BEGIN)
-            const e = lines.indexOf(END)
-            if (b === -1 || e === -1 || e < b) return { wrote: false, note: `WARN motherhome upsert skipped — markers missing/corrupted in ${page}` }
-            const rows = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
-            const cur = rows.find((row) => row.root === me.root)
-            const dataSame = cur != null && cur.name === me.name && cur.version === me.version && cur.mode === me.mode
-            const fresh = cur != null && (Date.parse(today) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
-            if (dataSame && fresh) return { wrote: false }
-            // prune rows for repos that no longer exist at their recorded path
-            const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
-            atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
-            const committed = autoCommitRow(page, me.name)
-            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})${committed}` }
-        })
-        // lock lost to a racing reporter — self-heals on the next run
-        return r.ok ? r.value : { wrote: false }
+        const me: Filed = { page, name: config.name, root: resolve(root), version, mode, seen: today }
+        const key = `${ROW}${me.root}`
+        if (JSON.stringify(machineGet<Filed>(key)) === JSON.stringify(me)) return { wrote: false }
+        return machineSet(key, me) ? { wrote: true } : { wrote: false, note: 'WARN motherhome row not filed: the machine db could not be written' }
     } catch (err) {
-        return { wrote: false, note: `WARN motherhome upsert failed (${String(err).slice(0, 120)}) — registry may be stale` }
+        return { wrote: false, note: `WARN motherhome row not filed (${String(err).slice(0, 120)})` }
+    }
+}
+
+/** a page's rows once the filed ones are merged in: a filed row replaces the
+ *  page's only when its data changed or the page's day is STALE_DAYS old,
+ *  and a row whose repo path is gone is pruned */
+function mergeRows(onPage: Row[], filed: Row[]): Row[] {
+    const by = new Map(onPage.map((r) => [r.root, r]))
+    for (const f of filed) {
+        const cur = by.get(f.root)
+        const same = cur != null && cur.name === f.name && cur.version === f.version && cur.mode === f.mode
+        const fresh = cur != null && (Date.parse(f.seen) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
+        if (!(same && fresh)) by.set(f.root, { name: f.name, root: f.root, version: f.version, mode: f.mode, seen: f.seen })
+    }
+    return [...by.values()].filter((r) => existsSync(r.root)).sort((a, z) => a.name.localeCompare(z.name) || a.root.localeCompare(z.root))
+}
+
+/** render every filed row into its page and land each changed page as one
+ *  commit, at most once per LAND_GAP_MS. Returns what to print */
+export function landMotherhome(o: { now?: number; gapMs?: number } = {}): string[] {
+    const now = o.now ?? Date.now()
+    const notes: string[] = []
+    const filed = machineList<Filed>(ROW)
+    for (const f of filed) if (!existsSync(f.value.root)) machineDelete(f.name)
+    const pages = new Map<string, Row[]>()
+    for (const f of filed) if (existsSync(f.value.root)) pages.set(f.value.page, [...(pages.get(f.value.page) ?? []), f.value])
+    for (const [page, rows] of pages) {
+        try {
+            if (!existsSync(page)) continue
+            const last = machineGet<number>(`${LANDED}${page}`)
+            if (last != null && now - last < (o.gapMs ?? LAND_GAP_MS)) continue
+            const r = withFileLock(page, (): boolean => {
+                const text = readFileSync(page, 'utf8')
+                const lines = text.split('\n')
+                const b = lines.indexOf(BEGIN)
+                const e = lines.indexOf(END)
+                if (b === -1 || e === -1 || e < b) { notes.push(`WARN motherhome: markers missing or out of order in ${page}, rows not written`); return false }
+                const onPage = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
+                const next = [...lines.slice(0, b + 1), ...mergeRows(onPage, rows).map(rowLine), ...lines.slice(e)].join('\n')
+                if (next === text) return false
+                atomicWrite(page, next)
+                return true
+            })
+            if (!r.ok || !r.value) continue
+            machineSet(`${LANDED}${page}`, now)
+            const landed = machineCommit({ anchor: resolve(page, '..'), message: 'chore(machine): refresh local-projects rows', paths: [page] })
+            notes.push(`motherhome: ${page} rows refreshed${landed ? ' + committed' : ', not committed'}`)
+        } catch (err) {
+            notes.push(`WARN motherhome: ${page} not refreshed (${String(err).slice(0, 120)})`)
+        }
     }
+    return notes
 }

package/src/core/run-check.ts

@@ -87,11 +87,8 @@ export type CheckOpts = {
     /** the gate binary that own ledger is keyed on (default: the one running
      *  it). Ignored when `ledger` is passed, which carries its own. */
     cliEntry?: string
-    /** refresh the motherhome registry row. runCi passes false and does it
-     *  ITSELF, after the ledger has committed: that row is a TRACKED file under
-     *  `wiki/`, so writing it before the post-run re-hash makes the gate look
-     *  like an agent editing the tree and throws away every result the run just
-     *  measured. */
+    /** file the motherhome row in the machine db (core/motherhome.ts). runCi
+     *  passes false and does it ITSELF, once, after its verdict. */
     reportHome?: boolean
 }
 

package/src/core/run-ci.ts

@@ -289,9 +289,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // a narrowed run asked no question about
     const verdict = code === 0 && !run.interrupted ? verdictLine(run.results, scope.fullGate ? { tier, cache: ledger?.counts ?? null } : null) : null
     if (verdict != null) sink(verdict)
-    // motherhome row (docsBase wiki on this disk) — never affects the gate,
-    // and never fires under frozen: a bump/release gate must not re-dirty the
-    // tree it just proved clean
+    // the motherhome row, filed in the machine db and landed in the docsBase
+    // page by the daemon (core/motherhome.ts): never affects the gate, never
+    // writes in another repo, and a frozen run files nothing
     if (o.frozen !== true) {
         const mh = reportToMotherhome(root, c)
         if (mh.note != null) print(mh.note)

package/src/core/wire.ts

@@ -3,22 +3,51 @@
 // exit 0/1. FROZEN: consumers grep startsWith('FAIL'/'WARN'/'skip:') — a
 // prefix change is a breaking change of the whole toolkit.
 
-export type Line = { kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'; text: string }
+import { CACHED, RAN } from './outcome-words.ts'
+
+/** when a remembered world answer was measured, and until when it keeps
+ *  (null: until its declaration changes). Kept as data, never as text, and
+ *  rendered against the reader's clock: a time frozen into the line reads
+ *  as a future expiry long after it passed */
+export type Stamp = { at: number; until: number | null; cached?: boolean }
+
+export type Line = { kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'; text: string; stamp?: Stamp }
+
+/** a span in its one biggest unit: `45s`, `12m`, `3h`, `2d` */
+export function spanShort(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** `cached, ran 3h ago, kept 57m more`, `ran 1d ago, expired 1d ago` */
+export function stampWords(s: Stamp, now: number): string {
+    const age = now - s.at
+    const ran = age < 1000 ? `${RAN} just now` : `${RAN} ${spanShort(age)} ago`
+    const keeps = s.until == null ? 'kept until its declaration changes' : s.until > now ? `kept ${spanShort(s.until - now)} more` : `expired ${spanShort(now - s.until)} ago`
+    return `${s.cached === true ? `${CACHED}, ` : ''}${ran}, ${keeps}`
+}
+
+/** a line's text as a reader sees it now, its stamp rendered */
+export const lineText = (l: Line, now: number = Date.now()): string => (l.stamp == null ? l.text : `${l.text} (${stampWords(l.stamp, now)})`)
 
 const green = (s: string): string => `\x1b[32m${s}\x1b[0m`
 const red = (s: string): string => `\x1b[31m${s}\x1b[0m`
 const yellow = (s: string): string => `\x1b[33m${s}\x1b[0m`
 
-export function formatLine(l: Line, color: boolean): string {
+export function formatLine(l: Line, color: boolean, now: number = Date.now()): string {
     const c = (f: (s: string) => string, s: string) => (color ? f(s) : s)
+    const text = lineText(l, now)
     switch (l.kind) {
-        case 'ok': return `${c(green, 'ok:')} ${l.text}`
-        case 'warn': return c(yellow, `WARN ${l.text}`)
-        case 'fail': return c(red, `FAIL: ${l.text}`)
-        case 'fix-warn': return `      ${c(yellow, `fix: ${l.text}`)}`
-        case 'fix-fail': return `      ${c(red, `fix: ${l.text}`)}`
-        case 'skip': return `skip: ${l.text}`
-        case 'note': return l.text
+        case 'ok': return `${c(green, 'ok:')} ${text}`
+        case 'warn': return c(yellow, `WARN ${text}`)
+        case 'fail': return c(red, `FAIL: ${text}`)
+        case 'fix-warn': return `      ${c(yellow, `fix: ${text}`)}`
+        case 'fix-fail': return `      ${c(red, `fix: ${text}`)}`
+        case 'skip': return `skip: ${text}`
+        case 'note': return text
     }
 }
 

package/src/home/activity-shape.ts

@@ -64,8 +64,11 @@ export type StatusCheck = {
     status: 'fail' | 'warn'
     /** when that outcome was recorded, epoch ms */
     at: number | null
-    /** the first line it printed about the problem, '' when it printed none */
+    /** the worst line it printed about the problem, '' when it printed none */
     line: string
+    /** every fail and warn line it printed, the worst weight first: a check
+     *  reporting three findings lists three */
+    lines: string[]
 }
 
 export type ActivityAnswer = { now: number; minutes: number; rows: ActivityRow[]; ms: number }

package/src/home/activity.ts

@@ -11,7 +11,7 @@
 import { gitBin } from '../core/git-bin.ts'
 import { readLastStatusReadonly } from '../ledger/run-log.ts'
 import { checkStateOf, recordOf } from '../serve/project-gutter.ts'
-import type { Line } from '../core/wire.ts'
+import { lineText, type Line } from '../core/wire.ts'
 import { MAX_COMMITS, MAX_FILES, type ActivityAnswer, type ActivityCommit, type ActivityRepo, type ActivityRow, type FileKind, type StatusCheck } from './activity-shape.ts'
 
 export * from './activity-shape.ts'
@@ -93,26 +93,32 @@ export type Declared = (name: string) => ReadonlySet<string> | null
 /** each declared check's title by id; null = not known, the id stands in */
 export type Titles = (name: string) => ReadonlyMap<string, string> | null
 
-/** the line a check printed about its problem: its first line of the same
- *  weight (a fail for a failure, a warning for a warning), else its first
- *  line that is not a pass, without the id its line leads with */
-export function findingOf(lines: string, status: 'fail' | 'warn', id: string): string {
+/** every line a check printed about its problems: its fail and warn lines,
+ *  those of its own weight first (a fail for a failure, a warning for a
+ *  warning), else its first line that is not a pass, each without the id it
+ *  leads with */
+export function findingsOf(lines: string, status: 'fail' | 'warn', id: string): string[] {
     let parsed: Line[]
     try {
         parsed = JSON.parse(lines) as Line[]
     } catch {
-        return ''
+        return []
     }
-    if (!Array.isArray(parsed)) return ''
-    const kinds = status === 'fail' ? ['fail', 'fix-fail'] : ['warn', 'fix-warn']
-    const hit = parsed.find((l) => kinds.includes(l.kind)) ?? parsed.find((l) => l.kind !== 'ok' && l.kind !== 'skip')
-    if (hit == null) return ''
-    const t = hit.text.trim()
-    // `[ID] text`, and a runner line's `ID — text`: the list names the id already
-    for (const lead of [`[${id}]`, `${id} —`]) if (t.startsWith(lead)) return t.slice(lead.length).trim()
-    return t
+    if (!Array.isArray(parsed)) return []
+    const of = (k: Line['kind']): Line[] => parsed.filter((l) => l.kind === k)
+    let hits = status === 'fail' ? [...of('fail'), ...of('warn')] : [...of('warn'), ...of('fail')]
+    if (hits.length === 0) hits = parsed.filter((l) => l.kind !== 'ok' && l.kind !== 'skip').slice(0, 1)
+    return hits.map((l) => {
+        const t = lineText(l).trim()
+        // `[ID] text`, and a runner line's `ID — text`: the list names the id already
+        for (const lead of [`[${id}]`, `${id} —`]) if (t.startsWith(lead)) return t.slice(lead.length).trim()
+        return t
+    })
 }
 
+/** the worst of them, '' when it printed none */
+export const findingOf = (lines: string, status: 'fail' | 'warn', id: string): string => findingsOf(lines, status, id)[0] ?? ''
+
 /** a repo's checks as its run record last saw them, counted over what it
  *  declares, and the failing and warning ones with what each said */
 export function statusOf(repo: ActivityRepo, declared: Declared | null = null, titles: Titles | null = null): Pick<ActivityRow, 'status' | 'failing'> {
@@ -125,7 +131,8 @@ export function statusOf(repo: ActivityRepo, declared: Declared | null = null, t
     const named = titles?.(repo.name) ?? null
     const one = (id: string, st: 'fail' | 'warn'): StatusCheck => {
         const r = byId.get(id)
-        return { id, title: named?.get(id) ?? id, status: st, at: status.since[id] ?? null, line: r == null ? '' : findingOf(r.lines, st, id) }
+        const lines = r == null ? [] : findingsOf(r.lines, st, id)
+        return { id, title: named?.get(id) ?? id, status: st, at: status.since[id] ?? null, line: lines[0] ?? '', lines }
     }
     return { status, failing: [...status.reds.map((id) => one(id, 'fail')), ...status.warns.map((id) => one(id, 'warn'))] }
 }