kerfjs 5.0.0-beta.18 → 5.0.0-beta.19

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- Added `npx kerfjs setup` and the `kerfjs/setup` automation API for safe,
+  AI-first initialization and migration of core and UI projects. The command
+  provides bounded dry-run diffs, explicit per-conflict keep/Kerf choices,
+  package-scoped hash-backed upgrades, monorepo selection, transactional
+  rollback, shipped guidance, strict TypeScript/ESLint, and UI catalog/profile
+  and doctor discovery. Empty application component metadata now emits a valid
+  empty v2 catalog. Existing JSONC TypeScript configuration is structurally
+  merged without discarding comments, trailing commas, authored fields, or line
+  endings; malformed roots and compiler-option containers require an explicit
+  keep/Kerf decision. Workspace selection now evaluates ordered globstar,
+  brace, exclusion, and re-inclusion patterns deterministically across npm,
+  Yarn, and pnpm declarations, rejects path/symlink/name ambiguity, and uses
+  manager-correct offline commands with explicit Yarn Classic/Berry detection
+  and network-disabled Berry installs.
+- Added `@kerfjs/ui/doctor` and the `kerf-ui-doctor` command: a versioned, redacted repair-loop report that merges catalog/profile validation, TypeScript, Kerf UI ESLint, static analysis, and opt-in browser evaluation with changed/full modes, monorepo selection, reasoned suppressions, caching, and deterministic exits.
+- Added the public Playwright-backed `kerf-ui-evaluate` CLI and `@kerfjs/ui/evaluator` Node API. It resolves application profiles and composition catalogs, exercises wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion contexts across Chromium, Firefox, and WebKit, and emits versioned repair-oriented `KUI-B###` diagnostics plus focused DOM/style evidence and hashed screenshots. Subjective visual quality remains an explicitly separate unrecorded reviewer rubric.
+- Added `kerf-ui-analyze`, a profile- and catalog-aware static evaluator for Kerf UI integrations. It resolves directory policy per source, follows project-local CSS import graphs without cross-package class leakage, and evaluates shared stylesheets against every consuming source policy before deduplicating findings. Stable portable text, JSON, or SARIF diagnostics cover private selectors, unknown tokens, competing geometry/scroll owners, repeated insets, forced dimensions, off-scale spacing, and dynamic-class review, with exact scoped profile exceptions, a public report schema, and configurable CI review failure.
+- Added catalog/profile-aware `recommended-ui` and `strict-ui` flat presets to `eslint-plugin-kerfjs`. Toolbar zone acceptance/cardinality and valid wiring imports come from the shipped catalogs; intrinsic or unknown zone children, root/subpath/namespace wiring, and the non-colliding `KUI-L090` load diagnostic are covered by real packed downstream installs on every supported ESLint major.
+- **Breaking (`@kerfjs/ui` TypeScript declarations):** strengthened invalid-integration contracts for ListHeader modes, Select naming and literal choice identity, SegmentedControl/TabScaffold literal identity, collapsible TokenSearchField props, protected editor metadata, PanelHeader summary ids, ToolbarText line caps, and token-removal callbacks. Added named public unions for previously anonymous finite variants plus source and packed-tarball positive/negative compilation gates. See `ui/docs/type-contracts.md` for the compatibility review and dynamic-data widening syntax.
+- `create-kerf-component` now scaffolds explicit `kerf.components.json` AI metadata and a deterministic `kerf-component-catalog` generator/checker. Generated v2 entries carry package identity, purpose, verified named exports, composition and geometry ownership, tokens, accessibility, and source links; publishing rejects missing author decisions, schema-invalid source/output fields, deleted sources, renamed exports, duplicate ids, or output drift, including multi-package workspaces. Syntax-aware TypeScript/TSX export discovery prevents JSX text, nested scopes, comments, and literals from impersonating public exports.
+- Added a versioned application UI profile for AI tools and static evaluators. Shipped package defaults, schema, TypeScript types, Node discovery/merge/validation APIs, and a workspace example now make catalog locations, preferred components/recipes, theme/density policy, semantic token overrides, responsive/layout conventions, and narrow source-located exceptions explicit. Composition-only generated consumer catalogs load without a fabricated v1 selection artifact, while Kerf retains its required v1 selection catalog. Deterministic package → workspace → parent-to-child directory precedence validates every raw layer before merge, attributes resolved diagnostics through field provenance, and rejects stale catalogs, unknown components/tokens/rules, conflicts, malformed value shapes, and broad exemptions.
+- Fixed `CatalogExampleStack` accessible labels: the helper now renders a semantic `section`, so a supplied `label` exposes the documented named region to assistive technology while an unlabeled stack remains an ordinary grouping.
+- Added first-class `Pane` and `SunkenPanel` primitives to `@kerfjs/ui`. `Pane` standardizes semantic header/content/footer columns, explicit logical-edge separators, and one content scroll owner; `SunkenPanel` supplies one lowered surface with an 8px inset and vertical rhythm. The Catalog shell now dogfoods `Pane`, and both components ship focused demos, catalog metadata, documentation, and three-engine browser coverage.
+- Added the package-qualified component catalog v2 alongside the compatible v1 artifact. Its schema and generated metadata formalize child zones, cardinality, exclusivity, wiring, state, responsive behavior, layout and accessibility boundaries, stable validation diagnostics, provenance, and consumer extension catalogs, so AI tools can join Kerf and application components without guessing composition contracts.
+- Added an AST-based Catalog demo conformance gate. It checks every first-party demo for public helper usage, package imports, focused specimen structure, geometry-overlay metadata, and reviewed schema-checked exceptions, with adversarial fixtures and authoring guidance that makes the same contract available to downstream AI tools.
+- Made `ui/docs/catalog.md` the authoritative Catalog demo authoring contract, covering focused versus composition previews, public row/group nesting, exact specimen selection, conditional geometry overlays, skip-marker behavior, metadata ownership, and an explicit overlay legend. A shipped `ai/catalog-authoring.json` discovery artifact now routes AI tools to that contract and exact signatures, with schema, link-integrity, and browser-consumer fixture coverage.
+- Extended `CatalogExample` and `CatalogExampleStack` with typed, runtime-filtered `rootAttributes` for catalog-authoring `data-*` metadata such as `data-demo` and `data-catalog-geometry-overlay-skip`, while preserving helper-owned structural and alignment markers. The UX catalog now composes its example stacks through these public helpers instead of copying private `kui-catalog-*` markup.
 - Added `revealCatalogEntry` and opt-in `wireCatalog({ revealSelection })` support to the exported Catalog tool. Sidebar or related-entry selection can now reveal the matching row after the controlled render settles, using a desktop-safe media guard, exact id matching, configurable scroll alignment/behavior, focus-preserving scrolling, and cancellation of stale rapid selections; the Kerf UX demo now uses the public behavior.
 - Added a reusable consumer component-catalog extension schema and checked app-component example. Downstream packages can now publish the same selection facts and margin/border/padding ownership vocabulary as Kerf, and the README, component contract, Catalog guide, `llms.txt`, and AI skill explain how to combine package-qualified app entries with Kerf's shipped catalog for alignment decisions.
 - Added an opt-in geometry inspector to the exported `@kerfjs/ui/catalog` tool. `geometryOverlay` plus `wireCatalogGeometryOverlay` now marks transparent component bounds with a dashed outline and positive intrinsic margins with devtools-style bands, excludes example labels/alignment scaffolding, stays synchronized across preview changes, and replaces the Kerf UX demo's private implementation.

package/README.md

@@ -51,6 +51,19 @@ Here's the whole development loop — write a component, run the dev server, cli
 npm install kerfjs
 ```
 
+For an existing project, install the AI guidance, strict TypeScript/ESLint
+feedback, and package scripts with a reviewed dry run:
+
+```bash
+npx kerfjs setup                 # inspect a value-level plan
+npx kerfjs setup --write --yes   # apply it
+```
+
+The command detects core versus `@kerfjs/ui`, supports deterministic npm,
+pnpm, and Yarn workspace selection plus manager-correct offline installs, and
+never adds UI to a core-only project. See
+[`docs/24-ai-first-setup.md`](./docs/24-ai-first-setup.md).
+
 ```jsonc
 // tsconfig.json — point JSX at kerf
 { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "kerfjs" } }
@@ -287,7 +300,7 @@ Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwes
 
 ### Optional: `create-kerf-component`
 
-Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports) plus an example component showing per-instance state via a factory and a `wire(root)` delegation disposer:
+Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports), includes an example component showing per-instance state via a factory and a `wire(root)` delegation disposer, and generates checked package-qualified AI component metadata from explicit author decisions:
 
 ```bash
 npm create kerf-component@latest my-widgets
@@ -302,7 +315,7 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
 - **Migrating:** [coming from another framework?](https://brianwestphal.github.io/kerf/migrating/) — side-by-side TodoMVC translations + per-framework gotchas
 - **AI guide:** [`docs/ai/usage-guide.md`](./docs/ai/usage-guide.md) — reference for AI tools fetching kerf docs (linked from `llms.txt`)
 - **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight rules (four hard-rule errors + four warns: `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs`) at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
-- **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with the hard packaging rules pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
+- **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
 - **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)
 - **Repo:** [github.com/brianwestphal/kerf](https://github.com/brianwestphal/kerf)
 

package/ai/manifest.json

@@ -1,5 +1,5 @@
 {
-  "kerfjsVersion": "5.0.0-beta.18",
+  "kerfjsVersion": "5.0.0-beta.19",
   "files": [
     {
       "name": "skill",

package/llms.txt

@@ -10,13 +10,17 @@ kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "
 
 ## For AI assistants
 
+- One-step project setup: run `npx kerfjs setup` for a safe dry-run, then
+  `npx kerfjs setup --write --yes`; see
+  [AI-first setup](https://github.com/brianwestphal/kerf/blob/main/docs/24-ai-first-setup.md).
+
 - [AI usage guide](https://github.com/brianwestphal/kerf/blob/main/docs/ai/usage-guide.md): when to recommend kerf, the full public API, the four core patterns, hard rules, and a common-errors table.
 - [Code summary](https://github.com/brianwestphal/kerf/blob/main/docs/ai/code-summary.md): directory tree + reverse index of every public export.
 - [Requirements summary](https://github.com/brianwestphal/kerf/blob/main/docs/ai/requirements-summary.md): synthesized view of the numbered design docs.
 - [`kerf.cursorrules`](https://github.com/brianwestphal/kerf/blob/main/kerf.cursorrules): drop-in [Cursor](https://cursor.sh) rules for projects that import `kerfjs`. Copy into your project as `.cursorrules` — or use the bundled mirror at `node_modules/kerfjs/ai/cursorrules` once you've `npm install`ed kerfjs.
 - [`kerf.claude-skill.md`](https://github.com/brianwestphal/kerf/blob/main/kerf.claude-skill.md): drop-in [Claude Code](https://claude.com/claude-code) skill. Copy into `~/.claude/skills/kerf-app/SKILL.md` (or your project's `.claude/skills/kerf-app/SKILL.md`) — or use the bundled mirror at `node_modules/kerfjs/ai/skill.md` once you've `npm install`ed kerfjs.
 - [`eslint-plugin-kerfjs`](https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/README.md): companion ESLint plugin enforcing the hard rules at edit time — eight rules: `no-inline-jsx-event-handlers`, `require-data-key-in-each`, `no-nested-mount`, `prefer-module-jsx-augmentation` (error) plus `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs` (warn). AST-only, no `parserServices` dependency. Install with `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to your eslint config. Recommended when authoring kerf code with an AI assistant — eslint feedback surfaces in the IDE before `tsc` or runtime warns ever run.
-- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules already wired (kerfjs as a peer dependency + `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports) plus an example component (per-instance state via a factory, a `wire(root)` delegation disposer). Run `npm create kerf-component@latest <dir>`.
+- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules, an example component, and explicit `kerf.components.json` source metadata plus deterministic `component-catalog-v2.json` generation/checking. Run `npm create kerf-component@latest <dir>`.
 - [`@kerfjs/ui` AI guide](https://github.com/brianwestphal/kerf/blob/main/ui/ai/skill.md): component-selection, styling, accessibility, and event-wiring contract for the optional first-party UI package.
 
 ## Reference docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kerfjs",
-  "version": "5.0.0-beta.18",
+  "version": "5.0.0-beta.19",
   "description": "Tiny reactive UI framework — fine-grained signals + DOM morphing + JSX. Apply the smallest possible cut to update your DOM.",
   "type": "module",
   "sideEffects": [
@@ -35,6 +35,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "kerfjs": "./setup/cli.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -100,11 +103,17 @@
       "types": "./dist/attach.d.ts",
       "import": "./dist/attach.js"
     },
-    "./ai/*": "./ai/*"
+    "./ai/*": "./ai/*",
+    "./setup": {
+      "types": "./setup/index.d.mts",
+      "import": "./setup/index.mjs"
+    },
+    "./setup/state.schema.json": "./setup/state.schema.json"
   },
   "files": [
     "dist",
     "ai",
+    "setup",
     "llms.txt",
     "README.md",
     "CHANGELOG.md",
@@ -165,7 +174,9 @@
     "check:audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@preact/signals-core": "^1.14.1"
+    "@preact/signals-core": "^1.14.1",
+    "minimatch": "^9.0.5",
+    "yaml": "^2.8.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/setup/cli.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import process from 'node:process';
+
+import { applyKerfSetup, formatSetupPlan, planKerfSetup } from './index.mjs';
+
+const args = process.argv.slice(2);
+const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'setup';
+const take = (name) => {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith('--'))
+    throw new Error(`${name} requires a value.`);
+  args.splice(index, 2);
+  return value;
+};
+const takeAll = (name) => {
+  const values = [];
+  while (args.includes(name)) values.push(take(name));
+  return values;
+};
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerfjs setup [options]
+
+Options:
+  --root <path>       Workspace root (default: current directory)
+  --package <name>    Select a workspace package by name or relative path
+  --core | --ui       Choose a mode when it cannot be detected
+  --resolve <id>=<choice>
+                       Resolve one conflict with keep or kerf (repeatable)
+  --write             Apply the displayed plan (default is dry-run)
+  --yes               Required with --write in non-interactive use
+  --offline           Forbid registry access during dependency installation
+  --no-install        Write configuration without running the package manager`);
+    process.exit(0);
+  }
+  if (command !== 'setup') throw new Error(`Unknown command ${command}.`);
+  const core = args.includes('--core');
+  const ui = args.includes('--ui');
+  if (core && ui) throw new Error('--core and --ui are mutually exclusive.');
+  const write = args.includes('--write');
+  const yes = args.includes('--yes');
+  const offline = args.includes('--offline');
+  const noInstall = args.includes('--no-install');
+  const root = take('--root');
+  const packageSelector = take('--package');
+  const resolutions = {};
+  for (const entry of takeAll('--resolve')) {
+    const index = entry.lastIndexOf('=');
+    if (index < 1) throw new Error('--resolve requires <id>=keep|kerf.');
+    const id = entry.slice(0, index);
+    const choice = entry.slice(index + 1);
+    if (id in resolutions && resolutions[id] !== choice)
+      throw new Error(`Conflicting resolutions for ${id}.`);
+    resolutions[id] = choice;
+  }
+  const known = new Set([
+    '--core',
+    '--ui',
+    '--write',
+    '--yes',
+    '--offline',
+    '--no-install',
+  ]);
+  const unknown = args.filter((arg) => !known.has(arg));
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  const plan = await planKerfSetup({
+    root,
+    package: packageSelector,
+    mode: ui ? 'ui' : core ? 'core' : undefined,
+    resolutions,
+  });
+  console.log(formatSetupPlan(plan));
+  if (plan.conflicts.length) {
+    process.exitCode = 2;
+  } else if (write) {
+    if (!yes)
+      throw new Error('--write requires --yes after reviewing the plan.');
+    await applyKerfSetup(plan, { install: !noInstall, offline });
+    console.log(`Applied ${plan.actions.length} change(s).`);
+  }
+} catch (error) {
+  console.error(`kerfjs setup: ${error.message}`);
+  process.exitCode = 2;
+}

package/setup/index.d.mts

@@ -0,0 +1,37 @@
+export interface SetupConflict {
+  id: string;
+  message: string;
+}
+export interface SetupAction {
+  path: string;
+  absolutePath: string;
+  before: string | null;
+  after: string;
+  kind: string;
+}
+export interface KerfSetupPlan {
+  schemaVersion: 1;
+  root: string;
+  packageRoot: string;
+  packageName: string;
+  packageManager: 'npm' | 'pnpm' | 'yarn';
+  packageManagerVersion?: string;
+  packageManagerVariant?: 'classic' | 'berry';
+  mode: 'core' | 'ui';
+  setupVersion: string;
+  actions: SetupAction[];
+  conflicts: SetupConflict[];
+  generatedPaths: string[];
+}
+export function planKerfSetup(options?: {
+  root?: string;
+  package?: string;
+  mode?: 'core' | 'ui';
+  version?: string;
+  resolutions?: Record<string, 'keep' | 'kerf'>;
+}): Promise<KerfSetupPlan>;
+export function formatSetupPlan(plan: KerfSetupPlan): string;
+export function applyKerfSetup(
+  plan: KerfSetupPlan,
+  options?: { install?: boolean; offline?: boolean; runner?: Function },
+): Promise<{ changed: string[] }>;