rvlib-shipkit 1.1.0 → 1.2.0

package/src/comfy/comfy-panel.ts

@@ -8,6 +8,7 @@
 import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, resolve } from 'path'
 import { defaultHubPort } from '../serve/hub-port.ts'
+import { portHolders } from '../core/port-holders.ts'
 
 export type ComfyWorkflow = { id: string; file: string }
 export type ComfyPanelUp = { url: string; port: number }
@@ -127,22 +128,6 @@ const KILL_STEP_MS = 25
 const QUIET_TRIES = 60
 const QUIET_STEP_MS = 50
 
-/** the pids LISTENING on a tcp port, on darwin and linux. `-sTCP:LISTEN`
- *  carries the whole answer: `-i tcp:<port>` alone also matches every client
- *  connected to it, this process included, and those must never be killed.
- *  lsof sits in /usr/sbin on darwin, which a gui-launched shell can miss */
-function portHolders(port: number): number[] {
-    const lsof = Bun.which('lsof') ?? ['/usr/sbin/lsof', '/usr/bin/lsof'].find((p) => existsSync(p))
-    if (lsof == null) return []
-    const r = Bun.spawnSync([lsof, '-ti', `tcp:${port}`, '-sTCP:LISTEN'], { stdout: 'pipe', stderr: 'ignore' })
-    const pids = r.stdout
-        .toString()
-        .split('\n')
-        .map((l) => Number(l.trim()))
-        .filter((n) => Number.isInteger(n) && n > 0)
-    return [...new Set(pids)]
-}
-
 /** a pid that died between the scan and the signal is the outcome we wanted */
 function kill(pid: number, signal: 'SIGTERM' | 'SIGKILL'): void {
     try {

package/src/core/attach.ts

@@ -39,9 +39,11 @@ export type ShareOpts = {
     abort?: () => boolean
 }
 
-/** how long an answer file stays on disk. Only an in flight asker can adopt
- *  one, so this is housekeeping, not a validity window. */
-const KEEP_MS = 60 * 60 * 1000
+/** how long a slot file stays on disk. Only an in flight asker can adopt an
+ *  answer, so this is housekeeping, not a validity window. A live holder
+ *  heartbeats its lock (locked-write.ts), so a lock this old is one a killed
+ *  run left behind. */
+export const INFLIGHT_KEEP_MS = 60 * 60 * 1000
 
 const readShared = <T>(path: string): Shared<T> | null => {
     try {
@@ -50,12 +52,15 @@ const readShared = <T>(path: string): Shared<T> | null => {
     } catch { return null }
 }
 
-const sweep = (dir: string, now: number): void => {
+/** every slot file past the keep window goes: answers, the locks killed runs
+ *  left, the graves of a steal. One level of namespace dirs below `dir` is
+ *  walked too. */
+export function sweepSlots(dir: string, now: number, keepMs = INFLIGHT_KEEP_MS): void {
     try {
-        for (const f of readdirSync(dir)) {
-            if (f.endsWith('.lock')) continue
-            const p = `${dir}/${f}`
-            try { if (statSync(p).mtimeMs < now - KEEP_MS) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = `${dir}/${e.name}`
+            if (e.isDirectory()) { sweepSlots(p, now, keepMs); continue }
+            try { if (statSync(p).mtimeMs < now - keepMs) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
         }
     } catch { /* housekeeping never fails a run */ }
 }
@@ -86,7 +91,7 @@ export async function shareRun<T>(slot: string, o: ShareOpts, body: () => Promis
                 // an answer nobody can adopt costs the waiters a measurement, never a verdict
             }
         }
-        sweep(dirname(slot), now)
+        sweepSlots(dirname(slot), now)
         return { kind: 'measured', value: r.value }
     })
     if (leased.ok) return leased.value

package/src/core/check-file-names.ts

@@ -5,6 +5,14 @@
 import { basename, relative } from 'path'
 
 export const CHECK_SUFFIX = '.check.ts'
+/** the unit file: a check, a global process or a widget, by its default
+ *  export (shipkit-files.ts). Discovery reads both suffixes, and will later
+ *  read this one alone */
+export const UNIT_SUFFIX = '.shipkit.ts'
+
+/** the name a unit file answers to when it declares no id: its basename,
+ *  `.check` dropped too, so `x.check.shipkit.ts` is `x` */
+export const unitBase = (file: string): string => basename(file).slice(0, -UNIT_SUFFIX.length).replace(/\.check$/, '')
 
 /** dirs discovery never walks into, beside every dot dir: installs, build
  *  output, scratch, and templates meant for other repos */

package/src/core/check-runner.ts

@@ -346,35 +346,57 @@ export function selectChecks(o: Pick<RunChecksOpts, 'checks' | 'audience' | 'ful
  *  was still streaming into, so the surviving FAIL line pointed at a path
  *  that no longer existed. Now each run owns `run-<pid>-<started>/`.
  *
- *  Old run dirs are swept on the way in, and only ones nothing can be using:
- *  the pid must not be running AND the dir must be older than the grace
- *  window, so a recycled pid cannot cost a live run its logs. */
+ *  Old run dirs are swept on the way in (sweepRunDirs), and only ones nothing
+ *  can be using: the pid must not be running, so a live run keeps its logs. */
 function openRunDir(base: string): string {
     // the pid plus the millisecond separates two PROCESSES; the counter
     // separates two runs inside one (the TUI can start a second before the
     // clock ticks), so no run ever writes into another's dir
     const dir = join(base, `run-${process.pid}-${Date.now()}-${runSeq++}`)
     mkdirSync(dir, { recursive: true })
-    const cutoff = Date.now() - RUN_DIR_KEEP_MS
+    sweepRunDirs(base, Date.now(), { keep: basename(dir) })
+    return dir
+}
+
+/** how long a finished run's logs stay readable, and the pid-reuse guard */
+export const RUN_DIR_KEEP_MS = 6 * 60 * 60 * 1000
+/** the most finished runs whose logs stay, newest first */
+export const RUN_DIR_MAX = 40
+
+const RUN_ENTRY = /^(?:run|releases)-(\d+)-(\d+)(?:-\d+)?(?:\.json(?:\.lock)?)?$/
+
+const pidRuns = (pid: number): boolean => {
+    try { process.kill(pid, 0); return true } catch (e) { return (e as { code?: string }).code === 'EPERM' }
+}
+
+/** the run dirs under a log base, and the per run release survey files a
+ *  killed run leaves beside them: both carry the pid and the start time */
+export function runEntries(base: string): { name: string; pid: number; started: number }[] {
     try {
-        for (const name of readdirSync(base)) {
-            // run dirs AND the per-run release survey files, which a killed
-            // run leaves behind: both carry the pid and the start time, so one
-            // sweep covers both rather than one path leaking forever
-            const m = /^(?:run|releases)-(\d+)-(\d+)(?:-\d+)?(?:\.json(?:\.lock)?)?$/.exec(name)
-            if (m == null || name === basename(dir)) continue
-            if (Number(m[2]) > cutoff) continue
-            try { process.kill(Number(m[1]), 0); continue } catch (e) { if ((e as { code?: string }).code === 'EPERM') continue }
-            rmSync(join(base, name), { recursive: true, force: true })
-        }
+        return readdirSync(base).flatMap((name) => {
+            const m = RUN_ENTRY.exec(name)
+            return m == null ? [] : [{ name, pid: Number(m[1]), started: Number(m[2]) }]
+        })
     } catch {
-        // an unreadable log base is a housekeeping miss, never a gate failure
+        return []
     }
-    return dir
 }
 
-/** how long a finished run's logs stay readable, and the pid-reuse guard */
-const RUN_DIR_KEEP_MS = 6 * 60 * 60 * 1000
+/** the run logs' cap: every entry past the keep window (no run lasts that
+ *  long, so a live pid there is a long lived process's finished run, or a
+ *  reused pid), then the oldest past `max` whose pid no longer runs. `keep`
+ *  spares the caller's own dir */
+export function sweepRunDirs(base: string, now: number, o: { keep?: string; keepMs?: number; max?: number } = {}): void {
+    const all = runEntries(base).sort((a, b) => b.started - a.started)
+    const cutoff = now - (o.keepMs ?? RUN_DIR_KEEP_MS)
+    all.forEach((e, i) => {
+        if (e.name === o.keep) return
+        const old = e.started <= cutoff
+        if (!old && i < (o.max ?? RUN_DIR_MAX)) return
+        if (!old && pidRuns(e.pid)) return
+        try { rmSync(join(base, e.name), { recursive: true, force: true }) } catch { /* an unreadable log base is a housekeeping miss */ }
+    })
+}
 let runSeq = 0
 
 type Live = RunnableCheck & CheckResult & {

package/src/core/discover-checks.ts

@@ -21,7 +21,8 @@ import { readdirSync, readFileSync, realpathSync, statSync } from 'fs'
 import { basename, join, relative } from 'path'
 import { check, type CheckDef, type CheckFrom } from '../check.ts'
 
-import { CHECK_SUFFIX as SUFFIX, fallbackNames, isLegacyCheckSource, SKIPPED_DIRS as IGNORED_DIRS } from './check-file-names.ts'
+import { CHECK_SUFFIX as SUFFIX, fallbackNames, isLegacyCheckSource, SKIPPED_DIRS as IGNORED_DIRS, UNIT_SUFFIX, unitBase } from './check-file-names.ts'
+import { unitKind } from '../shipkit-files.ts'
 
 export { fallbackNames, isLegacyCheckSource } from './check-file-names.ts'
 
@@ -54,16 +55,39 @@ export type DiscoveredCheck = {
     from: CheckFrom
 }
 
-function walk(dir: string, out: string[]): void {
+function walk(dir: string, out: string[], suffix = SUFFIX): void {
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
     for (const e of entries) {
         if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out)
-        } else if (e.name.endsWith(SUFFIX)) out.push(join(dir, e.name))
+            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix)
+        } else if (e.name.endsWith(suffix)) out.push(join(dir, e.name))
     }
 }
 
+/** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted */
+export function repoUnitFiles(root: string): string[] {
+    const out: string[] = []
+    walk(root, out, UNIT_SUFFIX)
+    return out.sort()
+}
+
+/** a file's default export, re-imported whenever the file on disk moves. An
+ *  ES module is cached by path for the life of the process, so a repo that
+ *  rewrites a file mid process would keep the old one without the stamp */
+export async function importFresh(path: string): Promise<unknown> {
+    let stamp = ''
+    // no dot in the stamp: a query ending `.1234` reads as the module's
+    // extension, and a load plugin then never sees the file
+    try { stamp = String(statSync(path).mtimeMs).replace('.', '_') } catch {}
+    // the REAL path: through a linked one, the resolver misses a file
+    // created after it first listed the directory, which is exactly the
+    // file a fix pass just wrote
+    let real = path
+    try { real = realpathSync(path) } catch {}
+    return ((await import(`${real}?v=${stamp}`)) as { default?: unknown }).default
+}
+
 /** every `*.check.ts` file under a repo root, check files and legacy
  *  scripts alike, by the same walk discovery takes, without importing one.
  *  Sorted. */
@@ -98,22 +122,14 @@ export function builtinCheckIds(): string[] {
 /** the module, re-imported whenever the file on disk moves. An ES module is
  *  cached by path for the life of the process, so a repo that rewrites a
  *  check file mid process would keep running the old body without this. */
-async function load(path: string): Promise<CheckDef> {
-    let stamp = ''
-    // no dot in the stamp: a query ending `.1234` reads as the module's
-    // extension, and a load plugin then never sees the file
-    try { stamp = String(statSync(path).mtimeMs).replace('.', '_') } catch {}
+async function load(path: string): Promise<CheckDef | null> {
     // the path rides on every message from here down, because `check()` knows
     // the object and not where it was written, and an agent reading a refused
     // declaration needs the file before it needs the rule
     try {
-        // the REAL path: through a linked one, the resolver misses a file
-        // created after it first listed the directory, which is exactly the
-        // file a fix pass just wrote
-        let real = path
-        try { real = realpathSync(path) } catch {}
-        const mod = (await import(`${real}?v=${stamp}`)) as { default?: unknown }
-        const d = mod.default
+        const d = await importFresh(path)
+        // a unit file of another kind is its reader's, never a check
+        if (path.endsWith(UNIT_SUFFIX) && unitKind(d) !== 'check') return null
         if (d == null || typeof d !== 'object' || (!('run' in d) && !('cmd' in d)))
             throw new Error(`a check file must \`export default check({...})\` with a \`run\` or a \`cmd\``)
         // re-validated here rather than trusted: a file can build the object
@@ -133,6 +149,7 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
     walk(BUILTIN_CHECK_DIR, builtins)
     const found: string[] = []
     walk(root, found)
+    const units = repoUnitFiles(root)
     // the repo that HOSTS the toolkit walks over `src/checks/` too, and a file
     // discovered twice is a duplicate id rather than a second check. Real paths,
     // because a consumer reaches the same files through a linked node_modules
@@ -147,13 +164,14 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
 
     const out: DiscoveredCheck[] = []
     const ids = new Set<string>()
-    for (const f of [...builtins, ...own]) {
+    for (const f of [...builtins, ...own, ...units]) {
         const isBuiltin = builtins.includes(f)
         const def = await load(f)
+        if (def == null) continue
         const rel = isBuiltin ? null : relative(root, f).replace(/\\/g, '/')
         const fallback = isBuiltin
             ? (BUILTIN_ID_RE.exec(base(f))?.[1] ?? base(f))
-            : names.get(f)!
+            : f.endsWith(UNIT_SUFFIX) ? unitBase(f) : names.get(f)!
         const id = def.id ?? fallback
         if (isBuiltin) {
             if (id !== fallback) throw new Error(`${f}: declares id '${id}' but its file name says '${fallback}' — a built-in id is its file name`)

package/src/core/identity-color.ts

@@ -0,0 +1,203 @@
+// a repo's identity colours: `identity: { colorLight, colorDark }` in its
+// repo.config.ts, one hex each. colorLight reads on a light background,
+// colorDark on a dark one. This module is pure (the page imports it): hue
+// maths, the fallback from the repo name, and the byte preserving edit of the
+// config text. Reading an icon is core/identity.ts.
+
+export type Identity = { colorLight: string; colorDark: string }
+
+export const HEX_RE = /^#[0-9a-fA-F]{6}$/
+
+/** why this value is not an identity, or null */
+export function identityProblem(v: unknown): string | null {
+    if (v == null) return 'no identity colours'
+    if (typeof v !== 'object') return 'identity is not an object'
+    const o = v as Record<string, unknown>
+    for (const k of ['colorLight', 'colorDark'] as const)
+        if (typeof o[k] !== 'string' || !HEX_RE.test(o[k] as string)) return `identity.${k} is ${o[k] == null ? 'missing' : `'${String(o[k])}'`}, not a #rrggbb hex`
+    return null
+}
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v))
+
+/** hsl (h in degrees, s and l in 0..1) as #rrggbb */
+export function hslHex(h: number, s: number, l: number): string {
+    const a = s * Math.min(l, 1 - l)
+    const f = (n: number): string => {
+        const k = (n + h / 30) % 12
+        const c = l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))
+        return Math.round(c * 255).toString(16).padStart(2, '0')
+    }
+    return `#${f(0)}${f(8)}${f(4)}`
+}
+
+/** #rrggbb as hsl, h in degrees */
+export function hexHsl(hex: string): { h: number; s: number; l: number } {
+    const n = Number.parseInt(hex.slice(1), 16)
+    return rgbHsl((n >> 16) & 255, (n >> 8) & 255, n & 255)
+}
+
+export function rgbHsl(r8: number, g8: number, b8: number): { h: number; s: number; l: number } {
+    const r = r8 / 255
+    const g = g8 / 255
+    const b = b8 / 255
+    const max = Math.max(r, g, b)
+    const min = Math.min(r, g, b)
+    const l = (max + min) / 2
+    const d = max - min
+    if (d === 0) return { h: 0, s: 0, l }
+    const s = d / (1 - Math.abs(2 * l - 1))
+    let h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+    h *= 60
+    if (h < 0) h += 360
+    return { h, s, l }
+}
+
+/** the pair for one hue: saturated enough to read as a colour, dark enough
+ *  for white paper, light enough for a dark page */
+export function identityOfHue(h: number, s = 0.7): Identity {
+    const sat = clamp(s, 0.5, 0.85)
+    return { colorLight: hslHex(h, sat, 0.38), colorDark: hslHex(h, sat, 0.68) }
+}
+
+/** a hue hashed from the name, stable from one run to the next */
+export function nameHue(name: string): number {
+    let h = 0
+    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
+    return h % 360
+}
+
+export const identityOfName = (name: string): Identity => identityOfHue(nameHue(name))
+
+/** the dominant saturated hue of rgba pixels, weighted by saturation, or
+ *  null when the image is grey, transparent or empty */
+export function dominantHue(rgba: Uint8Array | Buffer, channels = 4): { h: number; s: number } | null {
+    const BINS = 36
+    const weight = new Float64Array(BINS)
+    const sumS = new Float64Array(BINS)
+    const vecX = new Float64Array(BINS)
+    const vecY = new Float64Array(BINS)
+    for (let i = 0; i + channels - 1 < rgba.length; i += channels) {
+        if (channels === 4 && rgba[i + 3]! < 128) continue
+        const { h, s, l } = rgbHsl(rgba[i]!, rgba[i + 1]!, rgba[i + 2]!)
+        if (s < 0.3 || l < 0.12 || l > 0.9) continue
+        const b = Math.floor(h / (360 / BINS)) % BINS
+        const w = s * (1 - Math.abs(2 * l - 1))
+        weight[b]! += w
+        sumS[b]! += s * w
+        vecX[b]! += Math.cos((h * Math.PI) / 180) * w
+        vecY[b]! += Math.sin((h * Math.PI) / 180) * w
+    }
+    let best = -1
+    let bestW = 0
+    // a bin and its two neighbours, so a hue on a bin edge is not split
+    for (let b = 0; b < BINS; b++) {
+        const w = weight[b]! + weight[(b + 1) % BINS]! + weight[(b + BINS - 1) % BINS]!
+        if (w > bestW) { bestW = w; best = b }
+    }
+    if (best < 0 || bestW === 0) return null
+    let x = 0, y = 0, s = 0, w = 0
+    for (const b of [(best + BINS - 1) % BINS, best, (best + 1) % BINS]) {
+        x += vecX[b]!
+        y += vecY[b]!
+        s += sumS[b]!
+        w += weight[b]!
+    }
+    let h = (Math.atan2(y, x) * 180) / Math.PI
+    if (h < 0) h += 360
+    return { h, s: s / w }
+}
+
+// ── the config text ─────────────────────────────────────────────────────
+
+// the key where a config writes it: at a line start, or inline after `{` or
+// `,` (a one line config), bare or quoted
+const KEY_RE = /(?:^|[{,])\s*(['"]?)identity\1\s*:\s*/gm
+
+/** per char of the text: the object depth inside `defineRepo({` after that
+ *  char (1 on the top level keys), or -1 inside a string or a comment */
+function configDepths(text: string): Int32Array {
+    const depth = new Int32Array(text.length).fill(0)
+    const open = /defineRepo\(\s*\{/.exec(text)
+    if (open == null) return depth
+    let d = 0
+    let quote: string | null = null
+    let comment: 'line' | 'block' | null = null
+    for (let i = open.index + open[0].length - 1; i < text.length; i++) {
+        const ch = text[i]!
+        if (comment === 'line') { if (ch === '\n') comment = null; else { depth[i] = -1; continue } }
+        else if (comment === 'block') { depth[i] = -1; if (ch === '/' && text[i - 1] === '*') comment = null; continue }
+        else if (quote != null) { depth[i] = -1; if (ch === '\\') { depth[++i] = -1 } else if (ch === quote) quote = null; continue }
+        else if (ch === '/' && text[i + 1] === '/') { comment = 'line'; depth[i] = -1; continue }
+        else if (ch === '/' && text[i + 1] === '*') { comment = 'block'; depth[i] = -1; continue }
+        else if (ch === "'" || ch === '"' || ch === '`') { quote = ch; depth[i] = -1; continue }
+        if (ch === '{' || ch === '[' || ch === '(') d++
+        else if (ch === '}' || ch === ']' || ch === ')') d--
+        depth[i] = d
+    }
+    return depth
+}
+
+/** every top level `identity` key of `defineRepo({…})`, as the offsets of
+ *  its `{…}` value (end exclusive), null when the value is not an object
+ *  literal. A key nested deeper, in a string or in a comment is not it */
+function identityKeys(text: string): { value: { start: number; end: number } | null }[] {
+    const depth = configDepths(text)
+    const out: { value: { start: number; end: number } | null }[] = []
+    for (const m of text.matchAll(KEY_RE)) {
+        const sep = /^[{,]/.test(m[0]) ? m.index : m.index - 1
+        if (sep < 0 || depth[sep] !== 1) continue
+        const at = m.index + m[0].length
+        if (text[at] !== '{') { out.push({ value: null }); continue }
+        let end = -1
+        for (let j = at; j < text.length; j++) if (depth[j] === 1 && text[j] === '}') { end = j + 1; break }
+        out.push({ value: end === -1 ? null : { start: at, end } })
+    }
+    return out
+}
+
+/** whether the text declares an `identity` key at all, readable or not */
+export const declaresIdentity = (text: string): boolean => identityKeys(text).length > 0
+
+/** the identity the config text declares, read without loading it: the page
+ *  rows and the daemon read many configs per poll */
+export function identityOfText(text: string): Identity | null {
+    const keys = identityKeys(text)
+    const v = keys.length === 1 ? keys[0]!.value : null
+    if (v == null) return null
+    const body = text.slice(v.start, v.end)
+    const light = /(['"]?)colorLight\1\s*:\s*['"`](#[0-9a-fA-F]{6})['"`]/.exec(body)?.[2]
+    const dark = /(['"]?)colorDark\1\s*:\s*['"`](#[0-9a-fA-F]{6})['"`]/.exec(body)?.[2]
+    return light == null || dark == null ? null : { colorLight: light.toLowerCase(), colorDark: dark.toLowerCase() }
+}
+
+/** the config text with `identity` set to these colours. Only that key
+ *  moves: an existing object value is replaced in place, a missing key lands
+ *  as the first key of `defineRepo({`, and every other byte stays. Throws
+ *  when the text holds the key twice, holds it with a value that is not an
+ *  object literal, or has no `defineRepo({` to write into */
+export function setIdentityText(text: string, id: Identity): string {
+    const bad = identityProblem(id)
+    if (bad != null) throw new Error(bad)
+    const q = /\bname\s*:\s*"/.test(text) && !/\bname\s*:\s*'/.test(text) ? '"' : "'"
+    const value = `{ colorLight: ${q}${id.colorLight.toLowerCase()}${q}, colorDark: ${q}${id.colorDark.toLowerCase()}${q} }`
+    const keys = identityKeys(text)
+    if (keys.length > 1) throw new Error('repo.config.ts declares `identity` more than once, set it by hand')
+    if (keys.length === 1) {
+        const v = keys[0]!.value
+        if (v == null) throw new Error('repo.config.ts declares `identity` as something other than `{ … }`, set it by hand')
+        return `${text.slice(0, v.start)}${value}${text.slice(v.end)}`
+    }
+    const lines = text.split('\n')
+    const open = lines.findIndex((l) => /defineRepo\(\s*\{/.test(l))
+    if (open === -1) throw new Error('repo.config.ts has no `defineRepo({` to write `identity` into, set it by hand')
+    const line = lines[open]!
+    if (/defineRepo\(\s*\{\s*$/.test(line)) {
+        const next = lines.slice(open + 1).find((l) => l.trim() !== '' && !/^\s*}/.test(l))
+        const pad = next != null ? /^(\s*)/.exec(next)![1]! : `${/^(\s*)/.exec(line)![1]!}    `
+        return [...lines.slice(0, open + 1), `${pad}identity: ${value},`, ...lines.slice(open + 1)].join('\n')
+    }
+    // a config on one line: the key goes right after the brace
+    lines[open] = line.replace(/defineRepo\(\s*\{\s*/, (m) => `${m}identity: ${value}, `)
+    return lines.join('\n')
+}

package/src/core/identity.ts

@@ -0,0 +1,91 @@
+// a repo's identity colours, from disk: the dominant saturated colour of its
+// rail icon (serve/project-gutter.ts ICON_FILES), else a hue hashed from its
+// name, written into repo.config.ts with only the `identity` key moving. SK024
+// warns when the key is missing, its fix and the daemon's load both call
+// ensureIdentity, and the page's two swatches reach writeIdentity.
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
+import sharp from 'sharp'
+import { atomicWrite } from './locked-write.ts'
+import { dominantHue, identityOfHue, identityOfName, identityOfText, identityProblem, setIdentityText, type Identity } from './identity-color.ts'
+import { ICON_FILES } from '../serve/project-gutter.ts'
+
+export const CONFIG_FILE = 'repo.config.ts'
+
+/** where a repo's own copy declares the config keys it knows */
+export const INSTALLED_CONFIG_SRC = 'node_modules/rvlib-shipkit/src/repo-config.ts'
+
+/** why the key cannot be written in this repo yet, or null. `source` is the
+ *  text of its own copy's repo-config.ts, null when it has none. A copy that
+ *  does not know the key would refuse it (its config load in ci, its
+ *  typecheck), so nothing writes it there. Read by capability, not version:
+ *  a linked copy is the source itself, whatever its package.json says */
+export const identityRefusal = (source: string | null): string | null =>
+    source != null && !source.includes("'identity'")
+        ? `its own rvlib-shipkit predates the identity key, so writing it would break that copy: update rvlib-shipkit first`
+        : null
+
+const installedSource = (root: string): string | null => {
+    try {
+        return readFileSync(join(root, INSTALLED_CONFIG_SRC), 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** the name the config declares, else the folder name */
+export const configName = (text: string, root: string): string => /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(text)?.[1] ?? basename(root)
+
+/** the colours an image's pixels suggest, or null when it is grey, unreadable
+ *  or a format sharp does not read (an .ico) */
+export async function identityOfImage(bytes: Uint8Array): Promise<Identity | null> {
+    try {
+        const { data } = await sharp(bytes).resize(64, 64, { fit: 'inside' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+        const d = dominantHue(data, 4)
+        return d == null ? null : identityOfHue(d.h, d.s)
+    } catch {
+        return null
+    }
+}
+
+/** the repo's icon file, first hit wins, repo-relative */
+export const iconFileOf = (root: string): string | null => ICON_FILES.find((f) => existsSync(join(root, f))) ?? null
+
+/** what the colours should be: from the icon when it has a colour, else from the name */
+export async function deriveIdentity(root: string, name: string, read: (rel: string) => Uint8Array | null = (rel) => readFileSync(join(root, rel))): Promise<{ id: Identity; from: string }> {
+    const icon = iconFileOf(root)
+    if (icon != null) {
+        const bytes = read(icon)
+        const id = bytes == null ? null : await identityOfImage(bytes)
+        if (id != null) return { id, from: icon }
+    }
+    return { id: identityOfName(name), from: `the name '${name}'` }
+}
+
+/** the config with valid colours: derived and written when the key is
+ *  missing or malformed, the text left byte for byte otherwise */
+export async function ensureIdentity(root: string): Promise<{ changed: boolean; id: Identity | null; from: string | null; refused?: string }> {
+    const path = join(root, CONFIG_FILE)
+    if (!existsSync(path)) return { changed: false, id: null, from: null }
+    const text = readFileSync(path, 'utf8')
+    const have = identityOfText(text)
+    if (have != null && identityProblem(have) == null) return { changed: false, id: have, from: null }
+    const refused = identityRefusal(installedSource(root))
+    if (refused != null) return { changed: false, id: identityOfName(configName(text, root)), from: null, refused }
+    const { id, from } = await deriveIdentity(root, configName(text, root))
+    atomicWrite(path, setIdentityText(text, id))
+    return { changed: true, id, from }
+}
+
+/** set the colours by hand; a value left out keeps what the config has */
+export function writeIdentity(root: string, next: Partial<Identity>): Identity {
+    const refused = identityRefusal(installedSource(root))
+    if (refused != null) throw new Error(refused)
+    const path = join(root, CONFIG_FILE)
+    const text = readFileSync(path, 'utf8')
+    const have = identityOfText(text) ?? identityOfName(configName(text, root))
+    const id = { colorLight: next.colorLight ?? have.colorLight, colorDark: next.colorDark ?? have.colorDark }
+    const out = setIdentityText(text, id)
+    if (out !== text) atomicWrite(path, out)
+    return { colorLight: id.colorLight.toLowerCase(), colorDark: id.colorDark.toLowerCase() }
+}