@contentful/experience-design-system-cli 2.34.5-dev-build-75bf00ac.0 → 2.35.0-alpha.0

package/README.md

@@ -32,11 +32,18 @@ All intermediate data flows through a local SQLite session database (`~/.content
 
 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.
+### Atomic vs. composite
+
+Imports are **atomic by default** — flat components, no embedded hierarchy. This is the right choice when you just want each component registered on its own. Opt into hierarchy resolution with `--composite` (or any composition flag, which implies it).
+
+| Mode | Flag | Behavior |
+|---|---|---|
+| Atomic | default | Flat import; composition stripped before push |
+| Composite | `--composite` | Resolve and import the parent→child hierarchy |
 
 ### How composition is resolved
 
-Relationships are resolved from the highest-confidence source available, in this precedence order:
+Under `--composite`, 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.
@@ -79,7 +86,7 @@ The CLI invokes the agent non-interactively in a subprocess. If the binary is no
 
 ### Contentful credentials
 
-`apply` and `import` (when pushing) require access to a Contentful space. Configure these environment variables or run `experiences setup`:
+`apply` and `import` (when pushing) require access to a Contentful space. Set these environment variables or pass the equivalent flags:
 
 ```bash
 export CONTENTFUL_MANAGEMENT_TOKEN=<your-cma-token>   # required
@@ -106,8 +113,8 @@ experiences import [flags]
 ```
 welcome
   ↓
-extracting             — runs analyze extract with composite relationships enabled;
-                         spawns internal generation in parallel (prefetch)
+extracting             — runs analyze extract (atomic by default; resolves composition
+                         under --composite, see below); spawns internal generation in parallel (prefetch)
   ↓
 [auto-filter]          — analyze select-agent runs automatically
   ↓
@@ -147,7 +154,8 @@ Custom `.md` skill prompt paths can be saved via `experiences setup`; the CLI em
 | `--project <path>`                | `.`                                    | Project root to analyze                                                                                      |
 | `--agent <name>`                  | saved by setup / `claude`              | Agent for `analyze select-agent` and internal generation                                                     |
 | `--model <name>`                  | agent default                          | Model name                                                                                                   |
-| `--composition-map <path>`        | —                                      | Consume a hand-authored parent→children interchange map                                                       |
+| `--composite`                     | —                                      | Import the embedded-component hierarchy (any composition flag implies this)                                   |
+| `--composition-map <path>`        | —                                      | Consume a hand-authored parent→children interchange map (implies `--composite`)                              |
 | `--prompt <stage=value>`          | —                                      | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt composition=./p.md` |
 | `--skip-map-tokens`               | —                                      | Skip the `map tokens` step between internal generation and apply                                             |
 | `--no-cache`                      | cache on                               | Bypass extract/select/internal-generation/map-tokens/composition caches and force re-run                    |
@@ -180,15 +188,15 @@ experiences print validate   [--components <path>] [--tokens <path>]
 
 ### `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.
+This command is the non-wizard route to the same diff and push logic. Its flag surface is unchanged.
 
 `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.
 
 ```bash
-experiences apply <file>
+experiences apply
 ```
 
-`apply` is interactive and loads credentials from `experiences setup` or environment variables. Remote ComponentTypes and DesignTokens missing from the pushed manifest are always skipped.
+Shared flags: `--components`, `--tokens`. `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.
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-75bf00ac.0",
+  "version": "2.35.0-alpha.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/credentials-store.d.ts

@@ -1,3 +1,4 @@
+import { type CompositionMode } from './lib/composition-mode.js';
 export type ExperiencesCredentials = {
     spaceId: string;
     environmentId: string;
@@ -11,6 +12,12 @@ export type ExperiencesCredentials = {
     debug?: boolean;
     /** Persisted opt-out for anonymous CLI usage analytics, set via `experiences setup`. */
     analyticsDisabled?: boolean;
+    /**
+     * Feature (atomic mode): default composition mode. `atomic` (default) imports
+     * flat components with no embedded-component hierarchy; `composite` opts into
+     * the slot-graph machinery. Resolved `flag > env > this > default`.
+     */
+    compositionMode?: CompositionMode;
 };
 /**
  * Read persisted Contentful credentials.

package/dist/src/import/strip-allowed-components.d.ts

@@ -0,0 +1,18 @@
+import type { CDFComponentEntry } from '@contentful/experience-design-system-types';
+/**
+ * Atomic-mode normalization (spec T8, option a): keep every slot's structure
+ * but drop its `$allowedComponents` composition constraint. Applied over the
+ * loaded component array regardless of source (`--session` or `--components`),
+ * so the atomic bypass cannot leak a live composition link into the pushed
+ * CDF document. Starving `$allowedComponents` at this single point also makes
+ * slot-cycle detection structurally return zero (see T12).
+ *
+ * Returns a new array with cloned entries; inputs are not mutated.
+ */
+export declare function stripAllowedComponents(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>): Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>;

package/dist/src/import/tui/WizardApp.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { CompositionMode } from '../../lib/composition-mode.js';
 export declare function buildGenerateComponentsArgs(opts: {
     sessionId: string;
     tokensPath?: string;
@@ -10,13 +11,6 @@ export declare function buildGenerateComponentsArgs(opts: {
     promptOverrides?: string[];
     existingEntitiesPath?: string;
 }): string[];
-export declare function buildGenerateTokensArgs(opts: {
-    rawTokensPath: string;
-    agent: string;
-    model?: string;
-    bedrock?: boolean;
-    noCache?: boolean;
-}): string[];
 export declare function buildMapTokensArgs(opts: {
     sessionId: string;
     agent: string;
@@ -44,6 +38,7 @@ export type WizardAppProps = {
     bedrock?: boolean;
     initialProjectPath?: string;
     host?: string;
+    compositionMode?: CompositionMode;
     compositionMap?: string;
     promptOverrides?: string[];
     noCache?: boolean;
@@ -52,4 +47,4 @@ export type WizardAppProps = {
     skipMapTokens?: boolean;
     initialRawTokensPath?: string;
 };
-export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, compositionMap, promptOverrides, noCache, livePreview, generatePromptPath, skipMapTokens, initialRawTokensPath, }?: WizardAppProps): React.ReactElement;
+export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, compositionMode, compositionMap, promptOverrides, noCache, livePreview, generatePromptPath, skipMapTokens, initialRawTokensPath, }?: WizardAppProps): React.ReactElement;

package/dist/src/import/tui/final-review-host.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
+import type { CompositionMode } from '../../lib/composition-mode.js';
 import type { ReviewStepProps } from './review-step-props.js';
 export type FinalReviewHostProps = Omit<ReviewStepProps, 'extractSessionId'> & {
     extractSessionId: string | null;
+    compositionMode?: CompositionMode;
 };
-export declare function FinalReviewHost({ extractSessionId, tokenSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: FinalReviewHostProps): React.ReactElement;
+export declare function FinalReviewHost({ extractSessionId, tokenSessionId, compositionMode, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: FinalReviewHostProps): React.ReactElement;

package/dist/src/import/tui/lineage-input.d.ts

@@ -5,8 +5,8 @@ type LineageInputKey = {
     tab: boolean;
     return: boolean;
 };
-export declare function handleLineageNavigation({ key, cursor, jumpables, onCursorChange, onJump, onClose, allowTab, }: {
-    input?: string;
+export declare function handleLineageNavigation({ input, key, cursor, jumpables, onCursorChange, onJump, onClose, allowTab, }: {
+    input: string;
     key: LineageInputKey;
     cursor: number;
     jumpables: LineageJumpable[];

package/dist/src/import/tui/scope-gate-host.d.ts

@@ -1,8 +1,10 @@
 import React from 'react';
 import type { ScopeComponent } from './steps/ScopeGateStep.js';
+import type { CompositionMode } from '../../lib/composition-mode.js';
 export type { ScopeComponent };
 export type ScopeGateHostProps = {
     components: ReadonlyArray<ScopeComponent>;
+    compositionMode?: CompositionMode;
     onConfirm: (decisions: {
         accepted: string[];
         rejected: string[];
@@ -16,4 +18,4 @@ export type ScopeGateHostProps = {
     } | null;
     aiFilterError?: string | null;
 };
-export declare function ScopeGateHost({ components, onConfirm, onQuit }: ScopeGateHostProps): React.ReactElement;
+export declare function ScopeGateHost({ components, compositionMode, onConfirm, onQuit, }: ScopeGateHostProps): React.ReactElement;

package/dist/src/import/tui/steps/AtomicGenerateReviewStep.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+type GenerateReviewStepProps = {
+    extractSessionId: string;
+    tokenSessionId?: string | null;
+    onFinalize: (accepted: number, rejected: number, unresolved: number) => void;
+    onQuit: () => void;
+    /**
+     * Feature 2 (live preview after every save). When `true` (default), the
+     * wizard re-runs `previewImport` after each successful FieldEditor Ctrl+S
+     * (debounced 500ms) and refreshes the sidebar's previewAnnotation badges.
+     * Live preview is enabled for the wizard flow.
+     */
+    livePreview?: boolean;
+    spaceId?: string;
+    environmentId?: string;
+    cmaToken?: string;
+    host?: string;
+    tokensPath?: string;
+    /**
+     * INTEG-4411 refined: initial value for the inline `finalizeError` banner.
+     * The wizard sets this when it routes back to `final-review` after the
+     * preview API returned an empty diff (pure no-op push). Cleared on the
+     * next `a` / `A` keystroke.
+     */
+    initialFinalizeError?: string | null;
+};
+export declare function AtomicGenerateReviewStep({ extractSessionId, tokenSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: GenerateReviewStepProps): React.ReactElement;
+export {};

package/dist/src/import/tui/steps/AtomicScopeGateStep.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { ScopeGateStepProps } from './ScopeGateStep.js';
+export declare function AtomicScopeGateStep({ components, onConfirm, onQuit }: ScopeGateStepProps): React.ReactElement;