rvlib-shipkit 0.1.0 → 0.2.0

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

@@ -0,0 +1,360 @@
+// The studio HTTP server — roll variants, compare, pick, geometry metadata,
+// category grid data. 127.0.0.1 ONLY, forever. Never run with --watch: the
+// queue is in-memory (fill is the recovery path).
+//
+// ids/names are validated against the kit + the roll-file regex — no path
+// from the client ever reaches the filesystem unchecked.
+import { existsSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { findAsset, allAssets, missingPanelScripts, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit } from '../kit-config.ts'
+import { randomSeed } from '../gen/comfy-gen.ts'
+import { generateRoll, type ComfyRuntime } from '../gen/generate-roll.ts'
+import { loadWorkflows, type Workflow } from '../gen/workflow-loader.ts'
+import { alphaHeight, toPng } from '../image-ops.ts'
+import { readJson, updateJson } from '../json-store.ts'
+import { assetDir, isRollFile, listRolls, metaPath, readPick, readPromptOverlay, updatePick, updatePromptOverlay } from '../roll-workspace.ts'
+import { cleanRect, defaultLegs as legDefaults, liveRect, type GroundRect } from '../panels/geometry-rects.ts'
+import { StudioQueue } from './studio-queue.ts'
+
+export type StudioDeps = {
+    kit: ResolvedKit
+    root: string
+    page: () => string
+    /** test seam — defaults to the comfy engine */
+    generateOne?: (found: FoundAsset, prompt: string, seed: number, destDir: string) => Promise<void>
+}
+
+export type Studio = { server: ReturnType<typeof Bun.serve>; queue: StudioQueue; stop: () => void }
+
+type ShipCtx = {
+    assetId: string
+    file: string
+    asset: FoundAsset['asset']
+    kind: FoundAsset['kind']
+    meta: unknown
+    rect: GroundRect | null
+    projectRoot: string
+    img: { toPng: typeof toPng; alphaHeight: typeof alphaHeight }
+}
+type ShipFn = (ctx: ShipCtx) => Promise<string | void>
+
+export async function serveStudio(deps: StudioDeps): Promise<Studio> {
+    const { kit, root } = deps
+    const workspace = join(root, kit.workspace)
+    const dirOf = (id: string): string => assetDir(workspace, id)
+    let workflows: Map<string, Workflow> | null = null
+    if (kit.comfy != null) workflows = await loadWorkflows(join(root, kit.comfy.workflows))
+
+    // custom panel scripts fail-fast here too (tests/embedders may bypass loadKit)
+    const missingPanels = missingPanelScripts(kit, root)
+    if (missingPanels.length > 0) throw new Error(`custom panel scripts missing — create them or fix the kit:\n  ${missingPanels.join('\n  ')}`)
+
+    const geometryOf = (f: FoundAsset): GeometryPanelSpec | null =>
+        (f.kind.meta?.panels?.find((p) => p.panel === 'geometry') as GeometryPanelSpec | undefined) ?? null
+    const customPanelsOf = (f: FoundAsset): CustomPanelSpec[] =>
+        (f.kind.meta?.panels ?? []).filter((p): p is CustomPanelSpec => p.panel === 'custom')
+
+    // effective prompt: workspace overlay wins over the kit's builder output
+    const promptOf = async (f: FoundAsset): Promise<string> =>
+        (await readPromptOverlay(dirOf(f.asset.id))).prompt ?? f.asset.prompt
+
+    // workflows are pre-loaded above (fail-fast for a comfy studio); the
+    // resolver just hands the shared roll generator the ready runtime.
+    const resolveComfy = async (): Promise<ComfyRuntime> => {
+        if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
+        return { workflows, host: kit.comfy.host, heal: kit.comfy.heal }
+    }
+    const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir) =>
+        generateRoll(found, { prompt, seed, destDir }, resolveComfy))
+
+    const queue = new StudioQueue(async (job, seed) => {
+        const found = findAsset(kit, job.assetId)
+        if (found == null) throw new Error(`asset '${job.assetId}' not in the kit — job dropped`)
+        await generateOne(found, job.prompt, seed, dirOf(job.assetId))
+    }, randomSeed)
+
+    // ── session/live rect plumbing ─────────────────────────────────────────
+    const rectPath = (id: string, roll: string): string => join(dirOf(id), `${roll}.rect.json`)
+    const sessionRect = async (f: FoundAsset, roll: string): Promise<GroundRect> => {
+        const g = geometryOf(f)!
+        const raw = await readJson<Record<string, unknown> | null>(rectPath(f.asset.id, roll), null)
+        if (raw != null) return cleanRect(raw, g.ratio)
+        const size = g.sizeByCategory?.[f.kind.category] ?? g.defaultOval.size
+        return cleanRect({ ...g.defaultOval, size }, g.ratio)
+    }
+    const writeThrough = async (f: FoundAsset, rect: GroundRect): Promise<string[]> => {
+        const errs = f.kind.meta?.validate?.(rect) ?? []
+        if (errs.length > 0) return errs
+        if (f.kind.meta?.file != null) {
+            const target = join(root, f.kind.meta.file)
+            await updateJson<{ rects: Record<string, GroundRect> }>(target, { rects: {} }, (d) => {
+                d.rects[f.asset.id] = liveRect(rect)
+            })
+        }
+        return []
+    }
+    const saveRect = async (f: FoundAsset, roll: string, raw: Record<string, unknown>): Promise<{ rect: GroundRect } | { errors: string[] }> => {
+        const g = geometryOf(f)
+        if (g == null) return { errors: [`kind '${f.kind.id}' has no geometry panel`] }
+        const rect = cleanRect(raw, g.ratio)
+        const img = join(dirOf(f.asset.id), roll)
+        if (existsSync(img)) rect.art = await alphaHeight(img) // measure on EVERY save
+        await Bun.write(rectPath(f.asset.id, roll), JSON.stringify(rect, null, 2) + '\n')
+        const errs = await writeThrough(f, rect)
+        return errs.length > 0 ? { errors: errs } : { rect }
+    }
+
+    // ── ship hooks (probed once PER PATH — kinds may point at different
+    // hooks via ship.via; fixing a hook needs a studio restart) ────────────
+    const shipFns = new Map<string, ShipFn | null>()
+    const ship = async (f: FoundAsset, roll: string): Promise<{ shipped: string | null }> => {
+        const shipPath = join(root, f.kind.ship?.via ?? '.rv-assets/ship.ts')
+        let fn = shipFns.get(shipPath)
+        if (fn === undefined) {
+            if (existsSync(shipPath)) {
+                const mod = (await import(shipPath)) as { ship?: ShipFn; default?: ShipFn }
+                fn = mod.ship ?? mod.default ?? undefined // undefined on bad exports: EVERY pick keeps erroring loudly, never silently downgrades to record-only
+                if (fn == null) throw new Error(`${shipPath} exists but exports neither \`ship\` nor a default function — fix it and RESTART the studio (imports are cached)`)
+            } else fn = null
+            shipFns.set(shipPath, fn)
+        }
+        if (fn == null) return { shipped: null } // no hook: pick.json is the record
+        const dir = dirOf(f.asset.id)
+        const g = geometryOf(f)
+        const dest = await fn({
+            assetId: f.asset.id,
+            file: join(dir, roll),
+            asset: f.asset,
+            kind: f.kind,
+            meta: await readJson(metaPath(dir, roll), null),
+            rect: g != null ? await sessionRect(f, roll) : null,
+            projectRoot: root,
+            img: { toPng, alphaHeight },
+        })
+        return { shipped: dest ?? 'shipped' }
+    }
+
+    // ── http ────────────────────────────────────────────────────────────────
+    const json = (data: unknown, status = 200): Response => Response.json(data, { status })
+    const bad = (msg: string): Response => json({ error: msg }, 400)
+    const safeRoll = (name: unknown): string | null => (typeof name === 'string' && isRollFile(name) ? name : null)
+
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: kit.port,
+        async fetch(req) {
+            const url = new URL(req.url)
+            const q = (k: string): string => url.searchParams.get(k) ?? ''
+            const body = async (): Promise<Record<string, unknown>> => (await req.json().catch(() => ({}))) as Record<string, unknown>
+
+            if (url.pathname === '/') return new Response(deps.page(), { headers: { 'Content-Type': 'text/html; charset=utf-8' } })
+
+            if (url.pathname === '/api/state') {
+                const assets = await Promise.all(allAssets(kit).map(async (f) => {
+                    const dir = dirOf(f.asset.id)
+                    const pick = await readPick(dir)
+                    return {
+                        id: f.asset.id, cat: f.kind.category, label: f.asset.label ?? f.asset.id,
+                        prompt: await promptOf(f), rolls: listRolls(dir).length, picked: pick.pick != null,
+                        icon: f.kind.mode === 'icon',
+                    }
+                }))
+                return json({ ...queue.state, queued: queue.queuedCount, errors: queue.errors.slice(-5), assets })
+            }
+
+            if (url.pathname === '/api/asset') {
+                const f = findAsset(kit, q('id'))
+                if (f == null) return bad(`unknown asset '${q('id')}'`)
+                const dir = dirOf(f.asset.id)
+                const pick = await readPick(dir)
+                const rolls = listRolls(dir).map((name) => ({ name, picked: name === pick.pick, alt: pick.alts.includes(name), hasMeta: existsSync(metaPath(dir, name)) }))
+                const custom = customPanelsOf(f).map((p) => ({ id: p.id, kind: f.kind.id, url: `/panel/${encodeURIComponent(f.kind.id)}/${encodeURIComponent(p.id)}.js` }))
+                return json({ asset: { ...f.asset, prompt: await promptOf(f), cat: f.kind.category, geometry: geometryOf(f) != null, custom }, rolls, pick })
+            }
+
+            if (url.pathname.startsWith('/panel/')) {
+                // repo-defined editor module; ids resolved against the kit — the
+                // URL never reaches the filesystem directly
+                const m = url.pathname.match(/^\/panel\/([^/]+)\/([^/]+)\.js$/)
+                const kind = m == null ? null : (kit.kinds.find((k) => k.id === decodeURIComponent(m[1]!)) ?? null)
+                const spec = kind?.meta?.panels?.find((p): p is CustomPanelSpec => p.panel === 'custom' && p.id === decodeURIComponent(m![2]!))
+                if (spec == null) return new Response('', { status: 404 })
+                const file = Bun.file(join(root, spec.script))
+                if (!(await file.exists())) return new Response(`// ${spec.script} vanished after studio boot — restore it`, { status: 404 })
+                return new Response(file, { headers: { 'Content-Type': 'text/javascript; charset=utf-8' } })
+            }
+
+            if (url.pathname === '/img') {
+                const name = safeRoll(q('name'))
+                const f = findAsset(kit, q('id'))
+                if (f == null || name == null) return new Response('', { status: 404 })
+                const file = Bun.file(join(dirOf(f.asset.id), name))
+                return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
+            }
+
+            if (url.pathname === '/api/thumb') {
+                const f = findAsset(kit, q('id'))
+                if (f == null) return new Response('', { status: 404 })
+                const dir = dirOf(f.asset.id)
+                const pick = await readPick(dir)
+                const name = pick.pick ?? listRolls(dir)[0]
+                if (name == null) return new Response('', { status: 404 })
+                const file = Bun.file(join(dir, name))
+                return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
+            }
+
+            if (url.pathname === '/api/rect' && req.method === 'GET') {
+                const f = findAsset(kit, q('id'))
+                const name = safeRoll(q('name'))
+                if (f == null || name == null) return bad('bad id/name')
+                if (geometryOf(f) == null) return bad(`kind '${f.kind.id}' has no geometry panel`)
+                return json({ rect: await sessionRect(f, name) })
+            }
+
+            if (url.pathname === '/api/catrects') {
+                const rows = []
+                for (const f of allAssets(kit).filter((x) => x.kind.category === q('cat'))) {
+                    const dir = dirOf(f.asset.id)
+                    const rolls = listRolls(dir)
+                    if (rolls.length === 0) continue
+                    const pick = await readPick(dir)
+                    const name = pick.pick ?? rolls[0]!
+                    const icon = f.kind.mode === 'icon'
+                    let rect: GroundRect | null = null
+                    if (!icon && geometryOf(f) != null) {
+                        rect = await sessionRect(f, name)
+                        if (f.kind.meta?.artNormalized === true && rect.art == null) {
+                            const img = join(dir, name)
+                            if (existsSync(img)) rect.art = await alphaHeight(img)
+                        }
+                    }
+                    rows.push({ id: f.asset.id, label: f.asset.label ?? f.asset.id, name, rect, prop: f.kind.meta?.artNormalized === true, icon })
+                }
+                return json({ rows })
+            }
+
+            if (req.method !== 'POST') return new Response('', { status: 404 })
+            const b = await body()
+
+            if (url.pathname === '/api/generate') {
+                const f = findAsset(kit, String(b.id))
+                if (f == null) return bad(`unknown asset '${String(b.id)}'`)
+                const count = Math.max(1, Math.min(24, Number(b.count) || 1))
+                const prompt = typeof b.prompt === 'string' && b.prompt.trim() !== '' ? b.prompt : await promptOf(f)
+                queue.enqueue([{ assetId: f.asset.id, prompt, count }])
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/generate-cat') {
+                const hit = allAssets(kit).filter((f) => f.kind.category === b.cat)
+                if (hit.length === 0) return bad(`no assets in cat '${String(b.cat)}'`)
+                const count = Math.max(1, Math.min(6, Number(b.count) || 1))
+                queue.enqueue(await Promise.all(hit.map(async (f) => ({ assetId: f.asset.id, prompt: await promptOf(f), count }))))
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/queue/clear') {
+                queue.clear()
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/pick') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                const dir = dirOf(f.asset.id)
+                try {
+                    const res = await ship(f, name)
+                    await updatePick(dir, (s) => {
+                        s.pick = name
+                        s.shippedAt = res.shipped != null ? new Date().toISOString() : s.shippedAt
+                    })
+                    return json(res)
+                } catch (e) {
+                    queue.pushError(`ship ${String(b.id)}: ${(e as Error).message}`)
+                    return json({ error: (e as Error).message }, 500)
+                }
+            }
+            if (url.pathname === '/api/alt') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                await updatePick(dirOf(f.asset.id), (s) => {
+                    s.alts = s.alts.includes(name) ? s.alts.filter((a) => a !== name) : [...s.alts, name]
+                })
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/discard') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                const dir = dirOf(f.asset.id)
+                for (const path of [join(dir, name), metaPath(dir, name), rectPath(f.asset.id, name)]) if (existsSync(path)) unlinkSync(path)
+                await updatePick(dir, (s) => {
+                    if (s.pick === name) s.pick = null
+                    s.alts = s.alts.filter((a) => a !== name)
+                })
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/prompt') {
+                if (typeof b.prompt !== 'string') return bad('prompt must be a string')
+                const f = findAsset(kit, String(b.id))
+                if (f == null) return bad(`unknown asset '${String(b.id)}'`)
+                // structure is git-reviewed TS; the studio edits the OVERLAY
+                await updatePromptOverlay(dirOf(f.asset.id), (s) => { s.prompt = (b.prompt as string) === f.asset.prompt ? null : (b.prompt as string) })
+                return json({ ok: true })
+            }
+            if (url.pathname === '/api/rect') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                if (typeof b.rect !== 'object' || b.rect == null) return bad('rect must be an object')
+                const res = await saveRect(f, name, b.rect as Record<string, unknown>)
+                return 'errors' in res ? bad(res.errors.join('; ')) : json({ ok: true, rect: res.rect })
+            }
+            if (url.pathname === '/api/legs-default') {
+                // legs derived server-side so the SPA never duplicates the constants
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                if (geometryOf(f) == null) return bad(`kind '${f.kind.id}' has no geometry panel`)
+                const current = await sessionRect(f, name)
+                if (current.legs == null) {
+                    current.legs = legDefaults(current)
+                    current.legColor ??= '#c8a070'
+                    const res = await saveRect(f, name, current as unknown as Record<string, unknown>)
+                    if ('errors' in res) return bad(res.errors.join('; '))
+                    return json({ ok: true, rect: res.rect })
+                }
+                return json({ ok: true, rect: current }) // non-destructive: existing legs never replaced
+            }
+            if (url.pathname === '/api/flip') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                const current = await sessionRect(f, name)
+                const flipped = { ...current, flip: current.flip === true ? undefined : true } as unknown as Record<string, unknown>
+                const res = await saveRect(f, name, flipped)
+                if ('errors' in res) return bad(res.errors.join('; '))
+                // flipping the CURRENT pick re-ships mirrored pixels
+                const pick = await readPick(dirOf(f.asset.id))
+                if (pick.pick === name) await ship(f, name).catch((e: Error) => queue.pushError(`re-ship ${f.asset.id}: ${e.message}`))
+                return json({ ok: true, flip: res.rect.flip === true })
+            }
+            if (url.pathname === '/api/meta') {
+                const name = safeRoll(b.name)
+                const f = findAsset(kit, String(b.id))
+                if (name == null || f == null) return bad('bad id/name')
+                const path = metaPath(dirOf(f.asset.id), name)
+                if (b.text === undefined) return json({ text: existsSync(path) ? await Bun.file(path).text() : '' })
+                try {
+                    const parsed: unknown = JSON.parse(String(b.text))
+                    await Bun.write(path, JSON.stringify(parsed, null, 2) + '\n') // meta sidecars have a single writer (this route)
+                    return json({ ok: true })
+                } catch (e) {
+                    return bad(`not valid JSON: ${(e as Error).message}`)
+                }
+            }
+            return new Response('', { status: 404 })
+        },
+    })
+
+    return { server, queue, stop: () => server.stop(true) }
+}

package/src/assets/vite.ts

@@ -0,0 +1,62 @@
+// Vite save-endpoint factory — the declarative form of the hand-rolled
+// dev-only middleware pattern (editor POSTs → validate → write into src/ →
+// optional registry splice). Serve-only: never active in a build. No vite
+// dependency — the plugin shape is duck-typed.
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+
+type Middleware = (req: { method?: string; url?: string; on: (ev: string, cb: (chunk?: unknown) => void) => void }, res: { statusCode: number; setHeader: (k: string, v: string) => void; end: (body?: string) => void }, next: () => void) => void
+type ViteDevServer = { middlewares: { use: (fn: Middleware) => void } }
+export type VitePluginShape = { name: string; apply: 'serve'; configureServer: (server: ViteDevServer) => void }
+
+export type SaveEndpoint<T> = {
+    /** e.g. '/__map/save' */
+    route: string
+    /** throw or return error strings to reject */
+    validate: (data: unknown) => T | string[]
+    /** produce { path: content } writes from the validated payload */
+    write: (data: T) => Record<string, string>
+    /** optional post-write hook (registry splice, logging) */
+    after?: (data: T, written: string[]) => void
+}
+
+export function saveEndpoint<T>(spec: SaveEndpoint<T>): VitePluginShape {
+    return {
+        name: `atelier-save:${spec.route}`,
+        apply: 'serve',
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                // query strings stripped — connect req.url carries them, the route key never does
+                const path = req.url?.split('?')[0]
+                if (req.method !== 'POST' || path !== spec.route) return next()
+                const chunks: Buffer[] = []
+                req.on('data', (c) => chunks.push(c as Buffer))
+                req.on('end', () => {
+                    void (async () => {
+                        res.setHeader('Content-Type', 'application/json')
+                        try {
+                            const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+                            const validated = spec.validate(parsed)
+                            if (Array.isArray(validated)) {
+                                res.statusCode = 400
+                                res.end(JSON.stringify({ error: validated.join('; ') }))
+                                return
+                            }
+                            const files = spec.write(validated)
+                            for (const [path, content] of Object.entries(files)) {
+                                mkdirSync(dirname(path), { recursive: true })
+                                writeFileSync(path, content)
+                            }
+                            spec.after?.(validated, Object.keys(files))
+                            res.statusCode = 200
+                            res.end(JSON.stringify({ ok: true, written: Object.keys(files) }))
+                        } catch (e) {
+                            res.statusCode = 400
+                            res.end(JSON.stringify({ error: (e as Error).message }))
+                        }
+                    })()
+                })
+            })
+        },
+    }
+}

package/src/cli/cmd_Asks.ts

@@ -0,0 +1,83 @@
+// shipkit asks — the per-repo human queue: `asks` lists, `asks check`
+// probes + archives, `ask "<title>"` creates. Three thin commands over
+// asks/asks-queue.ts (the plain module owns all logic).
+import { join } from 'path'
+import { Command, Option } from 'clipanion'
+import { checkAsks, createAsk, renderAsksTable } from '../asks/asks-queue.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+const asksDir = async (root: string): Promise<string> => join(root, (await loadRepoConfig(root)).asks?.dir ?? 'asks')
+
+export class AsksCommand extends Command {
+    static override paths = [['asks']]
+
+    static override usage = Command.Usage({
+        category: 'Asks',
+        description: 'list open asks — the per-repo human action queue',
+        examples: [['list open asks', 'shipkit asks']],
+    })
+
+    async execute(): Promise<number> {
+        try {
+            const root = process.cwd()
+            const c = await loadRepoConfig(root)
+            renderAsksTable(join(root, c.asks?.dir ?? 'asks'), undefined, { emptyText: c.asks?.emptyText })
+            return 0
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}
+
+export class AsksCheckCommand extends Command {
+    static override paths = [['asks', 'check']]
+
+    static override usage = Command.Usage({
+        category: 'Asks',
+        description: 'probe every open ask and archive the ones whose check now passes',
+        examples: [['probe + auto-close', 'shipkit asks check']],
+    })
+
+    async execute(): Promise<number> {
+        try {
+            checkAsks(await asksDir(process.cwd()))
+            return 0
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}
+
+export class AskNewCommand extends Command {
+    static override paths = [['ask'], ['asks', 'new']]
+
+    static override usage = Command.Usage({
+        category: 'Asks',
+        description: 'create a new ask file in the queue',
+        examples: [
+            ['minimal', 'shipkit ask "rotate the API token"'],
+            ['with a reason', 'shipkit ask "buy the domain" --why "landing page is blocked on it"'],
+            ['with metadata', 'shipkit ask "buy the domain" --kind action --blocks deploy --check "dig +short example.com"'],
+        ],
+    })
+
+    title = Option.String({ required: true })
+    kind = Option.String('--kind', { required: false, description: 'ask kind: action | credential | decision | purchase' })
+    blocks = Option.String('--blocks', { required: false, description: 'what this ask blocks (task id, page, plain words)' })
+    check = Option.String('--check', { required: false, description: 'shell probe that exits 0 once the ask is done (enables auto-close)' })
+    why = Option.String('--why', { required: false, description: 'one line of context — why this is worth his time' })
+
+    async execute(): Promise<number> {
+        try {
+            const dir = await asksDir(process.cwd())
+            const file = createAsk(dir, this.title, { kind: this.kind, blocks: this.blocks, check: this.check, why: this.why })
+            this.context.stdout.write(`created ${dir}/${file}\n`)
+            return 0
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Assets.ts

@@ -0,0 +1,120 @@
+// shipkit assets — asset atelier: declare kinds in .rv-assets/kit.ts, roll
+// (ComfyUI or procedural canvas), curate in the studio, ship with metadata
+// write-through. Thin clipanion surfaces; logic in assets/run-assets.ts.
+import { Command, Option } from 'clipanion'
+import { runAssetsCheck, runAssetsGen, runAssetsIdentity, runAssetsServe, runAssetsTopUp, type AssetsIo } from '../assets/run-assets.ts'
+
+const ioOf = (cmd: Command): AssetsIo => ({
+    print: (l) => cmd.context.stdout.write(`${l}\n`),
+    printErr: (l) => cmd.context.stderr.write(`${l}\n`),
+})
+
+export class AssetsServeCommand extends Command {
+    static override paths = [['assets', 'serve']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'the studio — roll, curate, pick, ship (127.0.0.1, kit port)',
+        examples: [['launch the studio for the cwd kit', 'shipkit assets serve']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsServe(process.cwd(), ioOf(this))
+    }
+}
+
+export class AssetsFillCommand extends Command {
+    static override paths = [['assets', 'fill']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'top rolls up to N per asset (canvas or comfy), sparsest-first',
+        examples: [
+            ['every asset up to 8 rolls', 'shipkit assets fill 8'],
+            ['only two categories', 'shipkit assets fill 8 icons sprites'],
+        ],
+    })
+
+    n = Option.String({ required: true })
+    categories = Option.Rest()
+
+    async execute(): Promise<number> {
+        const n = Number(this.n)
+        if (!Number.isInteger(n) || n <= 0) {
+            this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets fill <N> [category…]\n`)
+            return 1
+        }
+        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
+    }
+}
+
+export class AssetsAddCommand extends Command {
+    static override paths = [['assets', 'add']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'N more rolls per asset (canvas or comfy), regardless of what it has',
+        examples: [['3 fresh rolls everywhere', 'shipkit assets add 3']],
+    })
+
+    n = Option.String({ required: true })
+    categories = Option.Rest()
+
+    async execute(): Promise<number> {
+        const n = Number(this.n)
+        if (!Number.isInteger(n) || n <= 0) {
+            this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets add <N> [category…]\n`)
+            return 1
+        }
+        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
+    }
+}
+
+export class AssetsGenCommand extends Command {
+    static override paths = [['assets', 'gen']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'one-shot rolls for a single asset (canvas or comfy)',
+        examples: [
+            ['one roll', 'shipkit assets gen hero'],
+            ['five rolls', 'shipkit assets gen hero --n 5'],
+        ],
+    })
+
+    assetId = Option.String({ required: true })
+    n = Option.String('--n', '1', { description: 'how many rolls (default 1)' })
+
+    async execute(): Promise<number> {
+        const n = Math.max(1, Number(this.n) || 1)
+        return runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
+    }
+}
+
+export class AssetsIdentityCommand extends Command {
+    static override paths = [['assets', 'identity']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'render favicon/logo/OG from .rv-identity/brand.ts into public/',
+        examples: [['regenerate the identity outputs', 'shipkit assets identity']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsIdentity(process.cwd(), ioOf(this))
+    }
+}
+
+export class AssetsCheckCommand extends Command {
+    static override paths = [['assets', 'check']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'kit loads, kinds valid, workflows bound, backend reachable, identity outputs present',
+        examples: [['health-check the asset pipeline', 'shipkit assets check']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsCheck(process.cwd(), ioOf(this))
+    }
+}

package/src/cli/cmd_Check.ts

@@ -0,0 +1,30 @@
+// shipkit check — periodic health, TTL-cached. Thin clipanion surface;
+// logic in core/run-check.ts.
+import { Command, Option } from 'clipanion'
+import { runCheck } from '../core/run-check.ts'
+
+export class CheckCommand extends Command {
+    static override paths = [['check']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'periodic health: contracts + every *.check.ts in the repo (auto-discovered, run as subprocesses), clean passes replay from a TTL cache',
+        examples: [
+            ['run (cached where valid)', 'shipkit check'],
+            ['bust every cache layer', 'shipkit check --fresh'],
+            ['machine-readable', 'shipkit check --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
+    fresh = Option.Boolean('--fresh', false, { description: 'bust every TTL cache layer (travels to child checks)' })
+
+    async execute(): Promise<number> {
+        try {
+            return await runCheck(process.cwd(), { json: this.json, fresh: this.fresh, print: (l) => this.context.stdout.write(`${l}\n`) })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}