rvlib-shipkit 0.38.1 → 1.0.0

package/src/collections/checks.ts

@@ -0,0 +1,258 @@
+// THE GATE CHECKS, one resource each. Repo health used to be the text of
+// STATUS.md parsed back into one row per wire line, so seventy checks shared
+// one destination, an id was a whole sentence, and nothing could be timed,
+// opened or addressed on its own.
+//
+// Everything here is READ: `gateInventory` is the one enumeration of what the
+// gate runs (ledger/gate-checks.ts), the timings come from the store and the
+// run record beside it, and the last wire lines come from what the last run
+// wrote. Nothing in this file decides anything about a run.
+//
+// THE DEMOTION, which is why `status` is not read off the lines: a check that
+// cannot block has its FAIL rewritten to a warn inside the check engine, so
+// the wire is honest about the GATE and silent about the check. The run
+// record keeps the real outcome, and `advisory` is what says a red here
+// stops nothing.
+import { existsSync, readFileSync } from 'fs'
+import { homedir } from 'os'
+import { isAbsolute, join, relative, resolve } from 'path'
+import { rawName, routesToShipkit } from '../core/canonical-scripts.ts'
+import { FLOOR_IDS } from '../core/floor.ts'
+import { formatLine, parseDuration } from '../core/wire.ts'
+import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
+import { readLastLines, readRuns, runsPath, type LastLine, type RunRow } from '../ledger/run-log.ts'
+import { checkStatsFor, type CheckStat } from '../ledger/check-stats.ts'
+import { NEGATIVE_TTL_CAP_MS } from '../ledger/world-cache.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { Collection, Instance, NeedSeverity, ResourceState, CheckFacts, RecentRun } from './collection-types.ts'
+import { checkVerdictWords, plural } from '../core/outcome-words.ts'
+
+/** what a check is killed at when it names no `timeoutMs`: a build step runs a
+ *  whole tool chain, everything else answers one question */
+export const CHECK_TIMEOUT_MS = 120_000
+export const BUILD_TIMEOUT_MS = 600_000
+
+export type ChecksOpts = {
+    /** injected by tests; production reads the store plus the run record */
+    stats?: Map<string, CheckStat>
+    lastLines?: Record<string, LastLine>
+    runs?: RunRow[]
+    scripts?: Record<string, string>
+}
+
+/** how many outcomes a check's page draws as its bar row. Enough to see a
+ *  shape, few enough that one wide widget holds them all */
+const KEEP_RUNS = 16
+
+/** the last outcomes of every check, oldest first. The AVERAGE hides the
+ *  shape: what a page draws is the run after run verdict, reds and replays
+ *  included, which only the log has */
+export function recentRuns(runs: RunRow[], keep = KEEP_RUNS): Record<string, RecentRun[]> {
+    const out: Record<string, RecentRun[]> = {}
+    for (const r of [...runs].sort((a, b) => a.at - b.at)) {
+        const list = out[r.id] ?? []
+        list.push({ at: r.at, ms: r.ms, status: r.status, replayed: r.replayed })
+        out[r.id] = list.length > keep ? list.slice(-keep) : list
+    }
+    return out
+}
+
+export function checksCollection(root: string, c: RepoConfig, o: ChecksOpts = {}): Collection {
+    return {
+        id: 'checks',
+        title: 'gate checks',
+        media: 'health',
+        list: async () => {
+            const rows = await gateInventory(root, c)
+            const stats = o.stats ?? checkStatsFor(root, rows.map((r) => ({ id: r.decl.id })))
+            const lines = o.lastLines ?? readLastLines(runsPath(root))
+            const recent = recentRuns(o.runs ?? readRuns(runsPath(root)))
+            const scripts = o.scripts ?? readScripts(root)
+            return rows.map((row) => {
+                const key = row.decl.id
+                return instanceOf(root, c, row, stats.get(key), lines[key], recent[key], scriptOf(scripts, row))
+            })
+        },
+    }
+}
+
+/** the package.json scripts, or none when the file is absent or unreadable:
+ *  the page then shows the argv alone, which is still the truth */
+function readScripts(root: string): Record<string, string> {
+    try { return (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
+    catch { return {} }
+}
+
+/** the script behind a build step: the one `<pm> run <name>` names, else for a
+ *  floor slot the body the floor resolved (`lint:raw`, then `lint` when it
+ *  does not route back to shipkit), which is what the test slot runs through
+ *  the suite runner */
+export function scriptOf(scripts: Record<string, string>, row: CheckRow): { name: string; body: string } | null {
+    if (!row.build) return null
+    const argv = row.decl.argv ?? []
+    const floor = (FLOOR_IDS as readonly string[]).includes(row.decl.id)
+    const names = [argv[1] === 'run' ? argv[2] : undefined, ...(floor ? [rawName(row.decl.id), row.decl.id] : [])]
+    for (const name of names) {
+        const body = name == null ? undefined : scripts[name]
+        if (name != null && body != null && !routesToShipkit(body)) return { name, body }
+    }
+    return null
+}
+
+function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat | undefined, last: LastLine | undefined, recent: RecentRun[] | undefined, script: { name: string; body: string } | null = null): Instance {
+    const id = row.decl.id
+    const wireLines = (last?.lines ?? []).map((l) => formatLine(l, false))
+    const status = stat?.last?.status ?? null
+    const replayed = stat?.last?.replayed === true
+    // the real outcome against what it declared: a FAIL that cannot block
+    // stops nothing, and is the one case the wire lines hide
+    const advisory = status === 'fail' && row.blocking === false
+    const facts: CheckFacts = {
+        checkId: id,
+        description: row.description,
+        lastLines: wireLines,
+        gate: row.gate,
+        build: row.build,
+        blocking: row.blocking,
+        advisory,
+        optIn: row.optIn,
+        ...where(row),
+        file: sourceFile(root, row),
+        doc: docPage(root, c, row),
+        cmd: row.decl.argv ?? null,
+        script,
+        deps: row.deps,
+        from: row.from,
+        group: row.group,
+        inputs: row.decl.inputs ?? undefined,
+        ttl: row.decl.ttl ?? undefined,
+        never: row.decl.never ?? undefined,
+        reads: row.decl.reads === true ? true : undefined,
+        timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
+        status,
+        replayed,
+        lastMs: stat?.last == null || replayed ? null : stat.last.ms,
+        lastAt: stat?.last?.at ?? null,
+        avgMs: stat?.avgMs ?? null,
+        samples: stat?.samples ?? 0,
+        slowestMs: stat?.slowestMs ?? null,
+        failures: stat?.failures ?? 0,
+        measuredAt: stat?.measuredAt ?? null,
+        measuredStatus: stat?.measuredStatus ?? null,
+        keepsUntil: keepsUntil(row.decl.ttl, stat),
+        recent: recent ?? [],
+    }
+    const wire = last?.lines ?? []
+    return {
+        id: `check:${id}`,
+        text: feedLine(row, facts),
+        label: rowLabel(row, facts),
+        type: 'check',
+        ...place(root, c, row),
+        state: stateOf(facts),
+        severity: severityOf(facts),
+        check: facts,
+        md: wireLines.length === 0 ? undefined : `\`\`\`\n${wireLines.join('\n')}\n\`\`\``,
+        file: facts.file ?? undefined,
+    }
+}
+
+/** when a world probe's remembered answer runs out: its ttl from the last
+ *  MEASUREMENT, or the shorter negative window when that measurement was not
+ *  clean (ledger/world-cache.ts rememberWorld keeps the same two). null for a
+ *  check that remembers nothing on a clock, or was never measured */
+export function keepsUntil(ttl: string | undefined, stat: Pick<CheckStat, 'measuredAt' | 'measuredStatus'> | undefined): number | null {
+    if (ttl == null || ttl === '' || stat?.measuredAt == null) return null
+    let ms = 0
+    try { ms = parseDuration(ttl) } catch { return null }
+    if (ms <= 0) return null
+    return stat.measuredAt + (stat.measuredStatus === 'pass' ? ms : Math.min(ms, NEGATIVE_TTL_CAP_MS))
+}
+
+/** where this check runs today, in the one vocabulary. The inventory already
+ *  read it (core/when.ts owns the `when` key and the two spellings it
+ *  replaces), so this only spreads it onto the wire shape */
+function where(row: CheckRow): Pick<CheckFacts, 'when' | 'whenReason' | 'whenSource'> {
+    return { when: row.when.at, whenReason: row.when.reason, whenSource: row.when.source }
+}
+
+/** a check whose OWNER is the argv it runs: a floor slot and a `tasks: []`
+ *  entry have a command where a path would be, so neither has a file to open
+ *  nor a page to link. A `*.check.ts` that declares itself a build step still
+ *  has both. */
+const ownerIsCommand = (row: CheckRow): boolean => row.owner != null && row.owner === row.decl.argv?.join(' ')
+
+/** the file a reader opens to see what this check DOES: its own module, when
+ *  it has one in this repo. A build step derived from a script is a command,
+ *  and a built-in ships inside the toolkit, so both answer null. A test check
+ *  carries its test files as code for its KEY, and none of them is what it is */
+function sourceFile(root: string, row: CheckRow): string | null {
+    if (ownerIsCommand(row)) return null
+    const code = row.decl.code?.[0]
+    return code == null ? null : repoRelative(root, code) ?? code
+}
+
+/** the PAGE that owns the invariant, when the owner names one. A check whose
+ *  owner is its own file in this repo has no page: `file` already points at
+ *  it, and a doc link to the same path is one link saying nothing twice. */
+function docPage(root: string, c: RepoConfig, row: CheckRow): string | null {
+    if (row.owner == null || ownerIsCommand(row)) return null
+    return repoRelative(root, row.owner) != null ? null : `${c.docsBase ?? ''}${row.owner}`
+}
+
+/** the TREE label: the name, and nothing else. The verdict, the duration and
+ *  where it runs are slots of their own on the row, aligned down the column,
+ *  and the words behind them are the row's tooltip. */
+function rowLabel(row: CheckRow, f: CheckFacts): string {
+    return row.title === f.checkId ? f.checkId : `${f.checkId} ${row.title}`
+}
+
+/** the FEED line: a terminal has no slots, so `shipkit needs` and the ping
+ *  still need one sentence carrying what it last did and what it costs. */
+function feedLine(row: CheckRow, f: CheckFacts): string {
+    const timing = f.lastMs != null ? `, took ${fmtMs(f.lastMs)}` : ''
+    const avg = f.avgMs != null && f.samples > 1 ? `, average ${fmtMs(f.avgMs)} over ${plural(f.samples, 'run')}` : ''
+    return `${rowLabel(row, f)} ${checkVerdictWords(f.status, f)}${timing}${avg}`
+}
+
+export const fmtMs = (ms: number): string => (ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`)
+
+/** green is MEASURED passing and nothing else may claim it, so a replay is
+ *  quiet: it is the last verdict, not this tree's evidence. */
+function stateOf(f: CheckFacts): ResourceState {
+    if (f.status === 'fail') return f.advisory ? 'warn' : 'red'
+    if (f.status === 'warn') return 'warn'
+    if (f.status === 'skip') return 'quiet'
+    if (f.status === 'pass') return f.replayed ? 'quiet' : 'ok'
+    return 'idle'
+}
+
+/** what reaches `shipkit needs` and the ping. An advisory failure is about
+ *  the world rather than this change, so it is taste debt, never a phone
+ *  notification at night. */
+function severityOf(f: CheckFacts): NeedSeverity | undefined {
+    if (f.status === 'fail') return f.advisory ? 'yellow' : 'red'
+    if (f.status === 'warn') return 'yellow'
+    return undefined
+}
+
+/** where the check lives on the tree. A check that IS a file in this repo, or
+ *  whose owner page is one, sits beside everything else in that folder, which
+ *  is the whole payoff of pathing resources. A build step is a command, so it
+ *  has no file and says so under a virtual root. */
+function place(root: string, c: RepoConfig, row: CheckRow): Pick<Instance, 'path' | 'virtual'> {
+    const virtual = { path: `health/check/${row.decl.id}`, virtual: true as const }
+    if (row.owner == null || ownerIsCommand(row)) return virtual
+    const rel = repoRelative(root, row.owner) ?? repoRelative(root, `${c.docsBase ?? ''}${row.owner}`)
+    return rel == null ? virtual : { path: rel }
+}
+
+/** a rule's owner is a page of the docs wiki, which may live in ANOTHER repo
+ *  entirely (docsBase is a path, `~` included). Only a file inside this repo
+ *  can be a node of this repo's tree. */
+function repoRelative(root: string, p: string): string | null {
+    const abs = resolve(root, p.startsWith('~/') ? join(homedir(), p.slice(2)) : p)
+    if (!existsSync(abs)) return null
+    const rel = relative(root, abs).replace(/\\/g, '/')
+    return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? null : rel
+}

package/src/collections/collection-types.ts

@@ -6,14 +6,217 @@
 // default, or a paste-from-elsewhere. Doctrine page: build/collections in
 // the docs wiki this lib ships beside.
 
+import type { WhenAt, WhenSource } from '../core/when.ts'
+import type { CheckFrom } from '../ledger/gate-checks.ts'
+
 export type NeedSeverity = 'red' | 'yellow'
 
 export type CurationVerb = 'pick' | 'approve' | 'rate' | 'provide' | 'paste-proof' | 'set' | 'done' | 'archive'
 
+/** the id the runs page opens by. The page is a PAGE, reached from the
+ *  header, never a resource of the tree. Its tab rides after it
+ *  (`runs:files`), so a reload lands on the same list */
+export const RUNS_ID = 'runs'
+
+/** the resource id of one test file, from its repo relative path: the tree
+ *  row, the runs page and the to fix list all open the same page by it */
+export const testId = (file: string): string => `test:${file}`
+
+/** where the tree files the test files no check reaches, in both views */
+export const NO_CHECK = 'in no check'
+
+/** the resource KIND, never the collection it came from: one folder holds
+ *  several kinds, which is what makes the path tree worth having. `health`
+ *  is what belongs to no check (the hub's own staleness line) */
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'health', 'check', 'test', 'reflection'] as const
+
+export type ResourceType = (typeof RESOURCE_TYPES)[number]
+
+/** what a gate check is and what it last cost. The wire lines say none of
+ *  this: a non-blocking failure is demoted to a warn before anything reads
+ *  them, and a duration is nowhere on them at all. */
+/** one outcome of one check, as its page draws it */
+export type RecentRun = { at: number; ms: number; status: 'pass' | 'warn' | 'fail' | 'skip'; replayed: boolean }
+
+export type CheckFacts = {
+    /** the id `--only` takes, which is NOT the resource id */
+    checkId: string
+    /** the check's one line description (the shape: check.ts
+     *  descriptionProblem). Every inventory row carries one, a generated row
+     *  included (ledger/gate-checks.ts CheckRow) */
+    description: string
+    /** the wire lines of its last run, already formatted, one per entry. The
+     *  page renders each one as INLINE markdown, so a `fix:` pointer's url is
+     *  clickable and its backtick spans read as code, while the line
+     *  structure the wire protocol fixes stays exactly as it was printed. */
+    lastLines: string[]
+    /** does `shipkit ci` run it? false = proactive, `shipkit check` only */
+    gate: boolean
+    /** a BUILD STEP: the gate runs it, the health pass does not (derived from
+     *  a floor slot or the repo's `tasks: []`, never declared by a check) */
+    build: boolean
+    /** null = the check never declared, which the check runner treats as fatal */
+    blocking: boolean | null
+    /** it FAILED and cannot block: orange here, nothing on the gate */
+    advisory: boolean
+    /** off the default run unless named with `--with` */
+    optIn: boolean
+    /** where it runs TODAY, in the one vocabulary the switch writes:
+     *  always (every gate) · release (`--full` and the release path only) ·
+     *  health (the health pass only) · off (not at all, with a reason) */
+    when: WhenAt
+    /** mandatory on off, null otherwise */
+    whenReason: string | null
+    /** which declaration decided it, so a page can say whether the switch is
+     *  reading `when` or one of the two spellings it replaces */
+    whenSource: WhenSource
+    /** the file that IS the check, when it has one in this repo. A build step
+     *  is a command and a built-in ships inside the toolkit, so both say
+     *  null */
+    file: string | null
+    /** the page that owns the answer, when the owner is a docs page */
+    doc: string | null
+    /** the argv a subprocess check runs */
+    cmd: string[] | null
+    /** a build step filled by a package.json script: its name and the body
+     *  it expands to, so a page can say what `bun run lint` really runs */
+    script?: { name: string; body: string } | null
+    /** what it waits on, when it waits on anything */
+    deps: string[] | null
+    /** whose check it is: `shipkit` = the toolkit ships it, `repo` = this repo
+     *  declared it (its package.json script behind a floor slot, a task, a
+     *  rule, a check file) */
+    from: CheckFrom
+    group: string | null
+    /** the cache population it declared: content, world, or decided never */
+    inputs?: string[]
+    ttl?: string
+    never?: string
+    /** keyed on what its body read through the check context */
+    reads?: boolean
+    /** where it is killed: a check creeping toward its ceiling is visible
+     *  before it trips */
+    timeoutMs: number
+    status: 'pass' | 'warn' | 'fail' | 'skip' | null
+    replayed: boolean
+    /** what the last run cost, ms. null on a replay: it measured nothing */
+    lastMs: number | null
+    lastAt: number | null
+    /** mean over the MEASURED runs, reds included */
+    avgMs: number | null
+    samples: number
+    slowestMs: number | null
+    failures: number
+    /** when it was last MEASURED rather than replayed, and what that said.
+     *  A remembered answer expires from its measurement */
+    measuredAt?: number | null
+    measuredStatus?: 'pass' | 'warn' | 'fail' | 'skip' | null
+    /** a world probe only: when its remembered answer runs out, so the next
+     *  health pass after it measures again. null = nothing kept on a clock */
+    keepsUntil?: number | null
+    /** the last outcomes, oldest first: the shape an average hides */
+    recent?: RecentRun[]
+}
+
+/** the declaration of a slow suite, carried by the test file it names. A
+ *  suite is not a gate check: it is suite granularity inside one task, so it
+ *  carries its own facts rather than borrowing CheckFacts it cannot fill */
+export type SuiteFacts = {
+    /** the suite path as the declaration writes it, relative to the repo root
+     *  or to the unit's own dir */
+    file: string
+    /** what it catches that no fast test can */
+    catches: string
+    /** why it cannot be made fast */
+    whyNotFast: string
+    /** the config file that declares it */
+    configPath: string
+    /** the unit whose `tests.slow` holds it, null = the repo root's */
+    unit: string | null
+    /** the per suite quick tier budget it broke, ms */
+    budgetMs: number
+}
+
+/** one recorded run of one test file, newest first on its page. The three
+ *  optional fields are absent on a row recorded before the record kept them
+ *  (ledger/suite-log.ts SuiteRow says what each one means) */
+export type TestRun = {
+    at: number
+    ms: number
+    status: 'pass' | 'fail'
+    tier: 'quick' | 'full'
+    budgetMs: number
+    cpuMs?: number | null
+    phase?: 'parallel' | 'sequential' | 'serial' | ''
+    phaseMs?: number | null
+    failLine?: string
+}
+
+/** where a test file stands with the checks: a check runs it, a bunfig
+ *  ignore keeps it out on purpose, no check reaches it (what SK018 fails),
+ *  its check's script is not a plain `bun test` so nothing can say, or a slow
+ *  declaration names a file that is not on disk */
+export type TestStanding = 'runs' | 'ignored' | 'orphan' | 'opaque' | 'missing'
+
+/** one test file, as its row and its page read it */
+export type TestFacts = {
+    /** repo relative */
+    file: string
+    /** relative to its unit's dir, the name its row carries */
+    inUnit: string
+    /** the unit whose dir holds it: `root` or a unit id */
+    unit: string
+    /** that unit's dir, '' for the root */
+    unitDir: string
+    /** the check that runs it (or would, for an ignored or opaque file), null
+     *  when no check reaches it */
+    checkId: string | null
+    standing: TestStanding
+    /** the ignore pattern, or why no check reaches it, or why nothing can say */
+    why: string | null
+    /** `quick` = every gate, `full` = declared slow, the release path only */
+    tier: 'quick' | 'full'
+    /** the per file quick tier budget, ms */
+    budgetMs: number
+    /** THE to fix verdict, from ledger/run-timeline.ts testFilesToFix, the one
+     *  function the runs page tab reads too. null = nothing to fix */
+    toFix: { red: boolean; slow: boolean } | null
+    /** the last recorded runs, newest first */
+    runs: TestRun[]
+    /** how to run it alone: the command, from `cwd` (repo relative, '' the root) */
+    cmd: { cwd: string; line: string }
+    /** a declared slow suite: the case its declaration argued */
+    suite?: SuiteFacts
+}
+
+/** the colour source on a tree label, wider than severity:
+ *  red = broken · warn = taste pending or a default in use · ok = MEASURED
+ *  passing (nothing unmeasured may claim it) · idle = healthy and worth
+ *  reading, the neutral default · quiet = archived, replayed, out of play */
+export type ResourceState = 'red' | 'warn' | 'ok' | 'idle' | 'quiet'
+
 export type Instance = {
     id: string
     /** one-line human text — the feed line */
     text: string
+    /** the tree label, when the feed line is not one. A row carries a NAME
+     *  and puts its verdict in the slots beside it; the feed keeps the
+     *  sentence, because a terminal has no slots */
+    label?: string
+    /** the ONE short fact this kind shows in the tree's note slot: an ask its
+     *  kind, a secret present or missing, a post its venue, an asset its roll
+     *  count. Absent = this kind has nothing to say there */
+    slot?: string
+    type: ResourceType
+    /** a slash path. Where a truth file exists this IS its repo-relative
+     *  path; otherwise a VIRTUAL path under a root named for the type, and
+     *  `virtual` says so rather than sending a reader hunting for a file */
+    path: string
+    /** true when `path` names no file on disk */
+    virtual?: boolean
+    /** absent = derived from severity (red → red, yellow → warn, none →
+     *  idle). Set it directly to claim `ok` or `quiet` */
+    state?: ResourceState
     /** absent = healthy, nothing needed */
     severity?: NeedSeverity
     /** deep link (studio anchor, /status, external editor) */
@@ -33,6 +236,10 @@ export type Instance = {
     /** the truth file's markdown BODY (frontmatter stripped) — clamped card
      *  in the grid, full in the item view; capped server-side, never a dump */
     md?: string
+    /** gate checks only: what it is, and what it last cost */
+    check?: CheckFacts
+    /** test files only: where it runs and what it last cost */
+    test?: TestFacts
     /** an open ask owns the action (dedup = acted-on once, never hidden):
      *  the instance stays red HERE but verbs and pings live with the ask */
     askOwned?: boolean
@@ -48,6 +255,52 @@ export type Collection = {
 
 export type NeedItem = Instance & { collection: string }
 
+/** the wire shape the hub tree reads: one flat array for the whole repo.
+ *  `title` is the row label and `state` its colour, both filled HERE so no
+ *  provider states them twice. `text` stays as the alias every older
+ *  consumer reads, and dies with the last provider that writes it */
+export type Resource = Instance & { collection: string; title: string; state: ResourceState }
+
+/** PROACTIVE kinds: work waiting on a human, which is not the same thing as
+ *  something being broken. Red is reserved for broken (a blocking check that
+ *  failed, a secret a page needs and does not have, a collector that threw),
+ *  so these read as taste pending on the tree. Their `severity` is untouched,
+ *  because that is the axis `shipkit needs` and the once ever ping read */
+const PROACTIVE: ReadonlySet<ResourceType> = new Set<ResourceType>(['ask'])
+
+/** THE mapping from what a provider declared to the colour a row wears. One
+ *  place, so a kind cannot be red on the tree and yellow in the feed */
+export const stateOf = (i: Instance): ResourceState =>
+    i.state ?? (i.severity === 'red' ? (PROACTIVE.has(i.type) ? 'warn' : 'red') : i.severity === 'yellow' ? 'warn' : 'idle')
+
+export async function listResources(c: Collection): Promise<Resource[]> {
+    return (await c.list()).map((i) => ({ ...i, collection: c.id, title: i.label ?? i.text, state: stateOf(i) }))
+}
+
+/** every resource of every collection, failure-isolated per collection: a
+ *  broken source reports itself as ONE red row, never blanks the tree */
+export async function projectResources(collections: Collection[]): Promise<Resource[]> {
+    const out: Resource[] = []
+    for (const c of collections) {
+        try {
+            out.push(...(await listResources(c)))
+        } catch (e) {
+            out.push({
+                collection: c.id,
+                id: `${c.id}:broken`,
+                type: 'health',
+                path: `health/${c.id}-collector`,
+                virtual: true,
+                title: `collector broke: ${(e as Error).message}`,
+                text: `collector broke: ${(e as Error).message}`,
+                severity: 'red',
+                state: 'red',
+            })
+        }
+    }
+    return out
+}
+
 /** the flat needs projection — failure-isolated per collection: a broken
  *  source reports itself as ONE red item, never blanks the feed */
 export async function projectNeeds(collections: Collection[]): Promise<NeedItem[]> {
@@ -56,7 +309,7 @@ export async function projectNeeds(collections: Collection[]): Promise<NeedItem[
         try {
             for (const i of await c.list()) if (i.severity != null) out.push({ ...i, collection: c.id })
         } catch (e) {
-            out.push({ collection: c.id, id: `${c.id}:broken`, text: `collector broke: ${(e as Error).message}`, severity: 'red' })
+            out.push({ collection: c.id, id: `${c.id}:broken`, type: 'health', path: `health/${c.id}-collector`, virtual: true, text: `collector broke: ${(e as Error).message}`, severity: 'red' })
         }
     }
     return out

package/src/collections/comfy.ts

@@ -0,0 +1,23 @@
+// comfy collection — the repo's workflow modules as section rows, so the
+// sidebar, the grid, the search and the cmd+j palette all reach a graph with
+// no second surface. Every row is QUIET on purpose: a module nobody tuned
+// needs nothing from him, and a GPU box that is off is the world's state, not
+// this repo's (the panel header states it instead).
+import { scanComfyWorkflows } from '../comfy/comfy-panel.ts'
+import type { Collection, Instance } from './collection-types.ts'
+
+export function comfyCollection(root: string): Collection {
+    return {
+        id: 'comfy',
+        title: 'comfy',
+        media: 'data',
+        list: async () =>
+            scanComfyWorkflows(root).map((w): Instance => ({
+                id: `comfy:${w.id}`,
+                text: w.id,
+                type: 'workflow',
+                path: `.shipkit/comfy/workflows/${w.id}.cflow.ts`,
+                file: `.shipkit/comfy/workflows/${w.id}.cflow.ts`,
+            })),
+    }
+}

package/src/collections/md-body.ts

@@ -0,0 +1,14 @@
+// a truth file's markdown body as a hub card: frontmatter stripped,
+// trimmed, capped. A card, not a document dump, and the cut is loud (…) so a
+// clamped card never passes for the whole file.
+import { existsSync, readFileSync } from 'fs'
+
+const MD_CAP = 4000
+
+export const mdBody = (path: string): string | undefined => {
+    if (!existsSync(path)) return undefined
+    const body = readFileSync(path, 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '').trim()
+    if (body === '') return undefined
+    // code-point slice, a UTF-16 cut can strand half a surrogate pair
+    return body.length > MD_CAP ? `${[...body].slice(0, MD_CAP).join('')}…` : body
+}