@contentful/experience-design-system-cli 2.11.4-dev-build-d47ab65.0 → 2.12.1-dev-build-589b615.0

package/dist/src/setup/auto-filter-prompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ask the operator whether to enable the AI auto-filter by default.
+ *
+ * The helper is injectable so it can be unit-tested without a TTY. The caller
+ * provides an `ask` function that yields one line of input per call.
+ *
+ * Behavior:
+ *   - Empty input returns `current` if defined, else `true` (default ON).
+ *   - Input starting with 'y' or 'Y' returns `true`.
+ *   - Input starting with 'n' or 'N' returns `false`.
+ *   - Any other input falls back to the same rule as empty input.
+ */
+export declare function promptAutoFilterPreference(ask: (q: string) => Promise<string>, current?: boolean): Promise<boolean>;

package/dist/src/setup/auto-filter-prompt.js

@@ -0,0 +1,24 @@
+/**
+ * Ask the operator whether to enable the AI auto-filter by default.
+ *
+ * The helper is injectable so it can be unit-tested without a TTY. The caller
+ * provides an `ask` function that yields one line of input per call.
+ *
+ * Behavior:
+ *   - Empty input returns `current` if defined, else `true` (default ON).
+ *   - Input starting with 'y' or 'Y' returns `true`.
+ *   - Input starting with 'n' or 'N' returns `false`.
+ *   - Any other input falls back to the same rule as empty input.
+ */
+export async function promptAutoFilterPreference(ask, current) {
+    const defaultValue = current ?? true;
+    const hint = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = (await ask(`  Enable AI auto-filter by default? ${hint} `)).trim().toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    if (answer.startsWith('y'))
+        return true;
+    if (answer.startsWith('n'))
+        return false;
+    return defaultValue;
+}

package/dist/src/setup/command.d.ts

@@ -1,2 +1,9 @@
 import type { Command } from 'commander';
+export type SkillPromptKind = 'select' | 'generate';
+/**
+ * Prompt the operator for a custom skill prompt path. Returns the resolved
+ * trimmed value, or `undefined` to leave the current value unchanged, or `null`
+ * to clear it. `ask` is injectable so tests can stub stdin.
+ */
+export declare function promptCustomSkillPath(kind: SkillPromptKind, current: string | undefined, ask?: (q: string) => Promise<string>): Promise<string | undefined | null>;
 export declare function registerSetupCommand(program: Command): void;

package/dist/src/setup/command.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { promisify } from 'node:util';
 import { readExperiencesCredentials, writeExperiencesCredentials, experiencesCredentialsPath, } from '../credentials-store.js';
+import { promptAutoFilterPreference } from './auto-filter-prompt.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../host-utils.js';
 const execFileAsync = promisify(execFile);
 const REQUIRED_NODE_MAJOR = 24;
@@ -521,12 +522,43 @@ async function setupContentfulCredentials() {
     info('Run experiences import — credentials will be pre-filled automatically.');
     return true;
 }
+/**
+ * Prompt the operator for a custom skill prompt path. Returns the resolved
+ * trimmed value, or `undefined` to leave the current value unchanged, or `null`
+ * to clear it. `ask` is injectable so tests can stub stdin.
+ */
+export async function promptCustomSkillPath(kind, current, ask = prompt) {
+    const flagName = kind === 'select' ? '--select-prompt-path' : '--generate-prompt-path';
+    void flagName;
+    const label = kind === 'select' ? 'select (analyze select-agent)' : 'generate (generate components)';
+    const currentLabel = current ? ` [${current}]` : ' [none]';
+    const answer = await ask(`  Custom ${label} prompt path${currentLabel} (empty=keep, "-"=clear): `);
+    const trimmed = answer.trim();
+    if (trimmed === '')
+        return undefined;
+    if (trimmed === '-')
+        return null;
+    return trimmed;
+}
 // ── Step 6: Optional quality-of-life ─────────────────────────────────────────
 async function setupQoL(profilePath) {
     section('Step 6: Optional extras', '[optional]');
     info('These are not required for experiences import but improve the experience.');
     info('');
-    // 6a: EDS_EXTRACT_CONCURRENCY
+    // 6a: AI auto-filter default
+    const existingCreds = await readExperiencesCredentials();
+    info('AI auto-filter — runs an agent pass before the manual scope-gate to prefilter components.');
+    info('Operators who prefer to review every component can default this OFF and override per run with --auto-filter.');
+    const autoFilter = await promptAutoFilterPreference((q) => prompt(q), existingCreds.autoFilter);
+    if (autoFilter !== (existingCreds.autoFilter ?? true)) {
+        await writeExperiencesCredentials({ ...existingCreds, autoFilter });
+        ok(`AI auto-filter default set to ${autoFilter ? 'ON' : 'OFF'}`);
+    }
+    else {
+        dim('     unchanged');
+    }
+    info('');
+    // 6b: EDS_EXTRACT_CONCURRENCY
     const hasConcurrency = await profileContains(profilePath, 'EDS_EXTRACT_CONCURRENCY');
     if (!hasConcurrency) {
         info('EDS_EXTRACT_CONCURRENCY — controls how many components are analyzed in parallel.');
@@ -543,7 +575,31 @@ async function setupQoL(profilePath) {
     else {
         ok('EDS_EXTRACT_CONCURRENCY — already set');
     }
-    // 6b: NO_COLOR
+    // 6c (Feature 8): custom skill prompt paths
+    info('');
+    info('Custom skill prompt paths — point select-agent and/or generate components at your own .md prompts.');
+    info('When set, the bundled invariants (utility-wrapper rejection, description rules) do NOT apply.');
+    const offerCustomPrompts = await confirm('Configure custom skill prompt paths?', false);
+    if (offerCustomPrompts) {
+        const stored = await readExperiencesCredentials();
+        const selectAnswer = await promptCustomSkillPath('select', stored.selectPromptPath);
+        const generateAnswer = await promptCustomSkillPath('generate', stored.generatePromptPath);
+        const updated = { ...stored };
+        if (selectAnswer === null)
+            delete updated.selectPromptPath;
+        else if (selectAnswer !== undefined)
+            updated.selectPromptPath = selectAnswer;
+        if (generateAnswer === null)
+            delete updated.generatePromptPath;
+        else if (generateAnswer !== undefined)
+            updated.generatePromptPath = generateAnswer;
+        await writeExperiencesCredentials(updated);
+        ok(`Custom prompt paths saved to ${experiencesCredentialsPath()}`);
+    }
+    else {
+        dim('     skipped');
+    }
+    // 6d: NO_COLOR
     info('');
     info('NO_COLOR — set to 1 to disable ANSI color output (useful in CI or plain terminals).');
     const setNoColor = await confirm('Add NO_COLOR=1 (disable colors) to your profile?', false);

package/dist/src/types.d.ts

@@ -22,6 +22,10 @@ export interface RawPropDefinition {
     allowedValues?: string[];
     description?: string;
     tokenReference?: string;
+    /** 1-indexed source line where this prop's declaration begins; relative to RawComponentDefinition.source. */
+    sourceStartLine?: number;
+    /** 1-indexed inclusive source line where this prop's declaration ends; relative to RawComponentDefinition.source. */
+    sourceEndLine?: number;
 }
 export interface RawSlotDefinition {
     name: string;
@@ -45,6 +49,8 @@ export interface RawComponentDefinition {
     reviewReasons?: string[];
     needsReview?: boolean;
     validationIssues?: ExtractionValidationIssue[];
+    /** Absolute path to the source file this component was extracted from. Null for synthesized / multi-file. */
+    sourcePath?: string;
 }
 export interface ComponentExtractionResult {
     components: RawComponentDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.11.4-dev-build-d47ab65.0",
+  "version": "2.12.1-dev-build-589b615.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.11.4-dev-build-d47ab65.0"
+    "@contentful/experience-design-system-types": "2.12.1-dev-build-589b615.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/skills/generate-components.md

@@ -75,13 +75,13 @@ Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not
 **Four tool calls:**
 
 ```
-{"tool":"classify_component","description":"<required: one-sentence description of the component>"}
+{"tool":"classify_component","description":"<required: one-sentence description of the component>","rationale":{"description":"<why this component is classified this way>","props":"<why these props were chosen / excluded>","slots":"<why these slots were chosen / excluded>"}}
 
-{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<reason>","values":["a","b"],"token_kind":"color","default":"<value>"}
+{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","values":["a","b"],"token_kind":"color","default":"<value>"}
 
 {"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
 
-{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>"}
+{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<short customer-facing description>","rationale":"<why this slot was kept / its role>"}
 ```
 
 **Rules:**
@@ -92,7 +92,21 @@ Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not
 - `values` is required for `cdf_type: "enum"` — must be a non-empty string array.
 - `token_kind` is required for `cdf_type: "token"` — must be a DTCG `$type` string, e.g. `"color"`.
 - `required` must be a JSON boolean (`true`/`false`), not a string.
-- `description` on `classify_prop` documents your reasoning — always include it.
+- `description` on `classify_prop` is customer-facing — keep it short and subject to the description content rules below.
+- `reason` on `classify_prop` is **required** and is your internal rationale — shown to the developer reviewing the import, never to end-users. Use it to explain your reasoning in detail. The customer-facing description content rules below apply to `description` only, not to `reason`.
+- `rationale` on `classify_component` is **REQUIRED**. It is an object with three REQUIRED string sub-fields:
+  - `rationale.description` — why this component is classified the way it is (its purpose, where it fits in the design system, atom/molecule/organism reasoning). **Subject to the same "Description content rules" as the `description` field — no internal initiative names, no `INTEG-*`, no `EDSI`/`DSI`/`M1`/`M2`/wave/phase references.**
+  - `rationale.props` — operator-facing explanation of which props you accepted vs excluded and why. Audience is the developer reviewing the import (not the customer), so you may discuss types, framework internals, and category corrections in technical terms. Do not include internal initiative names.
+  - `rationale.slots` — operator-facing explanation of which slots you kept vs collapsed and why. Same audience and rules as `rationale.props`.
+  - All three sub-fields are required strings, minimum one sentence each. Never emit an empty string. If the component has zero slots, `rationale.slots` should state that explicitly (e.g. `"No slots — the component renders no injectable regions."`).
+- `rationale` on `classify_slot` is **REQUIRED**. It is a single string explaining why this slot exists and what role it plays in the component (operator-facing; minimum one sentence). Same audience and rules as `rationale.props` / `rationale.slots` above.
+
+**Description content rules (CRITICAL — applies to every `description` field on `classify_component`, `classify_prop`, and `classify_slot`, AND to `rationale.description` on `classify_component`):**
+
+- Write **customer-facing technical descriptions**. The audience is a third-party developer or content editor configuring this component in Contentful — not a Contentful engineer.
+- **Never** reference internal Contentful initiatives, project code names, sprint or roadmap labels, product development phases, or implementation milestones. This includes (non-exhaustive) terms like `P1`, `P2`, `P3`, `M1`, `M2`, `EXT-*`, `INTEG-*`, `DSI`, `EDSI`, `CDF compliance`, `wave 1`, `wave 2`, `phase 1`, `phase 2`, "for compliance with…", "to support the … initiative", or any internal-sounding rationale.
+- Do not invent rationale. If you do not know **why** a prop exists, describe **what** it does (its observable effect on the component) — never guess at organizational context.
+- Descriptions should explain WHAT the prop/component does in terms a developer reading the public component catalog would understand. Stick to behavior, appearance, and configuration semantics.
 
 ---
 
@@ -292,7 +306,7 @@ Input:
 Output:
 ```
 Starting Button classification — 5 props, 1 slot
-{"tool":"classify_component","description":"Primary action button with variant and state support"}
+{"tool":"classify_component","description":"Primary action button with variant and state support","rationale":{"description":"Button is an atom — a single interactive control that triggers an action. It carries a label, a small set of visual variants, and a disabled flag, which is the minimal surface a marketer needs to configure a call-to-action.","props":"Kept label (content), variant (enum, design), disabled (boolean, state), and className (string, design escape hatch). Excluded onClick because it is an event handler — framework-internal and not configurable in Contentful.","slots":"Kept the icon slot as optional because the button renders correctly without it and the icon is purely decorative."}}
 label is a required string content prop
 {"tool":"classify_prop","prop":"label","cdf_type":"string","cdf_category":"content","required":true,"description":"Button label text"}
 variant is a string union — enum type, category design
@@ -304,7 +318,38 @@ onClick is an event handler — framework internal
 className is a DOM pass-through — developers wire CSS, marketers never set this
 {"tool":"exclude_prop","prop":"className","reason":"DOM pass-through — not a marketer-configurable surface"}
 icon slot is clearly optional (decorative leading icon)
-{"tool":"classify_slot","slot":"icon","required":false,"description":"Optional leading icon"}
+{"tool":"classify_slot","slot":"icon","required":false,"description":"Optional leading icon","rationale":"Icon is a decorative leading glyph — optional because the button reads cleanly without it, but kept as a slot so marketers can inject a brand-specific icon component when desired."}
+```
+
+### Component with multiple slots (Card)
+
+Input:
+```json
+{
+  "name": "Card",
+  "props": [
+    {"name":"title","type":"string","category":"content","required":true},
+    {"name":"elevation","type":"'flat'|'raised'|'floating'","category":"design","defaultValue":"'raised'"}
+  ],
+  "slots": [
+    {"name":"body","description":"Main card body"},
+    {"name":"footer","description":"Optional footer area"}
+  ]
+}
+```
+
+Output:
+```
+Starting Card classification — 2 props, 2 slots
+{"tool":"classify_component","description":"Container that groups related content with a title, body, and optional footer","rationale":{"description":"Card is a molecule — it composes a title with body and footer slots into a single visual container. Useful as a building block for lists and grids of related content.","props":"Kept title (string, content) as the customer-facing label and elevation (enum, design) for the three visual depth variants. Nothing was excluded — both raw props map cleanly to CDF.","slots":"Kept both body (required, primary content area) and footer (optional, supplementary area). Body is required because a card with no body renders empty; footer is optional because many cards do not need one."}}
+title is a required content string
+{"tool":"classify_prop","prop":"title","cdf_type":"string","cdf_category":"content","required":true,"description":"Card title text"}
+elevation is a finite visual variant — enum, design
+{"tool":"classify_prop","prop":"elevation","cdf_type":"enum","cdf_category":"design","required":false,"values":["flat","raised","floating"],"default":"raised","description":"Visual depth variant"}
+body is the primary content region — required
+{"tool":"classify_slot","slot":"body","required":true,"description":"Main card body content","rationale":"Body is the primary content region of the card. Required because a card with no body renders an empty container, which is never a useful editor state."}
+footer is supplementary and optional
+{"tool":"classify_slot","slot":"footer","required":false,"description":"Optional footer area for actions or metadata","rationale":"Footer is a supplementary region typically used for actions or metadata. Optional because most cards do not need one and the card renders correctly without it."}
 ```
 
 ### Named type (HeadingSize, ButtonVariant, etc.)
@@ -355,6 +400,9 @@ Before emitting any tool calls, verify:
 8. Framework, DOM, accessibility, and data-* pass-through props are excluded — `className`/`classes`/`classNames`/`rootClassName`/`prefixCls`, `style`, `id`, `role`, `tabIndex`, `name` (bare HTML form attribute), `aria-*` (and bare `aria`), `data-*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. Discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) ARE classified as `string` design props. Common semantic props (`icon`, `items`, `actions`, `options`, `value`, `form`, `inputId`, `componentId`) are NOT excluded — classify them per their content/design/state nature.
 9. No `cdf_type: "link"` used — `link` is reserved and rejected by the CLI parser
 10. No `cdf_type: "number"` used — this is not a supported type; use `"string"` with numeric defaults. `cdf_type: "boolean"` IS valid — use it for boolean toggle props.
+11. `classify_component` includes a `rationale` object with all three sub-fields (`rationale.description`, `rationale.props`, `rationale.slots`) populated as non-empty strings.
+12. Every `classify_slot` includes a non-empty `rationale` string.
+13. `rationale.description` follows the same "Description content rules" as `description` — no internal initiative names (`INTEG-*`, `EDSI`, `DSI`, `M1`, `M2`, wave/phase references, etc.).
 
 After the run completes, the developer can validate the pipeline output with:
 

package/skills/select-components.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Review the single extracted React/Next.js component provided below and decide whether it belongs in **Contentful Experience Orchestration** as a Component Type. Output one JSON tool call to stdout.
+Review the extracted React/Next.js component(s) provided below and decide whether each belongs in **Contentful Experience Orchestration** as a Component Type. The input is a JSON array — you may receive 1–N components in a single message. Output one JSON tool call per input component to stdout, named after the component. Tool calls may appear in any order.
 
 ---
 
@@ -66,6 +66,14 @@ These are **not** valid reasons to reject a component:
 
 > **Data-fetch wrapper rule**: Reject a component if it imports or calls a generated query hook, loads data, and then forwards that data into a sibling renderer. The sibling renderer is the Component Type; the data-loader wrapper is not.
 
+> **Utility-wrapper rule**: Reject a component if **all three** of the following are true:
+>
+> 1. It has no props that meaningfully shape user-facing content (no text strings, headings, image URLs, links, body content, rich text, or media references).
+> 2. The props it does have are purely structural or behavioral — e.g., `container`, `target`, `as`, `asChild`, render-prop callbacks, internal `ref` forwarding, focus/portal targets, debug toggles, or `children` only.
+> 3. It is a utility wrapper rather than a composable content surface. Concrete examples to reject under this rule: `Portal`, `SrOnly` (screen-reader-only wrappers), `FocusTrap`, `ErrorBoundary`, `Suspense` fallbacks, debug-only wrappers, and provider-shaped components whose only job is to forward children.
+>
+> Use `reject_component` with a reason like `"Utility wrapper — no authorable content surface"` or `"Structural-only component — no user-shaping props"`. This rule is additive to the categories above; do **not** use it to reject a component that has even one author-shaping prop (e.g., a `label`, `title`, `text`, `href`, `src`, or `richText` prop) — those still belong as Component Types per the "one rule" above.
+
 ## Using `selectionContext`
 
 If the input includes `selectionContext`, treat it as the only repo-level context you may use. It is already bounded to the customer-provided project files and may include:
@@ -89,7 +97,7 @@ Use that bounded context to distinguish the author-facing renderer from infrastr
 
 Emit one JSON object on a single line. Lines not starting with `{` are ignored by the parser — use them freely for reasoning.
 
-**Two tool calls — emit exactly one:**
+**Two tool calls — emit exactly one per input component:**
 
 ```
 {"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>","confidence":<1-5>}
@@ -99,8 +107,9 @@ Emit one JSON object on a single line. Lines not starting with `{` are ignored b
 
 **Rules:**
 
-- Emit exactly one JSON object, on one line. No multi-line JSON. No markdown fences.
-- The `name` must match the component name in the input.
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit exactly one tool call per input component. Tool calls may appear in any order.
+- The `name` must match a component name from the input array exactly.
 - `reason` is a brief phrase documenting your decision.
 - `confidence` is your certainty (1–5) that the decision is correct:
   - **5** — obvious case, no doubt (clear UI atom, or clear infrastructure with no visual output)