rvlib-shipkit 0.1.1 → 0.3.0

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

@@ -0,0 +1,58 @@
+// Generation queue: single worker, IN-MEMORY (never run the studio with
+// --watch — a restart drops every queued roll; the fill CLI is the recovery
+// path), errors surfaced in a ring buffer, never fatal.
+export type Job = { assetId: string; prompt: string; count: number }
+export type QueueState = { generating: boolean; current: string | null; done: number; total: number }
+
+export class StudioQueue {
+    private jobs: Job[] = []
+    readonly state: QueueState = { generating: false, current: null, done: 0, total: 0 }
+    readonly errors: string[] = []
+
+    /** generateOne throws on failure — the queue logs and moves on */
+    constructor(private generateOne: (job: Job, seed: number) => Promise<void>, private newSeed: () => number) {}
+
+    pushError(msg: string): void {
+        this.errors.push(msg)
+        if (this.errors.length > 20) this.errors.shift()
+        console.log(`FAIL: ${msg}`)
+    }
+
+    get queuedCount(): number { return this.jobs.length }
+
+    clear(): void { this.jobs.length = 0 }
+
+    enqueue(newJobs: Job[]): void {
+        if (!this.state.generating) {
+            this.state.done = 0
+            this.state.total = 0
+        }
+        this.state.total += newJobs.reduce((s, j) => s + j.count, 0)
+        this.jobs.push(...newJobs)
+        if (!this.state.generating) {
+            this.state.generating = true
+            void this.workerLoop()
+        }
+    }
+
+    private async workerLoop(): Promise<void> {
+        while (true) {
+            const job = this.jobs.shift()
+            if (job == null) {
+                this.state.generating = false
+                this.state.current = null
+                return
+            }
+            this.state.current = job.assetId
+            for (let i = 0; i < job.count; i++) {
+                const seed = this.newSeed()
+                try {
+                    await this.generateOne(job, seed)
+                } catch (e) {
+                    this.pushError(`${job.assetId} seed ${seed}: ${(e as Error).message}`)
+                }
+                this.state.done++
+            }
+        }
+    }
+}

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

@@ -0,0 +1,412 @@
+// 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, relative } from 'path'
+import { findAsset, allAssets, missingPanelScripts, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit, type ShipFn } 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 }
+
+// what the studio detail view shows about an asset's plumbing (W2-2)
+export type AssetInfo = {
+    backend: 'canvas' | 'comfy'
+    /** canvas rolls have no seed input — every roll is identical */
+    deterministic: boolean
+    /** comfy only: resolved workflow id + its .rv-comfy path (note = why unresolved) */
+    workflow: { id: string | null; path: string | null; note?: string } | null
+    ship: { mode: 'built-in' | 'hook' | 'record'; path?: string; note?: string }
+    /** live write-through target (kind.meta.file), repo-root-relative */
+    metaFile: string | null
+    kindId: string
+    kitSource: string
+}
+
+// the studio's route table without a server: `handle` answers the studio's
+// own path space ('/', '/api/…', '/img', '/panel/…') so serveStudio can own
+// a port AND the shipkit hub can mount the same routes under /assets/.
+export type StudioRoutes = { handle: (req: Request, pathname: string) => Promise<Response>; queue: StudioQueue }
+
+export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
+    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')
+
+    // ── per-asset provenance for the studio's info surface (W2-2): where every
+    //    roll comes from and where a pick goes. Read-only; never throws (a
+    //    misconfigured comfy kind still shows WHY, it doesn't blank the view).
+    const relOf = (p: string): string => relative(root, p) || p
+    const infoOf = (f: FoundAsset): AssetInfo => {
+        const gen = f.kind.generate
+        const backend = gen.backend
+        let workflow: AssetInfo['workflow'] = null
+        if (gen.backend === 'comfy') {
+            let id = gen.workflow ?? null
+            let note: string | undefined
+            if (id == null) {
+                if (workflows != null && workflows.size === 1) id = [...workflows.keys()][0]!
+                else if (workflows != null) note = `names no workflow; ${workflows.size} loaded — set workflow on the kind`
+            }
+            const wf = id != null && workflows != null ? workflows.get(id) : undefined
+            if (id != null && wf == null && note == null) note = `workflow '${id}' not loaded`
+            const path = wf != null ? relOf(wf.jsonPath) : id != null && kit.comfy != null ? join(kit.comfy.workflows, `${id}.json`) : null
+            workflow = { id, path, note }
+        }
+        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'
+            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' }
+    }
+
+    // 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: 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
+    // 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')
+        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)
+        }
+        return fn ?? null
+    }
+    const ship = async (f: FoundAsset, roll: string): Promise<{ shipped: string | null }> => {
+        const fn = await resolveShipFn(f)
+        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 handle = async (req: Request, pathname: string): Promise<Response> => {
+    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 (pathname === '/') return new Response(deps.page(), { headers: { 'Content-Type': 'text/html; charset=utf-8' } })
+
+        if (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 (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 }, info: infoOf(f), rolls, pick })
+        }
+
+        if (pathname.startsWith('/panel/')) {
+            // repo-defined editor module; ids resolved against the kit — the
+            // URL never reaches the filesystem directly
+            const m = 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 (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 (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 (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 (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 (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 (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 (pathname === '/api/queue/clear') {
+            queue.clear()
+            return json({ ok: true })
+        }
+        if (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 (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 (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 (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 (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 (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 (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 (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 { handle, queue }
+}
+
+// standalone studio server (`shipkit assets serve`): the same routes on
+// their own port. The hub (`shipkit serve`) mounts studioRoutes under
+// /assets/ instead — one route table, two front doors.
+export async function serveStudio(deps: StudioDeps): Promise<Studio> {
+    const routes = await studioRoutes(deps)
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: deps.kit.port,
+        fetch: (req) => routes.handle(req, new URL(req.url).pathname),
+    })
+    return { server, queue: routes.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
+        }
+    }
+}