rvlib-shipkit 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 0.2.0 — 2026-07-22
+
+The one-runner release: shipkit becomes the all-in-one companion
+binary/cli/tui of every repo — ci gate, health checks, contracts, asks,
+wiki graphs, asset atelier, live dashboard, init.
+
+BREAKING:
+
+- repo.config `checks:[]` + the `RepoCheck` type are DELETED (zero
+  consumers existed) — drop a `<name>.check.ts` file anywhere instead;
+  `shipkit check` discovers it.
+- `defineRepo` now REJECTS unknown top-level and `defaults` keys — a typo
+  can no longer silently thin the gate.
+- the standalone `rvlib-atelier` npm package is SUPERSEDED by this release
+  (its source folded in as `src/assets/`); it stays published as the frozen
+  predecessor, no new releases, deprecated after its last consumer swaps.
+
+New:
+
+- assets: `customPanel({ id, script })` — repo-defined metadata editors in
+  the studio. `script` is a repo-root-relative ES module served at
+  `GET /panel/<kindId>/<panelId>.js` and mounted as a drawer tab per asset:
+  `mount(el, api)` (+ optional `unmount()`), api =
+  `{ assetId, kindId, roll, imgUrl, getMeta(), saveMeta(json) }` backed by
+  the roll's meta sidecar (`/api/meta`, single writer). Script paths are
+  validated at kit load AND studio boot (loud error, never a silent 404);
+  panel ids are url-safe kebab-case, no `..`/absolute paths. geometry/grid
+  panels stay baked in — this is the escape hatch for any other shape.
+
+- tui: `shipkit tui` — ONE live dashboard for every repo. Built-in panels:
+  Tasks (the ci gate streamed through the DAG runner via the new
+  `onTaskFinish` tap; STATUS.md refreshes like a terminal `shipkit ci`) and
+  Checks (contracts + discovered `*.check.ts` via the new CheckSuite
+  `onResult` tap — cached replays flagged, TTL layers intact). Panels are
+  render-free data (`TuiPanelDef`: rows + wire-format detail lines); repos
+  append their own via repo.config `tui: { panels: [...] }`. The view (ink +
+  mobx `makeAutoObservable`) normalizes wire lines to one visual language
+  (✓/✗/⚠/~/»). `asks.emptyText` config personalizes the `shipkit asks`
+  all-clear line.
+
+- floor integrity (zero-config O6): with no package.json script,
+  `imports:check`/`cycles` fill from the bundled rvlib-ts-tools dep and
+  `typecheck` from the repo's tsc; a slot nothing can fill prints a
+  `skip: <id> (reason)` line — a thin gate is never silent. `defineRepo`
+  now REJECTS unknown top-level and `defaults` keys. `shipkit init` prints
+  how each floor slot resolved and gains `--bin <cli.ts path>` for
+  in-repo-source consumers (scripts become `bun <path> <cmd>`).
+- STATUS.md: `writeStatus(root, …)` in the lib is THE writer — timestamp +
+  RED/GREEN verdict + fenced compact render, atomic (tmp + rename),
+  lock-guarded (concurrent runner skips with a WARN; stale locks stolen).
+  `shipkit ci` and `shipkit check` refresh it by default (`status: false`
+  opts out).
+- check: `*.check.ts` auto-discovery is THE registration — `shipkit check`
+  scans the repo (skips node_modules/dist/tmp/references + dot-dirs) and
+  runs each file as a subprocess: wire output parsed back (`parseWireOutput`
+  exported), exit code is truth, non-zero exit with no FAIL line still fails
+  loud. Checks running their own CheckSuite are never double-cached; plain
+  checks get a 30m orchestrator TTL; `--fresh` busts every layer and travels
+  to children.
+- core: ONE spawn-with-timeout (`spawnWithTimeout`, exported) — task runner
+  and `CheckCtx.exec` now share it (binary resolved before spawn, streamed
+  output, SIGTERM→SIGKILL escalation); duplicate implementations deleted.
+
+- assets: the atelier folded in as the `src/assets/` surface — asset-kind
+  registry (defineKit/defineKind), ComfyUI + procedural-canvas generators,
+  roll-and-pick studio server, metadata editor panels, kits/identity
+  (favicon/logo/OG), `rvlib-shipkit/vite` save-endpoint factory. CLI:
+  `shipkit assets serve|fill|add|gen|identity|check`.
+- CLI rebuilt on clipanion (one command per file, `Command.Usage` help with
+  categories + examples, testable contexts); wire output contract unchanged
+  and frozen by a CLI-level test. Every value-taking option carries a
+  description — per-command `--help` renders a clean synopsis + Options
+  table.
+- deps: @napi-rs/canvas + sharp (assets), clipanion (CLI), ink + react +
+  mobx + mobx-react-lite (tui), rvlib-ts-tools (imports/cycles floor for
+  every repo).
+
 ## 0.1.1 — 2026-07-22
 
 - `init` now points at the identity/assets setup (rvlib-atelier: brand.ts +

package/README.md

@@ -1,8 +1,9 @@
 # rvlib-shipkit
 
 Repo toolkit for shipping: one config file gives a repo a commit gate
-(task DAG), release-contract fulfillness checks, a human ask queue, and
-markdown-wiki tooling.
+(task DAG), release-contract fulfillness checks, a human ask queue,
+markdown-wiki tooling, and the asset atelier (generate, curate, and ship
+assets — favicon/logo/OG included).
 
 ```sh
 bun add -d rvlib-shipkit
@@ -17,20 +18,32 @@ export default defineRepo({
     name: 'my-game',
     venues: ['itch'],          // which release contracts are REQUIRED
     social: ['x', 'discord'],  // .rv-social/<channel>/ post folders (+ .rv-discord/)
-    tasks: [{ id: 'typecheck', cmd: ['bun', 'run', 'typecheck'], deps: ['lint'] }],
+    tasks: [{ id: 'e2e', cmd: ['bun', 'run', 'e2e'], deps: ['lint'] }],
 })
 ```
 
+Health checks need no config at all: drop a `<name>.check.ts` file anywhere
+and `shipkit check` discovers and runs it (wire output + exit code).
+
 ## CLI
 
 ```
-shipkit ci        commit gate: auto-registered floor (lint/typecheck/test/…)
-                  + contracts + your tasks, parallel DAG   [--bail --skip g --only id --json]
+shipkit ci        commit gate: floor (lint/typecheck/test/imports/cycles —
+                  scripts win, imports/cycles/typecheck fill from bundled
+                  tools with zero config, gaps print visibly) + contracts
+                  + your tasks, parallel DAG; refreshes STATUS.md
+                  [--bail --skip g --only id --json]
 shipkit contracts release-contract fulfillness alone       [--venue v --json]
-shipkit check     periodic health checks, TTL-cached       [--json --fresh]
+shipkit check     periodic health: every *.check.ts in the repo,
+                  auto-discovered + TTL-cached              [--json --fresh]
+shipkit tui       live dashboard: ci tasks + discovered checks + panels
+                  the repo injects via repo.config tui.panels
 shipkit asks      human action queue: list · ask "<title>" · asks check (auto-close)
 shipkit wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
-shipkit init      scaffold config + scripts
+shipkit assets    serve|fill|add|gen|identity|check — the asset atelier
+                  (declare kinds in .rv-assets/kit.ts, roll, curate, ship)
+shipkit init      scaffold config + scripts, print the resolved floor
+                  [--bin <cli.ts path> for in-repo-source consumers]
 ```
 
 Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with
@@ -52,7 +65,9 @@ Ship your own contracts via `contracts: { extra: [defineContract({...})] }`
 ## Library use
 
 Everything the CLI does is importable: `runTasks`, `CheckSuite`,
-`evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`.
+`evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`,
+and the assets surface (`defineKit`/`defineKind`, `identityKinds`,
+`serveStudio`, `saveEndpoint` via `rvlib-shipkit/vite`).
 Ships TypeScript source; Bun ≥ 1.0.
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.1.1",
-    "description": "Repo toolkit: task runner, release-contract fulfillness checker, asks queue, md-wiki tools",
+    "version": "0.2.0",
+    "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",
     "files": [
@@ -15,9 +15,21 @@
     "exports": {
         ".": "./src/shipkit.ts",
         "./contracts": "./src/contracts/contract-types.ts",
+        "./vite": "./src/assets/vite.ts",
         "./src/*": "./src/*"
     },
     "devDependencies": {
-        "@types/bun": "^1.3.14"
+        "@types/bun": "^1.3.14",
+        "@types/react": "^19.2.17"
+    },
+    "dependencies": {
+        "@napi-rs/canvas": "^1.0.2",
+        "clipanion": "^4.0.0-rc.4",
+        "ink": "^7.1.1",
+        "mobx": "^6.16.1",
+        "mobx-react-lite": "^4.1.1",
+        "react": "^19.2.7",
+        "rvlib-ts-tools": "^0.2.0",
+        "sharp": "^0.35.3"
     }
 }

package/src/asks/asks-queue.ts

@@ -9,7 +9,18 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFile
 import { join } from 'path'
 
 export type Ask = { file: string; status: string; kind: string; created: string; blocks: string; check: string | null; title: string }
-export type CreateOpts = { kind?: string; blocks?: string; check?: string }
+export type CreateOpts = { kind?: string; blocks?: string; check?: string; why?: string }
+
+/** filename slug: kebab, truncated at a WORD boundary (never mid-word — a
+ *  `…-rvlib-` stub reads as broken). Falls back to a hard cut only when the
+ *  first word alone already exceeds max. */
+export function slugify(title: string, max = 40): string {
+    const full = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+    if (full.length <= max) return full
+    const cut = full.slice(0, max)
+    const lastDash = cut.lastIndexOf('-')
+    return (lastDash > 0 ? cut.slice(0, lastDash) : cut).replace(/-+$/, '')
+}
 
 const parse = (dir: string, file: string): Ask => {
     const md = readFileSync(join(dir, file), 'utf8')
@@ -62,10 +73,14 @@ export function createAsk(dir: string, title: string, opts?: CreateOpts): string
     const done = join(dir, 'done')
     const archived = existsSync(done) ? readdirSync(done).filter((f) => f.endsWith('.md')) : []
     const n = Math.max(0, ...[...listAsks(dir).map((a) => a.file), ...archived].map((f) => parseInt(f, 10) || 0)) + 1
-    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40)
+    const slug = slugify(title)
     const file = `${String(n).padStart(3, '0')}-${slug}.md`
     if (existsSync(join(dir, file))) throw new Error(`refusing to overwrite existing ${file}`)
     const check = opts?.check ?? null
+    // Why is OPTIONAL — omit the line entirely rather than ship a literal
+    // "TODO" that never gets filled (the ask itself is the record).
+    const why = opts?.why?.trim()
+    const whyBlock = why != null && why !== '' ? `**Why**: ${why}\n\n` : ''
     writeFileSync(join(dir, file), `---
 status: open
 kind: ${opts?.kind ?? 'action'}
@@ -77,18 +92,16 @@ blocks: ${opts?.blocks ?? '-'}${check != null ? `\ncheck: ${check}` : ''}
 
 **Ask**: ${title}
 
-**Why**: TODO
-
-**Answer**: _(fill in / check off, or just do it — the check probe auto-closes when it passes)_
+${whyBlock}**Answer**: _(fill in / check off, or just do it — the check probe auto-closes when it passes)_
 
 **Done when**: ${check != null ? `\`${check}\` exits 0` : 'status flipped to done'}
 `)
     return file
 }
 
-export function renderAsksTable(dir: string, print: (line: string) => void = console.log): number {
+export function renderAsksTable(dir: string, print: (line: string) => void = console.log, opts?: { emptyText?: string }): number {
     const open = openAsks(dir)
-    if (open.length === 0) { print('no open asks — all caught up 🎉'); return 0 }
+    if (open.length === 0) { print(opts?.emptyText ?? 'no open asks — all caught up 🎉'); return 0 }
     for (const a of open) print(`${a.status.padEnd(9)} ${a.kind.padEnd(7)} ${a.file.padEnd(44)} blocks: ${a.blocks}`)
     print(`\n${open.length} open — details: ${dir}/<file>`)
     return open.length

package/src/assets/gen/comfy-gen.ts

@@ -0,0 +1,106 @@
+// ComfyUI HTTP engine — post/wait/fetch plumbing, zero node-id knowledge
+// (node ids live in each workflow's .ts sidekick).
+import { mkdirSync } from 'fs'
+import { extname, join } from 'path'
+import type { Graph, Sidekick, Workflow } from './workflow-loader.ts'
+
+export type ComfyOpts = {
+    /** e.g. 'http://127.0.0.1:8085' */
+    host: string
+    /** shell command that heals the backend (tunnel/boot) — shown in error hints, never executed by the lib */
+    heal?: string
+    waitTimeoutMs?: number
+    pollMs?: number
+}
+
+const WAIT_TIMEOUT_MS = 10 * 60_000 // covers cold model loads
+const POLL_MS = 1500
+
+const healHint = (o: ComfyOpts): string => (o.heal != null ? ` — is the backend up? (${o.heal})` : '')
+
+/** Loud guard for setInputs escape hatches: the node must exist and match. */
+export function expectNode(graph: Graph, id: string, classType: string): Graph[string] {
+    const n = graph[id]
+    if (n == null) throw new Error(`graph has no node '${id}' (expected ${classType})`)
+    if (n.class_type !== classType) throw new Error(`node '${id}' is ${n.class_type}, expected ${classType}`)
+    return n
+}
+
+export function applyInputs(graph: Graph, sk: Sidekick, args: { prompt: string; seed: number; prefix: string }): void {
+    if (sk.setInputs != null) return sk.setInputs(graph, args)
+    for (const [role, value] of [['prompt', args.prompt], ['seed', args.seed], ['prefix', args.prefix]] as const) {
+        const b = sk.bindings[role]
+        graph[b.node]!.inputs[b.input] = value
+    }
+}
+
+export async function submit(o: ComfyOpts, graph: Graph): Promise<string> {
+    const res = await fetch(`${o.host}/prompt`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ prompt: graph, client_id: crypto.randomUUID() }),
+    })
+    if (!res.ok) throw new Error(`POST /prompt → ${res.status}: ${(await res.text()).slice(0, 300)} — bad graph or server mid-boot${healHint(o)}`)
+    return ((await res.json()) as { prompt_id: string }).prompt_id
+}
+
+type HistoryOutputs = Record<string, { images?: { filename: string; subfolder?: string; type?: string }[] }>
+
+export async function waitFor(o: ComfyOpts, promptId: string): Promise<HistoryOutputs> {
+    const timeoutMs = o.waitTimeoutMs ?? WAIT_TIMEOUT_MS
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+        const res = await fetch(`${o.host}/history/${promptId}`)
+        if (res.ok) {
+            const h = (await res.json()) as Record<string, { outputs: HistoryOutputs; status?: { status_str?: string } }>
+            const entry = h[promptId]
+            if (entry != null) {
+                if (entry.status?.status_str === 'error') throw new Error(`prompt ${promptId} errored on the server — open the ComfyUI UI (${o.host}) for the node error`)
+                return entry.outputs
+            }
+        }
+        await Bun.sleep(o.pollMs ?? POLL_MS)
+    }
+    throw new Error(`prompt ${promptId} still not done after ${Math.round(timeoutMs / 60000)} min — server stuck? check ${o.host} queue${healHint(o)}`)
+}
+
+async function fetchImage(o: ComfyOpts, img: { filename: string; subfolder?: string; type?: string }, dest: string): Promise<void> {
+    const q = new URLSearchParams({ filename: img.filename, subfolder: img.subfolder ?? '', type: img.type ?? 'output' })
+    const res = await fetch(`${o.host}/view?${q}`)
+    if (!res.ok) throw new Error(`GET /view ${img.filename} → ${res.status}`)
+    await Bun.write(dest, await res.arrayBuffer())
+}
+
+/**
+ * Run one generation through a workflow pair: fresh graph copy, sidekick
+ * bindings applied, submitted, waited, non-preview outputs saved as
+ * <destDir>/<name>.<ext> (ONE clean file per asset — no _00001_ counter noise).
+ */
+export async function generate(o: ComfyOpts, wf: Workflow, args: { prompt: string; seed: number; destDir: string; name: string }): Promise<string[]> {
+    const graph = structuredClone(wf.graph)
+    applyInputs(graph, wf.sidekick, { prompt: args.prompt, seed: args.seed, prefix: args.name })
+    mkdirSync(args.destDir, { recursive: true })
+    const outputs = await waitFor(o, await submit(o, graph))
+    const saved: string[] = []
+    for (const node of Object.values(outputs)) {
+        for (const img of node.images ?? []) {
+            if (img.type === 'temp') continue // PreviewImage — raw, non-transparent
+            // >1 saved image (batch_size, second Save node): suffix instead of silently overwriting
+            const ext = extname(img.filename) || '.webp'
+            const dest = join(args.destDir, `${args.name}${saved.length > 0 ? `-${saved.length + 1}` : ''}${ext}`)
+            await fetchImage(o, img, dest)
+            saved.push(dest)
+        }
+    }
+    if (saved.length === 0) throw new Error(`workflow '${wf.id}' produced no saved images (only previews?) — does the graph end in a Save node?`)
+    return saved
+}
+
+export const randomSeed = (): number => Math.floor(Math.random() * 2_000_000_000) + 1
+
+/** Shell-stamped batch folder name — the one-shot output convention. */
+export function batchFolderName(slug: string): string {
+    const d = new Date()
+    const p = (n: number) => String(n).padStart(2, '0')
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}-${slug}`
+}

package/src/assets/gen/generate-roll.ts

@@ -0,0 +1,57 @@
+// The ONE roll generator — canvas (procedural, in-process via @napi-rs/canvas)
+// or comfy (HTTP through a workflow pair). The studio worker AND the
+// fill/add/gen CLI both call this, so a canvas kit rolls the SAME way in both
+// (before this, canvas draw lived only in the studio and the CLI refused
+// canvas kinds — A30). Comfy context is resolved LAZILY: canvas-only kits
+// never touch a comfy config or the box.
+import { mkdirSync } from 'fs'
+import { join } from 'path'
+import type { FoundAsset } from '../kit-config.ts'
+import { generate } from './comfy-gen.ts'
+import { loadWorkflows, workflowFor, type Workflow } from './workflow-loader.ts'
+
+/** roll canvas master size (square) — favicon/logo/sprites derive from it */
+export const CANVAS_SIZE = 1024
+
+export type ComfyRuntime = { workflows: Map<string, Workflow>; host: string; heal?: string }
+export type ComfyResolver = () => Promise<ComfyRuntime>
+
+/** Draw/generate one roll for `found` into destDir as v<seed>.png (canvas) or
+ *  v<seed>.<ext> (comfy). `resolveComfy` is only awaited for comfy backends. */
+export async function generateRoll(
+    found: FoundAsset,
+    args: { prompt: string; seed: number; destDir: string },
+    resolveComfy: ComfyResolver,
+): Promise<void> {
+    const gen = found.kind.generate
+    if (gen.backend === 'canvas') {
+        const { createCanvas } = await import('@napi-rs/canvas')
+        const c = createCanvas(CANVAS_SIZE, CANVAS_SIZE)
+        await gen.draw(c.getContext('2d'), { ...found.asset, prompt: args.prompt })
+        mkdirSync(args.destDir, { recursive: true })
+        await Bun.write(join(args.destDir, `v${args.seed}.png`), c.toBuffer('image/png'))
+        return
+    }
+    const rt = await resolveComfy()
+    const wf = workflowFor(rt.workflows, { workflow: gen.workflow, assetId: found.asset.id })
+    await generate({ host: rt.host, heal: rt.heal }, wf, { prompt: args.prompt, seed: args.seed, destDir: args.destDir, name: `v${args.seed}` })
+}
+
+/** Memoized lazy comfy runtime for a resolved kit — loads the workflow pairs on
+ *  the FIRST comfy roll only. `onMissing` is called (never returns) if a comfy
+ *  asset needs it but the kit declares no comfy config. */
+export function comfyResolver(
+    root: string,
+    kit: { comfy?: { host: string; workflows: string; heal?: string } },
+    onMissing: () => never,
+): ComfyResolver {
+    let cached: Promise<ComfyRuntime> | null = null
+    return () => {
+        if (kit.comfy == null) onMissing()
+        return (cached ??= (async () => ({
+            workflows: await loadWorkflows(join(root, kit.comfy!.workflows)),
+            host: kit.comfy!.host,
+            heal: kit.comfy!.heal,
+        }))())
+    }
+}

package/src/assets/gen/workflow-loader.ts

@@ -0,0 +1,67 @@
+// Workflow pairs: <id>.json exported graph + <id>.ts sidekick (bindings +
+// optional expects/setInputs). Every violation THROWS loud with the fix in
+// the message — CLIs die, checkers turn it into a FAIL line.
+import { existsSync, readdirSync } from 'fs'
+import { basename, join } from 'path'
+
+export type Binding = { node: string; input: string }
+export type Sidekick = {
+    bindings: { prompt: Binding; seed: Binding; prefix: Binding }
+    expects?: Record<string, string>
+    requires?: { customNodes?: string[]; models?: string[] }
+    setInputs?: (graph: Graph, args: { prompt: string; seed: number; prefix: string }) => void
+}
+export type Graph = Record<string, { inputs: Record<string, unknown>; class_type: string }>
+export type Workflow = { id: string; jsonPath: string; graph: Graph; sidekick: Sidekick }
+
+// function declaration, not const — TS only narrows on never-calls to
+// directly-declared functions
+function fail(msg: string): never { throw new Error(msg) }
+
+/** dir = the folder holding the <id>.json + <id>.ts pairs */
+export async function loadWorkflows(dir: string): Promise<Map<string, Workflow>> {
+    const out = new Map<string, Workflow>()
+    if (!existsSync(dir)) fail(`${dir}/ missing — ship at least one <id>.json + <id>.ts workflow pair`)
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
+        const id = basename(f, '.json')
+        const jsonPath = join(dir, f)
+        const tsPath = join(dir, `${id}.ts`)
+        if (!existsSync(tsPath)) fail(`workflow '${id}': ${f} has no sidekick ${id}.ts — every graph json ships with its adjacent .ts module`)
+        const graph = (await Bun.file(jsonPath).json()) as Graph
+        // ?rvload = a DISTINCT module instance: when a self-executing sidekick
+        // is the running script, importing its bare path would await its own
+        // in-flight top-level evaluation — a deadlock. NOTE the busted
+        // instance STILL sees import.meta.main=true (bun compares paths sans
+        // query), so its CLI tail runs too — the cliRunning guard in the
+        // sidekick runner is what keeps it inert. Never remove that guard.
+        const mod = (await import(`${tsPath}?rvload`)) as Partial<Sidekick>
+        const b = mod.bindings
+        if (b == null || !b.prompt?.node || !b.seed?.node || !b.prefix?.node) {
+            fail(`workflow '${id}': sidekick must export bindings = { prompt|seed|prefix: { node, input } }`)
+        }
+        for (const [role, bind] of Object.entries(b!) as [string, Binding][]) {
+            const n = graph[bind.node]
+            if (n == null) fail(`workflow '${id}': bindings.${role} points at node '${bind.node}' which is not in ${f} — graph re-exported with renumbered nodes? update the sidekick`)
+            if (!(bind.input in n!.inputs)) fail(`workflow '${id}': node '${bind.node}' (${n!.class_type}) has no input '${bind.input}' (has: ${Object.keys(n!.inputs).join(', ')})`)
+        }
+        for (const [node, cls] of Object.entries(mod.expects ?? {})) {
+            const n = graph[node]
+            if (n == null) fail(`workflow '${id}': expects node '${node}' missing from ${f}`)
+            if (n.class_type !== cls) fail(`workflow '${id}': node '${node}' is ${n.class_type}, sidekick expects ${cls} — graph changed under the sidekick, re-check bindings`)
+        }
+        out.set(id, { id, jsonPath, graph, sidekick: mod as Sidekick })
+    }
+    if (out.size === 0) fail(`${dir}/ has no <id>.json graphs`)
+    return out
+}
+
+/** Resolve a workflow: explicit id, else the sole loaded workflow. */
+export function workflowFor(workflows: Map<string, Workflow>, ref: { workflow?: string; assetId?: string }): Workflow {
+    if (ref.workflow != null) {
+        const w = workflows.get(ref.workflow)
+        if (w == null) fail(`asset '${ref.assetId ?? '?'}': unknown workflow '${ref.workflow}' (have: ${[...workflows.keys()].join(', ')})`)
+        return w!
+    }
+    if (workflows.size === 1) return [...workflows.values()][0]!
+    return fail(`asset '${ref.assetId ?? '?'}' names no workflow and ${workflows.size} are loaded (${[...workflows.keys()].join(', ')}) — set workflow on the kind`)
+}

package/src/assets/image-ops.ts

@@ -0,0 +1,30 @@
+// Shared image utils for pick-ship hooks (sharp — the PIL replacement).
+// Ship hooks import these instead of forking convert/flip code.
+import sharp from 'sharp'
+
+/** Convert any roll (webp/png) to PNG at dest; optional horizontal mirror.
+ *  Flipped assets ship MIRRORED PIXELS — downstream metadata (rects…) must
+ *  mirror coordinates itself and drop the flag so loaders never double-flip. */
+export async function toPng(src: string, dest: string, opts?: { flipX?: boolean }): Promise<void> {
+    let img = sharp(src)
+    if (opts?.flipX === true) img = img.flop()
+    await img.png().toFile(dest)
+}
+
+/** Alpha-content height in px (alpha > threshold — AI cutouts leave low-alpha
+ *  noise). Used to normalize prop sizes by visible art height. */
+export async function alphaHeight(src: string, threshold = 24): Promise<number> {
+    const { data, info } = await sharp(src).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+    let top = -1
+    let bottom = -1
+    for (let y = 0; y < info.height; y++) {
+        for (let x = 0; x < info.width; x++) {
+            if (data[(y * info.width + x) * info.channels + 3]! > threshold) {
+                if (top === -1) top = y
+                bottom = y
+                break
+            }
+        }
+    }
+    return top === -1 ? info.height : bottom - top + 1
+}

package/src/assets/json-store.ts

@@ -0,0 +1,27 @@
+// Locked JSON read-modify-write — the ONE way any tool (studio, fill CLI,
+// a hand-rolled project script) writes workspace JSON files. Re-reads inside
+// the lock so concurrent hand edits are never clobbered by a stale in-memory
+// copy; never cache-and-write a whole file from outside.
+import { existsSync } from 'fs'
+
+const locks = new Map<string, Promise<void>>()
+
+export async function updateJson<T>(path: string, init: T, updater: (data: T) => void | Promise<void>): Promise<T> {
+    while (locks.has(path)) await locks.get(path)
+    let release!: () => void
+    locks.set(path, new Promise<void>((r) => (release = r)))
+    try {
+        const data = existsSync(path) ? ((await Bun.file(path).json()) as T) : structuredClone(init)
+        await updater(data)
+        await Bun.write(path, JSON.stringify(data, null, 2) + '\n')
+        return data
+    } finally {
+        locks.delete(path)
+        release()
+    }
+}
+
+export async function readJson<T>(path: string, fallback: T): Promise<T> {
+    if (!existsSync(path)) return fallback
+    return (await Bun.file(path).json()) as T
+}