@estiva-app/ui 0.27.0 → 0.29.0

package/src/gates/token-lint.ts

@@ -16,6 +16,9 @@
  *   inline style that sets a colour (errors); heights, spacing and border
  *   widths written by hand (warnings, never blocking).
  *
+ * And `tokenConfig`, the two on their own as an app's `lint:tokens` runs them
+ * (UIG-37), with TypeScript's rule names known so its directives pass.
+ *
  * The patterns are the same for everyone. Only the words differ: an app is told
  * to use "the package", the package is told to add the token to `tokens.css`.
  * Measured on 17 September: the UIG-28 block was byte for byte the same in Peek
@@ -32,10 +35,10 @@
  */
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
-import type { Linter } from 'eslint'
+import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults'
-import { parser as typescriptParser } from 'typescript-eslint'
+import { parser as typescriptParser, plugin as typescriptPlugin } from 'typescript-eslint'
 
 /** Who reads the messages. */
 export type TokenAudience = 'app' | 'package'
@@ -47,9 +50,30 @@ export interface TokenLintOptions {
   audience?: TokenAudience
 }
 
+export interface TokenConfigOptions extends TokenLintOptions {
+  /**
+   * Plugins whose `eslint-disable` directives appear in the source, registered
+   * with every rule off. ESLint refuses a directive for a rule it does not
+   * know. TypeScript's are registered already.
+   */
+  quiet?: Record<string, ESLint.Plugin>
+  /** Folders the token lint never reads, beside build output. */
+  ignores?: string[]
+}
+
 /** What the token lint never reads: build output. */
 export const TOKEN_LINT_IGNORES = ['dist/', 'storybook-static/', 'node_modules/']
 
+/**
+ * Plugins a check that runs on its own registers, every rule off, so the
+ * directives another lint writes do not fail it (UIG-37). TypeScript's lint is
+ * in every app and writes `eslint-disable-next-line @typescript-eslint/...`;
+ * Peek PR #324 failed the token lint on one. Only the checks that run alone
+ * take this — a full lint that loads TypeScript's rules from its own copy would
+ * refuse a second plugin under the same name.
+ */
+export const KNOWN_PLUGINS: Record<string, ESLint.Plugin> = { '@typescript-eslint': typescriptPlugin as ESLint.Plugin }
+
 const CLASS_MAP_SELECTOR = {
   kind: 'variable',
   name: '^(?:[A-Z][A-Z0-9_]*_(?:STYLES|CLASSES)|[a-z][a-zA-Z0-9]*(?:Styles|Classes))$',
@@ -229,3 +253,24 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
     },
   }
 }
+
+/**
+ * The token lint on its own — an app's `eslint.tokens.config.js`, `npm run
+ * lint:tokens`, the CI step. It fails on the token contract and on nothing
+ * else, so a backlog in the full lint never blocks it. Peek built this file by
+ * hand until UIG-37.
+ */
+export function tokenConfig({ quiet = {}, ignores = [], ...options }: TokenConfigOptions = {}): Linter.Config[] {
+  return [
+    { ignores: [...TOKEN_LINT_IGNORES, ...ignores] },
+    {
+      plugins: { ...KNOWN_PLUGINS, ...quiet },
+      // Every other lint's directives are unused here, because their rules are
+      // off here. Reporting them would be this config complaining about the
+      // others' business.
+      linterOptions: { reportUnusedDisableDirectives: 'off' },
+    },
+    tokenLint(options),
+    tokenValues({ audience: options.audience }),
+  ]
+}

package/src/registry/app.test.ts

@@ -526,6 +526,25 @@ describe('one search over the package and the apps', () => {
     expect(found.indexOf('estiva-ui:EmptyState')).toBeLessThan(found.indexOf('fixture:EmptyState'))
   })
 
+  it("puts a package part whose name carries a word before an app's part answering as many (UIG-20)", () => {
+    // "panel header" put an app's own `Header` above the package's `ContainerHeader`: its whole name is one of the words.
+    const header = buildAppRegistry({
+      root: app({ 'src/Header.tsx': '/** The top row of a panel: its title and its buttons. */\nexport function Header() {\n  return <header />\n}\n' }),
+      repo: 'fixture',
+    })
+    const found = findInRegistries([packageRegistry, header], 'panel header', { limit: 5 }).map((f) => `${f.entry.repo}:${f.entry.name}`)
+    expect(found[0]).toBe('estiva-ui:ContainerHeader')
+    expect(found).toContain('fixture:Header')
+  })
+
+  it("does not let a package part the words reach only through its notes bury the app's answer", () => {
+    const composer = buildAppRegistry({
+      root: app({ 'src/Composer.tsx': '/** Where a comment is written and sent. */\nexport function Composer() {\n  return <form />\n}\n' }),
+      repo: 'fixture',
+    })
+    expect(findInRegistries([packageRegistry, composer], 'comment composer')[0].entry).toMatchObject({ repo: 'fixture', name: 'Composer' })
+  })
+
   it('says which apps hand a package part on, and how a default is imported', () => {
     const text = formatFindings([packageRegistry, registry], findInRegistries([packageRegistry, registry], 'Button', { limit: 1 }), 'Button')
     expect(text).toContain('fixture hands it on from @/components/ui/Button')
@@ -554,10 +573,48 @@ describe.skipIf(!existsSync(cli))('estiva-ui in an app', () => {
     }
     expect(failed.stdout).toMatch(/^fixture: 17 parts in 15 files \(2 more hold none\)/)
     expect(failed.stderr).toContain('Timeline (reusable, src/components/Timeline.tsx) has no usage page: write src/components/Timeline.mdx')
-    const one = app({ 'src/One.tsx': '/** One, drawn once. */\nexport function One() {\n  return <i />\n}\n' })
+    const one = app({ 'src/One.tsx': '/** One, drawn once. */\nexport function One() {\n  return <i />\n}\n', 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    run(['skill'], one)
     expect(run(['check'], one)).toContain('usage pages: all 0 reusable parts keep the contract')
   })
 
+  it('skill writes a loader that reads the installed package, and check fails when it is missing or differs (UIG-20)', () => {
+    const two = app({ 'src/Two.tsx': '/** Two, drawn once. */\nexport function Two() {\n  return <i />\n}\n', 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    const failure = (cwd: string) => {
+      try {
+        run(['check'], cwd)
+      } catch (error) {
+        return (error as { stderr?: string }).stderr ?? ''
+      }
+      return ''
+    }
+    expect(failure(two)).toContain('.claude/skills/estiva-ui/SKILL.md is missing: run "estiva-ui skill" and commit it')
+    run(['skill'], two)
+    const loader = readFileSync(join(two, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), 'utf8')
+    expect(loader).toMatch(/^---\nname: estiva-ui\ndescription: "Use before building/)
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    expect(JSON.parse(readFileSync(join(two, '.claude', 'settings.json'), 'utf8')).permissions.allow).toContain('Bash(npm run ui:find *)')
+    // Its text is the package's, never a copy.
+    expect(loader).not.toContain('# The skill')
+    expect(run(['check'], two)).toContain('claude skill: the loader reads the package’s text')
+    writeFileSync(join(two, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), `${loader}\nA line of our own.\n`)
+    expect(failure(two)).toContain('SKILL.md is not what the package writes')
+  })
+
+  it('skill --out writes a loader for a folder that holds the repositories, reading an app inside it', () => {
+    const holder = mkdtempSync(join(tmpdir(), 'uig20-holder-'))
+    made.push(holder)
+    mkdirSync(join(holder, 'one', 'node_modules', '@estiva-app', 'ui', 'skill'), { recursive: true })
+    writeFileSync(join(holder, 'one', 'package.json'), JSON.stringify({ name: 'one' }))
+    writeFileSync(join(holder, 'one', 'node_modules', '@estiva-app', 'ui', 'skill', 'estiva-ui.md'), '# The skill\n')
+    run(['skill', '--out', '..'], join(holder, 'one'))
+    const loader = readFileSync(join(holder, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), 'utf8')
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/one/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    // Claude Code refuses a path that climbs out with `..`, so a folder that does not hold the app is refused here.
+    const elsewhere = app({ 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    expect(() => run(['skill', '--out', holder], elsewhere)).toThrow(/does not hold/)
+  })
+
   it("find searches the app and the package, and never takes an app's own registry.json for the package's", () => {
     // What `estiva-ui build` leaves behind in an app, and git ignores.
     run(['build'], root)

package/src/registry/cli.ts

@@ -3,9 +3,10 @@
  * `estiva-ui` — the catalogue as a command (UIG-12, UIG-13; docs/GATES.md §23
  * for why it ships in the package rather than as a script pasted into each repo).
  *
- *   estiva-ui find <words…> [--also [name=]<folder>]… [--json] [--limit n]
+ *   estiva-ui find <words…> [--here | --also [name=]<folder>…] [--json] [--limit n]
  *   estiva-ui build [--out <path>]
  *   estiva-ui check
+ *   estiva-ui skill [--out <folder>]
  *
  * Every command takes `--root <folder>` (the library it reads; default: here)
  * and `--repo <name>` (what an app's entries are called; default: its package name).
@@ -21,15 +22,23 @@
  *
  * `find` searches the package's catalogue — the one shipped inside the installed
  * package, or this repo's own in the package — plus, in an app, the app's own,
- * built fresh, plus each `--also` app that sits beside it.
+ * built fresh, plus every app beside it (UIG-20, `./siblings`): found, not
+ * named, so one command answers the same from any repository, or from the
+ * folder that holds them. `--here` searches no neighbour; `--also` names them.
+ *
+ * `skill` writes the repository's Claude skill loader (UIG-20, `./skill`), or
+ * the one for `--out <folder>`; `check` fails when the repository's is missing
+ * or differs.
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { basename, join, resolve } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { CONTRACT_KINDS, contractProblems, linkProblems } from './contract'
 import { findInRegistries, formatFindings } from './find'
+import { findSiblings, workspaceOf } from './siblings'
+import { loaderPath, loaderProblem, loaderText, repositoryOf, settingsPath, settingsWithSearch } from './skill'
 import { CLASSES, validateRegistry, type Registry } from './schema'
 
 /**
@@ -91,6 +100,20 @@ function readPackageRegistry(): Registry {
   return registry
 }
 
+/** The installed package whose skill text a loader reads: this repo in the package, else the app's install. */
+const packageRoot = () => (isPackage ? root : resolve(root, 'node_modules', '@estiva-app', 'ui'))
+
+/** The Claude skill loader (UIG-20): reports, and says whether it passed. */
+function checkLoader(): boolean {
+  const problem = loaderProblem(repositoryOf(root), packageRoot())
+  if (problem) {
+    process.stderr.write(`claude skill: ${problem}\n`)
+    return false
+  }
+  process.stdout.write('claude skill: the loader reads the package’s text\n')
+  return true
+}
+
 async function buildApp(folder: string, repo: string | undefined): Promise<Registry> {
   const { buildAppRegistry } = await appBuilder()
   const registry = buildAppRegistry({ root: folder, repo })
@@ -179,7 +202,13 @@ async function main(): Promise<number> {
           process.stderr.write(`not searched: ${first}${more.length ? `\n${more.slice(0, 3).join('\n')}${more.length > 3 ? `\n  …and ${more.length - 3} more — run "estiva-ui check" there` : ''}` : ''}\n`)
         }
       }
-      if (!isPackage) await add(root, value('repo'))
+      // The folder it runs in is searched when it is an app; the folder that
+      // holds the repositories is not one, and only its neighbours answer.
+      const here = !isPackage && existsSync(resolve(root, 'package.json')) ? (manifestAt(root).name ?? basename(root)) : null
+      if (here) await add(root, value('repo'))
+      if (!values('also').length && !flag('here')) {
+        for (const sibling of findSiblings(workspaceOf(root), { skip: here ? [here] : [] })) await add(sibling.folder, sibling.name)
+      }
       for (const also of values('also')) {
         const [name, folder] = also.includes('=') ? [also.slice(0, also.indexOf('=')), also.slice(also.indexOf('=') + 1)] : [undefined, also]
         const at = resolve(root, folder)
@@ -236,7 +265,8 @@ async function main(): Promise<number> {
         }
         const linked = checkLinks(registry, root)
         const shown = await checkGated(registry, root)
-        return broken.length || !linked || !shown ? 1 : 0
+        const loaded = checkLoader()
+        return broken.length || !linked || !shown || !loaded ? 1 : 0
       }
       const { buildRegistry, serializeRegistry } = await packageBuilder()
       const path = packageRegistryPath()
@@ -259,11 +289,33 @@ async function main(): Promise<number> {
       process.stdout.write(`${path}: current, ${built.entries.length} entries from ${built.builtFrom.exports} exports\n`)
       const linked = checkLinks(built, root)
       const shown = await checkGated(built, root, ['component'])
-      return linked && shown ? 0 : 1
+      const loaded = checkLoader()
+      return linked && shown && loaded ? 0 : 1
+    }
+
+    case 'skill': {
+      const out = value('out')
+      const folder = out ? resolve(out) : repositoryOf(root)
+      // The loader's path starts where the session does and cannot climb out:
+      // Claude Code refuses a `..` in it.
+      if (relative(folder, packageRoot()).startsWith('..')) {
+        process.stderr.write(`${folder} does not hold ${packageRoot()}: a loader there could not reach the skill's text\n`)
+        return 1
+      }
+      const path = loaderPath(folder)
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, loaderText(folder, packageRoot()), 'utf8')
+      process.stdout.write(`${path}: the Claude skill, read from ${packageRoot()}\n`)
+      const settings = settingsWithSearch(folder)
+      if (settings) {
+        writeFileSync(settingsPath(folder), settings, 'utf8')
+        process.stdout.write(`${settingsPath(folder)}: the search allowed without a prompt\n`)
+      }
+      return 0
     }
 
     default:
-      process.stderr.write('estiva-ui <find | build | check>\n')
+      process.stderr.write('estiva-ui <find | build | check | skill>\n')
       return 1
   }
 }

package/src/registry/find.ts

@@ -96,6 +96,11 @@ export function findInRegistry(registry: Registry, query: string, { limit = 5 }:
  * An app's pass-on is not a result of its own — it is the package's part, and
  * the package's entry answers for it, saying which apps hand it on. At the
  * same strength the package's part comes first: it is the one to reach for.
+ * And a package part whose name carries one of the words comes before an app's
+ * part answering as many words, whatever each scored: "panel header" put an
+ * app's own `Header`, whose whole name is one of the words, above the package's
+ * `ContainerHeader` (UIG-20). Only by name: a package part the words reach
+ * through its notes alone would bury the app part that is the answer.
  */
 export function findInRegistries(registries: Registry[], query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
   const all = words(query)
@@ -162,7 +167,11 @@ export function findInRegistries(registries: Registry[], query: string, { limit
   }
 
   const fromPackage = (finding: Finding) => (finding.entry.app === null ? 0 : 1)
-  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name))
+  const namedInPackage = (finding: Finding) => (finding.entry.app === null && finding.where.includes('name') ? 0 : 1)
+  findings.sort(
+    (a, b) =>
+      b.matched - a.matched || namedInPackage(a) - namedInPackage(b) || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name),
+  )
   return findings.slice(0, limit)
 }
 

package/src/registry/siblings.test.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+/**
+ * UIG-20: the apps beside this one, found rather than named. The folder below
+ * is the shape of the real one: two apps (one inside a `web/` folder), a
+ * service that does not install the package, a worktree and somebody's copy of
+ * an app, and the package itself.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { appName, findSiblings, workspaceOf } from './siblings'
+
+const workspace = mkdtempSync(join(tmpdir(), 'uig20-'))
+afterAll(() => rmSync(workspace, { recursive: true, force: true }))
+
+const UI = { '@estiva-app/ui': '^0.28.0' }
+function put(path: string, text: string) {
+  mkdirSync(dirname(join(workspace, path)), { recursive: true })
+  writeFileSync(join(workspace, path), text)
+}
+function appAt(folder: string, name: string, deps: Record<string, string> = UI, part = 'Part') {
+  put(`${folder}/package.json`, JSON.stringify({ name, dependencies: deps }))
+  put(`${folder}/src/${part}.tsx`, `/** The ${part.toLowerCase()} of ${name}. */\nexport function ${part}() {\n  return <i />\n}\n`)
+}
+// A repository is a folder with `.git`: a directory, or a worktree's file.
+appAt('alpha', 'alpha-app', UI, 'Tabletop')
+put('alpha/.git/HEAD', 'ref: refs/heads/main\n')
+put('beta/package.json', JSON.stringify({ name: 'beta' }))
+put('beta/.git/HEAD', 'ref: refs/heads/main\n')
+appAt('beta/web', 'beta-web', { ...UI }, 'Workbench')
+appAt('alpha-copy', 'alpha-app')
+put('alpha-copy/.git', 'gitdir: ../alpha/.git/worktrees/alpha-copy\n')
+appAt('beta-notes/web', 'beta-web')
+appAt('service', 'service', { react: '^19.0.0' })
+put('ui/package.json', JSON.stringify({ name: '@estiva-app/ui' }))
+mkdirSync(join(workspace, 'ui', 'src'), { recursive: true })
+
+describe('the apps beside this one', () => {
+  it('is an app only when it installs the package and has a src', () => {
+    expect(appName(join(workspace, 'alpha'))).toBe('alpha-app')
+    expect(appName(join(workspace, 'service'))).toBeNull()
+    expect(appName(join(workspace, 'ui'))).toBeNull()
+    expect(appName(join(workspace, 'beta'))).toBeNull()
+  })
+
+  it('finds the folder that holds the repositories, from inside one or from that folder itself', () => {
+    expect(workspaceOf(join(workspace, 'beta', 'web', 'src'))).toBe(workspace)
+    expect(workspaceOf(join(workspace, 'alpha-copy'))).toBe(workspace)
+  })
+
+  it('finds each app once, inside a web folder too, and never a second checkout of the same app', () => {
+    expect(findSiblings(workspace).map((s) => [s.name, s.packageName])).toEqual([
+      ['alpha', 'alpha-app'],
+      ['beta', 'beta-web'],
+    ])
+  })
+
+  it('leaves out the app the search runs in, so a worktree of it is not searched twice', () => {
+    expect(findSiblings(workspace, { skip: ['alpha-app'] }).map((s) => s.name)).toEqual(['beta'])
+  })
+})
+
+// The command, as a session runs it: `dist/` is what `npm test` builds first.
+const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'dist', 'registry', 'cli.js')
+describe.skipIf(!existsSync(cli))('estiva-ui find, with nothing else typed', () => {
+  const find = (cwd: string, ...words: string[]) =>
+    execFileSync(process.execPath, [cli, 'find', ...words], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+
+  it('searches every app beside the one it runs in', () => {
+    const out = find(join(workspace, 'alpha-copy'), 'workbench')
+    expect(out).toMatch(/^Workbench {2}· .* · {2}beta/m)
+  })
+
+  it('answers the same from the folder that holds them', () => {
+    expect(find(workspace, 'tabletop')).toMatch(/^Tabletop {2}· .* · {2}alpha/m)
+    expect(find(workspace, 'zzqqx')).toContain('Nothing in estiva-ui, alpha, beta matches')
+  })
+
+  it('searches no neighbour when told --here', () => {
+    expect(find(join(workspace, 'alpha'), 'workbench', '--here')).not.toContain('Workbench')
+  })
+})

package/src/registry/siblings.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+/**
+ * The apps beside this one, found rather than named (UIG-20).
+ *
+ * `estiva-ui find` with nothing else typed searches the package, the app it is
+ * run in, and every app that sits beside it. Katerina's condition for having no
+ * shared Storybook is that one search, run unasked from any repository, covers
+ * every catalogue; a list of names written into each repository's script would
+ * be the drifting copy the gates exist to remove, and would miss the next app.
+ *
+ * An app is a folder, or one folder inside it, whose `package.json` depends on
+ * `@estiva-app/ui` and which has a `src` to read. A service that does not
+ * install the package is not an app of this catalogue until it does.
+ *
+ * Each app is searched once. A second checkout of the same app (a worktree, or
+ * somebody's copy) carries the same package name; the app the search runs in
+ * wins, then the one whose top folder has the shortest name.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+export const PACKAGE_NAME = '@estiva-app/ui'
+
+export interface Sibling {
+  /** What its entries are called: its top folder's name. */
+  name: string
+  /** The folder the catalogue is built from. */
+  folder: string
+  /** Its `package.json` name, which says two checkouts are one app. */
+  packageName: string
+}
+
+function manifest(folder: string): { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null {
+  const file = join(folder, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** The name of the app in `folder`, or null when the folder is not one. */
+export function appName(folder: string): string | null {
+  const m = manifest(folder)
+  if (!m || m.name === PACKAGE_NAME) return null
+  const uses = Boolean(m.dependencies?.[PACKAGE_NAME] ?? m.devDependencies?.[PACKAGE_NAME])
+  return uses && existsSync(join(folder, 'src')) ? (m.name ?? basename(folder)) : null
+}
+
+const isDir = (path: string) => {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The folder that holds the repositories: the parent of the repository `from`
+ * is in, or `from` itself when it is in none (a folder that only holds them).
+ */
+export function workspaceOf(from: string): string {
+  let at = resolve(from)
+  for (;;) {
+    if (existsSync(join(at, '.git'))) return dirname(at)
+    const up = dirname(at)
+    if (up === at) return resolve(from)
+    at = up
+  }
+}
+
+/** Every app in `workspace`, one per package name, except those named in `skip`. */
+export function findSiblings(workspace: string, { skip = [] }: { skip?: string[] } = {}): Sibling[] {
+  let tops: string[]
+  try {
+    tops = readdirSync(workspace).filter((name) => !name.startsWith('.') && name !== 'node_modules' && isDir(join(workspace, name)))
+  } catch {
+    return []
+  }
+  const found: Sibling[] = []
+  for (const top of tops) {
+    const folder = join(workspace, top)
+    const inside = readdirSync(folder).filter((name) => !name.startsWith('.') && name !== 'node_modules' && isDir(join(folder, name)))
+    for (const candidate of [folder, ...inside.map((name) => join(folder, name))]) {
+      const packageName = appName(candidate)
+      if (packageName) found.push({ name: top, folder: candidate, packageName })
+    }
+  }
+  const byPackage = new Map<string, Sibling>()
+  for (const sibling of found.sort((a, b) => a.name.length - b.name.length || a.name.localeCompare(b.name))) {
+    if (skip.includes(sibling.packageName) || byPackage.has(sibling.packageName)) continue
+    byPackage.set(sibling.packageName, sibling)
+  }
+  return [...byPackage.values()].sort((a, b) => a.name.localeCompare(b.name))
+}

package/src/registry/skill.test.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+/**
+ * UIG-20: the skill's text, held to what it points at.
+ *
+ * The skill names the package's parts and props. Renaming one would leave the
+ * skill sending sessions to something that is not there, so every part it names
+ * is checked against the catalogue. Its Gotchas stand for recorded defects,
+ * reconciled in `docs/GATES-SKILL.md`; that table has to keep adding up.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import type { Registry } from './schema'
+import { loaderText, SKILL_DESCRIPTION } from './skill'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const text = readFileSync(join(repoRoot, 'skill', 'estiva-ui.md'), 'utf8').replace(/\r\n/g, '\n')
+const registry = JSON.parse(readFileSync(join(repoRoot, 'registry.json'), 'utf8')) as Registry
+const byName = new Map(registry.entries.map((entry) => [entry.name, entry]))
+const record = readFileSync(join(repoRoot, 'docs', 'GATES-SKILL.md'), 'utf8').replace(/\r\n/g, '\n')
+
+describe('the skill', () => {
+  it('has the four parts, stays short, and fits Claude Code’s description limit', () => {
+    expect(text).toMatch(/^# /)
+    for (const heading of ['## When this applies', '## Steps, in order', '## Gotchas']) expect(text).toContain(heading)
+    expect(text.split('\n').length).toBeLessThan(200)
+    expect(SKILL_DESCRIPTION.length).toBeLessThanOrEqual(1536)
+    expect(text).toMatch(/1\. \*\*Search before creating anything\.\*\* Run\n {3}`npm run ui:find/)
+  })
+
+  it('names only parts the package has', () => {
+    const named = [...new Set([...text.matchAll(/`([A-Z][A-Za-z]+)`/g)].map((m) => m[1]))]
+    expect(named.length).toBeGreaterThan(20)
+    expect(named.filter((name) => !byName.has(name))).toEqual([])
+  })
+
+  it('names only props those parts have', () => {
+    const props: [string, string][] = [
+      ['EmptyState', 'scope'],
+      ['ListColumn', 'above'],
+      ['IconButton', 'tooltip'],
+      ['SectionHeader', 'hover'],
+      ['WithTooltip', 'inline'],
+      ['Toolbar', 'surface'],
+      ['Form', 'busy'],
+      ['Popover', 'maxHeight'],
+      ['Popover', 'open'],
+    ]
+    for (const [part, prop] of props) expect(byName.get(part)?.props.map((p) => p.name), `${part}.${prop}`).toContain(prop)
+  })
+
+  it('carries the four regressions the ticket names', () => {
+    expect(text).toMatch(/header row drawn by hand[\s\S]*?`ContainerHeader`/)
+    expect(text).toMatch(/no scroll container[\s\S]*?`ListColumn`/)
+    expect(text).toMatch(/`EditableText` rendering too large/)
+    expect(text).toMatch(/`EmptyState` at the wrong level[\s\S]*?scope="page"/)
+  })
+
+  it('assumes no app: no app is named, so it holds in every one', () => {
+    expect(`${text}\n${SKILL_DESCRIPTION}`).not.toMatch(/\b(Peek|Ship|Leaf)\b/)
+  })
+
+  it('is read in by the loader, never copied into it', () => {
+    const loader = loaderText(repoRoot, repoRoot)
+    expect(loader).not.toContain('## Gotchas')
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/skill/estiva-ui.md"`')
+  })
+})
+
+describe('the Gotchas, against the record', () => {
+  const rows = [...record.matchAll(/^\| (\d+) \|.*\| (G\d+|EXCL)\b[^|]*\|$/gm)].map((m) => ({ n: Number(m[1]), verdict: m[2] }))
+  const gotchas = [...text.matchAll(/^(\d+)\. \*\*/gm)].map((m) => Number(m[1]))
+
+  it('gives every recorded defect a row, numbered without a gap', () => {
+    expect(rows.length).toBeGreaterThan(500)
+    expect(rows.map((row) => row.n)).toEqual(rows.map((_, i) => i + 1))
+  })
+
+  it('backs every Gotcha with at least two recorded defects, and points at none the skill lacks', () => {
+    const numbered = gotchas.filter((n, i) => i >= 5 || n > 5) // the five steps are numbered too
+    const count = (g: number) => rows.filter((row) => row.verdict === `G${g}`).length
+    for (let g = 1; g <= 24; g++) expect(count(g), `G${g}`).toBeGreaterThanOrEqual(2)
+    expect(rows.filter((row) => row.verdict.startsWith('G') && Number(row.verdict.slice(1)) > 24)).toEqual([])
+    expect(numbered.filter((n) => n >= 1 && n <= 24).length).toBeGreaterThanOrEqual(19)
+    expect(text).toMatch(/^24\. \*\*/m)
+  })
+
+  it('states counts that add up', () => {
+    const into = rows.filter((row) => row.verdict !== 'EXCL').length
+    const out = rows.filter((row) => row.verdict === 'EXCL').length
+    expect(record).toContain(`**${rows.length}** | **${into}** | **${out}**`)
+    expect(text).toContain(`counted ${rows.length}`)
+    expect(text).toContain(`cover the ${into}`)
+  })
+})