rvlib-shipkit 0.22.1 → 0.23.0

package/src/rules/SK006-npm-publish-safety.ts

@@ -14,9 +14,23 @@
 // and sanctioned sub-lib publishing must not turn this rule red.
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { resolveUnits } from '../release/units.ts'
 import type { Rule } from './rule.ts'
 
-type Pkg = { name?: string; private?: boolean; publishConfig?: unknown; scripts?: Record<string, string> }
+type Pkg = {
+    name?: string
+    private?: boolean
+    publishConfig?: unknown
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+}
+
+/** protocols that resolve to a path on THIS machine. In a block a consumer
+ *  installs, they are unresolvable: the published package is broken on
+ *  arrival, and it fails at install time for a stranger, never here. */
+const LOCAL_PROTOCOL = /^(link|file|portal|workspace):/
 
 export const npmPublishSafety: Rule = {
     id: 'SK006',
@@ -28,7 +42,27 @@ export const npmPublishSafety: Rule = {
         if (!existsSync(p)) return t.ok('no package.json — nothing publishable')
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { return t.note('package.json unreadable — SK001 reports it') }
-        if (pkg.name?.startsWith('rvlib-') === true) return t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+        // every block a CONSUMER resolves, for every unit that can publish:
+        // the ROOT is usually private, so scanning it alone guards nothing
+        const localHits: string[] = []
+        for (const u of [{ dir: env.root, id: 'root' }, ...resolveUnits(env.root, env.config).units.filter((x) => x.rel !== '')]) {
+            const up = join(u.dir, 'package.json')
+            if (!existsSync(up)) continue
+            let upkg: Pkg
+            try { upkg = JSON.parse(readFileSync(up, 'utf8')) as Pkg } catch { continue }
+            if (upkg.private === true) continue
+            for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
+                for (const [dep, range] of Object.entries(upkg[block] ?? {}))
+                    if (LOCAL_PROTOCOL.test(range)) localHits.push(`${u.id}: ${block}.${dep} = ${range}`)
+        }
+        if (localHits.length > 0)
+            t.fail(
+                `${localHits.join(', ')} — a local protocol cannot resolve on a consumer's machine, so publishing that ships a package which fails at install. Declare the version it WILL be, and keep the local wiring in overrides (npm ignores those from a dependency) or in devDependencies`,
+            )
+        if (pkg.name?.startsWith('rvlib-') === true) {
+            if (localHits.length === 0) t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+            return
+        }
         if (pkg.private !== true) return t.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')
@@ -38,6 +72,6 @@ export const npmPublishSafety: Rule = {
             machinery.push(`scripts.publish (runs npm/bun publish)`)
         if (machinery.length > 0)
             t.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
-        else t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root`)
+        else if (localHits.length === 0) t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root, no local dependency protocol in any unit`)
     },
 }

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

@@ -0,0 +1,77 @@
+// SK011 — a dependency range on a SIBLING release unit must be satisfied by
+// the version that sibling actually carries (build/shipkit.md, release units).
+//
+// The failure it exists for: one unit is edited and its dependents keep a
+// range that names a version nobody published, or an older one that lacks the
+// code they now call. Both are invisible until a consumer installs, which is
+// the worst place to find out. `shipkit bump` moves these ranges forward on
+// every bump, so a red here means someone hand-edited a range, or a bump was
+// interrupted.
+//
+// Local protocols (link:, file:) are SK006's story, not this rule's.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { resolveUnits } from '../release/units.ts'
+import type { Rule } from './rule.ts'
+
+type Pkg = {
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+}
+
+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. */
+export function satisfiesSimple(version: string, range: string): boolean | null {
+    const v = version.match(/^(\d+)\.(\d+)\.(\d+)/)
+    const r = range.trim().match(/^([\^~]?)(\d+)\.(\d+)\.(\d+)$/)
+    if (v == null || r == null) return null
+    const [, op, RA, RI, RP] = r as unknown as [string, string, string, string, string]
+    const [va, vi, vp] = [Number(v[1]), Number(v[2]), Number(v[3])]
+    const [ra, ri, rp] = [Number(RA), Number(RI), Number(RP)]
+    const atLeast = va > ra || (va === ra && (vi > ri || (vi === ri && vp >= rp)))
+    if (op === '^') {
+        // caret on 0.x pins the MINOR: ^0.1.4 accepts 0.1.9, never 0.2.0
+        if (ra === 0) return va === 0 && vi === ri && atLeast
+        return va === ra && atLeast
+    }
+    if (op === '~') return va === ra && vi === ri && atLeast
+    return va === ra && vi === ri && vp === rp
+}
+
+export const siblingUnitRanges: Rule = {
+    id: 'SK011',
+    blocking: true,
+    title: 'sibling unit ranges',
+    owner: 'build/shipkit.md',
+    lint: (t, env) => {
+        const { units } = resolveUnits(env.root, env.config)
+        const version = new Map(units.map((u) => [u.name, u.version]))
+        if (units.length < 2) return t.ok('one release unit — no sibling ranges to keep honest')
+        const bad: string[] = []
+        let checked = 0
+        for (const u of units) {
+            const p = join(u.dir, 'package.json')
+            if (!existsSync(p)) continue
+            let pkg: Pkg
+            try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { continue }
+            for (const block of BLOCKS)
+                for (const [dep, range] of Object.entries(pkg[block] ?? {})) {
+                    const actual = version.get(dep)
+                    if (actual == null) continue
+                    if (/^(link|file|portal|workspace):/.test(range)) continue
+                    const ok = satisfiesSimple(actual, range)
+                    if (ok == null) continue
+                    checked++
+                    if (!ok) bad.push(`${u.id}: ${block}.${dep} wants ${range}, ${dep} is ${actual}`)
+                }
+        }
+        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`)
+    },
+}

package/src/rules/rule-registry.ts

@@ -13,6 +13,7 @@ import { githubVisibility } from './SK007-github-visibility.ts'
 import { reviewerAgent } from './SK008-reviewer-agent.ts'
 import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
+import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -25,6 +26,7 @@ export const RULES: readonly Rule[] = [
     reviewerAgent,
     commitAiTells,
     undeclaredReleaseUnit,
+    siblingUnitRanges,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

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

@@ -129,7 +129,7 @@ export class ColsSvc {
     async remark(body: Record<string, unknown>): Promise<void> {
         const text = this.remarkDraft.trim()
         if (text === '') return
-        // draft survives a failed send — his words are never erased
+        // draft survives a failed send, so nothing typed is ever erased
         const ok = await this.act('remark', { ...body, text })
         if (ok) runInAction(() => { this.remarkDraft = '' })
     }

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

@@ -173,7 +173,7 @@ const Palette = observer(() => {
     )
 })
 
-// remark box on the ASSET view too — his words land in .rv-assets/notes.md
+// remark box on the ASSET view too: remarks land in .rv-assets/notes.md
 // and come back as `remarks` (exchange both ways, media included)
 const AssetRemarks = observer(() => {
     const m = app.media

package/src/serve/run-serve.ts

@@ -27,9 +27,14 @@ export function defaultHubPort(name: string): number {
 }
 
 export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
+    // the default wiki graph exists only when the repo HAS a wiki dir: a
+    // game repo's hub advertising a wiki route was startup noise
+    // 2026-08-05). A config-declared wikiGraph always mounts.
     const wikiGraph = c.serve?.wikiGraph != null
         ? { title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load }
-        : { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
+        : existsSync(join(root, 'wiki'))
+            ? { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
+            : null
     const agentRoot = join(root, 'agent')
     const agentGraph = existsSync(agentRoot)
         ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
@@ -104,10 +109,13 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     try {
         const hub = serveHub(deps)
         const base = `http://localhost:${hub.server.port}`
-        io.print(`ok: ${c.name} hub → ${base}`)
-        for (const t of hub.tools) io.print(`ok: ${t.label} → ${base}${t.path}`)
+        // a banner, not a checklist: one clickable line, then what is inside,
+        // dimmed by indentation. Wire prefixes stay reserved for problems.
+        io.print(`${c.name} hub → ${base}`)
+        const routes = hub.tools.filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
+        if (routes !== '') io.print(`  also: ${routes}`)
         // the off-machine door (phone, other machines) — publicHost is config
-        if (c.serve?.publicHost != null) io.print(`ok: public → http://${c.serve.publicHost}:${hub.server.port}/`)
+        if (c.serve?.publicHost != null) io.print(`  phone: http://${c.serve.publicHost}:${hub.server.port}/`)
         await new Promise(() => {}) // the hub owns the process — never resolve
         return 0
     } catch (e) {
@@ -120,8 +128,9 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             if (owner?.hub === 'shipkit' && owner.name === c.name) {
                 // a re-run terminal stays as clickable as a first run — the
                 // owner's /hub.json tool list is the same source of truth
-                io.print(`ok: hub already served → http://localhost:${deps.port} (another window owns it)`)
-                for (const t of owner.tools ?? []) io.print(`ok: ${t.label} → http://localhost:${deps.port}${t.path}`)
+                io.print(`${c.name} hub → http://localhost:${deps.port} (already running in another window)`)
+                const routes = (owner.tools ?? []).filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
+                if (routes !== '') io.print(`  also: ${routes}`)
                 return 0
             }
             io.printErr(`FAIL: port ${deps.port} is taken by ${owner?.name != null ? `repo '${owner.name}'` : 'another process'} — set serve: { port } in repo.config.ts to a free one`)

package/src/serve/serve-hub.ts

@@ -19,7 +19,8 @@ export type HubDeps = {
     name: string
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
-    wikiGraph: HubGraph
+    /** null = this repo has no wiki to graph — the route stays unmounted */
+    wikiGraph: HubGraph | null
     /** null = no agent/ dir */
     agentGraph: HubGraph | null
     /** the media API (mounted under /media/*); null only if the route
@@ -44,7 +45,7 @@ export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop
 // so they can never disagree
 export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph'>): HubTool[] {
     const tools: HubTool[] = [{ path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' }]
-    tools.push({ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title })
+    if (d.wikiGraph != null) tools.push({ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title })
     if (d.agentGraph != null) tools.push({ path: '/graph/agent', label: 'agent graph', desc: d.agentGraph.title })
     return tools
 }
@@ -98,8 +99,8 @@ export function serveHub(d: HubDeps): Hub {
                     }
                     else if (path === '/api/act/post-feedback') appendPostFeedback(d.root, b.channel ?? '', b.file ?? '', b.text ?? '')
                     else if (path === '/api/act/remark') {
-                        // ONE remark verb, routed by collection — his words
-                        // land in the item's own truth file
+                        // ONE remark verb, routed by collection: a remark
+                        // lands in the item's own truth file
                         const text = (b.text ?? '').trim()
                         if (text === '') return new Response('empty remark', { status: 400 })
                         if (b.kind === 'ask') appendAskRemark(d.root, d.asksDir, b.file ?? '', text)
@@ -124,8 +125,8 @@ export function serveHub(d: HubDeps): Hub {
                 return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
             }
             const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
-            if (path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
-            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
+            if (d.wikiGraph != null && path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
+            if (d.wikiGraph != null && path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
             if (d.agentGraph != null && path === '/graph/agent') return page(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
             if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
             // the media API namespace — the studio route table, ONE prefix strip

package/src/start-repo.ts

@@ -71,8 +71,8 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     // 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.
-    // --skip means shipkit NEVER TOUCHES that repo (his job repo lives on
-    // this list), not just no CLAUDE.md. And the cd contract survives a
+    // --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.
     if (!(opts.skip ?? []).includes(name)) {
         // git BEFORE the shipkit scaffold, and whether or not the dir is a

package/src/ts/config.ts

@@ -0,0 +1,185 @@
+// shared config for every rvt tool. Convention: the repo uses absolute
+// import specifiers with explicit extensions — repo-root paths
+// ('src/foo/Bar.ts') in single-package repos; in multi-package repos, files
+// living inside a sub-package (own package.json with a name) are addressed by
+// package name instead ('rvlib-x/src/foo.ts'), so published source resolves
+// identically for npm consumers. Sub-packages are auto-discovered by walking
+// the roots. Config sources, in order:
+//   1. package.json "rvt" field: { roots?: string[], skip?: string[] }
+//      (roots entries may be top-level globs like "rv-*")
+//   2. tsconfig "paths" keys ("src/*" → root 'src') when roots are not set
+//   3. fallback: ['src', 'scripts']
+// skip entries are repo-relative dir prefixes; the defaults below always apply.
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+export type RvtPackage = {
+   name: string // package.json "name" — the import root for files inside
+   dir: string // repo-relative posix dir of the package
+}
+
+export type RvtConfig = {
+   root: string // absolute repo root
+   roots: string[] // repo-relative dirs to crawl / allowed specifier roots
+   skip: string[] // repo-relative dir prefixes to never touch
+   packages: RvtPackage[] // discovered sub-packages, longest dir first
+}
+
+/** never source, at any depth */
+export const ALWAYS_SKIP = ['node_modules', '.git']
+/** build OUTPUT, and only where output lands: the repo root or a package root.
+ *  Matched at any depth these swallow real source, and a tree like
+ *  `wiki/build/<lib>/src` becomes invisible to every scan (field: a rename
+ *  that rewrote zero references and reported success) */
+export const ARTIFACT_SKIP = ['dist', 'build', 'cjs', 'out']
+export const DEFAULT_SKIP = [...ALWAYS_SKIP, ...ARTIFACT_SKIP]
+
+export function findRepoRoot(cwd: string = process.cwd()): string {
+   const p = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], { cwd, stdout: 'pipe', stderr: 'ignore' })
+   const out = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+   return out !== '' ? out : cwd
+}
+
+// tsconfig files are JSONC — strip comments + trailing commas, loosely
+function parseJsonc(text: string): unknown {
+   const noComments = text
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:])\/\/[^\n]*/g, '$1') // keep 'http://...' intact
+   return JSON.parse(noComments.replace(/,\s*([}\]])/g, '$1'))
+}
+
+function rootsFromTsconfig(root: string): string[] {
+   for (const name of ['tsconfig.base.json', 'tsconfig.json']) {
+      const p = join(root, name)
+      if (!existsSync(p)) continue
+      try {
+         const cfg = parseJsonc(readFileSync(p, 'utf8')) as { compilerOptions?: { paths?: Record<string, unknown> } }
+         const keys = Object.keys(cfg.compilerOptions?.paths ?? {})
+         // "src/*" → 'src'; ignore package-fixup mappings like "some-dep"
+         const roots = keys.filter((k) => k.endsWith('/*')).map((k) => k.slice(0, -2)).filter((k) => !k.includes('/') && existsSync(join(root, k)))
+         if (roots.length > 0) return roots
+      } catch {
+         // unparseable tsconfig → fall through to the next source
+      }
+   }
+   return []
+}
+
+// "rv-*" style entries expand against top-level dirs; plain entries pass through
+function expandRootGlobs(root: string, roots: string[]): string[] {
+   const out: string[] = []
+   for (const r of roots) {
+      if (!r.includes('*')) {
+         out.push(r)
+         continue
+      }
+      const re = new RegExp(`^${r.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`)
+      for (const e of readdirSync(root)) {
+         // statSync try: a dangling top-level symlink must not crash every rvt command
+         let isDir = false
+         try {
+            isDir = statSync(join(root, e)).isDirectory()
+         } catch {}
+         if (re.test(e) && isDir) out.push(e)
+      }
+   }
+   return [...new Set(out)].sort()
+}
+
+// sub-package discovery: any dir under the roots with a named package.json is
+// its own import root (files inside address each other via the package name)
+function discoverPackages(root: string, roots: string[], skip: string[]): RvtPackage[] {
+   const found: RvtPackage[] = []
+   const cfg = { root, roots, skip, packages: [] }
+   const walk = (rel: string): void => {
+      const abs = join(root, rel)
+      let entries
+      try {
+         entries = readdirSync(abs, { withFileTypes: true })
+      } catch {
+         return
+      }
+      const pkgFile = join(abs, 'package.json')
+      if (existsSync(pkgFile)) {
+         try {
+            const name = (JSON.parse(readFileSync(pkgFile, 'utf8')) as { name?: string }).name
+            if (name != null && name !== '') found.push({ name, dir: rel })
+         } catch {
+            // unparseable sub-package manifest → not a package boundary
+         }
+      }
+      for (const e of entries) {
+         if (e.isDirectory() && !isSkipped(`${rel}/${e.name}`, cfg)) walk(`${rel}/${e.name}`)
+      }
+   }
+   for (const r of roots) if (existsSync(join(root, r))) walk(r)
+   // longest dir first: nested packages resolve to the innermost boundary
+   return found.sort((a, b) => b.dir.length - a.dir.length)
+}
+
+export function loadConfig(cwd: string = process.cwd()): RvtConfig {
+   const root = findRepoRoot(cwd)
+   let roots: string[] = []
+   let skip: string[] = []
+   const pkgPath = join(root, 'package.json')
+   if (existsSync(pkgPath)) {
+      try {
+         const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { rvt?: { roots?: string[]; skip?: string[] } }
+         roots = pkg.rvt?.roots ?? []
+         skip = pkg.rvt?.skip ?? []
+      } catch {
+         // unparseable package.json → defaults
+      }
+   }
+   if (roots.length === 0) roots = rootsFromTsconfig(root)
+   if (roots.length === 0) roots = ['src', 'scripts'].filter((r) => existsSync(join(root, r)))
+   roots = expandRootGlobs(root, roots)
+   const mergedSkip = [...DEFAULT_SKIP, ...skip]
+   const packages = discoverPackages(root, roots, mergedSkip)
+   // a package named like a root (or another package) hijacks that specifier
+   // prefix — resolution would silently diverge from tsc/bun; be loud
+   const seen = new Set<string>(roots)
+   for (const p of packages) {
+      if (seen.has(p.name)) console.error(`rvt WARN: package name '${p.name}' (${p.dir}) collides with a root or another package — its specifiers may resolve wrong`)
+      seen.add(p.name)
+   }
+   return { root, roots, skip: mergedSkip, packages }
+}
+
+// innermost package containing a repo-relative path, or null
+export function packageFor(relPath: string, cfg: RvtConfig): RvtPackage | null {
+   const n = toPosix(relPath)
+   return cfg.packages.find((p) => n === p.dir || n.startsWith(`${p.dir}/`)) ?? null
+}
+
+// canonical specifier for a repo-relative file: package-name form when the
+// file lives inside a sub-package, repo-root form otherwise
+export function canonicalSpecifier(relPath: string, cfg: RvtConfig): string {
+   const pkg = packageFor(relPath, cfg)
+   return pkg == null ? toPosix(relPath) : `${pkg.name}${toPosix(relPath).slice(pkg.dir.length)}`
+}
+
+// resolve a package-name specifier ('rvlib-x/src/a.ts') back to a
+// repo-relative path, or null when no discovered package matches
+export function resolvePackageSpecifier(spec: string, cfg: RvtConfig): string | null {
+   const pkg = cfg.packages.find((p) => spec === p.name || spec.startsWith(`${p.name}/`))
+   return pkg == null ? null : `${pkg.dir}${spec.slice(pkg.name.length)}`
+}
+
+export const toPosix = (p: string): string => p.replace(/\\/g, '/')
+
+// entries with a slash ('src/legacy') match as repo-relative prefixes. A bare
+// name matches any segment when it is never source (node_modules, .git), and
+// only at a package boundary when it names build OUTPUT: `dist` under a
+// package root is output, `wiki/build/<lib>/src` is source.
+export function isSkipped(relPath: string, cfg: RvtConfig, packageDirs: readonly string[] = []): boolean {
+   const n = toPosix(relPath)
+   const segs = n.split('/')
+   return cfg.skip.some((s) => {
+      if (s.includes('/')) return n === s || n.startsWith(`${s}/`)
+      if (!ARTIFACT_SKIP.includes(s)) return segs.includes(s)
+      // output dir: at the repo root, or directly inside a known package
+      if (segs[0] === s) return true
+      return packageDirs.some((d) => n === `${d}/${s}` || n.startsWith(`${d}/${s}/`))
+   })
+}