@estiva-app/ui 0.20.0 → 0.21.1

package/dist/gates/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/gates/status.ts"],"names":[],"mappings":"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"}

package/dist/gates/token-lint.d.ts

@@ -0,0 +1,26 @@
+import type { Linter } from 'eslint';
+/** Who reads the messages. */
+export type TokenAudience = 'app' | 'package';
+export interface TokenLintOptions {
+    /** The Tailwind config the unknown-class rule reads, relative to where ESLint runs. */
+    tailwindConfig?: string;
+    /** `app` (the default) names the package; `package` names `tokens.css` and the preset. */
+    audience?: TokenAudience;
+}
+/** What the token lint never reads: build output. */
+export declare const TOKEN_LINT_IGNORES: string[];
+/**
+ * The class rules. `no-unknown-classes` reads the app's own Tailwind config, so
+ * it knows exactly what the preset and the app generate.
+ */
+export declare function tokenLint({ tailwindConfig, audience }?: TokenLintOptions): Linter.Config;
+/**
+ * UIG-28: the values the tokens already name, written by hand (Katerina's
+ * rulings B11, B12, C3 of 13 September and R2 of 15 September). Register it
+ * after `tokenLint`, whose parser and plugin settings it borrows. Under its own
+ * rule names, `token-values` and `token-spacing` (the same plugin twice, so one
+ * runs as errors and one as warnings): an escape for a hand-written size then
+ * cannot also silence a raw colour on the same line.
+ */
+export declare function tokenValues({ audience }?: Pick<TokenLintOptions, 'audience'>): Linter.Config;
+//# sourceMappingURL=token-lint.d.ts.map

package/dist/gates/token-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-lint.d.ts","sourceRoot":"","sources":["../../src/gates/token-lint.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAKpC,8BAA8B;AAC9B,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,CAAA;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,aAAa,CAAA;CACzB;AAED,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,UAAkD,CAAA;AA6BjF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,cAAqC,EAAE,QAAgB,EAAE,GAAE,gBAAqB,GAAG,MAAM,CAAC,MAAM,CAqC3H;AAiCD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAgB,EAAE,GAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAM,GAAG,MAAM,CAAC,MAAM,CAqExG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -23,15 +23,24 @@
       "types": "./dist/eslint/index.d.ts",
       "default": "./dist/eslint/index.js"
     },
+    "./gates": {
+      "types": "./dist/gates/index.d.ts",
+      "default": "./dist/gates/index.js"
+    },
     "./tailwind-preset": "./tailwind-preset.js",
     "./tokens.css": "./tokens.css",
     "./package.json": "./package.json",
     "./base.css": "./base.css"
   },
+  "bin": {
+    "create-estiva-app": "dist/gates/create-app.js",
+    "estiva-gates": "dist/gates/cli.js"
+  },
   "scripts": {
     "build": "node build.mjs && tsc -p tsconfig.build.json",
     "storybook": "storybook dev -p 6008 --no-open",
     "build-storybook": "storybook build",
+    "pretest": "node build.mjs",
     "test": "vitest run --project unit",
     "test:watch": "vitest --project unit",
     "test:a11y": "vitest run --project storybook-signal --project storybook-ship",
@@ -40,15 +49,32 @@
     "lint": "eslint .",
     "prelint:rules": "node build.mjs",
     "lint:rules": "eslint --config eslint.gates.config.js .",
-    "postlint:rules": "node scripts/gates-count.mjs",
-    "gates:status": "node scripts/gates-status.mjs",
+    "postlint:rules": "node dist/gates/cli.js count --repo estiva-ui --package",
+    "pregates:status": "node build.mjs",
+    "gates:status": "node dist/gates/cli.js status",
+    "pregates:compare": "node build.mjs",
+    "gates:compare": "node scripts/gates-compare.mjs",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
     "@tabler/icons-react": "^3.41.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "tailwindcss": "^3.4.0"
+    "tailwindcss": "^3.4.0",
+    "eslint": ">=9",
+    "eslint-plugin-better-tailwindcss": "^4.7.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
+    "eslint-plugin-better-tailwindcss": {
+      "optional": true
+    },
+    "typescript-eslint": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/gates/app-checks.ts

@@ -0,0 +1,226 @@
+/// <reference types="node" />
+/**
+ * The gate checks every app runs, written once (docs/GATES.md §23).
+ *
+ * Until UIG-10 Peek and Ship each wrote them into their own
+ * `scripts/gates-checks.mjs`. 65 different checks for finished tickets, counted
+ * on 17 September: 28 were identical in both, 21 were the same check written two
+ * ways, 2 read each app's real page, and 14 read code only one app has. This is
+ * the first three groups as one list. The fourth stays in the app's own checks
+ * file, beside this list.
+ *
+ * Where Peek and Ship wrote one check two ways, the check here runs both, so it
+ * passes wherever either did: the raw-link probe with both of their texts, the
+ * token probes against each token config the app has.
+ *
+ * `scripts/gates-compare.mjs` holds this list to Peek's and Ship's: every check
+ * of theirs must be here, or be about code only that app has, or the comparison
+ * fails and names it.
+ *
+ * A check for a ticket not built yet is a first guess at the evidence, taken
+ * from the ticket's own text; the ticket that builds it changes it here.
+ */
+import type { CheckResult, GateCheck, GateHelpers, GateTicket } from './status'
+
+export interface AppCheckOptions {
+  /** Where the app is inside the repository: `web` in Ship, `.` elsewhere. */
+  app?: string
+  /** A real page of the app, relative to the app, full of elements that are not controls. */
+  page: string
+  /** The ticket the gate chain is listed under, and whether this repo owns it: UIG-3 in Peek, UIG-4 in Ship. */
+  chain?: { ref: string; owner: boolean }
+  /** The token lint configs the app has, relative to the app. */
+  tokenConfigs?: string[]
+  /** The name of the app's header component a hand-made header row should name (UIG-22's first guess). */
+  headers?: string[]
+}
+
+export const APP_TICKET_TITLES: Record<string, string> = {
+  'UIG-2': 'The tracking rails — GATES.md, the status script, the guide committed',
+  'UIG-3': 'Tracer bullet — one rule, end to end, blocking in Peek',
+  'UIG-4': 'The same chain, blocking in Ship',
+  'UIG-6': 'Branch protection — the backstop, all three repos',
+  'UIG-7': 'Lint rule — every remaining raw element',
+  'UIG-8': 'Lint rule — forbid the reach',
+  'UIG-9': 'Lint rule — the className allow-list',
+  'UIG-13': "The registry widens to Peek's 115 and Ship's 74, with classification",
+  'UIG-19': 'Lock the contract in CI, and make the three Storybooks one search',
+  'UIG-20': 'The Claude skill, reading the registry',
+  'UIG-21': 'CLAUDE.md becomes an index, not a lecture',
+  'UIG-22': 'Fingerprint — a hand-made header row',
+  'UIG-23': 'Fingerprint — a hand-made empty state',
+  'UIG-24': 'Fingerprint — a browser tooltip where ours belongs',
+  'UIG-25': 'Fingerprint — a component copied out by hand',
+  'UIG-27': 'The components the apps had to build themselves — Link, ProgressBar, EmptyState padding',
+  'UIG-28': 'Close the two holes in the token contract — arbitrary values, and inline style',
+  'UIG-30': 'RichText — one component that draws a message\'s text, for both apps',
+  'UIG-32': 'Peek and Ship take their gate pieces from the package',
+}
+
+/** Run several checks as one: the first that does not pass is the answer. */
+function all(h: GateHelpers, steps: (() => CheckResult | Promise<CheckResult>)[], label: string): () => Promise<CheckResult> {
+  return async () => {
+    for (const step of steps) {
+      const r = await step()
+      if (r.result !== 'pass') return r
+    }
+    return h.PASS(label)
+  }
+}
+
+export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['ContainerHeader', 'SectionHeader'] }: AppCheckOptions): GateTicket[] {
+  const WEB = app === '.' ? '' : `${app.replace(/\/$/, '')}/`
+  const cwd = app === '.' ? undefined : app
+  const PROBE = 'src/components/__gates_probe__.tsx'
+  const GATES = 'eslint.gates.config.js'
+  const at = (rel: string) => `${WEB}${rel}`
+  const probe = (code: string, expect: 'error' | 'warning' | 'none', mentions?: string, file = PROBE, config = GATES) => () =>
+    h.lint({ ...(cwd ? { cwd } : {}), config, file, code, expect, mentions })
+  const component = (body: string) => `export function Probe() {\n  return ${body}\n}\n`
+  const installed = at('node_modules/@estiva-app/ui/dist/index.d.ts')
+  const realPage = (): Promise<CheckResult> => h.lint({ ...(cwd ? { cwd } : {}), config: GATES, file: page, code: h.read(at(page)), expect: 'none' })
+  const button = component('<button type="button">x</button>')
+  const ticket = (ref: string, checks: GateCheck[], owner = false): GateTicket => ({ ref, title: APP_TICKET_TITLES[ref], owner, checks })
+
+  const tokenProbe = (code: string, expect: 'error' | 'warning' | 'none', mentions?: string, file = PROBE) =>
+    all(h, tokenConfigs.map((config) => probe(code, expect, mentions, file, config)), `${tokenConfigs.join(' and ')}: as expected`)
+
+  return [
+    ticket('UIG-2', [
+      { what: 'npm run gates:status is wired', run: () => h.script('package.json', 'gates:status') },
+    ]),
+    ticket(chain.ref, [
+      { what: 'the gate lint config loads', run: () => h.loads(at(GATES)) },
+      { what: `${at('package.json')} has lint:rules`, run: () => h.script(at('package.json'), 'lint:rules') },
+      { what: 'CI runs lint:rules', run: () => h.ci('lint:rules') },
+      { what: 'the committed hook runs the gate lint', run: () => h.hook('.claude/settings.json', 'gates') },
+      { what: '.gates-count.json is committed and parses', run: () => h.json(h.exists('.gates-count.json') ? '.gates-count.json' : at('.gates-count.json')) },
+      { what: 'a raw <button> is an error naming Button', run: probe(button, 'error', 'Button') },
+      { what: 'the same in a story', run: probe(button, 'error', 'Button', 'src/stories/__gates_probe__.stories.tsx') },
+      { what: 'a test file is not checked, while source is', run: async () => {
+        const source = await probe(button, 'error', 'Button')()
+        if (source.result !== 'pass') return h.FAIL(`source is not checked yet, so this proves nothing: ${source.detail}`)
+        return probe(button, 'none', undefined, 'src/components/__gates_probe__.test.tsx')()
+      } },
+      { what: 'the debt list exists', run: () => h.file('docs/GATES-DEBT.md') },
+    ], chain.owner),
+    ticket('UIG-6', [
+      { what: 'GitHub requires the check gate to merge into main', run: () => h.protectedBranch(/^gate$/) },
+      { what: "CI's job gate runs lint:rules", run: () => h.ciJob('gate', 'lint:rules') },
+    ]),
+    ticket('UIG-7', [
+      { what: 'a raw <input> is an error naming TextInput', run: probe(component('<input />'), 'error', 'TextInput') },
+      { what: 'a raw <a> is an error naming Link', run: all(h, [probe(component('<a href="/topics">Topics</a>'), 'error', 'Link'), probe(component('<a href="/issues">Issues</a>'), 'error', 'Link')], 'a raw <a> is an error naming Link') },
+      { what: 'a raw <form> is an error naming Form, and a file input one naming FilePicker', run: async () => {
+        const form = await probe(component('<form />'), 'error', '`Form`')()
+        if (form.result !== 'pass') return form
+        return probe(component('<input type="file" />'), 'error', 'FilePicker')()
+      } },
+      { what: '<textarea>, <select>, <dialog> and <label> name Textarea, Select, DialogShell and Field', run: async () => {
+        for (const [element, part] of [['textarea', 'Textarea'], ['select', 'Select'], ['dialog', 'DialogShell'], ['label', 'Field']]) {
+          const one = await probe(component(`<${element} />`), 'error', `\`${part}\``)()
+          if (one.result !== 'pass') return one
+        }
+        return h.PASS('all four are errors, each naming its part')
+      } },
+      { what: 'an element the package has no part for is an error that says to ask for one', run: probe(component('<iframe title="Map" />'), 'error', 'ask Katerina') },
+      { what: 'an escaped element is not an error, while the same element is', run: async () => {
+        const raw = await probe(component('<form />'), 'error')()
+        if (raw.result !== 'pass') return h.FAIL(`a raw <form> is not caught yet, so this proves nothing: ${raw.detail}`)
+        return probe('export function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )\n}\n', 'none')()
+      } },
+      { what: 'a real page, full of elements that are not controls, gets no error', run: realPage },
+    ]),
+    ticket('UIG-8', [
+      { what: 'a Base UI import is an error naming the part built on it', run: probe("import { Popover } from '@base-ui/react/popover'\nexport const Probe = Popover\n", 'error', '`Popover`') },
+      { what: 'createPortal is an error naming the floating parts', run: probe("import { createPortal } from 'react-dom'\nexport const Probe = (to: HTMLElement) => createPortal(<span />, to)\n", 'error', '`DialogShell`') },
+      { what: 'a key listener on the whole page is an error, in a .ts file too', run: probe("export function listen() {\n  window.addEventListener('keydown', () => {})\n}\n", 'error', '`DialogShell`', 'src/lib/__gates_probe__.ts') },
+      { what: 'arrow keys by hand are an error; Enter in a field is not', run: async () => {
+        const arrows = await probe("export const onKeyDown = (e: KeyboardEvent) => e.key === 'ArrowDown'\n", 'error', '`Menu`', 'src/lib/__gates_probe__.ts')()
+        if (arrows.result !== 'pass') return arrows
+        return probe("export const onKeyDown = (e: KeyboardEvent) => e.key === 'Enter'\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
+      } },
+      { what: 'a hand-written role="option" is an error naming Select', run: probe(component('<div role="option" />'), 'error', '`Select`') },
+      { what: 'tabIndex={0} on a div is an error; tabIndex={-1} is not', run: async () => {
+        const zero = await probe(component('<div tabIndex={0} />'), 'error', '`Button`')()
+        if (zero.result !== 'pass') return h.FAIL(`tabIndex={0} is not caught yet, so this proves nothing: ${zero.detail}`)
+        return probe(component('<div tabIndex={-1} />'), 'none')()
+      } },
+      { what: 'overflow-y-auto is an error naming ScrollArea', run: probe(component('<div className="h-64 overflow-y-auto" />'), 'error', '`ScrollArea`') },
+      { what: 'an escaped listener is not an error, while the same listener is', run: async () => {
+        const raw = await probe("export function listen() {\n  document.addEventListener('mousedown', () => {})\n}\n", 'error', undefined, 'src/lib/__gates_probe__.ts')()
+        if (raw.result !== 'pass') return h.FAIL(`a page listener is not caught yet, so this proves nothing: ${raw.detail}`)
+        return probe("export function listen() {\n  // @estiva-escape: a probe that keeps its listener on purpose\n  document.addEventListener('mousedown', () => {})\n}\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
+      } },
+      { what: 'a real page gets no error', run: realPage },
+    ]),
+    ticket('UIG-9', [
+      { what: 'a border passed into Button is an error naming Button', run: probe(`import { Button } from '@estiva-app/ui'\n${component('<Button className="border">x</Button>')}`, 'error', 'on `Button` changes how it looks') },
+      { what: 'placement passed into Button is not', run: probe(`import { Button } from '@estiva-app/ui'\n${component('<Button className="mt-2 w-full flex-1 relative">x</Button>')}`, 'none') },
+      { what: 'an escaped look is not an error, while the same look is', run: async () => {
+        const raw = await probe(`import { Link } from '@estiva-app/ui'\n${component('<Link href="/x" className="after:absolute after:inset-0">x</Link>')}`, 'error', '`Link`')()
+        if (raw.result !== 'pass') return h.FAIL(`a restyled part is not caught yet, so this proves nothing: ${raw.detail}`)
+        return probe(`import { Link } from '@estiva-app/ui'\nexport function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its row link on purpose\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>\n  )\n}\n`, 'none')()
+      } },
+      { what: 'a real page gets no error', run: realPage },
+    ]),
+    ticket('UIG-13', [
+      { what: 'registry.json is committed and has entries', run: () => h.json(h.exists('registry.json') ? 'registry.json' : at('registry.json'), (d) => ((d as { entries?: unknown[]; components?: unknown[] }).entries ?? (d as { components?: unknown[] }).components ?? []).length > 0, 'registry.json has entries') },
+    ]),
+    ticket('UIG-19', [
+      { what: 'the usage-page contract runs in CI', run: () => h.ci(/[\w:-]*contract[\w:-]*/) },
+    ]),
+    ticket('UIG-20', [
+      { what: 'a committed skill runs ui:find', run: () => (h.listFiles('.claude/skills', (n) => n === 'SKILL.md').some((f) => h.read(f).includes('ui:find')) ? h.PASS('a skill runs ui:find') : h.FAIL('no skill in .claude/skills runs ui:find')) },
+    ]),
+    ticket('UIG-21', [
+      { what: 'path-scoped instructions exist', run: () => (h.listFiles('.claude/rules', (n) => n.endsWith('.md')).some((f) => /^paths:/m.test(h.read(f))) ? h.PASS('.claude/rules has paths: instructions') : h.FAIL('no .claude/rules file with paths:')) },
+    ]),
+    ticket('UIG-22', [
+      { what: 'a hand-made header row is an error naming the header part', run: all(h, headers.map((name) => probe(component(`<section className="flex flex-col"><div className="flex items-center px-3 py-2"><span>${name === 'SectionHeader' ? 'Issues' : 'Folders'}</span></div><div /></section>`), 'error', name)), 'a hand-made header row is an error naming the header part') },
+    ]),
+    ticket('UIG-23', [
+      { what: 'a hand-made empty line is an error naming EmptyState', run: probe("export function Probe({ items }: { items: string[] }) {\n  return <div>{items.length === 0 ? <p className=\"text-text-secondary\">Nothing here</p> : items.map((i) => <span key={i}>{i}</span>)}</div>\n}\n", 'error', 'EmptyState') },
+    ]),
+    ticket('UIG-24', [
+      { what: 'a title= is an error naming WithTooltip', run: probe(`import { Button } from '@estiva-app/ui'\n${component('<Button title="Delete">x</Button>')}`, 'error', 'WithTooltip') },
+    ]),
+    ticket('UIG-25', [
+      { what: "SectionLabel's class list, typed by hand, is a warning", run: probe(component('<span className="text-[10px] uppercase tracking-wide text-text-muted">Label</span>'), 'warning', 'SectionLabel') },
+    ]),
+    ticket('UIG-27', [
+      { what: 'the installed package has Link', run: () => h.contains(installed, /\bLink\b/, 'the installed @estiva-app/ui exports Link') },
+      { what: 'the installed package has ProgressBar', run: () => h.contains(installed, /\bProgressBar\b/, 'the installed @estiva-app/ui exports ProgressBar') },
+    ]),
+    ticket('UIG-28', [
+      { what: 'text-[14px] is an error', run: tokenProbe(component('<div className="text-[14px]">x</div>'), 'error') },
+      { what: 'a colour in an inline style is an error', run: tokenProbe(component("<div style={{ backgroundColor: '#ff0000' }}>x</div>"), 'error') },
+      { what: 'h-[240px] is a warning', run: tokenProbe(component('<div className="h-[240px]">x</div>'), 'warning') },
+      { what: 'h-[240px] is not an error', run: tokenProbe(component('<div className="h-[240px]">x</div>'), 'none') },
+      { what: 'a hand-written line height behind an arbitrary variant is an error', run: tokenProbe(component('<div className="[&_p]:leading-[1.4]">x</div>'), 'error') },
+      { what: 'a raw colour in a class is an error (the pattern that matched nothing, R1)', run: tokenProbe(component('<div className="bg-[#5c69dc]">x</div>'), 'error', 'raw colour') },
+      { what: 'a width and height from a prop pass', run: tokenProbe("export function Probe({ size }: { size: number }) {\n  return <div style={{ width: size, height: size }}>x</div>\n}\n", 'none') },
+      { what: 'a test file is not checked for hand-written values, while source is', run: all(h, tokenConfigs.map((config) => async () => {
+        const code = component("<div className=\"text-[14px]\" style={{ color: 'red' }}>x</div>")
+        const source = await probe(code, 'error', undefined, PROBE, config)()
+        if (source.result !== 'pass') return h.FAIL(`source is not checked yet, so this proves nothing: ${source.detail}`)
+        return probe(code, 'none', undefined, 'src/components/__gates_probe__.test.tsx', config)()
+      }), 'a test file is not checked for hand-written values, while source is') },
+    ]),
+    ticket('UIG-30', [
+      { what: 'the installed package has RichText', run: () => h.contains(installed, /\bRichText\b/, 'the installed @estiva-app/ui exports RichText') },
+    ]),
+    // Katerina's ruling of 17 September (docs/GATES.md §23): one copy, in the package. An app made
+    // by create-estiva-app passes this from its first commit; Peek and Ship do once UIG-32 lands.
+    ticket('UIG-32', [
+      { what: 'the gate pieces come from the package, and no repo keeps a copy', run: all(h, [
+        () => h.contains(at('eslint.gates.config.js'), /from '@estiva-app\/ui\/gates'/, 'the gate config imports @estiva-app/ui/gates'),
+        () => h.hook('.claude/settings.json', '@estiva-app/ui/dist/gates/cli.js'),
+        // `estiva-gates status` where npm can find the command; by path where it cannot,
+        // because the install is in the app's folder and the script is in the repo's top one (Ship).
+        () => h.contains('package.json', /"gates:status":\s*"[^"]*(?:estiva-gates|@estiva-app\/ui\/dist\/gates\/cli\.js)[^"]*status/, "gates:status runs the package's engine"),
+        () => (h.exists('scripts/gates-status.mjs') ? h.FAIL('scripts/gates-status.mjs is a copy of the status engine: run estiva-gates status instead') : h.PASS('no copy of the status engine')),
+      ], 'the gate config, the hook and gates:status are the package\'s; no copy of the engine') },
+    ]),
+  ]
+}

package/src/gates/cli.ts

@@ -0,0 +1,61 @@
+/// <reference types="node" />
+/**
+ * `estiva-gates` — the gate pieces as one command (docs/GATES.md §23).
+ *
+ *   estiva-gates count --repo <name> [--package]   write .gates-count.json (postlint:rules)
+ *   estiva-gates hook [--app <dir>] [--package]    the editor gate, run by a PreToolUse hook
+ *   estiva-gates status [--app <dir>] [--json] [--detail]   gates:status
+ *
+ * An app's `package.json` runs the first and the last through npm, which finds
+ * the command in `node_modules/.bin`. The hook is run by path, from the
+ * committed `.claude/settings.json`:
+ *
+ *   node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook
+ *
+ * A repo whose app sits in a folder of its own runs both by path, from the
+ * repo's top folder, and says where the app is — Ship (UIG-32):
+ *
+ *   node "$CLAUDE_PROJECT_DIR/web/node_modules/@estiva-app/ui/dist/gates/cli.js" hook --app web
+ *   node web/node_modules/@estiva-app/ui/dist/gates/cli.js status --app web
+ */
+import { writeGateCount } from './count'
+import { runHook } from './hook'
+import { runStatus } from './status'
+
+const [command, ...rest] = process.argv.slice(2)
+const flag = (name: string) => rest.includes(`--${name}`)
+const value = (name: string) => {
+  const i = rest.indexOf(`--${name}`)
+  return i === -1 ? undefined : rest[i + 1]
+}
+const audience = flag('package') ? 'package' : 'app'
+
+async function main(): Promise<number> {
+  switch (command) {
+    case 'count': {
+      const repo = value('repo')
+      if (!repo) {
+        process.stderr.write('estiva-gates count needs --repo <name>, the name written into .gates-count.json\n')
+        return 1
+      }
+      const result = await writeGateCount({ repo, audience, config: value('config') })
+      process.stdout.write(`${result.lines.join('\n')}\n`)
+      if (result.failures.length) process.stderr.write(`${result.failures.join('\n')}\n`)
+      return result.failures.length ? 1 : 0
+    }
+    case 'hook': {
+      const result = await runHook({ app: value('app'), audience })
+      if (result.code === 2) process.stderr.write(result.message)
+      return result.code
+    }
+    case 'status': {
+      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)
+      return 0
+    }
+    default:
+      process.stderr.write('estiva-gates <count | hook | status>\n')
+      return 1
+  }
+}
+
+process.exitCode = await main()

package/src/gates/count.ts

@@ -0,0 +1,76 @@
+/// <reference types="node" />
+/**
+ * Write `.gates-count.json`: what the gate finds, per rule — errors, warnings
+ * and escapes (seam S3 in docs/GATES.md §16). Written once (§23): until UIG-10
+ * Peek, Ship and this package each carried the same script, differing only in
+ * the repo's name and which rules it seeded.
+ *
+ * Runs after the gate lint (npm's `postlint:rules`), so CI runs it too. The
+ * file is committed: nothing compares it yet, and the later ratchet needs the
+ * history to start at the first commit. It lints with the gate's own config,
+ * with escapes reported, so an escape is counted rather than silent. The file
+ * is rewritten only when a count changes, so running the lint does not leave a
+ * changed file behind every time.
+ *
+ * It fails when an `eslint-disable` switched a gate rule off: that is not an
+ * escape, and the escape count cannot see it.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ESLint as ESLintClass } from 'eslint'
+import { APP_RULE_IDS, countGates, PACKAGE_RULE_IDS, type GateCount } from '../eslint/index'
+
+export interface CountOptions {
+  /** The folder the gate lints from, where `.gates-count.json` is written. */
+  root?: string
+  /** The name written into the file: `peek`, `ship`, `estiva-ui`, or the app's. */
+  repo: string
+  /** `app` seeds the app rules; `package` this package's inward set (UIG-5). */
+  audience?: 'app' | 'package'
+  /** The gate's config file, relative to `root`. */
+  config?: string
+}
+
+export interface CountResult extends GateCount {
+  changed: boolean
+  /** What to print, line by line. */
+  lines: string[]
+  /** What to print to stderr when a rule was switched off; empty when none was. */
+  failures: string[]
+}
+
+/** ESLint from where the gate lints, never from beside this file: an app's own install. */
+async function eslintFrom(root: string): Promise<typeof ESLintClass> {
+  const resolved = createRequire(join(root, 'package.json')).resolve('eslint')
+  return ((await import(pathToFileURL(resolved).href)) as { ESLint: typeof ESLintClass }).ESLint
+}
+
+export async function writeGateCount({ root = process.cwd(), repo, audience = 'app', config = 'eslint.gates.config.js' }: CountOptions): Promise<CountResult> {
+  const out = join(root, '.gates-count.json')
+  const ESLint = await eslintFrom(root)
+  const eslint = new ESLint({
+    cwd: root,
+    overrideConfigFile: join(root, config),
+    overrideConfig: { settings: { estiva: { reportEscapes: true } } },
+  })
+  // The set the gate runs, so a rule with nothing to report still has its row.
+  const { rules, disabled } = countGates(await eslint.lintFiles(['.']), audience === 'package' ? PACKAGE_RULE_IDS : APP_RULE_IDS)
+
+  const previous = existsSync(out) ? (JSON.parse(readFileSync(out, 'utf8')) as { rules?: unknown }) : null
+  const changed = JSON.stringify(previous?.rules) !== JSON.stringify(rules)
+  if (changed) {
+    const count = { schemaVersion: 1, repo, generatedAt: new Date().toISOString(), rules }
+    writeFileSync(out, `${JSON.stringify(count, null, 2)}\n`)
+  }
+  const lines = [changed ? '.gates-count.json: written' : '.gates-count.json: unchanged']
+  for (const [id, c] of Object.entries(rules)) lines.push(`  ${id}: ${c.errors} errors, ${c.warnings} warnings, ${c.escapes} escapes`)
+
+  const failures: string[] = []
+  if (disabled.length > 0) {
+    failures.push('', 'An eslint-disable switched a gate rule off. Write the reason above the element instead: // @estiva-escape: <reason>')
+    for (const d of disabled) failures.push(`  ${relative(root, d.filePath)}:${d.line}  ${d.ruleId}`)
+  }
+  return { rules, disabled, changed, lines, failures }
+}

package/src/gates/create-app-cli.ts

@@ -0,0 +1,25 @@
+/// <reference types="node" />
+/**
+ * `create-estiva-app <name>` (UIG-10): the command. What it makes is
+ * `create-app.ts`; this file only reads the arguments and says what happened.
+ *
+ *   npx -p @estiva-app/ui create-estiva-app leaf [--title Leaf] [--theme light] [--ui <version or tarball>]
+ */
+import { createApp } from './create-app'
+
+const [name, ...rest] = process.argv.slice(2)
+const value = (flag: string) => {
+  const i = rest.indexOf(`--${flag}`)
+  return i === -1 ? undefined : rest[i + 1]
+}
+
+try {
+  if (!name || name.startsWith('--')) throw new Error('create-estiva-app <name> [--title <on-screen name>] [--theme <theme>] [--ui <@estiva-app/ui version or tarball>]')
+  const dir = createApp({ name, title: value('title'), theme: value('theme'), ui: value('ui') })
+  process.stdout.write(
+    `Made ${dir}\n\nNext:\n  cd ${name}\n  npm install     (on Linux, or in a Linux container, so the lockfile carries every platform)\n  git init -b main && git add -A && git commit -m "The app, as create-estiva-app made it"\n  npm run dev\n`,
+  )
+} catch (error) {
+  process.stderr.write(`${(error as Error).message}\n`)
+  process.exitCode = 1
+}

package/src/gates/create-app.test.ts

@@ -0,0 +1,72 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { appFiles, createApp, themes } from './create-app'
+
+/**
+ * `create-estiva-app` (UIG-10). What the app does when it runs is proved on a
+ * throwaway app (docs/GATES.md, UIG-10: building it); these hold what it is made
+ * of, and that it is made from this package alone.
+ */
+const versions = { '@estiva-app/identity': '^0.2.2', 'eslint-plugin-react-hooks': '^7.0.1' }
+const files = appFiles({ name: 'probe-app', title: 'Probe', theme: 'dark', versions })
+const scratch = mkdtempSync(join(process.cwd(), 'node_modules', '.create-app-test-'))
+afterAll(() => rmSync(scratch, { recursive: true, force: true }))
+
+describe('create-estiva-app', () => {
+  it('reads nothing but this package: no Peek, no Ship, no sibling checkout', () => {
+    const source = readFileSync(new URL('./create-app.ts', import.meta.url), 'utf8')
+    expect(source).not.toMatch(/\.\.\/(peek|ship)\b|GATES_PEEK|GATES_SHIP|K:[\\/]Estiva/)
+  })
+
+  it('makes the frame, the checks and the gates, each as a file that imports the package', () => {
+    expect(Object.keys(files).sort()).toEqual(
+      [
+        '.claude/settings.json', '.env.example', '.gates-count.json', '.github/workflows/deploy.yml', '.gitignore', '.storybook/main.ts', '.storybook/preview.tsx',
+        'CLAUDE.md', 'README.md', 'docs/GATES-DEBT.md', 'eslint.config.js', 'eslint.gates.config.js', 'eslint.tokens.config.js', 'index.html', 'package.json',
+        'postcss.config.js', 'scripts/gates-checks.mjs', 'src/App.test.tsx', 'src/App.tsx', 'src/auth/AuthShell.tsx', 'src/auth/boot.ts', 'src/auth/estivaId.ts',
+        'src/config.ts', 'src/index.css', 'src/main.tsx', 'src/pages/HomePage.stories.tsx', 'src/pages/HomePage.tsx', 'src/vite-env.d.ts', 'tailwind.config.js',
+        'tsconfig.app.json', 'tsconfig.json', 'tsconfig.node.json', 'vite.config.ts',
+      ].sort(),
+    )
+    expect(files['eslint.gates.config.js']).toContain("from '@estiva-app/ui/gates'")
+    expect(files['scripts/gates-checks.mjs']).toContain("appChecks(h, { page: 'src/pages/HomePage.tsx' })")
+    expect(JSON.parse(files['.claude/settings.json']).hooks.PreToolUse[0].hooks[0].command).toBe('node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook')
+  })
+
+  it('uses the sidebar frame and one theme, set on <html>', () => {
+    expect(files['src/App.tsx']).toMatch(/<AppShell[\s\S]*<Sidebar>[\s\S]*<NavItem/)
+    expect(files['src/App.tsx']).not.toContain('Rail')
+    expect(files['index.html']).toContain('<html lang="en" data-theme="dark">')
+    expect(files['.storybook/preview.tsx']).toContain('document.documentElement.dataset.theme = "dark"')
+  })
+
+  it('starts the count at zero and keeps the CI job named gate', () => {
+    const count = JSON.parse(files['.gates-count.json'])
+    expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])
+    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run lint:rules/)
+    expect(files['docs/GATES-DEBT.md']).toContain('Nothing.')
+  })
+
+  it('never points at the real Estiva ID by itself', () => {
+    expect(files['.env.example']).toContain('VITE_ESTIVA_ID_ORIGIN=\n')
+    expect(Object.values(files).join('\n')).not.toContain('id.estiva.app')
+  })
+
+  it('takes its tool versions from this package, and the two it does not use from what it is given', () => {
+    const own = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+    const made = JSON.parse(files['package.json'])
+    expect(made.dependencies['@estiva-app/ui']).toBe(`^${own.version}`)
+    expect(made.devDependencies.vite).toBe(own.devDependencies.vite)
+    expect(made.devDependencies.eslint).toBe(own.devDependencies.eslint)
+    expect(made.dependencies['@estiva-app/identity']).toBe('^0.2.2')
+  })
+
+  it('refuses a name an app cannot have, a theme the package has not got, and a folder that exists', () => {
+    expect(themes()).toEqual(expect.arrayContaining(['light', 'dark', 'signal', 'ship']))
+    expect(() => appFiles({ name: 'Leaf', versions })).toThrow(/not a name/)
+    expect(() => appFiles({ name: 'leaf', theme: 'purple', versions })).toThrow(/not one of the package's themes/)
+    createApp({ name: 'once', parent: scratch, versions })
+    expect(() => createApp({ name: 'once', parent: scratch, versions })).toThrow(/already exists/)
+  })
+})