@dcoder-x/vite 0.1.5 → 0.1.6

package/README.md

@@ -0,0 +1,348 @@
+# @dcoder-x/vite
+
+Clippy build plugin for **Vite** (React, SvelteKit, Remix, and any Vite-based project). At compile time the plugin:
+
+1. Injects stable `data-clippy-id` attributes into every interactive HTML element in your compiled output — never modifying your source files.
+2. Analyzes your component tree to extract state variables, event handlers, and conditional render relationships.
+3. Discovers all routes, navigation links, and user-flow paths.
+4. Emits two JSON artifacts — `clippy-policy.json` and `clippy-selectors.json` — that the Clippy runtime uses to execute user prompts locally without LLM calls.
+
+---
+
+## Installation
+
+```bash
+npm install @dcoder-x/vite
+# or
+pnpm add @dcoder-x/vite
+# or
+yarn add @dcoder-x/vite
+```
+
+`@dcoder-x/plugin-shared` is a transitive dependency and is installed automatically. You do not need to install it separately.
+
+**Peer dependencies** (already present in any Vite project):
+
+```bash
+npm install --save-dev vite @babel/parser @babel/traverse
+```
+
+---
+
+## Quick start
+
+Add `clippyVitePlugin` to your Vite plugin array:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { clippyVitePlugin } from '@dcoder-x/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    clippyVitePlugin({
+      apiKey: process.env.CLIPPY_API_KEY!,
+      projectId: process.env.CLIPPY_PROJECT_ID!,
+    }),
+  ],
+})
+```
+
+The plugin runs automatically during `vite build` — no additional scripts or CI steps required. It is a no-op during `vite dev` (apply mode is `'build'` only).
+
+---
+
+## Configuration
+
+```ts
+interface ClippyPluginOptions {
+  /** Your Clippy API key. Get this from the Clippy developer dashboard. */
+  apiKey: string
+
+  /** Your Clippy project ID. Found in the project settings page. */
+  projectId: string
+
+  /**
+   * Skip uploading artifacts to the Clippy backend.
+   * Useful when you want to inspect the output before uploading.
+   * Artifacts are still written if localOutputDir is set.
+   * Default: false
+   */
+  skipUpload?: boolean
+
+  /**
+   * Only run the plugin during production builds (NODE_ENV === 'production').
+   * Default: false
+   */
+  productionOnly?: boolean
+
+  /**
+   * Write the generated JSON artifacts to a local directory in addition to
+   * (or instead of) uploading them.
+   *
+   * Two files are written:
+   *   <localOutputDir>/clippy-policy.json
+   *   <localOutputDir>/clippy-selectors.json
+   *
+   * Example: '.clippy-output'
+   */
+  localOutputDir?: string
+
+  /**
+   * How to upload artifacts to the Clippy backend.
+   *
+   * 'split'  — upload clippy-policy.json and clippy-selectors.json as separate
+   *             requests. Recommended for large projects.
+   * 'single' — bundle both artifacts into one gzipped payload.
+   *
+   * Default: 'split'
+   */
+  artifactUploadMode?: 'single' | 'split'
+
+  /**
+   * Provide a custom upload function. When set, the built-in HTTP uploader
+   * is bypassed entirely. Use this to integrate with your own artifact
+   * storage, a proxy endpoint, or a CI/CD pipeline step.
+   *
+   * Example:
+   *
+   * uploadAdapter: {
+   *   uploadArtifacts: async (artifacts) => {
+   *     await myApi.uploadPolicy(artifacts.policy)
+   *     await myApi.uploadSelectors(artifacts.selectorManifest)
+   *     return { skipped: false, policyUploaded: true, selectorsUploaded: true, mode: 'split' }
+   *   }
+   * }
+   */
+  uploadAdapter?: {
+    uploadArtifacts?: (artifacts: PolicyArtifacts) => Promise<UploadResult>
+  }
+}
+```
+
+### Recommended environment variable setup
+
+```bash
+# .env (never commit API keys — use .env.local or CI secrets)
+CLIPPY_API_KEY=pk_live_xxxxxxxxxxxx
+CLIPPY_PROJECT_ID=proj_xxxxxxxxxxxx
+```
+
+In Vite, environment variables must be prefixed with `VITE_` to be exposed to the browser. Clippy's API key and project ID are **only used at build time** inside the plugin, so they do not need the `VITE_` prefix and should not be exposed to the browser.
+
+```ts
+// Access in vite.config.ts via process.env (not import.meta.env)
+clippyVitePlugin({
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+})
+```
+
+---
+
+## Output files
+
+The plugin produces two files at the end of each build. Both share the same `buildId` so the Clippy runtime can link them to the active build.
+
+### `clippy-selectors.json`
+
+A flat, deduplicated manifest of every interactive element across all routes. Used for LLM context injection and selector health monitoring.
+
+```jsonc
+{
+  "version": "1.0.0",
+  "buildId": "abc123",
+  "generatedAt": "2026-06-02T10:00:00.000Z",
+  "selectors": [
+    {
+      // Stable ID injected as data-clippy-id in the compiled DOM.
+      // Format: ComponentName[-LabelText]-tag-lineNumber
+      "id": "SettingsPage-SaveChanges-button-205",
+
+      // CSS selector resolving this element in the live DOM.
+      "selector": "[data-clippy-id='SettingsPage-SaveChanges-button-205']",
+
+      "component": "SettingsPage",
+      "tag": "button",
+
+      // Human-readable label from aria-label, visible text, or placeholder.
+      // null when no static text is available.
+      "label": "Save Changes",
+
+      // All routes where this element is rendered.
+      // Shared components list multiple routes here rather than repeating.
+      "routes": ["/dashboard/settings"]
+    }
+  ]
+}
+```
+
+### `clippy-policy.json`
+
+The full knowledge document used by the Policy Executor for Tier 1 (no-LLM) flow execution and by the backend for LLM context enrichment.
+
+```jsonc
+{
+  "version": "1.0.0",
+  "buildId": "abc123",
+  "generatedAt": "2026-06-02T10:00:00.000Z",
+  "bundler": "vite",
+
+  // All discovered routes with relative file paths.
+  "routes": [
+    {
+      "path": "/dashboard/settings",
+      "filePath": "src/pages/settings.tsx",
+      "isDynamic": false,
+      "params": [],
+      "layout": null,
+      "routerType": "react-router",
+      "semantic": "settings dashboard"
+    }
+  ],
+
+  // All interactive elements with selector candidates.
+  "selectors": [ /* ... */ ],
+
+  // Components with meaningful state or interaction data.
+  // Purely presentational components (Button, Card, etc.) are excluded.
+  "components": [
+    {
+      "name": "SettingsPage",
+      "filePath": "src/pages/settings.tsx",
+      "route": "/dashboard/settings",
+      "stateVariables": [
+        { "name": "isDirty", "setter": "setIsDirty" }
+      ],
+      "interactions": [
+        {
+          "trigger": { "event": "onClick", "element": "button", "setsState": "isDirty" },
+          "effect": {
+            "type": "asyncEffect",
+            "waitStrategy": "domSettle",
+            "settleMs": 300
+          }
+        }
+      ]
+    }
+  ],
+
+  // Multi-step navigation flows inferred from Link/anchor elements.
+  "flows": [
+    {
+      "flowId": "flow_1",
+      "page": "/auth/login",
+      "intentPatterns": ["log in", "sign in", "login"],
+      "steps": [
+        { "step": 1, "action": "navigate", "target": "[data-clippy-id='LoginPage-form-115']" },
+        { "step": 2, "action": "transition", "target": "[data-clippy-id='Dashboard-a-42']" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## How stable selectors work
+
+The plugin transforms JSX at compile time — **not** your source files — to add two attributes to every native HTML element (`button`, `input`, `a`, `form`, `select`, `textarea`, `label`):
+
+```html
+<!-- Your source (never modified): -->
+<button>Save Changes</button>
+
+<!-- Compiled output (injected by the plugin): -->
+<button
+  data-clippy-id="SettingsPage-SaveChanges-button-205"
+  data-clippy-component="SettingsPage"
+>
+  Save Changes
+</button>
+```
+
+The `data-clippy-id` format is `ComponentName[-LabelText]-tag-lineNumber`:
+
+- **ComponentName** — the enclosing React component, or a route-derived name for page-level components.
+- **LabelText** — the element's visible text or `aria-label`, sanitized to TitleCase, max two words. Omitted when no static text is available.
+- **tag** — the lowercase HTML tag.
+- **lineNumber** — the element's position in the source file, acting as a stable tiebreaker when multiple elements share the same name.
+
+IDs are stable across builds as long as the component name and the element's file position don't change. CSS class hashes change with every Vite build; `data-clippy-id` does not.
+
+React component calls (`<Button />`, `<Modal />`) are never touched — only native HTML tags receive injected attributes.
+
+---
+
+## Router support
+
+| Router | Detection | Notes |
+|---|---|---|
+| React Router | AST — `createBrowserRouter`, `<Route path>` | Detected in `src/` |
+| TanStack Router | Filesystem — `src/routes/**/*.tsx` | Dot-separated filenames |
+| Pages Router (Next.js via Vite) | Filesystem — `pages/**/*.tsx` | |
+| App Router (Next.js via Vite) | Filesystem — `app/**/page.tsx` | Prefer `@dcoder-x/next` for Next.js |
+
+---
+
+## Using local output for inspection
+
+```ts
+clippyVitePlugin({
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+  localOutputDir: '.clippy-output',
+  skipUpload: true,
+})
+```
+
+Add `.clippy-output` to `.gitignore`.
+
+---
+
+## CI/CD
+
+The plugin runs at the end of `vite build` and uploads automatically. To control the upload yourself:
+
+```ts
+clippyVitePlugin({
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+  localOutputDir: 'dist/clippy',
+  skipUpload: true,
+  uploadAdapter: {
+    uploadArtifacts: async (artifacts) => {
+      // your upload logic
+    },
+  },
+})
+```
+
+---
+
+## Troubleshooting
+
+**`data-clippy-id` is not in the DOM**
+
+Confirm you are inspecting the production build output (`vite build`), not the dev server. The plugin only runs during the build phase.
+
+**Selectors show `button:contains(...)` instead of `data-clippy-id`**
+
+The `text:contains()` fallback appears when the injected ID can't be matched back to a discovered element. Adding `aria-label` to the element resolves this permanently.
+
+**No flows are generated**
+
+Flows are inferred from `<a href>` and `<Link to/href>` elements pointing to known routes. If your navigation uses programmatic `router.push()` without visible links, flows will not be automatically detected. Consider adding visible navigation links or using the Clippy dashboard to record flows explicitly.
+
+**Upload is failing**
+
+Verify `CLIPPY_API_KEY` and `CLIPPY_PROJECT_ID` are set in your build environment (not in `VITE_`-prefixed variables, which are client-only). Set `localOutputDir` to confirm artifacts are generating correctly before troubleshooting the upload.
+
+---
+
+## Related packages
+
+- [`@dcoder-x/next`](https://www.npmjs.com/package/@dcoder-x/next) — same plugin for Next.js projects
+- [`@dcoder-x/plugin-shared`](https://www.npmjs.com/package/@dcoder-x/plugin-shared) — internal shared extractors (not needed directly)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcoder-x/vite",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@dcoder-x/plugin-shared": "^0.1.6"
+    "@dcoder-x/plugin-shared": "^0.1.7"
   },
   "peerDependencies": {
     "vite": ">=4.0.0",