@sudosandwich/limps-headless 0.1.3

package/dist/types/index.d.ts.map

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

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for limps-headless extension.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/docs/architecture.md

@@ -0,0 +1,88 @@
+---
+title: limps-headless Architecture
+---
+
+# Architecture Overview
+
+limps-headless is a limps extension that extracts headless UI contracts (e.g. Radix UI), generates semantic signatures, and detects drift across versions.
+
+## Core Pipeline
+
+1. **Fetcher**
+   - Resolves versions and downloads type definitions
+   - Supports both individual `@radix-ui/react-*` packages and the unified `radix-ui` package
+
+2. **Extractor**
+   - Parses TypeScript `.d.ts` content
+   - Builds `ExtractedPrimitive` contracts (props, sub-components, exports)
+
+3. **Signatures**
+   - Converts raw contracts into behavioral signatures
+   - Classifies state, composition, and rendering patterns
+
+4. **Cache**
+   - Stores extracted contracts and signatures by primitive/version
+   - Speeds up repeated tool usage
+
+5. **Analyzer**
+   - Analyzes local components and matches against cached signatures
+   - Produces recommendations and confidence scores
+
+6. **Differ**
+   - Compares two versions of a primitive
+   - Emits breaking, warning, and info changes
+
+## What the diff does (planning and expansion)
+
+The diff exists to answer one question: **“If I upgrade Radix from one version to another, what will break or change in the public API?”** so you can plan migration work and avoid surprises.
+
+### What it compares
+
+It compares **contracts**, not source code or runtime behavior:
+
+- **Contract** = the extracted public API of each Radix primitive: props (name, type, required), subcomponents, and their types, as derived from the published `.d.ts` files.
+- For each primitive (or a subset), the differ loads the contract at the **from-version** and at the **to-version**, then diffs them.
+
+So you get a **type-level change report**: what was added, removed, or changed in the types consumers rely on.
+
+### What it produces
+
+A list of **changes**, each with:
+
+- **Severity**: `breaking` (will break your code), `warning` (may break or need review), `info` (additive, usually safe).
+- **Type**: e.g. `prop_removed`, `prop_required`, `type_narrowed`, `prop_added`, `type_widened`, `subcomponent_removed`, etc.
+- **Target**: which primitive, subcomponent, or prop the change applies to.
+- **Description**: a short, human-readable “what changed” (e.g. “Prop 'open' is now required on Root”).
+- **Migration hint**: actionable guidance (e.g. “Add an explicit value for this prop”) so you can plan fixes.
+
+So the diff is **planning-oriented**: it expands raw type deltas into descriptions and migration hints, not just “prop X changed”.
+
+### Flow (from-version → to-version)
+
+1. Resolve from-version and to-version (e.g. `1.0.0` and `latest`).
+2. For each primitive to diff: fetch/extract contract at from-version, fetch/extract contract at to-version (using cache when possible).
+3. Compare contracts: diff props (added/removed/required/type changes) and subcomponents; classify each change (breaking/warning/info) and generate description + migration hint.
+4. Return a single list of changes plus summary counts.
+
+### When to use it
+
+- **Before upgrading**: run diff from your current version (from-version) to the new version (to-version) to see breaking changes and plan code updates.
+- **With check-updates**: `headless_check_updates` can include a diff from current to latest so you see what an upgrade would entail.
+
+## Provider System
+
+Providers wrap library-specific behaviors (version resolution, type fetching) and enable future support for non-Radix component libraries.
+
+Default provider: `radix`
+
+## Tool Layer
+
+MCP tools are thin wrappers around the pipeline:
+
+- `headless_list_primitives`
+- `headless_extract_primitive`
+- `headless_analyze_component`
+- `headless_diff_versions`
+- `headless_check_updates`
+
+Each tool accepts an optional `provider` parameter (default: `radix`).

package/docs/providers.md

@@ -0,0 +1,47 @@
+---
+title: limps-headless Providers
+---
+
+# Providers
+
+Providers allow limps-headless to support different component libraries. Each provider implements a common interface and registers itself with the provider registry.
+
+## ComponentLibraryProvider Interface
+
+```typescript
+export interface ComponentLibraryProvider {
+  name: string;
+  displayName: string;
+  listPrimitives(version: string): Promise<string[]>;
+  resolveVersion(versionHint: string): Promise<string>;
+  fetchTypes(primitive: string, version: string): Promise<string>;
+  extract?(typeContent: string): ExtractedPrimitive;
+  generateSignature?(extracted: ExtractedPrimitive): BehaviorSignature;
+}
+```
+
+## Registering a Provider
+
+```typescript
+import { registerProvider } from '@sudosandwich/limps-headless/providers';
+
+registerProvider({
+  name: 'acme',
+  displayName: 'Acme UI',
+  async listPrimitives() {
+    return ['button', 'dialog'];
+  },
+  async resolveVersion(versionHint) {
+    return versionHint === 'latest' ? '1.0.0' : versionHint;
+  },
+  async fetchTypes(primitive, version) {
+    return `export interface ${primitive}Props {}`;
+  },
+});
+```
+
+## Notes
+
+- Providers can optionally override `extract` and `generateSignature`.
+- The default `radix` provider is registered automatically.
+- Some tools (analysis and diff) may only support the `radix` provider for now.

package/docs/tools.md

@@ -0,0 +1,143 @@
+---
+title: limps-headless Tool Reference
+---
+
+# Tool Reference
+
+All tools accept an optional `provider` (default: `radix`). Provider support is pluggable but only `radix` is fully supported today.
+
+## headless_list_primitives
+
+List available primitives.
+
+**Input**
+```json
+{
+  "version": "latest",
+  "provider": "radix"
+}
+```
+
+**Output**
+```json
+{
+  "version": "1.1.2",
+  "primitives": [
+    { "name": "dialog", "package": "@radix-ui/react-dialog" }
+  ]
+}
+```
+
+## headless_extract_primitive
+
+Extract a full primitive contract.
+
+**Input**
+```json
+{
+  "primitive": "dialog",
+  "version": "latest",
+  "provider": "radix"
+}
+```
+
+**Output**
+```json
+{
+  "primitive": "Dialog",
+  "package": "@radix-ui/react-dialog",
+  "version": "1.1.2",
+  "behavior": {
+    "statePattern": "binary",
+    "compositionPattern": "compound",
+    "renderingPattern": "portal-conditional"
+  },
+  "subComponents": [],
+  "similarTo": []
+}
+```
+
+## headless_analyze_component
+
+Analyze a local component and detect legacy Radix matches to inform Base UI migration. **filePath** is resolved relative to the current working directory (MCP server cwd or, when using the CLI, the directory you run `limps-headless` from—so run from your project root).
+
+**Input**
+```json
+{
+  "filePath": "src/components/MyDialog.tsx",
+  "radixVersion": "latest",
+  "threshold": 40,
+  "provider": "radix"
+}
+```
+
+**Output**
+```json
+{
+  "component": "MyDialog",
+  "filePath": "src/components/MyDialog.tsx",
+  "recommendation": {
+    "primitive": "Dialog",
+    "package": "@radix-ui/react-dialog",
+    "confidence": 78,
+    "action": "LEGACY_RADIX_MATCH_STRONG",
+    "reason": "High confidence legacy Radix match (78) - prioritize Base UI migration"
+  },
+  "isAmbiguous": false
+}
+```
+
+## headless_diff_versions
+
+**Purpose:** See what will break or need attention when upgrading Radix. Compares **two Radix versions** (not your code vs Radix)—primitive API contracts (props, subcomponents) between a from-version and a to-version. Reports breaking changes, warnings, and info. Input: `fromVersion` (e.g. your current), `toVersion` (e.g. latest).
+
+**Input**
+```json
+{
+  "fromVersion": "1.0.0",
+  "toVersion": "latest",
+  "primitives": ["dialog"],
+  "breakingOnly": false,
+  "provider": "radix"
+}
+```
+
+**Output**
+```json
+{
+  "fromVersion": "1.0.0",
+  "toVersion": "1.1.2",
+  "hasBreakingChanges": true,
+  "summary": { "totalChanges": 1, "breaking": 1, "warnings": 0, "info": 0 },
+  "changes": [
+    {
+      "primitive": "Dialog",
+      "type": "prop_removed",
+      "severity": "breaking",
+      "target": "allowPinchZoom"
+    }
+  ]
+}
+```
+
+## headless_check_updates
+
+Check for a newer version and include diffs when available.
+
+**Input**
+```json
+{
+  "refreshCache": false,
+  "provider": "radix"
+}
+```
+
+**Output**
+```json
+{
+  "currentVersion": "1.0.0",
+  "latestVersion": "1.1.2",
+  "hasUpdate": true,
+  "diff": { "summary": { "totalChanges": 2, "breaking": 0, "warnings": 1, "info": 1 } }
+}
+```

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@sudosandwich/limps-headless",
+  "version": "0.1.3",
+  "description": "limps extension for headless UI contract extraction, semantic analysis, and drift detection",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build && node scripts/prepare-publish.cjs",
+    "postpublish": "node scripts/cleanup-publish.cjs"
+  },
+  "keywords": [
+    "limps",
+    "headless-ui",
+    "radix-ui",
+    "mcp",
+    "extension"
+  ],
+  "author": "Paul Breuler",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paulbreuler/limps.git",
+    "directory": "packages/limps-headless"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "limps-headless": "bin/limps-headless"
+  },
+  "peerDependencies": {
+    "@sudosandwich/limps": "^2.0.0"
+  },
+  "devDependencies": {
+    "@sudosandwich/limps": "*",
+    "@types/node": "^25.0.0",
+    "@types/semver": "^7.7.1",
+    "typescript": "^5.9.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "semver": "^7.7.3",
+    "ts-morph": "^24.0.0",
+    "zod": "^4.3.6"
+  }
+}