rvlib-shipkit 0.38.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 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, markdown-wiki tooling, and the asset atelier (generate, curate, and ship assets — favicon/logo/OG included).
+Repo toolkit for shipping: one config file gives a repo a commit gate (one DAG over every check), 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
@@ -14,12 +14,23 @@ import { defineRepo } from 'rvlib-shipkit'
 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: 'e2e', cmd: ['bun', 'run', 'e2e'], deps: ['lint'] }],
+    social: ['x', 'discord'],  // .shipkit/social/<channel>/ post folders (+ .shipkit/discord/)
 })
 ```
 
-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).
+Everything the gate runs beyond the floor is a CHECK, and a check needs no config at all: drop a `<name>.check.ts` file anywhere and `shipkit ci`, `shipkit check`, `shipkit checks` and the hub discover it.
+
+```ts
+// e2e.check.ts
+import { check } from 'rvlib-shipkit/src/check.ts'
+export default check({
+    description: 'the end to end suite passes against a built app',
+    blocking: true,
+    build: true,
+    cmd: ['bun', 'run', 'e2e'],
+    deps: ['lint'],
+})
+```
 
 ## CLI
 
@@ -27,17 +38,18 @@ Health checks need no config at all: drop a `<name>.check.ts` file anywhere and
 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
+                  + your checks, parallel DAG; refreshes STATUS.md
                   [--bail --skip g --only id --json]
 shipkit contracts release-contract fulfillness alone       [--venue v --json]
-shipkit check     periodic health: built-in SK rules + every *.check.ts in
+shipkit check     periodic health: the built-in checks + every *.check.ts in
                   the repo, auto-discovered + TTL-cached
                   [--json --fresh --frozen --fix [SK### …]]
-                  --fix applies rule autofixes then re-lints; --frozen =
-                  self-maintaining rules (rvlib self-update) report only
-shipkit rules     the SK rule catalog: id, what it lints, owning doc,
-                  fixable?                                          [--json]
-shipkit tui       live dashboard: ci tasks + discovered checks + panels
+                  --fix applies check autofixes then re-runs them; --frozen =
+                  self-maintaining checks (rvlib self-update) report only
+shipkit checks    the inventory: every check, where it runs, blocks or warns,
+                  and how it caches. --fixable = what repairs itself,
+                  with its owning doc                     [--json --md --out]
+shipkit tui       live dashboard: build steps + every other check + panels
                   the repo injects via repo.config tui.panels
 shipkit asks      human action queue: list · ask "<title>" · asks check (auto-close)
 shipkit needs     everything blocked on a human, red/yellow by collection
@@ -45,7 +57,7 @@ shipkit needs     everything blocked on a human, red/yellow by collection
 shipkit wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
 shipkit mv        rename an md page + its sibling dir, sweeping every ref
 shipkit assets    serve|fill|add|gen|identity|check — the asset atelier
-                  (declare kinds in .rv-assets/kit.ts, roll, curate, ship)
+                  (declare kinds in .shipkit/assets/kit.ts, roll, curate, ship)
 shipkit pb        collection <name> — scaffold a PocketBase collection's UI
                   folder (columns/card/grid/form/index) from the app's
                   generated pb types, create-only          [--dry-run]
@@ -55,7 +67,7 @@ shipkit smoke     browser pass over a DEPLOYED web app, read only: login
                   quota headers, a detail page per `open` link. Exit code =
                   failed routes. Needs playwright in the repo
                                           [--base <url> --routes /a,/b]
-shipkit serve     the repo's ONE server: hub page, graphs, studio, status
+shipkit serve     the repo's ONE server: hub page, wikis, studio, status
 shipkit reflect   your prompts across every Claude Code session of a repo:
                   all config roots, queued-mid-run ones included, harness
                   noise out, chronological md corpus for a retrospective
@@ -75,6 +87,6 @@ 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`, and the assets surface (`defineKit`/`defineKind`, `identityKinds`, `studioRoutes`, `saveEndpoint` via `rvlib-shipkit/vite`). Ships TypeScript source. Bun ≥ 1.0.
+Everything the CLI does is importable: `runChecks`, `evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`, and the assets surface (`defineKit`/`defineKind`, `identityKinds`, `studioRoutes`, `saveEndpoint` via `rvlib-shipkit/vite`). Ships TypeScript source. Bun ≥ 1.0.
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.38.1",
+    "version": "1.0.0",
     "funding": "https://github.com/sponsors/rvion",
     "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",
@@ -35,7 +35,7 @@
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",
-        "comfy-ts": "^2.4.2",
+        "comfy-ts": "^2.9.0",
         "ink": "^7.1.1",
         "marked": "^18.0.7",
         "mobx": "^7.0.0",

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

@@ -96,15 +96,22 @@ export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown
     }
 }
 
-// ── per-asset drafts — comfy-ts disk format, path rule taken from the
-// ComfyTS instance so it cannot drift: .comfy-ts/drafts/<wfId>/<assetId>.json.
+// ── drafts — comfy-ts disk format, path rule taken from the ComfyTS instance
+// so it cannot drift: .comfy-ts/drafts/<wfId>/<draftId>.json.
+//
+// The draft id is the KIND, never the asset: ONE `creature` draft behind all
+// 107 creatures, so tuning the loras once tunes them for the whole kind. The
+// draft is the BASE and the asset's own prompt is injected ON TOP of it at run
+// time, so a prompt left sitting in a draft can never reach an asset, and
+// playing with a draft cannot break the assets that share it.
+//
 // Shipkit does its own IO here because comfy-ts exports no drafts API yet;
 // swap when it lands.
 const draftDir = (lw: LoadedWorkflow): string => ComfyTS.create().resolveFromDrafts(lw.id)
 export const draftPath = (lw: LoadedWorkflow, name: string): string => join(draftDir(lw), `${name}.json`)
 
-export function readAssetDraft(lw: LoadedWorkflow, assetId: string): Record<string, unknown> | null {
-    const p = draftPath(lw, assetId)
+export function readAssetDraft(lw: LoadedWorkflow, draftId: string): Record<string, unknown> | null {
+    const p = draftPath(lw, draftId)
     if (!existsSync(p)) return null
     try {
         return JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>
@@ -116,8 +123,8 @@ export function readAssetDraft(lw: LoadedWorkflow, assetId: string): Record<stri
 /** Seed `{ prompt }` ONLY when the draft is absent (hand-tuned state is never
  *  overwritten). The stored prompt is TUI context; generation overrides it.
  *  Returns true when just seeded. */
-export function ensureAssetDraft(lw: LoadedWorkflow, assetId: string, prompt: string): boolean {
-    const p = draftPath(lw, assetId)
+export function ensureAssetDraft(lw: LoadedWorkflow, draftId: string, prompt: string): boolean {
+    const p = draftPath(lw, draftId)
     if (existsSync(p)) return false
     mkdirSync(draftDir(lw), { recursive: true })
     writeFileSync(p, JSON.stringify({ prompt }, null, 2) + '\n')
@@ -133,22 +140,32 @@ export function ensureAssetDraft(lw: LoadedWorkflow, assetId: string, prompt: st
 export async function generateComfyTs(
     rt: ComfyTsRuntime,
     lw: LoadedWorkflow,
-    args: { prompt: string; seed: number; assetId: string; destDir: string; name: string; vars?: Record<string, unknown>; onProgress?: OnProgress },
+    args: { prompt: string; seed: number; assetId: string; draftId?: string; destDir: string; name: string; vars?: Record<string, unknown>; onProgress?: OnProgress },
 ): Promise<string[]> {
-    ensureAssetDraft(lw, args.assetId, args.prompt)
+    // the KIND's shared draft, falling back to the asset for a caller that
+    // names no kind. It is what the tune button edits
+    const draftId = args.draftId ?? args.assetId
+    ensureAssetDraft(lw, draftId, args.prompt)
     const defs = varsOf(lw.wf)
     // modules are import-cached: a previous asset's values must not leak
     for (const [, varDef] of lw.wf.entries()) varDef.reset()
     if (args.vars != null) applyVarValues(lw.wf, args.vars, `asset '${args.assetId}' kit vars`)
-    const draft = readAssetDraft(lw, args.assetId)
+    const draft = readAssetDraft(lw, draftId)
     if (draft != null) {
         for (const [key, value] of Object.entries(draft)) {
             const varDef = defs[key]
-            if (varDef == null) { console.log(`WARN draft '${args.assetId}': stale var '${key}' not on workflow '${lw.id}' — ignored`); continue }
+            if (varDef == null) { console.log(`WARN draft '${draftId}': stale var '${key}' not on workflow '${lw.id}' — ignored`); continue }
             varDef.loadJSON(value)
         }
     }
+    // LAST, and unconditionally, the three the KIT owns go ON TOP of the shared
+    // draft: the asset's prompt, the kind's declared size, and the roll's seed.
+    // Everything else (loras, steps, cfg, removeBg) is the draft's to own. Size
+    // is here because the kind ships its rolls into a fixed box, so a size tried
+    // in the panel must not silently resize every asset that shares the draft
     defs.prompt!.parse(args.prompt)
+    const kitSize = (args.vars ?? {})['size']
+    if (kitSize != null) defs['size']?.loadJSON(kitSize)
     // '= N' pins mode AND value, neutralizing any ?/+ mode a draft restored,
     // so the v<seed> file name stays truthful
     defs.seed!.parse(`= ${args.seed}`)

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

@@ -45,7 +45,7 @@ export async function generateRoll(
     }
     const rt = await resolveComfy()
     const lw = workflowFor(rt.workflows, { workflow: gen.workflow, assetId: found.asset.id })
-    await generateComfyTs(rt, lw, { prompt: args.prompt, seed: args.seed, assetId: found.asset.id, destDir: args.destDir, name: `v${args.seed}`, vars: gen.vars, onProgress: args.onProgress })
+    await generateComfyTs(rt, lw, { prompt: args.prompt, seed: args.seed, assetId: found.asset.id, draftId: found.kind.id, destDir: args.destDir, name: `v${args.seed}`, vars: gen.vars, onProgress: args.onProgress })
 }
 
 /** Memoized lazy comfy runtime for a resolved kit — loads the cflow modules on

package/src/assets/kit-config.ts

@@ -1,4 +1,4 @@
-// defineKit — the repo-side surface: .rv-assets/kit.ts declares asset kinds,
+// defineKit — the repo-side surface: .shipkit/assets/kit.ts declares asset kinds,
 // generators, ship targets and metadata panels; the studio/CLI derive
 // everything else. STRUCTURE lives here (git-reviewed TS); studio-edited
 // state lives in the workspace overlays (pick.json, prompt.json, *.rect.json).
@@ -64,7 +64,7 @@ export type CustomPanelSpec = {
     panel: 'custom'
     /** url-safe kebab-case, unique per kind — becomes the served module name */
     id: string
-    /** repo-root-relative ES module path (e.g. .rv-assets/panels/legs-editor.js) */
+    /** repo-root-relative ES module path (e.g. .shipkit/assets/panels/legs-editor.js) */
     script: string
     /** default corner of the floating card on the canvas (drag overrides) */
     anchor?: 'tl' | 'bl'
@@ -113,7 +113,7 @@ export type Kind = {
     media?: Media
     /** icon kinds get no geometry, thumbnails only */
     mode?: 'sprite' | 'icon'
-    /** via = repo hook module path (default .rv-assets/ship.ts) · fn = a
+    /** via = repo hook module path (default .shipkit/assets/ship.ts) · fn = a
      *  built-in lib hook (e.g. identityKinds re-rendering the set) — never
      *  both. With NO hook, `dir` alone is the zero-config ship: the picked
      *  roll is copied to <dir>/<assetId>.<ext>; hooks read dir as data. */
@@ -224,14 +224,14 @@ export function missingPanelScripts(kit: KitConfig, root: string): string[] {
 export function defineKit(k: KitConfig): ResolvedKit {
     const errs = validateKit(k)
     if (errs.length > 0) throw new Error(`invalid kit:\n  ${errs.join('\n  ')}`)
-    return { ...k, workspace: k.workspace ?? '.rv-assets/out' }
+    return { ...k, workspace: k.workspace ?? '.shipkit/assets/out' }
 }
 
 export const defineKind = (k: Kind): Kind => k
 
 export async function loadKit(root: string): Promise<ResolvedKit> {
-    const path = join(root, '.rv-assets/kit.ts')
-    if (!existsSync(path)) throw new Error(`no .rv-assets/kit.ts in ${root} — create one (defineKit) or run the init snippet from the docs`)
+    const path = join(root, '.shipkit/assets/kit.ts')
+    if (!existsSync(path)) throw new Error(`no .shipkit/assets/kit.ts in ${root} — create one (defineKit) or run the init snippet from the docs`)
     const mod = (await import(path)) as { default?: ResolvedKit }
     if (mod.default == null) throw new Error(`${path}: must default-export defineKit({...})`)
     const missing = missingPanelScripts(mod.default, root)

package/src/assets/run-assets.ts

@@ -107,19 +107,19 @@ export const runAssetsGen = (root: string, io: AssetsIo, o: { assetId: string; n
 // ── identity: ONE render path + a brand.ts content hash so drift is
 // machine-detectable — and machine-CLEARED (auto re-render), never a nag.
 // Only a missing PICK still asks a human (taste).
-const brandHashPath = (root: string): string => join(root, '.rv-identity/brand.hash')
+const brandHashPath = (root: string): string => join(root, '.shipkit/identity/brand.hash')
 const brandHash = async (root: string): Promise<string> =>
-    new Bun.CryptoHasher('sha256').update(await Bun.file(join(root, '.rv-identity/brand.ts')).text()).digest('hex').slice(0, 16)
+    new Bun.CryptoHasher('sha256').update(await Bun.file(join(root, '.shipkit/identity/brand.ts')).text()).digest('hex').slice(0, 16)
 
 export type IdentityRender = { written: string[] } | { blocked: string }
 
 export async function renderIdentityNow(root: string): Promise<IdentityRender> {
-    const brandPath = join(root, '.rv-identity/brand.ts')
-    if (!existsSync(brandPath)) return { blocked: 'no .rv-identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    const brandPath = join(root, '.shipkit/identity/brand.ts')
+    if (!existsSync(brandPath)) return { blocked: 'no .shipkit/identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
     // cache-bust: bun caches dynamic imports for the process lifetime — a
     // long-running hub must re-render the EDITED brand, not the cached one
     const mod = (await import(`${brandPath}?v=${await brandHash(root)}`)) as { default?: Brand }
-    if (mod.default == null) return { blocked: '.rv-identity/brand.ts must default-export the Brand' }
+    if (mod.default == null) return { blocked: '.shipkit/identity/brand.ts must default-export the Brand' }
     const brand = mod.default
     let markFile: string | undefined
     if (brand.mark.backend === 'comfy') {
@@ -141,7 +141,7 @@ export async function renderIdentityNow(root: string): Promise<IdentityRender> {
 /** brand.ts drifted since the last render → re-render NOW (autonomous).
  *  Returns what happened; 'blocked' = only a human pick can clear it. */
 export async function healIdentity(root: string): Promise<{ state: 'fresh' | 'rendered' | 'blocked' | 'absent'; detail?: string }> {
-    if (!existsSync(join(root, '.rv-identity/brand.ts'))) return { state: 'absent' }
+    if (!existsSync(join(root, '.shipkit/identity/brand.ts'))) return { state: 'absent' }
     const outputsMissing = ['public/favicon.png', 'public/og.png', 'public/logo.png'].some((p) => !existsSync(join(root, p)))
     const stored = existsSync(brandHashPath(root)) ? (await Bun.file(brandHashPath(root)).text()).trim() : null
     if (!outputsMissing && stored === (await brandHash(root))) return { state: 'fresh' }
@@ -197,10 +197,11 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
                         bad++
                     }
                 }
-                // one draft per comfy asset — the TUI's tweakable entry.
-                // ONE aggregate line: per-asset rows would drown the check
+                // one draft per comfy KIND, shared by its assets — the tweakable
+                // entry. ONE aggregate line: per-asset rows would drown the check
                 let draftCount = 0
                 let draftSeeded = 0
+                const draftKinds = new Set<string>()
                 for (const f of allAssets(kit).filter((x) => x.kind.generate.backend === 'comfy')) {
                     let lw: LoadedWorkflow
                     try {
@@ -209,10 +210,13 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
                         continue // an unresolvable workflow already FAILed on its kind above
                     }
                     const prompt = (await readPromptOverlay(assetDir(join(root, kit.workspace), f.asset.id))).prompt ?? f.asset.prompt
-                    if (ensureAssetDraft(lw, f.asset.id, prompt)) draftSeeded++
+                    // the first asset of a kind seeds it and the rest share it, so
+                    // a lora tuned once holds for every asset of that kind
+                    if (ensureAssetDraft(lw, f.kind.id, prompt)) draftSeeded++
+                    draftKinds.add(`${lw.id}/${f.kind.id}`)
                     draftCount++
                 }
-                if (draftCount > 0) io.print(`ok: drafts ensured for ${draftCount} comfy asset(s) in .comfy-ts/drafts/${draftSeeded > 0 ? ` (${draftSeeded} seeded now)` : ''}`)
+                if (draftCount > 0) io.print(`ok: ${draftKinds.size} draft(s) behind ${draftCount} comfy asset(s) in .comfy-ts/drafts/${draftSeeded > 0 ? ` (${draftSeeded} seeded now)` : ''}`)
                 // offline graph validation when the host has a schema cache;
                 // a missing cache is world state → WARN, never a repo FAIL
                 const hostsWarned = new Set<string>()

package/src/assets/server/studio-server.ts

@@ -83,10 +83,10 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         let ship: AssetInfo['ship']
         if (f.kind.ship?.fn != null) ship = { mode: 'built-in', note: 're-renders the set on pick' }
         else {
-            const via = f.kind.ship?.via ?? '.rv-assets/ship.ts'
+            const via = f.kind.ship?.via ?? '.shipkit/assets/ship.ts'
             ship = existsSync(join(root, via)) ? { mode: 'hook', path: via } : { mode: 'record', note: 'pick.json only — no ship hook' }
         }
-        return { backend, deterministic: backend === 'canvas', workflow, ship, metaFile: f.kind.meta?.file ?? null, kindId: f.kind.id, kitSource: '.rv-assets/kit.ts' }
+        return { backend, deterministic: backend === 'canvas', workflow, ship, metaFile: f.kind.meta?.file ?? null, kindId: f.kind.id, kitSource: '.shipkit/assets/kit.ts' }
     }
 
     // effective prompt: workspace overlay wins over the kit's builder output
@@ -100,7 +100,8 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
             try {
                 const gen = f.kind.generate as { workflow?: string }
                 const lw = workflowFor(workflows, { workflow: gen.workflow, assetId: f.asset.id })
-                if (ensureAssetDraft(lw, f.asset.id, await promptOf(f))) console.log(`ok: draft '${f.asset.id}' seeded → .comfy-ts/drafts/${lw.id}/${f.asset.id}.json`)
+                // the KIND's draft, shared by every asset of that kind
+                if (ensureAssetDraft(lw, f.kind.id, await promptOf(f))) console.log(`ok: draft '${f.kind.id}' seeded → .comfy-ts/drafts/${lw.id}/${f.kind.id}.json`)
             } catch (e) {
                 console.log(`WARN draft for '${f.asset.id}' not seeded — ${(e as Error).message}`)
             }
@@ -176,12 +177,12 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
 
     // ── ship hooks: a kind's BUILT-IN ship.fn (e.g. identityKinds re-rendering
     // the set from the pick) wins; otherwise the repo module is probed once
-    // PER PATH (ship.via, default .rv-assets/ship.ts; fixing a hook needs a
+    // PER PATH (ship.via, default .shipkit/assets/ship.ts; fixing a hook needs a
     // studio restart) ───────────────────────────────────────────────────────
     const shipFns = new Map<string, ShipFn | null>()
     const resolveShipFn = async (f: FoundAsset): Promise<ShipFn | null> => {
         if (f.kind.ship?.fn != null) return f.kind.ship.fn
-        const shipPath = join(root, f.kind.ship?.via ?? '.rv-assets/ship.ts')
+        const shipPath = join(root, f.kind.ship?.via ?? '.shipkit/assets/ship.ts')
         let fn = shipFns.get(shipPath)
         if (fn === undefined) {
             if (existsSync(shipPath)) {