@dcoder-x/next 0.1.5 → 0.1.6

package/README.md

@@ -0,0 +1,393 @@
+# @dcoder-x/next
+
+Clippy build plugin for **Next.js** (App Router and Pages Router). 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/next
+# or
+pnpm add @dcoder-x/next
+# or
+yarn add @dcoder-x/next
+```
+
+`@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 Next.js project):
+
+```bash
+npm install --save-dev next webpack @babel/parser @babel/traverse
+```
+
+---
+
+## Quick start
+
+Wrap your Next.js config with `withClippy`:
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+import { withClippy } from '@dcoder-x/next'
+
+const nextConfig: NextConfig = {
+  // your existing Next.js config
+}
+
+export default withClippy(nextConfig, {
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+})
+```
+
+```js
+// next.config.js (CommonJS)
+const { withClippy } = require('@dcoder-x/next')
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {}
+
+module.exports = withClippy(nextConfig, {
+  apiKey: process.env.CLIPPY_API_KEY,
+  projectId: process.env.CLIPPY_PROJECT_ID,
+})
+```
+
+On every production build (`next build`) the plugin runs automatically — no additional scripts or CI steps required.
+
+---
+
+## 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 in local development or 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').
+   * When true, the plugin is a no-op in development mode (next dev).
+   * Default: false — the plugin runs on every build including dev.
+   */
+  productionOnly?: boolean
+
+  /**
+   * Write the generated JSON artifacts to a local directory in addition to
+   * (or instead of) uploading them. Useful for inspecting output and for
+   * CI pipelines that handle uploads separately.
+   *
+   * 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 — upload to your own backend:
+   *
+   * 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.local (never commit this)
+CLIPPY_API_KEY=pk_live_xxxxxxxxxxxx
+CLIPPY_PROJECT_ID=proj_xxxxxxxxxxxx
+```
+
+```bash
+# CI/CD environment variables
+CLIPPY_API_KEY=pk_live_xxxxxxxxxxxx
+CLIPPY_PROJECT_ID=proj_xxxxxxxxxxxx
+```
+
+---
+
+## Output files
+
+The plugin produces two files per build. Both share the same `buildId` so the Clippy runtime can match them to the active build.
+
+### `clippy-selectors.json`
+
+A flat, deduplicated manifest of every interactive element across all routes. This is what gets injected into LLM prompts for Tier 3 execution and used for 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": "DashboardForms-CreateForm-button-138",
+
+      // CSS selector that resolves this element in the live DOM.
+      // Always data-clippy-id when injection succeeded; falls back
+      // to aria-label, data-testid, or button:contains() selectors.
+      "selector": "[data-clippy-id='DashboardForms-CreateForm-button-138']",
+
+      // The React component that contains this element.
+      "component": "DashboardForms",
+
+      // The HTML tag of the injected element.
+      "tag": "button",
+
+      // Human-readable label derived from aria-label, visible text,
+      // placeholder, or name attribute. null when none is available.
+      "label": "Create Form",
+
+      // Every route where this element appears. Shared components
+      // (Input, Textarea, etc.) list all routes here rather than
+      // appearing as duplicate entries.
+      "routes": ["/dashboard/forms"]
+    }
+  ]
+}
+```
+
+### `clippy-policy.json`
+
+The full knowledge document used by the Clippy Policy Executor for Tier 1 (no-LLM) flow execution and by the backend for Tier 3 LLM context enrichment.
+
+```jsonc
+{
+  "version": "1.0.0",
+  "buildId": "abc123",
+  "generatedAt": "2026-06-02T10:00:00.000Z",
+  "bundler": "webpack",
+
+  // All discovered routes with relative file paths.
+  "routes": [
+    {
+      "path": "/dashboard/forms",
+      "filePath": "app/dashboard/forms/page.tsx",
+      "isDynamic": false,
+      "params": [],
+      "layout": "app/dashboard/layout.tsx",
+      "routerType": "app",
+      "semantic": "forms dashboard"
+    }
+  ],
+
+  // All interactive elements with their selector candidates.
+  "selectors": [
+    {
+      "clippyId": "DashboardForms-CreateForm-button-138",
+      "selector": "[data-clippy-id='DashboardForms-CreateForm-button-138']",
+      "tag": "button",
+      "component": "DashboardForms",
+      "label": "Create Form",
+      "route": "/dashboard/forms",
+      "filePath": "app/dashboard/forms/page.tsx",
+      "attributes": [{ "name": "type", "value": "submit" }],
+      "candidates": [
+        { "type": "clippy_id", "value": "[data-clippy-id='...']", "confidence": 0.999 },
+        { "type": "aria", "value": "button[aria-label='Create Form']", "confidence": 0.93 }
+      ]
+    }
+  ],
+
+  // Components with meaningful state or interaction data.
+  // Pure presentational components (Button, Card, etc.) are excluded.
+  "components": [
+    {
+      "name": "DashboardForms",
+      "filePath": "app/dashboard/forms/page.tsx",
+      "route": "/dashboard/forms",
+      "stateVariables": [
+        { "name": "isOpen", "setter": "setIsOpen", "initialValue": "false" }
+      ],
+      "interactions": [
+        {
+          "trigger": { "event": "onClick", "element": "button", "setsState": "isOpen" },
+          "effect": {
+            "type": "conditionalRender",
+            "rendersWhenTrue": "CreateFormModal",
+            "waitStrategy": "elementAppears",
+            "selector": "[data-clippy-component='CreateFormModal']"
+          }
+        }
+      ]
+    }
+  ],
+
+  // Multi-step navigation flows inferred from Link/anchor elements.
+  "flows": [
+    {
+      "flowId": "flow_1",
+      "page": "/auth/signup",
+      "intentPatterns": ["sign up", "create account", "register", "get started"],
+      "steps": [
+        { "step": 1, "action": "navigate", "target": "[data-clippy-id='SignupContent-form-126']" },
+        { "step": 2, "action": "transition", "target": "[data-clippy-id='PlanSelectionContent-button-176']" },
+        { "step": 3, "action": "transition", "target": "[data-clippy-id='OTPVerificationPage-form-163']" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 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 className="primary">Create Form</button>
+
+<!-- Compiled output (injected by the plugin): -->
+<button
+  className="primary"
+  data-clippy-id="DashboardForms-CreateForm-button-138"
+  data-clippy-component="DashboardForms"
+>
+  Create Form
+</button>
+```
+
+The `data-clippy-id` format is `ComponentName[-LabelText]-tag-lineNumber`:
+
+- **ComponentName** — the enclosing React component, or a route-derived name for page components (e.g., `AdminTransactions` instead of `Page`).
+- **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.
+
+IDs are stable across builds as long as the component name and the element's file position don't change. CSS class hashes change on every build; `data-clippy-id` does not.
+
+React components (`<Button />`, `<AlertDialog />`) are never touched — only native HTML elements.
+
+---
+
+## Router support
+
+| Router | Detection | Notes |
+|---|---|---|
+| App Router (Next.js 13+) | Filesystem — `app/**/page.tsx` | Route groups like `(auth)` are stripped |
+| Pages Router | Filesystem — `pages/**/*.tsx` | `api/` directory skipped |
+| React Router | AST — `createBrowserRouter`, `<Route path>` | Detected in `src/` |
+| TanStack Router | Filesystem — `src/routes/**/*.tsx` | Dot-separated filenames |
+
+---
+
+## Using local output for inspection
+
+During development, write artifacts locally to inspect them before uploading:
+
+```ts
+export default withClippy(nextConfig, {
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+  localOutputDir: '.clippy-output',
+  skipUpload: true, // don't upload, just write locally
+})
+```
+
+Add `.clippy-output` to `.gitignore`.
+
+---
+
+## CI/CD
+
+The plugin runs during `next build` and uploads automatically. No extra CI step is needed. If you prefer to control the upload yourself:
+
+```ts
+withClippy(nextConfig, {
+  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 appearing in the DOM**
+
+The loader only runs on non-server webpack compilations. Confirm you are inspecting the client-side rendered HTML, not server-rendered markup before hydration. Also check that the element is a native HTML tag — React components like `<Button />` are intentionally skipped.
+
+**IDs contain `Page` as the component name**
+
+This happens for files outside the `app/` directory where route inference can't determine the route. Add an `aria-label` to the element — the label will override the generic name in the ID.
+
+**Selectors show `button:contains(...)` instead of `data-clippy-id`**
+
+The `text:contains()` fallback is used when the injected ID cannot be matched back to a discovered element (typically a line number mismatch between compilation passes). It still works at runtime but is less stable than the injected ID. Adding `aria-label` to the button resolves this permanently.
+
+**Upload is failing**
+
+Verify `CLIPPY_API_KEY` and `CLIPPY_PROJECT_ID` are set in your build environment. Set `localOutputDir` to confirm the artifacts are being generated correctly before troubleshooting the upload.
+
+**Plugin is running in development but I only want production**
+
+```ts
+withClippy(nextConfig, {
+  apiKey: process.env.CLIPPY_API_KEY!,
+  projectId: process.env.CLIPPY_PROJECT_ID!,
+  productionOnly: true,
+})
+```
+
+---
+
+## Related packages
+
+- [`@dcoder-x/vite`](https://www.npmjs.com/package/@dcoder-x/vite) — same plugin for Vite 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/next",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -10,7 +10,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dcoder-x/plugin-shared": "^0.1.6"
+    "@dcoder-x/plugin-shared": "^0.1.7"
   },
   "peerDependencies": {
     "next": ">=13.0.0",