@contentful/experience-design-system-cli 2.34.5-dev-build-4a4b9e84.0 → 2.34.5-dev-build-9dff4380.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -68
- package/dist/package.json +1 -1
- package/dist/src/analyze/extract-command.d.ts +7 -0
- package/dist/src/index.js +8894 -8843
- package/package.json +6 -6
- package/skills/select-components.md +1 -1
- package/dist/src/import/extract-project.d.ts +0 -33
package/README.md
CHANGED
|
@@ -6,11 +6,11 @@ CLI for extracting, reviewing, generating, validating, and pushing Contentful Ex
|
|
|
6
6
|
|
|
7
7
|
The package installs three equivalent binaries:
|
|
8
8
|
|
|
9
|
-
| Binary
|
|
10
|
-
|
|
|
11
|
-
| `experiences`
|
|
12
|
-
| `exo`
|
|
13
|
-
| `experience-design-system-cli`
|
|
9
|
+
| Binary | Notes |
|
|
10
|
+
| ------------------------------ | ----------------------------------------------------- |
|
|
11
|
+
| `experiences` | Preferred entry point — short and operator-facing |
|
|
12
|
+
| `exo` | Shorthand for Experience Orchestration |
|
|
13
|
+
| `experience-design-system-cli` | Full name; used in CI / scripts where clarity matters |
|
|
14
14
|
|
|
15
15
|
The rest of this README uses `experiences`.
|
|
16
16
|
|
|
@@ -18,11 +18,13 @@ The rest of this README uses `experiences`.
|
|
|
18
18
|
|
|
19
19
|
The CLI has two primary workflows:
|
|
20
20
|
|
|
21
|
-
1. **`experiences import`** — the wizard. Drives the full pipeline (extract → AI select → scope-gate →
|
|
21
|
+
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.**
|
|
22
22
|
|
|
23
|
-
2. **`experiences apply
|
|
23
|
+
2. **`experiences apply <file>`** — applies a CDF file of component and token definitions to Contentful.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
`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.
|
|
26
|
+
|
|
27
|
+
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.
|
|
26
28
|
|
|
27
29
|
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.
|
|
28
30
|
|
|
@@ -39,7 +41,7 @@ All imports use composite mode: embedded-component relationships are resolved an
|
|
|
39
41
|
Relationships are resolved from the highest-confidence source available, in this precedence order:
|
|
40
42
|
|
|
41
43
|
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.
|
|
42
|
-
2. **Agent** — direct edge emission for codebases that encode composition in
|
|
44
|
+
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.
|
|
43
45
|
|
|
44
46
|
When more than one source speaks to the same relationship, the higher-precedence one wins (**code slots > agent**).
|
|
45
47
|
|
|
@@ -48,7 +50,7 @@ When more than one source speaks to the same relationship, the higher-precedence
|
|
|
48
50
|
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.
|
|
49
51
|
|
|
50
52
|
- `--no-cache` — ignore caches and re-resolve composition from scratch, forcing the agent to run.
|
|
51
|
-
- `--agent <name>` — which coding agent
|
|
53
|
+
- `--agent <name>` — which coding agent runs composition, and the rest of the wizard's agent stages (`claude`, `codex`, `opencode`, `cursor`, `copilot`).
|
|
52
54
|
- `--prompt composition=<file-or-text>` — override the composition stage's prompt.
|
|
53
55
|
|
|
54
56
|
Because the agent path spawns a coding agent, it adds latency and cost and is best-effort.
|
|
@@ -65,13 +67,13 @@ If the resolved graph contains a circular slot dependency (A slots B, B slots A)
|
|
|
65
67
|
|
|
66
68
|
The import wizard's generation steps require a coding agent CLI in your `$PATH`. Choose one:
|
|
67
69
|
|
|
68
|
-
| Agent
|
|
69
|
-
|
|
70
|
-
| **Claude Code** (`claude`)
|
|
71
|
-
| **OpenAI Codex** (`codex`)
|
|
72
|
-
| **OpenCode** (`opencode`)
|
|
73
|
-
| **Cursor** (`cursor`)
|
|
74
|
-
| **GitHub Copilot** (`copilot`) | `npm install -g @github/copilot`
|
|
70
|
+
| Agent | Install | Auth |
|
|
71
|
+
| ------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
+
| **Claude Code** (`claude`) | `npm install -g @anthropic-ai/claude-code` | `claude login` (browser OAuth) **or** set `ANTHROPIC_API_KEY` |
|
|
73
|
+
| **OpenAI Codex** (`codex`) | `npm install -g @openai/codex` | Set `OPENAI_API_KEY` |
|
|
74
|
+
| **OpenCode** (`opencode`) | `npm install -g opencode-ai` | Configure via `opencode auth` (supports multiple providers) |
|
|
75
|
+
| **Cursor** (`cursor`) | Install [Cursor](https://cursor.com) | Sign in to Cursor; exposes `cursor-agent` binary |
|
|
76
|
+
| **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`) |
|
|
75
77
|
|
|
76
78
|
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.
|
|
77
79
|
|
|
@@ -103,38 +105,40 @@ experiences import [flags]
|
|
|
103
105
|
|
|
104
106
|
### Wizard step machine
|
|
105
107
|
|
|
108
|
+
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).
|
|
109
|
+
|
|
106
110
|
```
|
|
107
|
-
welcome
|
|
111
|
+
welcome — project path
|
|
108
112
|
↓
|
|
109
|
-
|
|
110
|
-
|
|
113
|
+
token-input — optional raw token file; Enter on an empty field skips
|
|
114
|
+
↓ (token-generation and token-reuse-gate run here when a file is given)
|
|
115
|
+
path-validation — confirms the project path and how many files will be scanned
|
|
111
116
|
↓
|
|
112
|
-
|
|
117
|
+
credentials — space ID, environment, CMA token and API host, prefilled from
|
|
118
|
+
`experiences setup`; press [s] to skip and save files only
|
|
113
119
|
↓
|
|
114
|
-
|
|
120
|
+
extracting — composite relationships enabled; the selection agent runs here
|
|
121
|
+
once components are extracted
|
|
115
122
|
↓
|
|
116
|
-
|
|
117
|
-
press [s] Skip to save-only without pushing
|
|
123
|
+
scope-gate — single human review gate: confirm the AI selection, toggle components
|
|
118
124
|
↓
|
|
119
|
-
|
|
120
|
-
$default, $allowedComponents per slot, $values, source/rationale panels
|
|
125
|
+
generating — component generation, then token mapping when a token file was given
|
|
121
126
|
↓
|
|
122
|
-
|
|
127
|
+
final-review — edit names, $description, $default, $allowedComponents per slot,
|
|
128
|
+
$values, with source and rationale panels
|
|
123
129
|
↓
|
|
124
|
-
|
|
130
|
+
path-prompt — where to save `components.json` (and `tokens.json`)
|
|
125
131
|
↓
|
|
126
|
-
|
|
132
|
+
previewing → preview-gate — diff against live Contentful; confirm to push
|
|
133
|
+
↓
|
|
134
|
+
pushing → done — the push emits a Contentful webapp view URL for the imported components
|
|
127
135
|
```
|
|
128
136
|
|
|
129
|
-
There is
|
|
130
|
-
|
|
131
|
-
### Configurable AI auto-filter
|
|
137
|
+
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.
|
|
132
138
|
|
|
133
|
-
|
|
139
|
+
### Save and push
|
|
134
140
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
The push-decision-gate defaults to **save AND push**: it writes one combined `components.json` CDF containing components and design tokens, then pushes it to Contentful in one step.
|
|
141
|
+
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`.
|
|
138
142
|
|
|
139
143
|
### Custom skill prompts
|
|
140
144
|
|
|
@@ -142,39 +146,25 @@ Custom `.md` skill prompt paths can be saved via `experiences setup`; the CLI em
|
|
|
142
146
|
|
|
143
147
|
### Flag reference — `experiences import`
|
|
144
148
|
|
|
145
|
-
| Flag
|
|
146
|
-
|
|
|
147
|
-
| `--project <path>`
|
|
148
|
-
| `--
|
|
149
|
-
| `--
|
|
150
|
-
| `--
|
|
151
|
-
| `--
|
|
152
|
-
| `--skip-map-tokens` | — | Skip the `map tokens` step between internal generation and apply |
|
|
153
|
-
| `--no-cache` | cache on | Bypass extract/select/internal-generation/map-tokens/composition caches and force re-run |
|
|
154
|
-
|
|
155
|
-
### `--model` and `--agent` overrides
|
|
149
|
+
| Flag | Default | Description |
|
|
150
|
+
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
151
|
+
| `--project <path>` | `.` | Project root to analyze |
|
|
152
|
+
| `--tokens <path>` | — | Raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, …) to classify and import alongside components; skips the interactive token prompt |
|
|
153
|
+
| `--agent <name>` | saved by setup / `claude` | Coding agent, with an optional model as `agent:model` or `"agent model"` |
|
|
154
|
+
| `--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` |
|
|
155
|
+
| `--no-cache` | cache on | Re-run all steps instead of reusing cached results |
|
|
156
156
|
|
|
157
|
-
`--model
|
|
157
|
+
`--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.
|
|
158
158
|
|
|
159
|
-
|
|
160
|
-
2. `model` field saved in `~/.config/experiences/credentials.json`
|
|
161
|
-
3. Built-in default for the chosen agent
|
|
159
|
+
### Choosing the agent and model
|
|
162
160
|
|
|
163
|
-
`--agent
|
|
161
|
+
`--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:
|
|
164
162
|
|
|
165
|
-
|
|
163
|
+
1. `--agent <name>` flag
|
|
164
|
+
2. `agent` field saved in `~/.config/experiences/credentials.json` by `experiences setup`
|
|
165
|
+
3. Built-in default, `claude`
|
|
166
166
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
Unchanged from prior releases.
|
|
170
|
-
|
|
171
|
-
```bash
|
|
172
|
-
experiences print components [--session <id>] [--out <path>]
|
|
173
|
-
experiences print tokens [--session <id>] [--out <path>]
|
|
174
|
-
experiences print validate [--components <path>] [--tokens <path>]
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
`print validate` exits `0` on success, `1` on validation errors.
|
|
167
|
+
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`).
|
|
178
168
|
|
|
179
169
|
---
|
|
180
170
|
|
|
@@ -184,6 +174,8 @@ This command is the non-wizard route to the same diff and push logic. It accepts
|
|
|
184
174
|
|
|
185
175
|
`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.
|
|
186
176
|
|
|
177
|
+
Design tokens are read from the same CDF file, so there is no separate token flag.
|
|
178
|
+
|
|
187
179
|
```bash
|
|
188
180
|
experiences apply <file>
|
|
189
181
|
```
|
|
@@ -202,9 +194,7 @@ All pipeline state is stored in `~/.contentful/experience-design-system-cli/pipe
|
|
|
202
194
|
|
|
203
195
|
## Terminal Compatibility
|
|
204
196
|
|
|
205
|
-
-
|
|
206
|
-
- 80+ columns recommended for full sidebar + detail view
|
|
207
|
-
- 120+ columns required to show the source code panel in `analyze select`
|
|
197
|
+
- 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
|
|
208
198
|
- `NO_COLOR=1` suppresses all ANSI color output
|
|
209
199
|
- Interactive views require both stdin and stdout to be TTYs and stdin to support raw mode.
|
|
210
200
|
- On Windows, use Windows Terminal with PowerShell. Older ConEmu and cmd.exe hosts may not provide the raw-mode support the interactive UI needs.
|
|
@@ -227,7 +217,7 @@ What may be included:
|
|
|
227
217
|
|
|
228
218
|
You can turn this off two ways:
|
|
229
219
|
|
|
230
|
-
- Persistently: run `experiences setup
|
|
220
|
+
- 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.
|
|
231
221
|
- Per invocation:
|
|
232
222
|
|
|
233
223
|
```bash
|
package/dist/package.json
CHANGED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { Command } from 'commander';
|
|
2
|
+
export declare function resolveExtractNoCache(opts: {
|
|
3
|
+
cache?: boolean;
|
|
4
|
+
noCache?: boolean;
|
|
5
|
+
}): boolean;
|
|
6
|
+
export declare function collectSourceFiles(directory: string, onProgress?: (scannedCount: number) => void): Promise<string[]>;
|
|
7
|
+
export declare function registerInternalExtractCommand(program: Command): void;
|