rvlib-shipkit 1.2.0 → 1.4.0

package/src/cli/cmd_Overview.ts

@@ -0,0 +1,98 @@
+// shipkit overview: the overview page in the console, top to bottom as the
+// page: the monitor widgets as the daemon last rendered them, their html read
+// as text by widget-text.ts, then the processes through
+// globalProcessesAnswer (the rows `shipkit gp` prints: pm, the daemon and the
+// web first, then the global processes). Nothing renders a widget here: the
+// daemon holds the render, and while it is down the monitor is unknown.
+import { Command, Option } from 'clipanion'
+import { daemonUrl } from '../home/home-paths.ts'
+import type { WidgetsAnswer } from '../home/home-routes.ts'
+import type { ChildView, PmAnswer } from '../home/pm.ts'
+import { splitWidgetHead, widgetText } from '../home/widget-text.ts'
+import { askDaemon, askPm, globalProcessesAnswer, localProcessDeps, renderGlobalProcesses, type GlobalProcessesAnswer, type GlobalProcessesDeps } from './cmd_GlobalProcesses.ts'
+
+export type OverviewAnswer = {
+    now: number
+    /** pm as it answered: its own pid and version, its children; null when it did not */
+    pm: { pid: number; since: number | null; version: string; children: ChildView[] } | null
+    /** the daemon's identity, asked of the daemon itself; null when it does not answer */
+    daemon: { version: string } | null
+    /** the global processes, exactly as `shipkit global-processes --json` */
+    processes: GlobalProcessesAnswer
+    /** the daemon's widgets route payload; null when the daemon does not answer */
+    widgets: WidgetsAnswer | null
+}
+
+export type OverviewDeps = Pick<GlobalProcessesDeps, 'declared' | 'order'> & {
+    pm: () => Promise<PmAnswer | null>
+    daemon: () => Promise<{ version: string } | null>
+    widgets: () => Promise<WidgetsAnswer | null>
+    now: number
+}
+
+async function getJson<T>(url: string): Promise<T | null> {
+    try {
+        const r = await fetch(url, { signal: AbortSignal.timeout(3_000) })
+        return r.ok ? ((await r.json()) as T) : null
+    } catch {
+        return null
+    }
+}
+
+/** the daemon's widgets route payload, or null */
+export const askWidgets = (url = daemonUrl()): Promise<WidgetsAnswer | null> => getJson<WidgetsAnswer>(`${url}/api/home/widgets.json`)
+
+export async function overviewAnswer(d: OverviewDeps): Promise<OverviewAnswer> {
+    const [pm, daemon, widgets] = await Promise.all([d.pm(), d.daemon(), d.widgets()])
+    const processes = await globalProcessesAnswer({ pm: async () => pm, daemon: async () => daemon, declared: d.declared, order: d.order, now: d.now })
+    return { now: d.now, pm: pm == null ? null : { pid: pm.pid, since: pm.since ?? null, version: pm.version, children: pm.children }, daemon, processes, widgets }
+}
+
+const indent = (lines: string[], by = '  '): string[] => lines.map((l) => by + l)
+
+/** the page as text: the monitor, then the processes (shipkit's own first),
+ *  each section saying what is unknown and why when pm or the daemon does not
+ *  answer */
+export function renderOverview(a: OverviewAnswer): string[] {
+    const out: string[] = ['monitor']
+    if (a.widgets == null) out.push(`  the daemon does not answer on ${daemonUrl()}, and it renders the widgets: the monitor is unknown`)
+    else {
+        if (a.widgets.widgets.length === 0 && a.widgets.errors.length === 0) out.push('  no widget declared: a repo declares one in a <name>.shipkit.ts file, as export default widget({...})')
+        for (const x of a.widgets.widgets) {
+            const { head, body } = splitWidgetHead(x.html ?? '')
+            out.push(`  ${x.title}${head == null ? '' : ` · ${widgetText(head).join(' ')}`}`)
+            if (x.error != null) out.push(`    WARN ${x.error}`)
+            if (x.html == null) out.push('    not rendered yet')
+            else out.push(...indent(widgetText(body), '    '))
+        }
+        for (const e of a.widgets.errors) out.push(`  WARN ${e}`)
+    }
+    out.push('processes', ...indent(renderGlobalProcesses(a.processes)))
+    if (a.daemon == null) out.push(`  the daemon does not answer on ${daemonUrl()}`)
+    return out
+}
+
+export class OverviewCommand extends Command {
+    static override paths = [['overview']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the overview page in the console: every monitor widget as text, from the html the daemon last rendered, then the processes as `shipkit gp` prints them (pm, the daemon and the web with pid, uptime and version, then every global process). When pm or the daemon does not answer, it says which and prints what is still known. Always exits 0',
+        examples: [
+            ['the overview', 'shipkit overview'],
+            ['the answers the page reads, as json', 'shipkit overview --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'the answers as json: { now, pm, daemon, processes, widgets }, processes as `shipkit gp --json`, widgets the daemon route\'s payload' })
+
+    async execute(): Promise<number> {
+        const a = await overviewAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        for (const l of renderOverview(a)) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Planned.ts

@@ -0,0 +1,117 @@
+// shipkit planned: the planned page in the console. The plan lives in the
+// daemon (its marks, the running batch, the catch up spread all exist only
+// there), so this asks the daemon's route, the one the page polls, and only
+// renders it: the order and every word come from plan-timeline.ts, the page's
+// own functions. Nothing is computed from disk: a plan rebuilt here would load
+// every repo's checks and still not know what the daemon's plan holds.
+import { Command, Option } from 'clipanion'
+import { daemonUrl } from '../home/home-paths.ts'
+import type { PlannedAnswer } from '../home/home-routes.ts'
+import { markOf, spanShort, timeline, titleWords, waitingRows, waitingWords, whenWords, type Section } from '../plan/plan-timeline.ts'
+import type { PlanRow } from '../plan/planner.ts'
+
+/** the daemon's planned answer, or null when it does not answer */
+export async function askPlanned(url = daemonUrl()): Promise<PlannedAnswer | null> {
+    try {
+        const r = await fetch(`${url}/api/home/planned.json`, { signal: AbortSignal.timeout(8_000) })
+        if (!r.ok) return null
+        return (await r.json()) as PlannedAnswer
+    } catch {
+        return null
+    }
+}
+
+/** the answer for one repo: its rows and its load error only */
+export function onlyRepo(a: PlannedAnswer, repo: string): PlannedAnswer {
+    return { ...a, rows: a.rows.filter((r) => r.repo === repo), errors: a.errors.filter((e) => e.repo === repo) }
+}
+
+const pad = (s: string, n: number): string => (s.length >= n ? s : s + ' '.repeat(n - s.length))
+
+const lastWords = (r: PlanRow, now: number): string =>
+    r.last == null ? 'never ran' : `last ${r.last.status} ${spanShort(Math.max(0, now - r.last.at))} ago${r.last.streak > 1 ? ` (${r.last.streak} in a row)` : ''}`
+
+const SECTION_WORDS: Record<Section, string> = { now: 'now', next: 'next' }
+
+/** the page's one list as text: its three sections in its order, a line per
+ *  row (when, repo, check and title, mark, last result) and the rule under
+ *  it; the checks that only wait for a save are counted, or listed with `all` */
+export function renderPlanned(a: PlannedAnswer, o: { all?: boolean } = {}): string[] {
+    const out: string[] = [...(a.held ?? [])]
+    const list = timeline(a.rows)
+    const idle = a.rows.filter((r) => r.state === 'idle')
+    const w = {
+        when: Math.max(0, ...list.map((x) => whenWords(x.row, a.now).length)),
+        what: Math.max(0, ...list.map((x) => `${x.row.repo} ${x.row.check}`.length)),
+    }
+    let prev: Section | null = null
+    for (const { section, row } of list) {
+        if (section !== prev) {
+            out.push(SECTION_WORDS[section])
+            prev = section
+        }
+        const m = markOf(row)
+        const title = titleWords(row.title, row.check)
+        const cells = [`  ${pad(whenWords(row, a.now), w.when)}`, pad(`${row.repo} ${row.check}`, w.what), m.words, lastWords(row, a.now)]
+        out.push(cells.filter((c) => c !== '').join('  '))
+        out.push(`      ${title == null ? '' : `${title} · `}${row.rule}`)
+        if (row.error != null) out.push(`      error: ${row.error}`)
+    }
+    if (list.length === 0) out.push(a.rows.length === 0 ? 'nothing is planned' : 'nothing has a time of its own')
+    const waiting = waitingRows(a.rows)
+    if (waiting.length > 0) {
+        out.push(`${waitingWords(a.rows)}${o.all === true ? '' : ' (--all lists them)'}`)
+        if (o.all === true) for (const r of waiting) out.push(`  ${r.repo} ${r.check}  ${lastWords(r, a.now)}  · ${r.rule}`)
+    }
+    if (o.all === true && idle.length > 0) {
+        out.push('on a save only')
+        for (const r of [...idle].sort((x, y) => x.repo.localeCompare(y.repo) || x.check.localeCompare(y.check))) out.push(`  ${r.repo} ${r.check}  ${lastWords(r, a.now)}  · ${r.rule}`)
+    }
+    for (const e of a.errors) out.push(`WARN ${e.repo}: ${e.error}`)
+    const n = { now: list.filter((x) => x.section === 'now').length, next: list.filter((x) => x.section === 'next').length }
+    out.push(`${n.now} now, ${n.next} next, ${waiting.length} waiting, ${idle.length} on a save only${o.all === true || idle.length === 0 ? '' : ' (--all lists them)'}`)
+    return out
+}
+
+export class PlannedCommand extends Command {
+    static override paths = [['planned']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the planned page in the console: every check the machine runs on its own time, running now, then next, each with its repo, check and title, when, the rule that planned it and its last result. Asks the daemon, which holds the plan. With the daemon down it says so and exits 0',
+        examples: [
+            ['the plan, as the page lists it', 'shipkit planned'],
+            ['one repo only', 'shipkit planned --repo my-app'],
+            ['also the checks that only a save runs', 'shipkit planned --all'],
+            ['the route\'s exact payload', 'shipkit planned --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'the daemon route\'s exact payload: { now, rows, errors, running, held }' })
+    repo = Option.String('--repo', { required: false, description: 'only this repo\'s rows' })
+    all = Option.Boolean('--all', false, { description: 'also list the checks that only a save runs (the page leaves them out)' })
+
+    async execute(): Promise<number> {
+        const got = await askPlanned()
+        if (got == null) {
+            const why = `the daemon does not answer on ${daemonUrl()}, and the plan lives there: no plan is known (\`shipkit pm\` starts it)`
+            if (this.json) {
+                this.context.stdout.write('null\n')
+                this.context.stderr.write(`${why}\n`)
+            } else this.context.stdout.write(`${why}\n`)
+            return 0
+        }
+        const a = this.repo == null ? got : onlyRepo(got, this.repo)
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        if (this.repo != null && a.rows.length === 0 && a.errors.length === 0) {
+            const known = [...new Set(got.rows.map((r) => r.repo))].sort()
+            this.context.stdout.write(`no planned check in ${this.repo}; the plan holds ${known.join(', ') || 'no repo'}\n`)
+            return 0
+        }
+        for (const l of renderPlanned(a, { all: this.all })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -9,7 +9,11 @@ import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenComma
 import { BumpCommand } from './cli/cmd_Bump.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
+import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
+import { GlobalProcessesCommand } from './cli/cmd_GlobalProcesses.ts'
+import { PlannedCommand } from './cli/cmd_Planned.ts'
+import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { FleetCommand } from './cli/cmd_Fleet.ts'
@@ -86,6 +90,10 @@ export function buildCli(): Cli {
     cli.register(SmokeCommand)
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
+    cli.register(GlobalProcessesCommand)
+    cli.register(CrossRepoActivityCommand)
+    cli.register(PlannedCommand)
+    cli.register(OverviewCommand)
     cli.register(ChecksCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
@@ -100,7 +108,7 @@ export function buildCli(): Cli {
 // this one (one-lib.ts), so the machine's version runs in every repo. Then pm
 // is started when it is down (autostart.ts), before the command runs
 if (import.meta.main) {
-    const argv = process.argv.slice(2)
+    const argv = aliasArgs(process.argv.slice(2))
     const { handoff } = await import('./home/handoff.ts')
     handoff(argv)
     const { useOneLib } = await import('./core/one-lib.ts')

package/src/collections/checks.ts

@@ -18,7 +18,7 @@ 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 { FOREVER_MS, formatLine, ttlMsOf } 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'
@@ -166,7 +166,8 @@ function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat
 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 }
+    try { ms = ttlMsOf(ttl) } catch { return null }
+    if (ms >= FOREVER_MS && stat.measuredStatus === 'pass') return null
     if (ms <= 0) return null
     return stat.measuredAt + (stat.measuredStatus === 'pass' ? ms : Math.min(ms, NEGATIVE_TTL_CAP_MS))
 }

package/src/collections/collection-types.ts

@@ -161,6 +161,19 @@ export type TestRun = {
  *  declaration names a file that is not on disk */
 export type TestStanding = 'runs' | 'ignored' | 'orphan' | 'opaque' | 'missing'
 
+/** an ask as its line on the asks page reads it: the frontmatter of its file */
+export type AskFacts = {
+    kind: string
+    /** `YYYY-MM-DD`, `?` when the file carries none */
+    created: string
+    /** `YYYY-MM-DD` for a done ask, null otherwise or when it was not stamped */
+    closed: string | null
+    /** what it blocks, `-` for nothing named */
+    blocks: string
+    /** the shell probe that closes it once it exits 0, null for a manual ask */
+    probe: string | null
+}
+
 /** one test file, as its row and its page read it */
 export type TestFacts = {
     /** repo relative */
@@ -243,6 +256,8 @@ export type Instance = {
     check?: CheckFacts
     /** test files only: where it runs and what it last cost */
     test?: TestFacts
+    /** asks only: what its frontmatter says */
+    ask?: AskFacts
     /** 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

package/src/collections/providers.ts

@@ -17,12 +17,12 @@ import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
 // runtime and the canvas binding, ~400ms of module load, and the hub's
 // collection list is built on every request by callers that mostly never heal
 import type { healIdentity } from '../assets/run-assets.ts'
-import { doneAsks, openAsks } from '../asks/asks-queue.ts'
+import { doneAsks, openAsks, type Ask } from '../asks/asks-queue.ts'
 import { evaluateContracts } from '../contracts/contracts-engine.ts'
 import { CheckCtx } from '../core/check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { activeContracts, contractsConfigFrom } from '../contracts/apply-contracts.ts'
-import type { CheckFacts, Collection, Instance } from './collection-types.ts'
+import type { AskFacts, CheckFacts, Collection, Instance } from './collection-types.ts'
 import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
 import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
@@ -31,7 +31,7 @@ import { testsCollection } from './tests.ts'
 import { checksCollection } from './checks.ts'
 import { LAYOUT } from '../core/layout.ts'
 import { isBudgetLine } from '../core/budget.ts'
-import { GH_LOGIN_CRED } from '../checks/SK021-github-login.check.ts'
+import { GH_LOGIN_CRED } from '../core/gh-login.ts'
 
 const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? LAYOUT.asks)
 // read path must not mint an asks/ dir (listAsks mkdirs on read)
@@ -119,6 +119,8 @@ const slug = (t: string): string => t.toLowerCase().replace(/[^a-z0-9]+/g, '-').
 /** wire lines re-rendered as a fenced block for an instance's md */
 const wireMd = (lines: string[]): string => `\`\`\`\n${lines.join('\n')}\n\`\`\``
 
+const askFacts = (a: Ask): AskFacts => ({ kind: a.kind, created: a.created, closed: a.closed, blocks: a.blocks, probe: a.check })
+
 export function asksCollection(root: string, c: RepoConfig): Collection {
     return {
         id: 'asks',
@@ -141,6 +143,7 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
                 file: `${rel}/${a.file}`,
                 md: mdBody(join(root, rel, a.file)),
                 remarks: lastRemarks(join(root, rel, a.file)),
+                ask: askFacts(a),
             }))
             // the done/ archive rides along QUIET (no severity) — past answers
             // stay consultable and remarkable; newest first, after every open ask
@@ -155,6 +158,7 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
                 file: `${rel}/done/${a.file}`,
                 md: mdBody(join(root, rel, 'done', a.file)),
                 remarks: lastRemarks(join(root, rel, 'done', a.file)),
+                ask: askFacts(a),
             }))
             return [...open, ...done]
         },

package/src/collections/test-time.ts

@@ -127,9 +127,15 @@ export type TestCheckRow = {
     shape: Shape | null
 }
 
+/** one file of any test check, named with the check that runs it */
+export type TestFileRow = FileTime & { check: string }
+
 export type TestsRootView = {
     /** slowest wall first, the never ran ones last */
     checks: TestCheckRow[]
+    /** every file of every test check, slowest first, the never ran ones
+     *  last: each check's own list, merged */
+    files: TestFileRow[]
     failing: FailingFile[]
 }
 
@@ -270,8 +276,10 @@ function lastRunOf(checkId: string, at: number, files: FileTime[], sumMs: number
 
 export function shapeTestsRoot(o: TestTimeInput): TestsRootView {
     const ids = [...new Set(o.facts.filter((f) => f.standing === 'runs' && f.checkId != null).map((f) => f.checkId!))]
+    const files: TestFileRow[] = []
     const checks = ids.map((checkId): TestCheckRow => {
         const v = shapeTestCheck(checkId, o)
+        for (const f of v.files) files.push({ ...f, check: checkId })
         const top = v.files.find((f) => f.ms != null)
         return {
             checkId,
@@ -284,5 +292,6 @@ export function shapeTestsRoot(o: TestTimeInput): TestsRootView {
             shape: v.last?.shape ?? null,
         }
     }).sort((a, b) => (b.wallMs ?? -1) - (a.wallMs ?? -1) || a.checkId.localeCompare(b.checkId))
-    return { checks, failing: failingOf(o.facts) }
+    files.sort((a, b) => (b.ms ?? -1) - (a.ms ?? -1) || a.file.localeCompare(b.file))
+    return { checks, files, failing: failingOf(o.facts) }
 }

package/src/contracts/apply-contracts.ts

@@ -10,21 +10,22 @@ import { tagCheckLines } from '../check.ts'
 import { defineScan } from '../scan.ts'
 import { allContracts } from './contract-manifests.ts'
 import type { ContractManifest } from './contract-types.ts'
+import { webDeploys, webRootOf, type WebDisk } from './web-surface.ts'
 import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts-engine.ts'
 
-export function contractsConfigFrom(c: RepoConfig, d: Pick<ScanCtx, 'root' | 'exists'>): ContractsConfig {
+export function contractsConfigFrom(c: RepoConfig, d: WebDisk & Pick<ScanCtx, 'root'>): ContractsConfig {
     const venues = c.venues ?? []
     const social = c.social ?? []
-    const declared = [
-        ...venues,
-        ...(social.length > 0 ? ['social'] : []),
-        ...(social.includes('discord') ? ['discord'] : []),
-    ]
+    const declared = [...venues, ...(social.length > 0 ? ['social'] : [])]
+    const deploys = webDeploys(d)
+    // a public repo whose only surface is an npm package has no page to serve an identity on
+    const npmOnly = c.release?.npm === true && deploys.length === 0 && venues.length === 0
     return {
         root: d.root,
         declared,
         social,
-        publicSurface: venues.length > 0 || d.exists('deploy.sh'),
+        publicSurface: venues.length > 0 || deploys.length > 0 || (c.visibility === 'public' && !npmOnly),
+        webRoot: webRootOf(c.contracts?.webRoot, deploys),
         exempt: c.contracts?.exempt,
         docsBase: c.docsBase,
     }
@@ -45,7 +46,7 @@ export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: { id
     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) {
+    if (r.lines.every((l) => l.kind === 'note')) {
         const text = 'no contracts apply (nothing declared, nothing detected)'
         t.ok(tag?.id != null ? `[${tag.id}] ${text}` : text)
     }

package/src/contracts/contract-types.ts

@@ -1,7 +1,8 @@
 // The data language `*.contract.ts` manifest files are written in: a venue
 // contract = folder + artifact rules + detectors. Evaluation engine lands in
 // ./contracts-engine.ts (0.1). All rule paths are REPO-ROOT-relative so a
-// contract can require files outside its own folder (e.g. public/og.png).
+// contract can require files outside its own folder (e.g. {web}/og.png, where
+// `{web}` is the repo's web root, contracts/web-surface.ts).
 // `warnOnly` demotes a rule to WARN — for mandates gated on a later step.
 
 export type RuleOpts = { warnOnly?: boolean }
@@ -25,9 +26,13 @@ export type Detector =
     | { kind: 'script'; pattern: string }
     | { kind: 'fileContains'; path: string; pattern: string }
     | { kind: 'dirExists'; path: string }
+    /** a file matching the glob holds a line matching the (multiline) pattern */
+    | { kind: 'fileMatches'; glob: string; pattern: string }
 
 export type ContractEnv = {
     root: string
+    /** the dir the site serves, what `{web}` in a rule path stands for */
+    webRoot: string
     venues: string[]
     social: string[]
     exists: (relPath: string) => boolean
@@ -47,7 +52,7 @@ export type ContractManifest = {
     owner: string
     /** `declared` = required once the repo names this venue. `always` = every repo, behind `gate` */
     appliesTo: 'declared' | 'always'
-    /** `always` contracts only: FAIL once a public surface exists, WARN before */
+    /** `always` contracts only: applies once a public surface exists, silent before */
     gate?: 'public-surface'
     /** signals that this venue is in play although the repo never declared it, so config cannot lie */
     detect: Detector[]
@@ -65,6 +70,7 @@ export const custom = (id: string, probe: CustomRule['probe'], p?: RuleOpts): Cu
 export const script = (pattern: string): Detector => ({ kind: 'script', pattern })
 export const fileContains = (path: string, pattern: string): Detector => ({ kind: 'fileContains', path, pattern })
 export const dirExists = (path: string): Detector => ({ kind: 'dirExists', path })
+export const fileMatches = (glob: string, pattern: string): Detector => ({ kind: 'fileMatches', glob, pattern })
 
 export function validateManifest(m: ContractManifest): string[] {
     const errs: string[] = []

package/src/contracts/contracts-engine.ts

@@ -4,8 +4,9 @@
 // - undeclared venue whose detectors fire → FAIL (config can't lie,
 //   folders can't rot)
 // - exempt venues skip VISIBLY with their reason; never silence
-// - 'always' contracts with gate 'public-surface': full severity once the
-//   repo has a public surface, everything demoted to WARN before.
+// - 'always' contracts with gate 'public-surface': apply once the repo has a
+//   public surface, silent before (nothing is served yet).
+// - a rule path's `{web}` is the repo's web root (contracts/web-surface.ts).
 // Every FAIL carries a fix: pointer = docsBase + manifest.owner.
 //
 // It reads ONLY through the disk it is handed (a check context), so what a
@@ -23,8 +24,10 @@ export type ContractsConfig = {
     declared: string[]
     /** social channel list — handed to custom rules via ContractEnv */
     social: string[]
-    /** repo has a public surface (deploy script or any declared venue) — gates 'always' contracts */
+    /** repo has a public surface (a deploy, a declared venue, a public repo) — gates 'always' contracts */
     publicSurface: boolean
+    /** the dir the site serves, substituted for `{web}` in rule paths (default 'public') */
+    webRoot?: string
     /** venue → reason; skips the venue VISIBLY */
     exempt?: Record<string, string>
     /** prefix for fix: pointers, e.g. a docs checkout path or URL */
@@ -84,6 +87,14 @@ export function globFiles(pattern: string, d: ContractDisk): string[] {
 /** 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)
 
+/** a rule with `{web}` replaced by the web root, `.` meaning the repo root */
+export function atWebRoot(rule: ArtifactRule, webRoot: string): ArtifactRule {
+    const sub = (s: string): string => s.replaceAll('{web}/', webRoot === '.' ? '' : `${webRoot}/`)
+    if ('path' in rule) return { ...rule, path: sub(rule.path) }
+    if ('pattern' in rule) return { ...rule, pattern: sub(rule.pattern) }
+    return rule
+}
+
 async function checkRule(rule: ArtifactRule, env: ContractEnv, d: ContractDisk): Promise<string[]> {
     const problems: string[] = []
     switch (rule.kind) {
@@ -145,6 +156,10 @@ 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 === 'fileMatches') {
+            const re = new RegExp(det.pattern, 'm')
+            const hit = globFiles(det.glob, d).find((f) => re.test(textOf(d, f) ?? ''))
+            if (hit != null) return `${hit} matches /${det.pattern}/`
         } 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}/`
@@ -166,8 +181,10 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
     const lines: Line[] = []
     const outcomes: ContractOutcome[] = []
     let anyFail = false
+    const webRoot = cfg.webRoot ?? 'public'
     const env: ContractEnv = {
         root: cfg.root,
+        webRoot,
         venues: cfg.declared,
         social: cfg.social,
         exists: (rel) => d.exists(rel),
@@ -180,7 +197,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
     for (const m of manifests) {
         const exemptReason = cfg.exempt?.[m.venue]
         if (exemptReason != null) {
-            lines.push({ kind: 'skip', text: `${m.venue}  exempt: "${exemptReason}"` })
+            lines.push({ kind: 'skip', text: `${m.venue}: exempt: "${exemptReason}"` })
             outcomes.push({ venue: m.venue, status: 'exempt', problems: 0 })
             continue
         }
@@ -189,28 +206,32 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
             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` })
+                lines.push({ kind: 'fail', text: `${m.venue}: ships (${signal}) but venue is not declared — declare it or remove the signal` })
                 lines.push(...fix(m, 'declare + fill the contract'))
                 outcomes.push({ venue: m.venue, status: 'fail', problems: 1 })
             } else {
+                // a folder with nothing out yet (local drafts) is work in progress, never a ship
+                if (d.exists(m.dir, 'dir')) lines.push({ kind: 'note', text: `${m.venue}: ${m.dir}/ holds work that is not out yet, nothing to check until the venue is declared` })
                 outcomes.push({ venue: m.venue, status: 'not-applicable', problems: 0 })
             }
             continue
         }
-        // demote everything to WARN on ungated 'always' contracts (no public surface yet)
-        const warnAll = m.appliesTo === 'always' && m.gate === 'public-surface' && !cfg.publicSurface
+        // an 'always' contract gated on a public surface means nothing before one exists
+        if (m.appliesTo === 'always' && m.gate === 'public-surface' && !cfg.publicSurface) {
+            outcomes.push({ venue: m.venue, status: 'not-applicable', problems: 0 })
+            continue
+        }
         let problems = 0
         let warned = 0
         for (const rule of m.artifacts) {
-            const found = await checkRule(rule, env, d)
-            const asWarn = warnAll || rule.warnOnly === true
+            const found = await checkRule(atWebRoot(rule, webRoot), env, d)
             for (const p of found) {
-                if (asWarn) {
+                if (rule.warnOnly === true) {
                     warned++
-                    lines.push({ kind: 'warn', text: `${m.venue}  ${p}${warnAll ? ' (no public surface yet — WARN not FAIL)' : ''}` })
+                    lines.push({ kind: 'warn', text: `${m.venue}: ${p}` })
                 } else {
                     problems++
-                    lines.push({ kind: 'fail', text: `${m.venue}  ${p}` })
+                    lines.push({ kind: 'fail', text: `${m.venue}: ${p}` })
                 }
             }
         }
@@ -224,7 +245,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
         } else if (warned > 0) {
             outcomes.push({ venue: m.venue, status: 'warn', problems: warned })
         } else {
-            lines.push({ kind: 'ok', text: `${m.venue}  ${m.dir}/ complete (${m.artifacts.length} rule(s))` })
+            lines.push({ kind: 'ok', text: `${m.venue}: ${m.dir}/ complete (${m.artifacts.length} rule(s))` })
             outcomes.push({ venue: m.venue, status: 'ok', problems: 0 })
         }
     }

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

@@ -1,6 +1,7 @@
 // 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.
+// its brand source + committed favicon/logo/OG outputs, at the web root its
+// deploy serves (`{web}`). gate: applies once a public surface exists (a
+// deploy, a declared venue, a public repo that is more than an npm package).
 import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
@@ -12,8 +13,8 @@ export default defineContract({
     detect: [],
     artifacts: [
         file('.shipkit/identity/brand.ts'),
-        png('public/favicon.png', 512, 512),
-        png('public/og.png', 1200, 630, { atLeast: true }),
-        glob('public/logo.*', { min: 1 }),
+        png('{web}/favicon.png', 512, 512),
+        png('{web}/og.png', 1200, 630, { atLeast: true }),
+        glob('{web}/logo.*', { min: 1 }),
     ],
 })

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

@@ -1,13 +1,15 @@
 // normative WHAT for .shipkit/social/ (posts ONLY — the Discord server contract is
 // discord.contract.ts). Declared = the repo config lists social channels.
-import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+// Undeclared, it ships only once a post is out (`status: posted`): a folder
+// of local drafts is work in progress, never a ship.
+import { custom, defineContract, fileMatches } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'social',
     dir: '.shipkit/social',
     owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
-    detect: [dirExists('.shipkit/social')],
+    detect: [fileMatches('.shipkit/social/**/*.md', '^status:\\s*posted\\b')],
     artifacts: [
         custom('declared-channel-dirs', (env) =>
             env.social

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

@@ -1,6 +1,6 @@
 // normative WHAT for .shipkit/steam/ — the WHY + workflow live in the sibling page.
 // Capsule sizes as of 2026-07 — Valve churns them: re-verify at use, bump here.
-import { defineContract, dir, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { custom, defineContract, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'steam',
@@ -22,7 +22,11 @@ export default defineContract({
         // .ico, dims not png-parseable — presence-checked only
         file('.shipkit/steam/capsules/client-icon.ico'),
         glob('.shipkit/steam/screenshots/*.png', { min: 5, width: 1920, height: 1080 }),
-        // vdf scripts only exist once the appid does — nag, don't block
-        dir('.shipkit/steam/vdf', { warnOnly: true }),
+        // vdf scripts need the Steamworks appid (recorded in steam_appid.txt,
+        // Valve's own file name): before it, the line names that blocker
+        custom('vdf', (env) => {
+            if (!env.exists('.shipkit/steam/steam_appid.txt')) return ['no Steamworks appid yet (.shipkit/steam/steam_appid.txt): the vdf/ build scripts wait on it']
+            return env.exists('.shipkit/steam/vdf') ? [] : ['.shipkit/steam/vdf/ missing: the appid exists, write the app build and depot scripts']
+        }, { warnOnly: true }),
     ],
 })