rvlib-shipkit 0.38.0 → 1.0.0

package/src/comfy/comfy-panel.ts

@@ -0,0 +1,292 @@
+// the comfy section's backend: the repo's .shipkit/comfy/ workflow modules, the
+// comfy-ts serve panel the hub embeds to tune and test one, and the box those
+// modules generate on. The contract this reads is owned by build/comfyui.md.
+//
+// The panel is a CHILD PROCESS rather than a route: comfy-ts owns that ui, and
+// a second implementation of a var form inside the hub is the redundant
+// mechanism that doctrine bans.
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join, resolve } from 'path'
+import { defaultHubPort } from '../serve/hub-port.ts'
+
+export type ComfyWorkflow = { id: string; file: string }
+export type ComfyPanelUp = { url: string; port: number }
+export type ComfyBox = { url: string; err: string | null }
+
+const SUFFIX = '.cflow.ts'
+/** the wm facts (build/comfyui.md) — an absent key defaults to them */
+const DEFAULT_BOX_PORT = 8085
+
+export const comfyWorkflowsDir = (root: string): string => join(root, '.shipkit/comfy', 'workflows')
+
+/** every workflow module, sorted. `_host.ts` carries no `.cflow` suffix on
+ *  purpose, so this scan and the comfy-ts one see the same list */
+export function scanComfyWorkflows(root: string): ComfyWorkflow[] {
+    const dir = comfyWorkflowsDir(root)
+    if (!existsSync(dir)) return []
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(SUFFIX))
+        .sort()
+        .map((f) => ({ id: f.slice(0, -SUFFIX.length), file: join(dir, f) }))
+}
+
+/** the box url .shipkit/comfy/config.json points at. An unreadable config reports
+ *  its own message: probing a default the repo never declared would answer a
+ *  question nobody asked */
+export function comfyBox(root: string): ComfyBox {
+    const p = join(root, '.shipkit/comfy', 'config.json')
+    const url = (port: number): string => `http://127.0.0.1:${port}`
+    if (!existsSync(p)) return { url: url(DEFAULT_BOX_PORT), err: null }
+    try {
+        const cfg = JSON.parse(readFileSync(p, 'utf8')) as { port?: number }
+        return { url: url(typeof cfg.port === 'number' ? cfg.port : DEFAULT_BOX_PORT), err: null }
+    } catch (e) {
+        return { url: url(DEFAULT_BOX_PORT), err: `.shipkit/comfy/config.json is unreadable (${(e as Error).message}), falling back to port ${DEFAULT_BOX_PORT}` }
+    }
+}
+
+/** is the box answering? read-only, and the ONE raw fetch this file makes */
+export async function comfyBoxUp(url: string): Promise<boolean> {
+    return await fetch(`${url}/system_stats`, { signal: AbortSignal.timeout(2500) })
+        .then((r) => r.ok)
+        .catch(() => false)
+}
+
+/** one house range above the hub's, from the same hash, so a repo whose hub
+ *  never collides never collides here either */
+export const defaultComfyPanelPort = (name: string): number => defaultHubPort(name) + 1000
+
+/** what `GET /` on a comfy-ts serve answers, narrowed to the identity fields */
+export type PanelIndex = { server?: string; workflows?: { module?: string; file?: string }[] }
+
+/** why a server already on the panel port cannot be adopted. `stale` is a panel
+ *  of OURS that booted before a module was written, which a restart fixes;
+ *  `foreign` is another repo's panel or another program, which only another
+ *  port fixes. Telling the two apart is the whole point: the two cures have
+ *  nothing in common */
+export type PanelVerdict = { ok: true } | { ok: false; kind: 'foreign' } | { ok: false; kind: 'stale'; missing: string[] }
+
+/** does the server on that port serve OUR modules? The FILE paths are the
+ *  identity: two repos both serving a 'txt2img-cutout' is the normal case, and
+ *  adopting the wrong one would tune another repo's graph */
+export function panelIdentity(index: PanelIndex, want: ComfyWorkflow[]): PanelVerdict {
+    if (index.server !== 'comfy-ts serve' || want.length === 0) return { ok: false, kind: 'foreign' }
+    const served = new Set((index.workflows ?? []).map((w) => resolve(w.file ?? '')))
+    const missing = want.filter((w) => !served.has(resolve(w.file)))
+    if (missing.length === 0) return { ok: true }
+    // not ONE file of ours: another repo serving the same module names
+    if (missing.length === want.length) return { ok: false, kind: 'foreign' }
+    return { ok: false, kind: 'stale', missing: missing.map((w) => w.id) }
+}
+
+export const panelServesOurs = (index: PanelIndex, want: ComfyWorkflow[]): boolean => panelIdentity(index, want).ok
+
+/** the refusal a reader can act on: the stale one names the modules the live
+ *  panel never imported, since changing the port there fixes nothing */
+export function panelRefusal(port: number, v: Extract<PanelVerdict, { ok: false }>): string {
+    if (v.kind === 'foreign') return `port ${port} is taken by another server — set serve: { comfyPort } in repo.config.ts to a free one`
+    return `the panel on port ${port} booted before ${v.missing.join(', ')} existed, and comfy-ts serve imports every module at boot. Use restart panel in the header to pick it up`
+}
+
+async function probeIndex(url: string, ms = 1500): Promise<PanelIndex | null> {
+    return await fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(ms) })
+        .then((r) => (r.ok ? (r.json() as Promise<PanelIndex>) : null))
+        .catch(() => null)
+}
+
+/** does `GET /` answer a BROWSER with a ui? comfy-ts serves its web bundle from
+ *  2.5 on, and an older one answers the json index to every request, this one
+ *  included. The content type is the whole answer: the index probe above is
+ *  green on both, so a panel adopted on identity alone can be a wall of json in
+ *  the frame */
+async function probeWebShell(url: string, ms = 1500): Promise<boolean> {
+    return await fetch(url, { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(ms) })
+        .then((r) => r.ok && (r.headers.get('content-type') ?? '').toLowerCase().includes('text/html'))
+        .catch(() => false)
+}
+
+/** the comfy-ts the repo would actually run, for the refusal to name */
+export function installedComfyTsVersion(root: string): string {
+    try {
+        const raw = readFileSync(join(root, 'node_modules', 'comfy-ts', 'package.json'), 'utf8')
+        return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'
+    } catch {
+        return 'unknown'
+    }
+}
+
+export const noWebPanelRefusal = (version: string): string => `comfy-ts ${version} serves no web panel (needs 2.5 or later), run: bun add comfy-ts@latest`
+
+const LOG_LINES = 40
+// short steps, same ceilings (30s to boot, 2s to die, 3s to go quiet): a
+// panel that is up in 80ms is not left waiting for the rest of a long step
+const BOOT_TRIES = 600
+const BOOT_STEP_MS = 50
+const KILL_TRIES = 80
+const KILL_STEP_MS = 25
+const QUIET_TRIES = 60
+const QUIET_STEP_MS = 50
+
+/** the pids LISTENING on a tcp port, on darwin and linux. `-sTCP:LISTEN`
+ *  carries the whole answer: `-i tcp:<port>` alone also matches every client
+ *  connected to it, this process included, and those must never be killed.
+ *  lsof sits in /usr/sbin on darwin, which a gui-launched shell can miss */
+function portHolders(port: number): number[] {
+    const lsof = Bun.which('lsof') ?? ['/usr/sbin/lsof', '/usr/bin/lsof'].find((p) => existsSync(p))
+    if (lsof == null) return []
+    const r = Bun.spawnSync([lsof, '-ti', `tcp:${port}`, '-sTCP:LISTEN'], { stdout: 'pipe', stderr: 'ignore' })
+    const pids = r.stdout
+        .toString()
+        .split('\n')
+        .map((l) => Number(l.trim()))
+        .filter((n) => Number.isInteger(n) && n > 0)
+    return [...new Set(pids)]
+}
+
+/** a pid that died between the scan and the signal is the outcome we wanted */
+function kill(pid: number, signal: 'SIGTERM' | 'SIGKILL'): void {
+    try {
+        process.kill(pid, signal)
+    } catch {
+        return
+    }
+}
+
+/** the panel process, started on the first ask and shared by every later one.
+ *  Adopting a live one matters more than owning it: `bun --watch` restarts the
+ *  hub on every lib edit, and the child it spawned outlives that restart */
+export class ComfyPanel {
+    private proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'> | null = null
+    private starting: Promise<ComfyPanelUp> | null = null
+    private log: string[] = []
+
+    constructor(private o: { root: string; port: number }) {}
+
+    get url(): string {
+        return `http://127.0.0.1:${this.o.port}`
+    }
+
+    async ensure(): Promise<ComfyPanelUp> {
+        const want = scanComfyWorkflows(this.o.root)
+        if (want.length === 0) throw new Error(`no ${SUFFIX} module under .shipkit/comfy/workflows`)
+        const live = await probeIndex(this.url)
+        if (live != null) {
+            const v = panelIdentity(live, want)
+            if (!v.ok) throw new Error(panelRefusal(this.o.port, v))
+            await this.requireWebShell()
+            return { url: this.url, port: this.o.port }
+        }
+        if (this.proc != null && this.proc.exitCode != null) this.proc = null
+        this.starting ??= this.spawn().finally(() => {
+            this.starting = null
+        })
+        return await this.starting
+    }
+
+    stop(): void {
+        this.proc?.kill()
+        this.proc = null
+    }
+
+    /** comfy-ts serve imports the workflow modules at BOOT, so an edited module
+     *  reaches the panel only through a new process. An ADOPTED panel is the
+     *  common case and there is no child to kill, so the port holder is killed
+     *  by pid: without that, ensure() re-adopts the same process and the
+     *  restart is the no-op the wait below exists to prevent. The wait matters:
+     *  a killed server still answers for a beat */
+    async restart(): Promise<ComfyPanelUp> {
+        const dying = this.proc
+        this.stop()
+        if (dying != null) await Promise.race([dying.exited, Bun.sleep(3000)])
+        else await this.killAdopted()
+        for (let i = 0; i < QUIET_TRIES && (await probeIndex(this.url, 400)) != null; i++) await Bun.sleep(QUIET_STEP_MS)
+        return await this.ensure()
+    }
+
+    /** the live panel nobody here spawned. Identity is verified AGAIN before
+     *  anything dies, because a foreign server on that port is another
+     *  program's process, and a port nothing listens on is said out loud
+     *  rather than restarted into the same old panel */
+    private async killAdopted(): Promise<void> {
+        const live = await probeIndex(this.url)
+        if (live == null) return
+        const v = panelIdentity(live, scanComfyWorkflows(this.o.root))
+        if (!v.ok && v.kind === 'foreign') throw new Error(panelRefusal(this.o.port, v))
+        const pids = portHolders(this.o.port).filter((pid) => pid !== process.pid)
+        if (pids.length === 0)
+            throw new Error(
+                `the panel on port ${this.o.port} cannot be restarted: no other process is listening there, so nothing to kill. Kill it by hand (lsof -ti tcp:${this.o.port} | xargs kill) and open the panel again`,
+            )
+        for (const pid of pids) kill(pid, 'SIGTERM')
+        for (let i = 0; i < KILL_TRIES && portHolders(this.o.port).some((p) => pids.includes(p)); i++) await Bun.sleep(KILL_STEP_MS)
+        for (const pid of portHolders(this.o.port).filter((p) => pids.includes(p))) kill(pid, 'SIGKILL')
+    }
+
+    /** nothing is mounted on a panel that cannot answer a browser: the frame
+     *  would show the json index and the chip would sit on starting forever */
+    private async requireWebShell(): Promise<void> {
+        if (await probeWebShell(this.url)) return
+        throw new Error(noWebPanelRefusal(installedComfyTsVersion(this.o.root)))
+    }
+
+    private tail(): string {
+        return this.log.length === 0 ? '(it printed nothing)' : this.log.join('\n')
+    }
+
+    private async spawn(): Promise<ComfyPanelUp> {
+        // the REPO's own copy: a workflow module imports the bare 'comfy-ts'
+        // specifier, so the engine running it must be the one it resolves
+        const bin = join(this.o.root, 'node_modules', '.bin', 'comfy-ts')
+        if (!existsSync(bin)) throw new Error(`comfy-ts is not installed in this repo — run: bun add comfy-ts`)
+        this.log = []
+        // process.execPath is bun: a .cflow.ts module is TypeScript and _host.ts
+        // reads import.meta.dir, so node loads neither
+        const proc = Bun.spawn([process.execPath, bin, 'serve', comfyWorkflowsDir(this.o.root), '--port', String(this.o.port)], {
+            cwd: this.o.root,
+            stdin: 'ignore',
+            stdout: 'pipe',
+            stderr: 'pipe',
+        })
+        this.proc = proc
+        void this.drain(proc.stdout)
+        void this.drain(proc.stderr)
+        for (let i = 0; i < BOOT_TRIES; i++) {
+            if (proc.exitCode != null) throw new Error(`comfy-ts serve exited (${proc.exitCode}):\n${this.tail()}`)
+            const idx = await probeIndex(this.url, 800)
+            if (idx != null) {
+                // a panel too old to serve a ui is killed rather than left
+                // holding the port for the next ensure() to adopt, and the
+                // refusal waits for the exit: a killed server still answers
+                // for a beat
+                await this.requireWebShell().catch(async (e: Error) => {
+                    proc.kill()
+                    this.proc = null
+                    await Promise.race([proc.exited, Bun.sleep(3000)])
+                    throw e
+                })
+                return { url: this.url, port: this.o.port }
+            }
+            await Bun.sleep(BOOT_STEP_MS)
+        }
+        proc.kill()
+        this.proc = null
+        throw new Error(`comfy-ts serve never answered on ${this.url}:\n${this.tail()}`)
+    }
+
+    /** the child's output is a startup wall of routes on success and the only
+     *  account of the failure otherwise, so the tail rides the error message
+     *  instead of the hub's terminal */
+    private async drain(s: ReadableStream<Uint8Array>): Promise<void> {
+        const dec = new TextDecoder()
+        let buf = ''
+        for await (const chunk of s as unknown as AsyncIterable<Uint8Array>) {
+            buf += dec.decode(chunk, { stream: true })
+            const lines = buf.split('\n')
+            buf = lines.pop() ?? ''
+            for (const l of lines) {
+                this.log.push(l)
+                if (this.log.length > LOG_LINES) this.log.shift()
+            }
+        }
+    }
+}

package/src/contracts/apply-contracts.ts

@@ -1,19 +1,18 @@
 // The ONE bridge from the contracts engine into wire output — every surface
 // that reports contract fulfillness (`shipkit check` via rule SK002, the ci
-// `contracts` task, `shipkit contracts`) goes through applyContractsResult,
+// `contracts` check, `shipkit contracts`) goes through applyContractsResult,
 // so tags, the empty-repo sentence, and severity plumbing exist exactly
 // once. Kinds pass through raw so fix pointers and visible exempts survive
 // every printer.
-import { existsSync } from 'fs'
-import { join } from 'path'
-import type { CheckCtx } from '../core/check-ctx.ts'
+import type { CheckCtx, ScanCtx } from '../core/check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
-import { tagRuleLines, type Rule } from '../rules/rule.ts'
+import { tagCheckLines } from '../check.ts'
+import { defineScan } from '../scan.ts'
 import { allContracts } from './contract-manifests.ts'
 import type { ContractManifest } from './contract-types.ts'
-import type { ContractsConfig, ContractsResult } from './contracts-engine.ts'
+import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts-engine.ts'
 
-export function contractsConfigFrom(c: RepoConfig, root: string): ContractsConfig {
+export function contractsConfigFrom(c: RepoConfig, d: Pick<ScanCtx, 'root' | 'exists'>): ContractsConfig {
     const venues = c.venues ?? []
     const social = c.social ?? []
     const declared = [
@@ -22,10 +21,10 @@ export function contractsConfigFrom(c: RepoConfig, root: string): ContractsConfi
         ...(social.includes('discord') ? ['discord'] : []),
     ]
     return {
-        root,
+        root: d.root,
         declared,
         social,
-        publicSurface: venues.length > 0 || existsSync(join(root, 'deploy.sh')),
+        publicSurface: venues.length > 0 || d.exists('deploy.sh'),
         exempt: c.contracts?.exempt,
         docsBase: c.docsBase,
     }
@@ -35,13 +34,19 @@ export function activeContracts(c: RepoConfig): ContractManifest[] {
     return [...allContracts, ...(c.contracts?.extra ?? [])]
 }
 
-export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: Rule): void {
-    const lines = tag != null ? tagRuleLines(tag, r.lines) : r.lines
+/** ONE evaluation per run, shared by every check that reports fulfillness
+ *  (SK002 and `contracts`), each of them cached on what it read */
+export const contractsResult = defineScan<ContractsResult>('contracts', (c) =>
+    evaluateContracts(activeContracts(c.config), contractsConfigFrom(c.config, c), c),
+)
+
+export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: { id?: string; fix?: unknown }): void {
+    const lines = tag?.id != null ? tagCheckLines({ id: tag.id, fix: tag.fix }, r.lines) : r.lines
     for (const l of lines) t.lines.push(l)
     if (r.exitCode === 1) t.failed = true
     if (r.lines.some((l) => l.kind === 'warn')) t.warned = true
     if (r.lines.length === 0) {
         const text = 'no contracts apply (nothing declared, nothing detected)'
-        t.ok(tag != null ? `[${tag.id}] ${text}` : text)
+        t.ok(tag?.id != null ? `[${tag.id}] ${text}` : text)
     }
 }

package/src/contracts/contract-types.ts

@@ -31,15 +31,27 @@ export type ContractEnv = {
     venues: string[]
     social: string[]
     exists: (relPath: string) => boolean
+    /** the text of a repo-relative file, null when none. A probe reads the
+     *  repo through this and `exists`, so a check reporting it is cached on
+     *  what the probe looked at: reaching the disk around them is what keeps
+     *  that check uncached (core/raw-access.ts) */
+    read: (relPath: string) => string | null
 }
 
 export type ContractManifest = {
-    venue: string // kebab id; the contract folder is `.rv-<venue>/`
+    /** kebab id of the venue, and the contract folder is `.shipkit/<venue>/` */
+    venue: string
+    /** the contract folder, `.shipkit/<venue>`, checked against the venue id */
     dir: string
-    owner: string // docs path suffix, rendered after the consumer-configured docsBase in fix: lines
+    /** docs path suffix, rendered after the consumer-configured docsBase in fix: lines */
+    owner: string
+    /** `declared` = required once the repo names this venue. `always` = every repo, behind `gate` */
     appliesTo: 'declared' | 'always'
-    gate?: 'public-surface' // 'always' contracts: FAIL once a public surface exists, WARN before
+    /** `always` contracts only: FAIL once a public surface exists, WARN before */
+    gate?: 'public-surface'
+    /** signals that this venue is in play although the repo never declared it, so config cannot lie */
     detect: Detector[]
+    /** the files the folder must carry. A contract with an empty list is prose */
     artifacts: ArtifactRule[]
 }
 
@@ -57,7 +69,7 @@ export const dirExists = (path: string): Detector => ({ kind: 'dirExists', path
 export function validateManifest(m: ContractManifest): string[] {
     const errs: string[] = []
     if (!/^[a-z0-9-]+$/.test(m.venue)) errs.push(`venue '${m.venue}' must be kebab-case [a-z0-9-]`)
-    if (m.dir !== `.rv-${m.venue}`) errs.push(`dir '${m.dir}' must be '.rv-${m.venue}' (folder naming rule)`)
+    if (m.dir !== `.shipkit/${m.venue}`) errs.push(`dir '${m.dir}' must be '.shipkit/${m.venue}' (folder naming rule)`)
     if (m.artifacts.length === 0) errs.push('artifacts must not be empty — a contract with nothing to check is prose, not a contract')
     if (m.appliesTo === 'declared' && m.detect.length === 0) errs.push(`appliesTo 'declared' needs >=1 detector — otherwise an undeclared venue can never be caught`)
     if (m.gate != null && m.appliesTo !== 'always') errs.push(`gate '${m.gate}' only applies to 'always' contracts`)

package/src/contracts/contracts-engine.ts

@@ -7,11 +7,16 @@
 // - 'always' contracts with gate 'public-surface': full severity once the
 //   repo has a public surface, everything demoted to WARN before.
 // Every FAIL carries a fix: pointer = docsBase + manifest.owner.
-import { existsSync, readFileSync, statSync } from 'fs'
-import { join } from 'path'
+//
+// It reads ONLY through the disk it is handed (a check context), so what a
+// verdict rests on is recorded, and a check reporting it is cached on that.
+import type { ScanCtx } from '../core/check-ctx.ts'
 import type { ArtifactRule, ContractEnv, ContractManifest } from './contract-types.ts'
 import type { Line } from '../core/wire.ts'
 
+/** what the engine reads through: a check context, or a shared scan's */
+export type ContractDisk = Pick<ScanCtx, 'read' | 'bytes' | 'exists' | 'entries'>
+
 export type ContractsConfig = {
     root: string
     /** venue ids the repo declares it ships on (config side of both-ways drift) */
@@ -31,35 +36,67 @@ export type ContractsResult = { lines: Line[]; exitCode: 0 | 1; outcomes: Contra
 
 // PNG dims from the IHDR header — bytes 16..23 big-endian, after the
 // 8-byte signature + IHDR length/type. No image dependency.
-export function pngDims(path: string): { width: number; height: number } | null {
-    try {
-        const fd = readFileSync(path)
-        if (fd.length < 24) return null
-        const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
-        for (let i = 0; i < sig.length; i++) if (fd[i] !== sig[i]) return null
-        return { width: fd.readUInt32BE(16), height: fd.readUInt32BE(20) }
-    } catch {
-        return null
+export function pngDims(bytes: Uint8Array | null): { width: number; height: number } | null {
+    if (bytes == null || bytes.length < 24) return null
+    const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+    for (let i = 0; i < sig.length; i++) if (bytes[i] !== sig[i]) return null
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    return { width: view.getUint32(16), height: view.getUint32(20) }
+}
+
+const WILD = /[*?[{]/
+
+/** the files matching a repo-relative glob, walked one dir at a time through
+ *  `entries`, so a folder git ignores is still seen and each dir read is
+ *  recorded. A hidden name matches only a segment that starts with a dot, and
+ *  `**` never walks into a hidden dir */
+export function globFiles(pattern: string, d: ContractDisk): string[] {
+    const segs = pattern.split('/').filter((x) => x !== '' && x !== '.')
+    const out = new Set<string>()
+    const at = (dir: string, name: string): string => (dir === '' ? name : `${dir}/${name}`)
+    const inside = (dir: string) => d.entries(dir === '' ? '.' : dir)
+    const walk = (dir: string, i: number): void => {
+        const seg = segs[i]
+        if (seg == null) return
+        const last = i === segs.length - 1
+        if (seg === '**') {
+            walk(dir, i + 1)
+            for (const e of inside(dir)) if (e.kind === 'dir' && !e.name.startsWith('.')) walk(at(dir, e.name), i)
+            return
+        }
+        if (!WILD.test(seg)) {
+            if (!last) walk(at(dir, seg), i + 1)
+            else if (d.exists(at(dir, seg), 'file')) out.add(at(dir, seg))
+            return
+        }
+        const g = new Bun.Glob(seg)
+        for (const e of inside(dir)) {
+            if (e.name.startsWith('.') && !seg.startsWith('.')) continue
+            if (!g.match(e.name)) continue
+            if (!last) { if (e.kind === 'dir') walk(at(dir, e.name), i + 1) }
+            else if (e.kind === 'file') out.add(at(dir, e.name))
+        }
     }
+    walk('', 0)
+    return [...out].sort()
 }
 
-const abs = (root: string, rel: string): string => join(root, rel)
+/** the text of a file, null when no FILE stands there */
+const textOf = (d: ContractDisk, rel: string): string | null => (d.exists(rel, 'file') ? d.read(rel) : null)
 
-async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]> {
+async function checkRule(rule: ArtifactRule, env: ContractEnv, d: ContractDisk): Promise<string[]> {
     const problems: string[] = []
     switch (rule.kind) {
         case 'file': {
-            const p = abs(env.root, rule.path)
-            if (!existsSync(p)) problems.push(`${rule.path} missing`)
-            else if (!statSync(p).isFile()) problems.push(`${rule.path} is not a file`)
-            else if (rule.nonEmpty && statSync(p).size === 0) problems.push(`${rule.path} is empty`)
+            if (!d.exists(rule.path)) problems.push(`${rule.path} missing`)
+            else if (!d.exists(rule.path, 'file')) problems.push(`${rule.path} is not a file`)
+            else if (rule.nonEmpty && (d.bytes(rule.path)?.length ?? 0) === 0) problems.push(`${rule.path} is empty`)
             break
         }
         case 'png': {
-            const p = abs(env.root, rule.path)
             const need = rule.atLeast === true ? `>= ${rule.width}x${rule.height} at ${rule.width}:${rule.height}` : `${rule.width}x${rule.height}`
-            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${need}`); break }
-            const dims = pngDims(p)
+            if (!d.exists(rule.path)) { problems.push(`${rule.path} missing — need png ${need}`); break }
+            const dims = pngDims(d.exists(rule.path, 'file') ? d.bytes(rule.path) : null)
             if (dims == null) problems.push(`${rule.path} is not a readable png`)
             else if (rule.atLeast !== true) {
                 if (dims.width !== rule.width || dims.height !== rule.height) problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${need}`)
@@ -75,27 +112,25 @@ async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]
             break
         }
         case 'glob': {
-            const matches = [...new Bun.Glob(rule.pattern).scanSync({ cwd: env.root, onlyFiles: true })]
+            const matches = globFiles(rule.pattern, d)
             if (matches.length < rule.min) { problems.push(`${rule.pattern}: ${matches.length} file(s) — need >= ${rule.min}`); break }
             if (rule.width != null && rule.height != null)
                 for (const m of matches) {
-                    const dims = pngDims(abs(env.root, m))
+                    const dims = pngDims(d.bytes(m))
                     if (dims == null || dims.width !== rule.width || dims.height !== rule.height)
                         problems.push(`${m} is ${dims == null ? 'not a readable png' : `${dims.width}x${dims.height}`} — need ${rule.width}x${rule.height}`)
                 }
             break
         }
         case 'md': {
-            const p = abs(env.root, rule.path)
-            if (!existsSync(p)) { problems.push(`${rule.path} missing`); break }
-            const text = readFileSync(p, 'utf8')
+            const text = textOf(d, rule.path)
+            if (text == null) { problems.push(`${rule.path} missing`); break }
             if (text.trim() === '') { problems.push(`${rule.path} is empty`); break }
             for (const needle of rule.mustContain) if (!text.includes(needle)) problems.push(`${rule.path} lacks required '${needle}'`)
             break
         }
         case 'dir': {
-            const p = abs(env.root, rule.path)
-            if (!existsSync(p) || !statSync(p).isDirectory()) problems.push(`${rule.path}/ missing`)
+            if (!d.exists(rule.path, 'dir')) problems.push(`${rule.path}/ missing`)
             break
         }
         case 'custom': {
@@ -106,19 +141,19 @@ async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]
     return problems
 }
 
-function detectorFires(m: ContractManifest, cfg: ContractsConfig): string | null {
-    for (const d of m.detect) {
-        if (d.kind === 'dirExists') {
-            if (existsSync(abs(cfg.root, d.path))) return `${d.path}/ exists`
-        } else if (d.kind === 'fileContains') {
-            const p = abs(cfg.root, d.path)
-            if (existsSync(p) && new RegExp(d.pattern).test(readFileSync(p, 'utf8'))) return `${d.path} matches /${d.pattern}/`
+function detectorFires(m: ContractManifest, d: ContractDisk): string | null {
+    for (const det of m.detect) {
+        if (det.kind === 'dirExists') {
+            if (d.exists(det.path)) return `${det.path}/ exists`
+        } else if (det.kind === 'fileContains') {
+            const text = textOf(d, det.path)
+            if (text != null && new RegExp(det.pattern).test(text)) return `${det.path} matches /${det.pattern}/`
         } else {
-            const pkgPath = abs(cfg.root, 'package.json')
-            if (!existsSync(pkgPath)) continue
+            const pkg = textOf(d, 'package.json')
+            if (pkg == null) continue
             try {
-                const scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}
-                const re = new RegExp(d.pattern)
+                const scripts = (JSON.parse(pkg) as { scripts?: Record<string, string> }).scripts ?? {}
+                const re = new RegExp(det.pattern)
                 const hit = Object.keys(scripts).find((k) => re.test(k))
                 if (hit != null) return `package.json script '${hit}'`
             } catch { /* unparseable package.json is another tool's FAIL */ }
@@ -127,7 +162,7 @@ function detectorFires(m: ContractManifest, cfg: ContractsConfig): string | null
     return null
 }
 
-export async function evaluateContracts(manifests: ContractManifest[], cfg: ContractsConfig): Promise<ContractsResult> {
+export async function evaluateContracts(manifests: ContractManifest[], cfg: ContractsConfig, d: ContractDisk): Promise<ContractsResult> {
     const lines: Line[] = []
     const outcomes: ContractOutcome[] = []
     let anyFail = false
@@ -135,7 +170,8 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
         root: cfg.root,
         venues: cfg.declared,
         social: cfg.social,
-        exists: (rel) => existsSync(abs(cfg.root, rel)),
+        exists: (rel) => d.exists(rel),
+        read: (rel) => textOf(d, rel),
     }
     const fix = (m: ContractManifest, text: string): Line[] => [
         { kind: 'fix-fail', text: `${text} — ${(cfg.docsBase ?? '') + m.owner}` },
@@ -150,7 +186,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
         }
         const declared = cfg.declared.includes(m.venue)
         if (m.appliesTo === 'declared' && !declared) {
-            const signal = detectorFires(m, cfg)
+            const signal = detectorFires(m, d)
             if (signal != null) {
                 anyFail = true
                 lines.push({ kind: 'fail', text: `${m.venue}  ships (${signal}) but venue is not declared — declare it or remove the signal` })
@@ -166,7 +202,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
         let problems = 0
         let warned = 0
         for (const rule of m.artifacts) {
-            const found = await checkRule(rule, env)
+            const found = await checkRule(rule, env, d)
             const asWarn = warnAll || rule.warnOnly === true
             for (const p of found) {
                 if (asWarn) {

package/src/contracts/manifests/discord.contract.ts

@@ -1,15 +1,15 @@
-// normative WHAT for .rv-discord/ — a project's public Discord server
-// contract. Posts stay in .rv-social/.
+// normative WHAT for .shipkit/discord/ — a project's public Discord server
+// contract. Posts stay in .shipkit/social/.
 import { defineContract, dirExists, md, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'discord',
-    dir: '.rv-discord',
+    dir: '.shipkit/discord',
     owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
-    detect: [dirExists('.rv-discord')],
+    detect: [dirExists('.shipkit/discord')],
     artifacts: [
-        md('.rv-discord/server.md', { mustContain: ['invite'] }),
-        png('.rv-discord/icon.png', 512, 512, { atLeast: true }),
+        md('.shipkit/discord/server.md', { mustContain: ['invite'] }),
+        png('.shipkit/discord/icon.png', 512, 512, { atLeast: true }),
     ],
 })

package/src/contracts/manifests/identity.contract.ts

@@ -1,17 +1,17 @@
-// normative WHAT for .rv-identity/ — every repo with a public surface owns
+// normative WHAT for .shipkit/identity/ — every repo with a public surface owns
 // its brand source + committed favicon/logo/OG outputs. gate: FAIL once a
 // public surface exists (deploy.sh or any declared venue), WARN before.
 import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'identity',
-    dir: '.rv-identity',
+    dir: '.shipkit/identity',
     owner: 'build/generate-assets.md',
     appliesTo: 'always',
     gate: 'public-surface',
     detect: [],
     artifacts: [
-        file('.rv-identity/brand.ts'),
+        file('.shipkit/identity/brand.ts'),
         png('public/favicon.png', 512, 512),
         png('public/og.png', 1200, 630, { atLeast: true }),
         glob('public/logo.*', { min: 1 }),