uidex 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uidex",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Convention-driven UI element registry and devtools surface for React apps.",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,18 +58,15 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@playwright/test": ">=1.40",
-    "react": ">=18",
-    "react-dom": ">=18"
+    "@hey-api/client-fetch": "^0.10.0"
   },
   "peerDependenciesMeta": {
-    "@playwright/test": {
+    "@hey-api/client-fetch": {
       "optional": true
     }
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@zag-js/combobox": "^1.40.0",
     "@zag-js/core": "^1.40.0",
     "@zag-js/dialog": "^1.40.0",
     "@zag-js/menu": "^1.40.0",
@@ -81,14 +78,17 @@
     "@zag-js/types": "^1.40.0",
     "@zag-js/utils": "^1.40.0",
     "clsx": "^2.1.1",
+    "lit-html": "^3.3.2",
     "lucide": "^1.8.0",
     "lucide-react": "^1.7.0",
+    "modern-screenshot": "^4.7.0",
     "tailwind-merge": "^3.5.0",
     "xstate": "^5.30.0",
     "zod": "^4.3.6",
     "zustand": "^5.0.2"
   },
   "devDependencies": {
+    "@hey-api/client-fetch": "^0.10.0",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.2.2",
     "@testing-library/jest-dom": "^6.6.3",
@@ -106,6 +106,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8",
+    "@uidex/api-client": "0.0.1",
     "@uidex/eslint-config": "0.0.0",
     "@uidex/tsconfig": "0.0.0"
   },
@@ -125,8 +126,9 @@
   },
   "scripts": {
     "dev": "tsup --watch",
-    "build": "pnpm run build:css && tsup && pnpm run check:bundles",
-    "build:css": "tailwindcss --input src/styles/tailwind.css --output src/styles/tailwind.built.css",
+    "build": "pnpm run generate:api-routes && pnpm run build:css && tsup && pnpm run check:bundles",
+    "generate:api-routes": "tsx scripts/generate-api-routes.ts",
+    "build:css": "tailwindcss --input src/browser/styles/tailwind.css --output src/browser/styles/tailwind.built.css",
     "check:bundles": "node scripts/check-bundles.mjs",
     "test": "vitest run",
     "test:watch": "vitest",

package/templates/claude/api.md

@@ -0,0 +1,110 @@
+# uidex API
+
+The uidex CLI includes an API client for querying and managing uidex resources (organizations, projects, reports, integrations, etc.).
+
+## Authentication
+
+```bash
+npx uidex api login                      # Interactive browser login (opens browser, creates a personal access token)
+npx uidex api login --token <tok>        # Store a token directly
+npx uidex api status                     # Check auth state
+```
+
+Tokens are stored at `~/.uidex/cloud-token.json`. The `UIDEX_TOKEN` env var overrides the stored token.
+
+## Making requests
+
+```bash
+npx uidex api <METHOD> <PATH> [flags]
+```
+
+### Flags
+
+| Flag               | Description                                              |
+| ------------------ | -------------------------------------------------------- |
+| `--body <json>`    | Request body (JSON string)                               |
+| `--query <params>` | Query string (`key=val&key2=val2`)                       |
+| `--base-url <url>` | Override API base URL (default: `https://app.uidex.dev`) |
+| `--token <tok>`    | Use a specific token for this request                    |
+| `--raw`            | Disable JSON pretty-printing                             |
+| `--no-color`       | Disable colored output                                   |
+
+Use `UIDEX_API_URL` env var to permanently override the base URL (e.g. for local dev at `http://localhost:4339`).
+
+## Discovering routes
+
+```bash
+npx uidex api --list                     # List all routes
+npx uidex api --list --tag Reports       # Filter by tag
+npx uidex api --list --json              # JSON output
+```
+
+## Common workflows
+
+### List organizations and projects
+
+```bash
+npx uidex api GET /api/organizations
+npx uidex api GET /api/organizations/{orgId}/projects
+```
+
+### Query reports
+
+```bash
+# All reports in an org
+npx uidex api GET /api/organizations/{orgId}/reports
+
+# Reports for a specific project
+npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/reports
+
+# Filter with query params (status, type, severity, search, page, limit)
+npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/reports \
+  --query "status=open&type=bug&limit=10"
+
+# Single report detail
+npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/feedback/{reportId}
+```
+
+### Update a report
+
+```bash
+npx uidex api PATCH /api/organizations/{orgId}/projects/{projectId}/feedback/{reportId} \
+  --body '{"status":"resolved"}'
+```
+
+### Resolve a project key
+
+Given a project key (e.g. from `NEXT_PUBLIC_UIDEX_PROJECT_KEY` in `.env.local`), resolve it to the project and org in one call:
+
+```bash
+npx uidex api GET /api/projects/resolve --query "key=ux_dev_6ghJQlUj-OfgvKvbyQCGc8ugqgYe_xjO"
+```
+
+Returns `{ organization, project, apiKey }` with full details.
+
+### Manage integrations
+
+```bash
+npx uidex api GET /api/organizations/{orgId}/integrations
+npx uidex api POST /api/organizations/{orgId}/integrations/{integrationId}/test
+```
+
+### Issue drafts
+
+```bash
+npx uidex api GET /api/organizations/{orgId}/issue-drafts
+npx uidex api POST /api/organizations/{orgId}/issue-drafts/{draftId}/submit
+```
+
+## Route tags
+
+Routes are grouped by tag: `Ingest`, `Organizations`, `Members`, `Invitations`, `Projects`, `API Keys`, `Reports`, `Integrations`, `External Issues`, `Issue Drafts`, `Triage`, `User Tokens`, `CLI Auth`. Use `--list --tag <Tag>` to explore a specific group.
+
+## Resolving IDs
+
+Most routes require `orgId` and `projectId` path parameters. To resolve them:
+
+- **From a project key** (fastest): `GET /api/projects/resolve?key=<raw_key>` → returns both `organization.id` and `project.id`
+- **From scratch**: `GET /api/organizations` → find org by `slug`, then `GET /api/organizations/{orgId}/projects` → find project by `slug`
+
+When working in a repo that has uidex configured, read `NEXT_PUBLIC_UIDEX_PROJECT_KEY` from `.env.local` (or `.env`) and use the resolve endpoint to get the org and project IDs in one call.

package/templates/claude/audit.md

@@ -1,8 +1,8 @@
 Run `npx uidex scan --audit` and fix all reported diagnostics.
 
 1. **`marker-md-ignored`** — legacy `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` files from v1. Migrate their content:
-   - Copy the description and acceptance list into a `@uidex page <id>` or `@uidex feature <id>` JSDoc block on the corresponding module (`page.tsx` for pages; the feature's main index/component for features).
-   - Each `- [ ]` checkbox becomes one `@acceptance <text>` tag.
+   - Create a `uidex.page.ts` (in the route directory) or `uidex.feature.ts` (in the feature directory) and add an `export const uidex` block carrying the `page`/`feature` id, the description, and the acceptance list.
+   - Each `- [ ]` checkbox becomes one entry in the `acceptance` array.
    - Delete the `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` file.
 
 2. **`acceptance-uncovered`** — a declared `@acceptance` criterion has no flow exercising it.
@@ -24,6 +24,12 @@ Run `npx uidex scan --audit` and fix all reported diagnostics.
 6. **`acceptance-orphan`** — an `@acceptance` tag appears on a JSDoc that doesn't declare `@uidex page|feature|widget`.
    - Move the acceptance tags into the correct JSDoc block, or remove them.
 
+7. **`prefer-well-known-file`** (INFO) — a page or feature's `export const uidex` lives on an arbitrary file instead of the well-known file (`uidex.page.ts` for pages, `uidex.feature.ts` for features). Migrate:
+   - Create `uidex.page.ts` (in the route directory) or `uidex.feature.ts` (in the feature directory).
+   - Move the `export const uidex` block from the current file into the new well-known file.
+   - Remove the export (and any now-unused `Uidex` type import) from the original file.
+   - Run `npx uidex scan` to regenerate the gen file — `loc.file` updates but the entity itself is unchanged.
+
 After fixing, run `npx uidex scan` to regenerate the gen file before re-running the audit.
 
 ## Decision rules for primitives

package/templates/claude/rules.md

@@ -2,6 +2,21 @@
 
 This project uses [uidex](https://github.com/soel/uidex) for UI element tracking and feedback ingestion.
 
+## AI behavior
+
+Before editing any file inside a feature directory (`src/features/<name>/`) or a Next.js route directory, read the entity's well-known metadata file first:
+
+- Feature directories: `uidex.feature.ts` — the feature's `export const uidex` block lives here.
+- Route directories: `uidex.page.ts` — the page's `export const uidex` block lives here.
+
+These files declare `acceptance` criteria and a `description`. Treat them as **context steering**, not test assertions:
+
+- Acceptance criteria capture what matters about the page or feature so changes preserve the right behaviors. They are NOT the testing source of truth — Playwright flows under `e2e/**` are.
+- Before making a change, check whether it would violate a declared acceptance criterion. If it would, flag the conflict to the user before proceeding.
+- If a change adds or removes user-visible behavior, update the acceptance list in the well-known file alongside the code change.
+
+If a feature or page directory has no `uidex.feature.ts` / `uidex.page.ts`, the metadata may live on an arbitrary file in the directory (legacy convention) — `uidex scan --audit` will surface a `prefer-well-known-file` diagnostic with the current location.
+
 ## Entity model
 
 Eight entity kinds make up the registry. Most are discovered by convention; annotations only override.