rvlib-shipkit 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.24.0
+
+- **Custom panels lead the studio drawer, and the prompt folds.** A repo's `customPanel` tabs (the tint-mask painter, a legs editor) are the working surfaces, yet they rendered LAST in the drawer tab row, behind two json diagnostics. They come first now, `asset` then `roll meta` after, and a kind with exactly one custom panel gets it as the drawer's default tab until the user picks another. The prompt textarea folds to one ellipsized line by default (click to expand, a chevron folds it back, state holds for the session), so the stage and the rolls get the height back. The drawer toggle now reads `drawer ▾`, because with a custom panel as default content a button labelled JSON opened a paint surface.
+
+- **`shipkit start` on a brand-new dir bootstraps a WORKING repo, end to end.** It used to stop at git + the github repo and hand back two `next:` steps, because init needs a package.json. Now the dir being created THIS RUN is the signal to scaffold: a minimal package.json (private, type module), a first `src/index.ts` so the ci gate is green from commit one instead of failing an imports scan over zero files, the baseline .gitignore before anything installs, `bun add -d rvlib-shipkit` so the wired scripts actually run, then init, first commit, push. The guards stay strict: a pre-existing folder without a project gets git only, `--github` on it forces the github half but never writes a project into someone's files, a subdirectory another work tree owns gets nothing, a temp dir or `SHIPKIT_NO_INSTALL=1` skips the install, and an install that cannot run (offline, no bun) is a WARN, never a stop.
+
+- **SK011 checks the FLOOR, not just resolution.** `^0.1.1` resolves 0.1.2, so a range left behind by a bump passed the rule while a consumer tree already holding 0.1.1 kept it and never saw the release. A sibling range must now name exactly the version that sibling carries, which is what `shipkit bump` has always written. It found one real stale floor the moment it tightened.
+
 ## 0.23.0
 
 - **Release order is a TOPOSORT of the units' own dependency graph.** It was "sub-units first, root last", so a `--all` run published in declaration order and a dependent could ship naming a version the registry did not have yet. Kahn's algorithm now, stable (ties keep declaration order, root always last), and a cycle degrades to declaration order rather than dropping a unit: a release that silently skips a package is worse than one in a bad order.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.23.0",
+    "version": "0.24.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",

package/src/cli/cmd_Start.ts

@@ -9,9 +9,9 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd: ensures the dir, seeds CLAUDE.md include lines, wires shipkit on the spot (repo.config.ts via init) when the project already has a package.json, then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in: ensures the dir, seeds CLAUDE.md include lines, and on a BRAND-NEW dir scaffolds a minimal package.json + src/index.ts + the rvlib-shipkit dev dep, wires shipkit (repo.config.ts via init), then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. A pre-existing folder with no project gets git only, never a scaffold (--github forces only the github half for it). Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
-            ['create or enter ~/dev/pong: dir, wiring, git, first commit, private github repo, push', 'shipkit start pong'],
+            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
             ['adopt a pre-existing repo from anywhere', 'shipkit start my-old-project'],
             ['force the private github repo for a folder that was already there', 'shipkit start old-notes --github'],

package/src/git-bootstrap.ts

@@ -48,8 +48,10 @@ const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 /** what a repo with NO .gitignore at all gets before its first commit. Not a
  *  policy (rule SK004 owns that one), just the three things nobody ever meant
  *  to publish. A repo that already has a .gitignore keeps its own answer, and
- *  the commit refuses instead when that answer misses these */
-const IGNORE_BASELINE = ['node_modules/', '.env', '.env.*', '!.env.example', '.DS_Store']
+ *  the commit refuses instead when that answer misses these. Two writers:
+ *  firstCommit below, and the start scaffold (BEFORE its dep install, so
+ *  node_modules never reaches the first commit) */
+export const IGNORE_BASELINE = ['node_modules/', '.env', '.env.*', '!.env.example', '.DS_Store']
 
 /** the one line of gh or git output worth reporting — both merge stderr into
  *  stdout, so the first non-empty line is the message and the rest is chatter */
@@ -68,7 +70,7 @@ export function carveGhJson<T>(out: string): T | null {
     }
 }
 
-const runner = (bin: string, root: string, timeoutMs: number): Run => async (cmd) => {
+export const runner = (bin: string, root: string, timeoutMs: number): Run => async (cmd) => {
     // a credential prompt would hang a bootstrap forever: git fails instead
     const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
     const r = await spawnWithTimeout([bin, ...cmd], { cwd: root, timeoutMs, env })

package/src/rules/SK011-sibling-unit-ranges.ts

@@ -23,9 +23,20 @@ type Pkg = {
 
 const BLOCKS = ['dependencies', 'peerDependencies', 'optionalDependencies', 'devDependencies'] as const
 
-/** does `version` satisfy a caret/tilde/exact range? Deliberately small: the
- *  ranges this repo writes are `^x.y.z`, `~x.y.z` or an exact pin, and a range
- *  shape it cannot read is SKIPPED rather than guessed at. */
+/** does this range name the sibling's CURRENT version as its floor? Not
+ *  "does it resolve": `^0.1.1` happily resolves 0.1.2, and then a consumer
+ *  whose tree already holds 0.1.1 keeps it and misses the release. The floor
+ *  moves on every bump, so a stale one means a bump nobody propagated.
+ *  Deliberately small: `^x.y.z`, `~x.y.z` or an exact pin, and a range shape
+ *  it cannot read is SKIPPED rather than guessed at. */
+export function floorMatches(version: string, range: string): boolean | null {
+    const r = range.trim().match(/^([\^~]?)(\d+\.\d+\.\d+)$/)
+    if (r == null || !/^\d+\.\d+\.\d+/.test(version)) return null
+    return r[2] === version
+}
+
+/** does `version` satisfy a caret/tilde/exact range? Kept for the resolution
+ *  question, which is a different one from the floor question above. */
 export function satisfiesSimple(version: string, range: string): boolean | null {
     const v = version.match(/^(\d+)\.(\d+)\.(\d+)/)
     const r = range.trim().match(/^([\^~]?)(\d+)\.(\d+)\.(\d+)$/)
@@ -64,14 +75,17 @@ export const siblingUnitRanges: Rule = {
                     const actual = version.get(dep)
                     if (actual == null) continue
                     if (/^(link|file|portal|workspace):/.test(range)) continue
-                    const ok = satisfiesSimple(actual, range)
+                    const ok = floorMatches(actual, range)
                     if (ok == null) continue
                     checked++
-                    if (!ok) bad.push(`${u.id}: ${block}.${dep} wants ${range}, ${dep} is ${actual}`)
+                    if (!ok)
+                        bad.push(
+                            `${u.id}: ${block}.${dep} floors at ${range}, ${dep} is ${actual}${satisfiesSimple(actual, range) === true ? ' (it resolves, but a tree already holding the older one keeps it)' : ''}`,
+                        )
                 }
         }
         if (bad.length > 0)
-            t.fail(`${bad.join(' · ')} — a range naming a version its sibling does not carry breaks at INSTALL, for a consumer. \`shipkit bump\` moves these forward, so fix the bump rather than the range`)
-        else t.ok(`${checked} sibling range(s) match the version each unit carries`)
+            t.fail(`${bad.join(' · ')} — a sibling range FLOORS at the version it names, so a stale floor lets a consumer keep an older copy and miss the release. \`shipkit bump\` moves every floor forward in the version commit, so a red here is a bump nobody propagated`)
+        else t.ok(`${checked} sibling range(s) floor at exactly the version each unit carries`)
     },
 }

package/src/serve/hub-app/hub.css

@@ -60,12 +60,18 @@ aside{border-right:1px solid var(--line);background:var(--panel);overflow-y:auto
 
 /* ── main column ── */
 main{display:flex;flex-direction:column;height:100vh;overflow:hidden}
-/* topbar: the prompt is its OWN full-width row (small mono, auto-grows to
-   its content, scrolls only past ~14 lines), then ONE slim toolbar row */
+/* topbar: the prompt is its OWN full-width row (folded by default to one
+   ellipsized line; expanded = small mono, auto-grows to its content,
+   scrolls only past ~14 lines), then ONE slim toolbar row */
 .bar{display:flex;flex-direction:column;gap:8px;padding:10px 16px;border-bottom:1px solid var(--line);background:var(--panel)}
 textarea{width:100%;min-height:64px;background:var(--bg);color:var(--ink);border:1px solid var(--line);
  border-radius:9px;padding:9px 11px;font:12px/1.5 ui-monospace,Menlo,monospace;resize:vertical}
-.bar .prompt{min-height:36px;max-height:252px;overflow-y:auto;resize:none;font:11px/1.5 ui-monospace,Menlo,monospace;padding:7px 10px}
+.promptrow{display:flex;gap:6px;align-items:flex-start}
+.promptrow .fold{flex:none;background:var(--panel2);color:var(--dim);border:1px solid var(--line);border-radius:9px;
+ padding:6px 9px;font-size:11px;line-height:1.5}
+.bar .prompt{flex:1;min-height:36px;max-height:252px;overflow-y:auto;resize:none;font:11px/1.5 ui-monospace,Menlo,monospace;padding:7px 10px}
+.bar .prompt.folded{min-height:0;max-height:none;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;cursor:pointer;
+ color:var(--dim);background:var(--bg);border:1px solid var(--line);border-radius:9px}
 .toolbar{display:flex;gap:8px;align-items:center;min-height:30px}
 .toolbar button{padding:5px 11px;font-size:12px}
 .toolbar .sp{flex:1}

package/src/serve/hub-app/media-svc.ts

@@ -58,6 +58,11 @@ export class MediaSvc {
     drawerOpen = false
     jsonText = ''
     jsonMsg = ''
+    /** prompt folded to one ellipsized line (session state, click toggles) */
+    promptOpen = false
+
+    /** latched by picking a NON-default tab, until then a sole custom panel is the default */
+    private tabPicked = false
 
     private hbTimer: ReturnType<typeof setInterval> | null = null
     private rectTimer: ReturnType<typeof setTimeout> | null = null
@@ -66,8 +71,8 @@ export class MediaSvc {
     private savedPrompt = ''
 
     constructor(private st: HubSt) {
-        makeAutoObservable<this, 'st' | 'hbTimer' | 'rectTimer' | 'promptTimer' | 'savedPrompt'>(
-            this, { st: false, hbTimer: false, rectTimer: false, promptTimer: false, savedPrompt: false })
+        makeAutoObservable<this, 'st' | 'hbTimer' | 'rectTimer' | 'promptTimer' | 'savedPrompt' | 'tabPicked'>(
+            this, { st: false, hbTimer: false, rectTimer: false, promptTimer: false, savedPrompt: false, tabPicked: false })
     }
 
     start(): void {
@@ -161,7 +166,11 @@ export class MediaSvc {
             this.savedPrompt = r.asset.prompt
             this.promptMsg = ''
             if (this.deterministic) this.n = '1'
-            if (this.tab.startsWith('c:') && !r.asset.custom.some((c) => `c:${c.id}` === this.tab)) this.tab = 'asset'
+            // custom panels are the working surfaces, a kind with exactly one
+            // gets it as the default tab (setTab latches an explicit divergence)
+            const sole = r.asset.custom.length === 1 ? `c:${r.asset.custom[0]!.id}` : null
+            if (this.tab.startsWith('c:') && !r.asset.custom.some((c) => `c:${c.id}` === this.tab)) this.tab = sole ?? 'asset'
+            else if (!this.tabPicked && sole != null) this.tab = sole
             this.pickActive(r)
         })
         if (this.hasGeom) await this.loadRect()
@@ -279,6 +288,9 @@ export class MediaSvc {
         this.promptMsg = 'copied'
         setTimeout(() => runInAction(() => { this.promptMsg = '' }), 900)
     }
+    togglePrompt(): void {
+        this.promptOpen = !this.promptOpen
+    }
 
     toggleFold(cat: string): void {
         if (this.st.query.trim() !== '') return // folds yield to a live search
@@ -370,9 +382,12 @@ export class MediaSvc {
         await this.fillCat()
     }
 
-    // ── drawer: asset json (read-only) · roll meta sidecar · custom panels ─
+    // ── drawer: custom panels · asset json (read-only) · roll meta sidecar ─
     setTab(tab: string): void {
         this.tab = tab
+        // clicking the sole panel IS the default, only a different pick latches
+        const c = this.detail?.asset.custom ?? []
+        if (tab !== (c.length === 1 ? `c:${c[0]!.id}` : null)) this.tabPicked = true
         this.drawerOpen = true
         void this.loadTab()
     }

package/src/serve/hub-app/media-view.tsx

@@ -1,6 +1,6 @@
 // Media views — topbar, info chips, stage (image/audio + geometry), roll
-// strip, category grid + size-true lineup, drawer (asset json · roll meta ·
-// repo-defined custom panels). Feature parity with the deleted vanilla
+// strip, category grid + size-true lineup, drawer (repo-defined custom
+// panels · asset json · roll meta). Feature parity with the deleted vanilla
 // studio SPA; state lives in MediaSvc (components read and call).
 import { runInAction } from 'mobx'
 import { observer } from 'mobx-react-lite'
@@ -27,12 +27,23 @@ export const MediaTopbar = observer(({ app }: { app: HubSt }) => {
         if (t == null) return
         t.style.height = 'auto'
         t.style.height = `${t.scrollHeight + 2}px`
-    }, [m.prompt])
+    }, [m.prompt, m.promptOpen])
     return (
         <div className="bar">
-            {/* the prompt AUTOSAVES (debounced) — no save button, no fear */}
-            <textarea className="prompt" ref={taRef} value={m.prompt} placeholder="select an asset ←"
-                onChange={(e) => m.setPrompt(e.target.value)} />
+            {/* the prompt AUTOSAVES (debounced), no save button, no fear.
+                folded (default) = one ellipsized line, click to expand */}
+            <div className="promptrow">
+                <button className="fold" title={m.promptOpen ? 'fold the prompt' : 'expand the prompt'}
+                    onClick={() => m.togglePrompt()}>{m.promptOpen ? '▾' : '▸'}</button>
+                {m.promptOpen
+                    ? <textarea className="prompt" ref={taRef} value={m.prompt} placeholder="select an asset ←"
+                        onChange={(e) => m.setPrompt(e.target.value)} />
+                    : <div className="prompt folded" onClick={() => m.togglePrompt()}>
+                        {/* placeholder only when NOTHING is selected, a selected
+                            asset with an empty prompt shows an empty line */}
+                        {m.curId == null ? 'select an asset ←' : m.prompt === '' ? '\u00a0' : m.prompt}
+                    </div>}
+            </div>
             <div className="toolbar">
                 {!manual ? <button disabled={m.curId == null} onClick={() => void m.generate()}>Generate</button> : null}
                 {!manual ? (
@@ -232,7 +243,7 @@ export const CatGrid = observer(({ app }: { app: HubSt }) => {
     )
 })
 
-// ── drawer: asset json (read-only) · roll meta · custom panels ───────────
+// ── drawer: custom panels · asset json (read-only) · roll meta ───────────
 const PanelHost = observer(({ app }: { app: HubSt }) => {
     const m = app.media
     const ref = useRef<HTMLDivElement>(null)
@@ -273,11 +284,13 @@ export const Drawer = observer(({ app }: { app: HubSt }) => {
     return (
         <div className="drawer">
             <div className="tabs">
-                {[{ id: 'asset', label: 'asset' }, { id: 'meta', label: 'roll meta' }, ...customs.map((c) => ({ id: `c:${c.id}`, label: c.id }))].map((t) => (
+                {/* customs lead: they are the working surfaces, json tabs are diagnostics */}
+                {[...customs.map((c) => ({ id: `c:${c.id}`, label: c.id })), { id: 'asset', label: 'asset' }, { id: 'meta', label: 'roll meta' }].map((t) => (
                     <button key={t.id} className={m.tab === t.id ? 'on' : ''} onClick={() => m.setTab(t.id)}>{t.label}</button>
                 ))}
                 <span className="sp" />
-                <button className="ghost" onClick={() => runInAction(() => { m.drawerOpen = !m.drawerOpen })}>JSON ▾</button>
+                {/* names the drawer, not the tab set (a sole custom panel is the default content) */}
+                <button className="ghost" onClick={() => runInAction(() => { m.drawerOpen = !m.drawerOpen })}>drawer ▾</button>
             </div>
             {m.drawerOpen ? (
                 <div id="drawerbody" className="on">

package/src/start-repo.ts

@@ -7,7 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
+import { ensureGitRepo, firstGhLine, IGNORE_BASELINE, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 
 export type StartOpts = {
@@ -24,6 +24,9 @@ export type StartOpts = {
     github?: boolean
     /** how `gh` runs — injected by tests, which never touch a real account */
     gh?: Run | null
+    /** how `bun` runs for the dep install — injected by tests, which never
+     *  touch the network. An explicit null means no bun on this machine */
+    bun?: Run | null
 }
 
 export async function startRepo(name: string, opts: StartOpts = {}): Promise<number> {
@@ -66,11 +69,15 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
             }
         }
     }
-    // start is the from-anywhere verb: a dir that is already a real project
-    // (package.json) gets wired on the spot, so a pre-existing repo goes
-    // 0 → shipkit'd with the one command. init itself stays cwd-only, like
-    // git init. A brand-new empty dir gets git + its remote all the same, and
-    // is told what is next, because the shipkit scaffold needs a package.json.
+    // start is the from-anywhere verb, and a STARTED repo comes out READY:
+    // a brand-new dir gets a minimal package.json, a first src/index.ts, the
+    // rvlib-shipkit dev dep, repo.config.ts via init, git, first commit,
+    // private github repo, push. A dir that already holds a project
+    // (package.json) gets the same minus the scaffold. A PRE-EXISTING dir
+    // with NO project is the everyday cd into some old folder: git only,
+    // never a scaffold (--github forces only the github half, so it must
+    // never write a package.json into a folder that holds someone's files).
+    // init itself stays cwd-only, like git init.
     // --skip means shipkit NEVER TOUCHES a listed repo (a day-job checkout
     // belongs on that list), not just no CLAUDE.md. And the cd contract survives a
     // failed adoption: the dir always prints, wiring trouble is a WARN.
@@ -83,6 +90,41 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         let wired = false
         try { wired = await ensureGitRepo(dir, { print }) }
         catch (e) { console.error(`WARN could not wire git in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+        // the scaffold fires ONLY for a dir this run created (never --github:
+        // forcing the github half on an old folder must not write a project
+        // into it), and only where git actually wired (a subdirectory of
+        // another work tree gets nothing): the minimal package.json lands so
+        // init below has its floor and the first commit carries a working
+        // repo, not an empty husk
+        if (wired && justCreated && !existsSync(join(dir, 'package.json')) && !existsSync(join(dir, 'repo.config.ts'))) {
+            const pkg = { name, version: '0.0.0', private: true, type: 'module', scripts: {} }
+            writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
+            // the first source file, so the ci gate is green from commit one:
+            // an imports gate over zero files fails loud on purpose
+            mkdirSync(join(dir, 'src'), { recursive: true })
+            writeFileSync(join(dir, 'src', 'index.ts'), 'export {}\n')
+            console.error('ok: package.json + src/index.ts scaffolded (private, type module)')
+            // the install below creates node_modules/ BEFORE the first
+            // commit, so the baseline ignore must exist first (SK004's block,
+            // written by init, does not carry node_modules)
+            if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+            // the scripts init wires call node_modules/rvlib-shipkit — a
+            // scaffold whose scripts exit 127 is not a started repo. Skips
+            // mirror the github half's guards: an injected runner wins, the
+            // env switch turns it off machine-wide, a temp dir is a rehearsal
+            // that must not pull the network. init owns the fix line for
+            // every not-installed outcome
+            let bun: Run | null
+            if (opts.bun !== undefined) bun = opts.bun
+            else if ((process.env.SHIPKIT_NO_INSTALL ?? '') !== '') { console.error('skip: rvlib-shipkit install — SHIPKIT_NO_INSTALL is set'); bun = null }
+            else if (isScratch(dir)) { console.error(`skip: rvlib-shipkit install — ${dir} is a temp dir`); bun = null }
+            else bun = Bun.which('bun') == null ? null : runner('bun', dir, 180_000)
+            if (bun != null) {
+                const r = await bun(['add', '-d', 'rvlib-shipkit'])
+                if (r.code === 0) console.error('ok: rvlib-shipkit installed (dev dep)')
+                else console.error(`WARN rvlib-shipkit install failed: ${firstGhLine(r.out)}`)
+            }
+        }
         let unscaffolded = false
         if (!existsSync(join(dir, 'repo.config.ts'))) {
             if (existsSync(join(dir, 'package.json'))) {