kerfjs 4.4.0 → 4.5.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kerfjs",
-  "version": "4.4.0",
+  "version": "4.5.0-beta.1",
   "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,18 +103,24 @@
       "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",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/clean-dist-output.mjs dist",
     "dev": "tsup --watch",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
@@ -123,13 +132,18 @@
     "test:dist:examples": "npm run build && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json",
     "test:dist:scaffold-typing": "npm run build && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json",
     "test:browser": "npm run build && playwright test",
+    "test:ui": "npm --prefix ui test",
     "bench:micro": "vitest bench --run --config vitest.config.bench.ts",
     "bench:serve": "bash bench/site.sh",
-    "lint": "eslint src tests",
+    "format": "prettier --write . --ignore-unknown",
+    "format:check": "prettier --check . --ignore-unknown",
+    "lint:eslint": "eslint src tests",
+    "lint": "npm run lint:eslint && npm run format:check",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
-    "check": "npm run lint && npm run typecheck && node scripts/check-doc-test-inventory.mjs && node scripts/check-doc-api-coverage.mjs && node scripts/check-doc-site-tickets.mjs && node scripts/check-cdn-versions.mjs && node scripts/check-dev-warn-docs.mjs && node scripts/check-skill-freshness.mjs && node scripts/check-design-rule-5.mjs && node scripts/check-feature-coverage.mjs && node scripts/check-ai-bundle.mjs && npm test && npm run build && node scripts/check-bundle-size.mjs && node scripts/check-doc-api-signatures.mjs && vitest run --config vitest.config.dist.ts && vitest run --config vitest.config.dist-full.ts && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json && node scripts/check-docs-examples.mjs",
+    "check": "npm run lint && npm run typecheck && node scripts/check-doc-test-inventory.mjs && node scripts/check-doc-api-coverage.mjs && node scripts/check-doc-site-tickets.mjs && node scripts/check-cdn-versions.mjs && node scripts/check-dev-warn-docs.mjs && node scripts/check-skill-freshness.mjs && node scripts/check-design-rule-5.mjs && node scripts/check-feature-coverage.mjs && node scripts/sync-lockstep-versions.mjs --check && node scripts/check-ai-bundle.mjs && npm test && npm run build && node scripts/check-bundle-size.mjs && node scripts/check-doc-api-signatures.mjs && vitest run --config vitest.config.dist.ts && vitest run --config vitest.config.dist-full.ts && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json && node scripts/check-docs-examples.mjs",
     "check:docs:examples": "node scripts/check-docs-examples.mjs",
     "check:full": "npm run check && npm run --silent check:audit && playwright test",
+    "check:ui": "npm --prefix ui run check",
     "check:docs:test-inventory": "node scripts/check-doc-test-inventory.mjs",
     "check:docs:api-coverage": "node scripts/check-doc-api-coverage.mjs",
     "check:docs:site-tickets": "node scripts/check-doc-site-tickets.mjs",
@@ -139,6 +153,8 @@
     "check:features": "node scripts/check-feature-coverage.mjs",
     "check:ai-bundle-in-sync": "node scripts/check-ai-bundle.mjs",
     "ai-bundle:sync": "node scripts/sync-ai-bundle.mjs",
+    "check:lockstep-versions": "node scripts/sync-lockstep-versions.mjs --check",
+    "sync:lockstep-versions": "node scripts/sync-lockstep-versions.mjs --write",
     "clean": "rm -rf dist coverage node_modules/.cache",
     "prepare": "husky",
     "release": "bash scripts/release.sh",
@@ -158,34 +174,40 @@
     "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.9",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "^1.63.0",
     "@types/jsdom": "^28.0.1",
     "@types/node": "^22.10.0",
     "@typescript-eslint/eslint-plugin": "^8.65.0",
     "@typescript-eslint/parser": "^8.65.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "domotion-svg": "^0.24.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "domotion-svg": "^0.30.1",
     "eslint": "^10.8.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "gitgist": "^1.1.0",
-    "happy-dom": "^20.9.0",
+    "happy-dom": "^20.14.5",
     "http-server": "^14.1.1",
     "husky": "^9.1.7",
     "jsdom": "^29.1.1",
+    "prettier": "^3.9.8",
+    "prettier-plugin-astro": "^1.0.1",
+    "prettier-plugin-sh": "^0.19.0",
     "tsup": "^8.3.0",
     "typescript": "^6.0.3",
     "typescript7": "npm:typescript@^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
+  },
+  "overrides": {
+    "esbuild": "0.28.2"
   },
   "gitgist": {
     "exclude": [
       "site/public/demos/*.svg",
-      "site/src/content/docs/docs/*",
-      "site/src/content/docs/api.md",
       "ai/*",
       "site/public/llms.txt",
       "bench/results.json",

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[] }>;