[NO-ISSUE] feat(webkit): design-system adoption toolkit — catalog, lint, MCP, CLI

[HerbertJulio]

Summary

A design-system adoption toolkit so any project can consume @aziontech/webkit correctly and performantly by construction — not just by documentation. It ships as sibling packages published from this monorepo; webkit itself stays "just a UI lib".

The toolkit is two layers over a single source of truth:

• Source of truth — catalog.json (generated inside @aziontech/webkit from package.json#exports + .specs, version-locked, regenerated at release). Every tool reads this one file, so nothing can drift from the installed webkit version.
• FORCE (deterministic, blocks in pre-commit/CI) — @aziontech/eslint-plugin-webkit + @aziontech/stylelint-config-webkit.
• GUIDE (assistive, helps the AI/dev get it right up front) — @aziontech/webkit-mcp (tool-agnostic MCP) + a Claude Code bundle (rules/skill/agents) dropped by @aziontech/webkit-cli init.

What it does (per package)

Package	What it does
@aziontech/webkit (modified)	scripts/build-catalog.mjs + generated catalog.json (shipped in files, built in .releaserc prepareCmd); ./catalog.json export added
@aziontech/eslint-plugin-webkit	6 rules — valid-import-path, no-deep-internal-import, no-barrel-import, no-hardcoded-color, prefer-tree-shakeable-root, no-whole-icon-set-import — with recommended / strict / performance presets. Reads the installed catalog (version-locked, fail-open)
@aziontech/stylelint-config-webkit	Token discipline in CSS/SCSS/Vue <style> (no hex/rgb/hsl)
@aziontech/webkit-mcp	MCP server (npx) over the catalog: list_components, get_component, get_import (returns the tree-shakeable -root + compound alternative), search/suggest_component, get_usage_example, validate_usage
@aziontech/webkit-cli	npx @aziontech/webkit init — one idempotent command wiring deps + eslint/stylelint + pre-commit + .mcp.json + the Claude Code bundle (4 rules, webkit-usage skill, webkit-expert/webkit-adopter/webkit-reviewer agents) + a CLAUDE.md fragment

How a consumer uses it

npx @aziontech/webkit init      # 1 command: installs + wires linter + MCP + Claude bundle

Then, day to day: the linter blocks incorrect/slow usage on commit & CI; the MCP makes the AI generate flat imports, tree-shakeable -root imports and token classes from the start. 0 extra commands after setup.

How to test

Requires Node ≥ 22. Run pnpm install at the repo root first so the new workspaces and their deps (eslint, vue-eslint-parser, stylelint) resolve.

# 1. Catalog is deterministic + matches exports (drift check)
node packages/webkit/scripts/build-catalog.mjs
pnpm --filter @aziontech/webkit catalog:check       # no diff = in sync

# 2. Unit tests — 38 total, all green
node --test packages/eslint-plugin-webkit/test/*.test.mjs     # 6  (RuleTester)
node --test packages/stylelint-config-webkit/test/*.test.mjs  # 5
node --test packages/webkit-mcp/test/*.test.mjs               # 17 (pure query fns)
node --test packages/webkit-cli/test/*.test.mjs               # 10 (plan/apply + idempotency)

# 3. CLI end-to-end (idempotent) — run init twice in a scratch project:
mkdir -p /tmp/demo && cd /tmp/demo && echo '{"name":"demo"}' > package.json
node <repo>/packages/webkit-cli/src/cli.js init            # writes configs + .claude bundle + .mcp.json
node <repo>/packages/webkit-cli/src/cli.js init --dry-run  # second run: all SKIP (never clobbers)

# 4. MCP smoke (version-locked to the installed catalog):
WEBKIT_CATALOG_PATH=<repo>/packages/webkit/catalog.json npx @aziontech/webkit-mcp

Also verified locally: a real ESLint run (flat config, strict preset, real catalog) flags a barrel import, an unknown subpath (datatable), a deep /src/ import, a whole-icon-set import, a hardcoded #hex, and a compound-used-root-only case — while clean flat/tree-shakeable/token code passes (8/8).

Notes

• Remaining infra (not blocking this PR): run pnpm install to link the new workspaces; add one .github/workflows/package-<name>.yml per new package (clone of package-webkit.yml) to publish them — the per-package .releaserc files are already in place with releaseRules byte-for-byte identical to webkit's (per .claude/rules/release-types.md).
• No AI review in CI for now (deliberate) — PR-time enforcement is the deterministic linter; webkit-reviewer provides local AI review. A claude-code-action CI reviewer is a documented future phase.
• New runtime deps introduced: @aziontech/webkit-mcp depends on @modelcontextprotocol/sdk + zod (loaded lazily; fetched at npx time).
• No breaking changes. feat across the touched packages → minor bump each.