@contentful/experience-design-system-cli 2.34.5-dev-build-4471673c.0 → 2.35.0

package/README.md

@@ -0,0 +1,245 @@
+# @contentful/experience-design-system-cli
+
+CLI for extracting, reviewing, generating, validating, and pushing Contentful Experience Design System component definitions into Experiences.
+
+## Binaries
+
+The package installs three equivalent binaries:
+
+| Binary                         | Notes                                                 |
+| ------------------------------ | ----------------------------------------------------- |
+| `experiences`                  | Preferred entry point — short and operator-facing     |
+| `exo`                          | Shorthand for Experience Orchestration                |
+| `experience-design-system-cli` | Full name; used in CI / scripts where clarity matters |
+
+The rest of this README uses `experiences`.
+
+## CLI Overview
+
+The CLI has two primary workflows:
+
+1. **`experiences import`** — the wizard. Drives the full pipeline (extract → AI select → scope-gate → generation → final-review → save and push) from a single command in a full-screen interactive TUI. **This is the recommended path for almost everyone.**
+
+2. **`experiences apply <file>`** — applies a CDF file of component and token definitions to Contentful.
+
+`experiences setup` and `experiences doctor` configure and check your environment. `experiences importv2` launches the newer v2 TUI, and `experiences build` rebuilds a local checkout and re-links the binaries.
+
+The import wizard owns extraction, selection, generation, validation, and apply orchestration internally; those implementation stages are not exposed as public commands. Hidden internal commands (`__extract`, `__generate`, `map tokens`, `print`) are what the wizard runs in subprocesses.
+
+All intermediate data flows through a local SQLite session database (`~/.contentful/experience-design-system-cli/pipeline.db`). No JSON files are written between steps — each pipeline step reads its inputs from the session and writes its outputs back to it.
+
+---
+
+## Composite components & composition
+
+A **composite component** is one that renders other components inside it — a `Card` that slots a `Button` and an `Icon`, a `Tabs` that slots `Tab` panels. When you import composite components, the CLI can populate each slot's `$allowedComponents` so the parent→child relationships survive into Contentful.
+
+All imports use composite mode: embedded-component relationships are resolved and preserved in the generated CDF.
+
+### How composition is resolved
+
+Relationships are resolved from the highest-confidence source available, in this precedence order:
+
+1. **Typed slots (code)** — slots the source already declares, e.g. React `ReactElement<XProps>` / `children`, Svelte `Snippet<[XProps]>`, or an explicit `@allowedComponents` JSDoc tag. Fully deterministic; picked up automatically.
+2. **Agent** — direct edge emission for codebases that encode composition in _code patterns_ rather than typed slots (common in real-world design systems). It is enabled automatically in composite mode and only runs when the deterministic sources above find nothing.
+
+When more than one source speaks to the same relationship, the higher-precedence one wins (**code slots > agent**).
+
+### The composition agent
+
+The composition agent emits one structured edge per relationship. The CLI validates component names and merges those edges with deterministic sources by provenance and precedence.
+
+- `--no-cache` — ignore caches and re-resolve composition from scratch, forcing the agent to run.
+- `--agent <name>` — which coding agent runs composition, and the rest of the wizard's agent stages (`claude`, `codex`, `opencode`, `cursor`, `copilot`).
+- `--prompt composition=<file-or-text>` — override the composition stage's prompt.
+
+Because the agent path spawns a coding agent, it adds latency and cost and is best-effort.
+
+### Slot cycles
+
+If the resolved graph contains a circular slot dependency (A slots B, B slots A), it is detected before push. `apply` and the wizard's push path **refuse to send a manifest with cycles**; the cycle path is reported so you can break it.
+
+---
+
+## Prerequisites
+
+### Coding agent
+
+The import wizard's generation steps require a coding agent CLI in your `$PATH`. Choose one:
+
+| Agent                          | Install                                    | Auth                                                                                                                                                                                                       |
+| ------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Code** (`claude`)     | `npm install -g @anthropic-ai/claude-code` | `claude login` (browser OAuth) **or** set `ANTHROPIC_API_KEY`                                                                                                                                              |
+| **OpenAI Codex** (`codex`)     | `npm install -g @openai/codex`             | Set `OPENAI_API_KEY`                                                                                                                                                                                       |
+| **OpenCode** (`opencode`)      | `npm install -g opencode-ai`               | Configure via `opencode auth` (supports multiple providers)                                                                                                                                                |
+| **Cursor** (`cursor`)          | Install [Cursor](https://cursor.com)       | Sign in to Cursor; exposes `cursor-agent` binary                                                                                                                                                           |
+| **GitHub Copilot** (`copilot`) | `npm install -g @github/copilot`           | Run `copilot` once to complete GitHub OAuth login. Free plan uses Auto model selection by default. Paid plans can pin a specific model via `EDS_AGENT_MODEL_COPILOT=<model-id>` (e.g. `claude-sonnet-4.6`) |
+
+The CLI invokes the agent non-interactively in a subprocess. If the binary is not found in `$PATH`, the command exits 1 and prints manual fallback instructions.
+
+`experiences setup` persists your chosen agent (and optional model + custom prompt paths) to `~/.config/experiences/credentials.json`; later commands pick them up automatically.
+
+### Contentful credentials
+
+`apply` and `import` (when pushing) require access to a Contentful space. Configure these environment variables or run `experiences setup`:
+
+```bash
+export CONTENTFUL_MANAGEMENT_TOKEN=<your-cma-token>   # required
+export CONTENTFUL_SPACE_ID=<your-space-id>             # required
+export CONTENTFUL_ENVIRONMENT_ID=master                # required
+```
+
+Or run `experiences setup` once and they get saved to `credentials.json` and pre-filled in the wizard.
+
+In the wizard's credentials step you can press `[s] Skip` to save-only without pushing — useful when you want a checked-in combined CDF file without a live push.
+
+---
+
+## The `import` wizard
+
+```bash
+experiences import [flags]
+```
+
+`experiences import` is the primary entry point and launches a full-screen wizard in a supported interactive terminal.
+
+### Wizard step machine
+
+The order below is the normal path. The first step depends on how the wizard is started: `--project` jumps straight to `token-input`, and `--tokens` jumps to `path-validation` (with `--project`) or `credentials` (without it).
+
+```
+welcome                — project path
+  ↓
+token-input            — optional raw token file; Enter on an empty field skips
+  ↓                       (token-generation and token-reuse-gate run here when a file is given)
+path-validation        — confirms the project path and how many files will be scanned
+  ↓
+credentials            — space ID, environment, CMA token and API host, prefilled from
+                         `experiences setup`; press [s] to skip and save files only
+  ↓
+extracting             — composite relationships enabled; the selection agent runs here
+                         once components are extracted
+  ↓
+scope-gate             — single human review gate: confirm the AI selection, toggle components
+  ↓
+generating             — component generation, then token mapping when a token file was given
+  ↓
+final-review           — edit names, $description, $default, $allowedComponents per slot,
+                         $values, with source and rationale panels
+  ↓
+path-prompt            — where to save `components.json` (and `tokens.json`)
+  ↓
+previewing → preview-gate — diff against live Contentful; confirm to push
+  ↓
+pushing → done         — the push emits a Contentful webapp view URL for the imported components
+```
+
+There is a single human review gate (`scope-gate`) before generation. Choosing to skip credentials still saves the files; it bypasses the preview and refuses to push.
+
+### Save and push
+
+After final-review the wizard always saves one combined `components.json` CDF (components and design tokens) and then, unless credentials were skipped, previews the diff and pushes it to Contentful. The wizard records each saved run in `~/.config/experiences/runs.json`.
+
+### Custom skill prompts
+
+Custom `.md` skill prompt paths can be saved via `experiences setup`; the CLI emits a banner at agent invocation when an override is active.
+
+### Flag reference — `experiences import`
+
+| Flag                     | Default                   | Description                                                                                                                                                         |
+| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project <path>`       | `.`                       | Project root to analyze                                                                                                                                             |
+| `--tokens <path>`        | —                         | Raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, …) to classify and import alongside components; skips the interactive token prompt             |
+| `--agent <name>`         | saved by setup / `claude` | Coding agent, with an optional model as `agent:model` or `"agent model"`                                                                                            |
+| `--prompt <stage=value>` | —                         | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt select=./p.md`. Stages used today: `composition`, `select`, `map-tokens` |
+| `--no-cache`             | cache on                  | Re-run all steps instead of reusing cached results                                                                                                                  |
+
+`--model`, `--composition-map`, `--skip-map-tokens` and `--raw-tokens` were removed from `import`. Unknown flags are rejected. Pass the model through `--agent` instead, and use `--tokens` for a token file.
+
+### Choosing the agent and model
+
+`--agent` accepts `claude`, `codex`, `opencode`, `cursor` or `copilot`, optionally followed by a model: `--agent claude:sonnet` or `--agent "claude sonnet"`. The agent resolves in this order:
+
+1. `--agent <name>` flag
+2. `agent` field saved in `~/.config/experiences/credentials.json` by `experiences setup`
+3. Built-in default, `claude`
+
+The model resolves the same way: the model part of `--agent`, then the `agentModel` field in `credentials.json`, then the agent's own lightweight default. You can also set a model per agent with `EDS_AGENT_MODEL_<AGENT>` (for example `EDS_AGENT_MODEL_CLAUDE`).
+
+---
+
+### `apply`
+
+This command is the non-wizard route to the same diff and push logic. It accepts one CDF file containing all component and design token definitions.
+
+`apply` emits a Contentful webapp view URL for the imported components in its JSON summary (`viewUrl`) so callers can deep-link into the management UI after a successful push.
+
+Design tokens are read from the same CDF file, so there is no separate token flag.
+
+```bash
+experiences apply <file>
+```
+
+`apply` is interactive and loads credentials from `experiences setup` or environment variables. Remote ComponentTypes and DesignTokens missing from the pushed manifest are always skipped.
+
+Design tokens are written first (component types may reference token kinds). Each entity write is recorded in the session database atomically — interrupted pushes resume from where they left off.
+
+---
+
+## Session Database
+
+All pipeline state is stored in `~/.contentful/experience-design-system-cli/pipeline.db` (SQLite). The path can be overridden with the `EDS_PIPELINE_DB_PATH` environment variable. The push-resumption database is at `~/.contentful/experience-design-system-cli/import.db` (override with `EDS_IMPORT_DB_PATH`).
+
+---
+
+## Terminal Compatibility
+
+- The scope-gate step shows two columns at 100 or more terminal columns and one column below that; a wider terminal is more comfortable for the final-review editor
+- `NO_COLOR=1` suppresses all ANSI color output
+- Interactive views require both stdin and stdout to be TTYs and stdin to support raw mode.
+- On Windows, use Windows Terminal with PowerShell. Older ConEmu and cmd.exe hosts may not provide the raw-mode support the interactive UI needs.
+- `experiences import` does not provide a non-interactive execution mode.
+
+---
+
+## Usage data
+
+The CLI collects **anonymous usage data** to help us understand which commands are used and where the import workflow succeeds or fails. This data does **not** include your source code, file paths, credentials, prompts, or any content you author.
+
+What may be included:
+
+- Command name and duration
+- CLI, Node.js, and operating-system version
+- Anonymous session identifiers that link steps within a single import run
+- Structural counts (for example, how many components were extracted or accepted)
+- Space and environment IDs you pass on the command line
+- Contentful request IDs from API responses (to correlate failures with server logs)
+
+You can turn this off two ways:
+
+- Persistently: run `experiences setup`, open **Usage analytics** and choose "Don't share usage data". This writes `analyticsDisabled: true` to `~/.config/experiences/credentials.json`, which persists across invocations until you change it again — it will not silently re-enable itself.
+- Per invocation:
+
+  ```bash
+  DISABLE_ANALYTICS=1 experiences import --project ./my-app
+  ```
+
+  Setting `DISABLE_ANALYTICS` to any value disables collection for that invocation. This is additive with the persisted opt-out — it can only disable, never re-enable, collection that setup has turned off.
+
+---
+
+## Development
+
+```bash
+# Install dependencies from repo root
+pnpm install
+
+# Build
+pnpm -F @contentful/experience-design-system-cli build
+
+# Run tests
+pnpm -F @contentful/experience-design-system-cli test
+
+# Typecheck
+pnpm -F @contentful/experience-design-system-cli typecheck
+```

package/bin/cli.js

@@ -1,2 +1,58 @@
 #!/usr/bin/env node
-await import("../dist/index.js");
+// Suppress the SQLite ExperimentalWarning before any modules load.
+// Must use dynamic import so this handler registers before sqlite is imported.
+process.removeAllListeners("warning");
+process.on("warning", (w) => {
+  if (w.name === "ExperimentalWarning" && w.message.includes("SQLite")) return;
+  process.stderr.write(`${w.name}: ${w.message}\n`);
+});
+
+// Auto-rebuild when running from source (dev mode only).
+// Skipped when src/ doesn't exist (e.g. npm-installed users).
+import { existsSync, statSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, join } from "node:path";
+
+function newestMtime(dir, depth = 0) {
+  if (depth > 10) return 0;
+  let max = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      max = Math.max(max, newestMtime(full, depth + 1));
+    } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+      max = Math.max(max, statSync(full).mtimeMs);
+    }
+  }
+  return max;
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+const srcDir = join(pkgRoot, "src");
+const distEntry = join(pkgRoot, "dist", "src", "index.js");
+
+if (
+  existsSync(srcDir) &&
+  existsSync(distEntry) &&
+  process.env.NODE_ENV !== "test"
+) {
+  const distMtime = statSync(distEntry).mtimeMs;
+  if (newestMtime(srcDir) > distMtime) {
+    process.stderr.write("⚙ Source changed — rebuilding...\n");
+    const tsc = join(pkgRoot, "node_modules", ".bin", "tsc");
+    try {
+      execFileSync(tsc, ["-p", join(pkgRoot, "tsconfig.build.json")], {
+        stdio: ["ignore", "ignore", "inherit"],
+        cwd: pkgRoot,
+      });
+      process.stderr.write("✓ Build complete\n");
+    } catch {
+      process.stderr.write("✗ Build failed — running with existing dist\n");
+    }
+  }
+}
+
+await import("../dist/src/index.js");

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-4471673c.0",
+  "version": "2.35.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -9,13 +9,13 @@
     "experiences": "./bin/cli.js",
     "exo": "./bin/cli.js"
   },
-  "main": "./dist/index.js",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./app": {
-      "types": "./dist/app.d.ts",
-      "import": "./dist/app.js",
-      "node": "./dist/app.js"
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
     }
   },
   "publishConfig": {
@@ -25,17 +25,20 @@
   "files": [
     "bin/",
     "dist/",
-    "legacy/"
+    "prompts/",
+    "skills/"
   ],
   "scripts": {
     "build": "nx build experience-design-system-cli",
     "typecheck": "nx typecheck experience-design-system-cli",
     "clean": "nx clean experience-design-system-cli",
     "test": "nx test experience-design-system-cli",
+    "test:watch": "nx test:watch experience-design-system-cli",
     "lint": "nx lint experience-design-system-cli",
     "lint:fix": "nx lint:fix experience-design-system-cli"
   },
   "dependencies": {
+    "@contentful/experience-design-system-cli-v2": "workspace:*",
     "@contentful/experience-design-system-types": "workspace:*",
     "@inkjs/ui": "^2.0.0",
     "@segment/analytics-node": "^3.0.0",
@@ -46,19 +49,21 @@
     "ink": "^5.2.1",
     "react": "^18.3.1",
     "react-devtools-core": "^4.19.1",
-    "semver": "^7.7.2",
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3"
   },
   "devDependencies": {
+    "@contentful/experience-design-system-client": "workspace:*",
+    "@contentful/experience-design-system-extraction": "workspace:*",
+    "@contentful/experience-design-system-generation": "workspace:*",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.0.3",
     "@types/react": "^18.3.24",
-    "@types/semver": "^7.7.1",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
+    "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16"
   },