rvlib-shipkit 0.34.0 → 0.35.0

package/src/ledger/store.ts

@@ -0,0 +1,122 @@
+// ONE STORE. Everything this toolkit remembers between runs lives here, in
+// one shape, under one root, busted by one flag.
+//
+// There used to be two: `tmp/.shipkit-cache` for the check orchestrator and
+// `tmp/.check-cache` for the page checks, each with its own bust env var, each
+// per worktree. Two stores means two staleness windows over one question, and
+// the stamps in this repo's own history went BACKWARDS between checkouts
+// because of it. This module is the single mechanism; what differs between
+// populations is the KEY, never the storage.
+//
+// THE SHAPE, unchanged from the check cache slice 2 landed and proved:
+// one immutable file per key, named by the key, written tmp + rename. No
+// lock, no merge, no read-modify-write, and no prune of another runner's
+// entries. Three agents in one checkout is the normal case, so the only safe
+// aggregate is no aggregate: a run with a different key writes a DIFFERENT
+// file, a run with the same key replaces its own whole answer or none of it,
+// and housekeeping sweeps by AGE, which needs no knowledge of what the
+// current run knows about.
+//
+// WHERE. `<git-common-dir>/shipkit/store/`, which is SHARED by every linked
+// worktree of the repo. That is safe only because no key component is a path:
+// the toolchain identity content-hashes the gate binary and every installed
+// package, so two worktrees carrying different installs produce different
+// keys and simply miss each other (ledger/toolchain-identity.ts owns the
+// measurement). It is also outside the work tree, so nothing here can dirty a
+// diff or reach a commit.
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+
+/** the storage FORMAT. Bumped when the envelope changes, so an old file can
+ *  never be handed to a new reader. The KEY carries everything about the
+ *  question; this is only about the file around it. */
+export const STORE_VERSION = 1
+
+/** the ONE env var that busts every remembered answer, content or TTL. */
+export const FRESH_ENV = 'SHIPKIT_FRESH'
+
+/** one remembered answer. `key` is stored as well as hashed into the file
+ *  name, and re-checked on read: a name collision must miss, never serve a
+ *  neighbour's answer. */
+export type Stored<T> = {
+    v: number
+    key: string
+    /** when it was written, ms since epoch */
+    at: number
+    payload: T
+}
+
+/** how long a superseded entry survives. Far past the longest TTL any check
+ *  declares, so a live entry is never swept out from under a replay. */
+export const KEEP_MS = 30 * 24 * 60 * 60 * 1000
+
+/** where this repo's remembered answers live.
+ *
+ *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
+ *  git dir but shares the common one, and slice 3 measured that sharing is
+ *  SAFE here because every key component is content or a version string.
+ *  A tree that is not a git repo at all still gets a store, under `tmp/`,
+ *  because a scaffold in progress must not crash on it. */
+export function storeRoot(root: string): string {
+    const p = Bun.spawnSync(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const dir = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+    return dir === '' ? join(root, 'tmp/.shipkit-store') : join(dir, 'shipkit/store')
+}
+
+const slug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
+
+/** where ONE answer lives. The key is in the file NAME, so a run whose key
+ *  moved writes a new file instead of rewriting the old one, and two runners
+ *  with different keys never collide. `ns` keeps populations apart so a sweep
+ *  or a manual `rm` can be scoped. */
+export function entryPath(store: string, ns: string, name: string, key: string): string {
+    const h = new Bun.CryptoHasher('sha256').update(`${ns}\0${name}\0${key}`).digest('hex').slice(0, 12)
+    return join(store, slug(ns), `${slug(name)}.${h}.json`)
+}
+
+/** a missing or half-written file reads as "no answer", which is the safe
+ *  side: the unit runs. tmp + rename means half-written cannot happen from a
+ *  shipkit write, so this only ever catches a truncated file from something
+ *  else, and treats it the same way. */
+export function readStored<T>(path: string, key: string): Stored<T> | null {
+    try {
+        const e = JSON.parse(readFileSync(path, 'utf8')) as Partial<Stored<T>>
+        if (e.v !== STORE_VERSION || e.key !== key || typeof e.at !== 'number' || e.payload == null) return null
+        return e as Stored<T>
+    } catch { return null }
+}
+
+export function writeStored<T>(path: string, key: string, payload: T, at: number): void {
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, payload }))
+    } catch {
+        // a store that cannot be written is slow, never wrong: the answer was
+        // already printed, and the next run measures again
+    }
+}
+
+export function dropStored(path: string): void {
+    try { rmSync(path, { force: true }) } catch { /* raced with another runner: it is gone either way */ }
+}
+
+/** age-based housekeeping. Sweeping by "the units I know about" is what made
+ *  the old prune wrong: a run narrowed with --only knows about one unit and
+ *  would delete the other sixty-five. */
+export function sweepStore(store: string, ns: string, now: number, keepMs = KEEP_MS): void {
+    const dir = join(store, slug(ns))
+    const cutoff = now - keepMs
+    try {
+        for (const f of readdirSync(dir)) {
+            // `.<name>.tmp-<pid>` is what atomicWrite lands beside its target,
+            // and a writer killed between the write and the rename leaves one
+            // behind. Sweeping only *.json accreted them without bound.
+            if (!f.endsWith('.json') && !/\.tmp-\d+$/.test(f)) continue
+            const p = join(dir, f)
+            try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+        }
+    } catch {
+        // no dir yet, or unreadable: housekeeping never fails a run
+    }
+}

package/src/ledger/toolchain-identity.ts

@@ -75,6 +75,36 @@ function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
     h.update(`clifiles=${files.length}\n`)
 }
 
+/**
+ * what ONE install holds, as a hash: every top-level package's name, version
+ * and link target.
+ *
+ * Exported because a repo's own install is not the only one a gate can run
+ * against. Sub-packages carry their own `node_modules`, gitignored like every
+ * other, so no git key can see them and the root toolchain does not describe
+ * them either. A unit whose declared inputs COVER such a directory folds this
+ * in beside the path, or the toolchain component stops at the repo root while
+ * the task it is meant to describe does not.
+ *
+ * ~2ms per install, and only for a path a scan already reported as ignored.
+ */
+export function installIdentity(nodeModules: string): string {
+    if (!existsSync(nodeModules)) return 'install=absent'
+    const h = createHash('sha256')
+    let names: string[] = []
+    try { names = installedNames(nodeModules) } catch { return 'install=unreadable' }
+    for (const n of names) {
+        const dir = join(nodeModules, n)
+        let version = 'MISSING'
+        try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
+        let link = ''
+        try { if (lstatSync(dir).isSymbolicLink()) link = `->${realpathSync(dir)}` } catch {}
+        h.update(`${n}@${version}${link}\n`)
+    }
+    h.update(`n=${names.length}\n`)
+    return `install=${h.digest('hex').slice(0, 16)}`
+}
+
 /**
  * the identity of the program about to run, for `repoRoot`, driven by `cliEntry`.
  *

package/src/pb/collection-scaffold.ts

@@ -101,7 +101,7 @@ function columnsFile(col: PbCollection): string {
     lines.push('// means the cell is derived and the database cannot order by it.')
     lines.push('// labels are plain text, swap them for i18n.t.<collection>.<field> when the')
     lines.push('// app carries a dict.')
-    lines.push(`import type { Column } from "rvlib-pb-shell"`)
+    lines.push(`import type { Column } from "rvlib-pb/ui"`)
     lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
     lines.push('')
     lines.push(`export const columns: Column<${col.prefix}Response>[] = [`)
@@ -144,8 +144,8 @@ function gridFile(col: PbCollection): string {
     return [
         `// the default grid for \`${col.name}\`. A page that wants the plain table renders`,
         '// this; a page that wants extra columns passes its own to LiveGrid directly.',
-        `import type { LiveList } from "rvlib-pb-mobx"`,
-        `import { LiveGrid } from "rvlib-pb-shell"`,
+        `import type { LiveList } from "rvlib-pb"`,
+        `import { LiveGrid } from "rvlib-pb/ui"`,
         `import type { ${col.prefix}Response } from "${TYPES}"`,
         `import { columns } from "./columns"`,
         '',
@@ -247,7 +247,7 @@ function indexFile(col: PbCollection, hasForm: boolean): string {
     lines.push('// registration: after this import, a LiveGrid or LiveCards over')
     lines.push(`// \`${col.name}\` with no columns of its own knows what to render, and any`)
     lines.push('// relation cell pointing AT one knows how to name it.')
-    lines.push(`import { defineCollectionUI } from "rvlib-pb-shell"`)
+    lines.push(`import { defineCollectionUI } from "rvlib-pb/ui"`)
     lines.push(`import { db } from "${PB}"`)
     lines.push(`import { ${col.prefix}Card } from "./card"`)
     lines.push(`import { columns } from "./columns"`)

package/src/release/run-release.ts

@@ -110,6 +110,11 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         frozen: true,
         status: false,
         config,
+        // THE CAP ON EVERY REMAINING HOLE IN THE KEY. Not a flag, not a config
+        // field: a release re-measures every unit, so the worst a wrong key
+        // can ever produce is an agent looking at a stale local green, never a
+        // stale green that authorised a publish (ledger/ledger.ts rule 4).
+        ledgerRead: false,
         // the FULL tier, always. A release runs on a clean tree with time to
         // spare, and the suites the working gate skips (the ones that build
         // real repositories) are exactly the ones a publish must not be wrong

package/src/release/run-releases.ts

@@ -204,7 +204,13 @@ export function attentionLines(r: UnitReport): string[] {
     // shape of a command
     const KIND = '<patch|minor|major>'
 
-    if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
+    if (r.npmTarget && r.npmLatest === 'unpublished') {
+        // NO version of this name is on the registry, which every drift branch
+        // below reads as "a bit behind" and none of them says. Every `bun add
+        // <name>` in a doc, a seed or a scaffold answers 404 while this holds,
+        // and that is the one state where the docs are not stale but dead
+        out.push(`WARN ${r.id}: nothing is published under the name ${r.name} — every "bun add ${r.name}" 404s until ${notesClause}shipkit bump ${KIND} ${r.id}`)
+    } else if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
         // the trap: a version stamped into package.json while work kept
         // landing. Publishing it ships that work under notes describing none
         // of it, so the answer is a NEW version, never this one.

package/src/repo-config.ts

@@ -23,7 +23,7 @@ import type { Rule } from './rules/rule.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
-import type { TaskDef } from './core/task-runner.ts'
+import { TASK_DEF_KEYS, type TaskDef } from './core/task-runner.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
 
@@ -51,8 +51,13 @@ export type RepoConfig = {
     social?: string[]
     /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
     docsBase?: string
-    /** override a floor task's def, or `false` to disable (always visible) */
-    defaults?: Record<string, TaskDef | false>
+    /** a floor slot: `false` disables it (always visible), a def with a
+     *  `cmd` or `logic` REPLACES it, and a def with neither DECORATES whatever
+     *  fills it. The decoration is how a repo declares what its own `test`
+     *  script reads (`{ test: { inputs: ['tests', 'src'] } }`) without
+     *  restating the command: the read set is repo knowledge, the command is
+     *  already in package.json, and restating it is a second source of truth. */
+    defaults?: Record<string, Partial<TaskDef> | false>
     /** repo-specific commit-gate tasks; deps double as race guards */
     tasks?: TaskDef[]
     /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
@@ -158,9 +163,19 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (isAbsolute(d) || rel === '.' || rel === '' || rel === '..' || rel.startsWith('../'))
             throw new Error(`defineRepo: notReleasable '${d}' is the repo root or outside it, and would excuse every package at once — name one package dir per entry`)
     }
-    for (const k of Object.keys(c.defaults ?? {}))
+    for (const [k, slot] of Object.entries(c.defaults ?? {})) {
         if (!(FLOOR_IDS as readonly string[]).includes(k))
             throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
+        // the slot's own FIELDS, not just its name. A slot with no cmd or logic
+        // decorates the resolved task, so a typo there (`input` for `inputs`)
+        // is not a type error at any call site and lands as a task that is
+        // simply never cached, silently, which is the one direction this file
+        // promises a typo cannot go.
+        if (slot === false || slot == null) continue
+        for (const f of Object.keys(slot))
+            if (!(TASK_DEF_KEYS as readonly string[]).includes(f))
+                throw new Error(`defineRepo: defaults.${k}.${f} is not a task field (fields: ${TASK_DEF_KEYS.join(', ')})`)
+    }
     for (const n of c.oneWayIn?.exempt ?? [])
         if (!(ROUTED_SCRIPTS as readonly string[]).includes(n))
             throw new Error(`defineRepo: oneWayIn.exempt '${n}' is not a governed script name (governed: ${ROUTED_SCRIPTS.join(', ')})`)
@@ -181,6 +196,13 @@ export async function loadRepoConfig(root: string): Promise<RepoConfig> {
 // the contracts commit-gate task — venue deploy tasks should dep on it.
 // Same SK002-tagged rendering as `shipkit check` and `shipkit contracts`
 // (contracts/apply-contracts.ts is the one bridge).
+//
+// DELIBERATELY UNDECLARED for the ledger, and this is where that decision
+// lives rather than in a commit message. It runs in process, shares one
+// evaluation with rule SK002 through `withContractsScope`, and measures 0.0s,
+// so a key would be risk against no reward. It is not `never:` either: the
+// contract dirs describe it perfectly well, so claiming nothing can is false,
+// and `never` has to keep meaning "somebody looked and no key exists".
 export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',

package/src/rules/SK004-gitignore-policy.ts

@@ -1,6 +1,5 @@
 // SK004 — the .gitignore policy block (meta/contracts.md git policy; tmp/
-// included because shipkit itself writes tmp/.shipkit-cache in every
-// repo). A marker-keyed managed block so the always-gitignored contract
+// included because shipkit writes its per-run logs there in every repo). A marker-keyed managed block so the always-gitignored contract
 // surfaces can never silently rot per repo. Ecosystem-specific names the
 // published lib may not carry ride as repo-contributed lines:
 // `defineRepo({ gitignore: [...] })` renders them INSIDE the block, so the