@contentful/experience-design-system-cli 2.34.4-dev-build-f08fbb9.0 → 2.34.5-dev-build-a88e62a.0

package/README.md

@@ -36,11 +36,20 @@ All intermediate data flows through a local SQLite session database (`~/.content
 
 ## 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. The CLI populates each slot's `$allowedComponents` so the parent→child relationships survive into Contentful.
+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.
+
+### 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 | `--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. **Mapping map** — a hand-authored parent→children interchange map you feed with `--composition-map <path>`. Use `--generate-map <path>` to emit a skeleton from whatever was resolved, then hand-edit it and feed it back.
@@ -112,8 +121,8 @@ experiences import [flags]
 ```
 welcome
   ↓
-extracting             — runs analyze extract (resolves composition when a source
-                         is provided; see below); spawns generate in parallel (prefetch)
+extracting             — runs analyze extract (atomic by default; resolves composition
+                         under --composite, see below); spawns generate in parallel (prefetch)
   ↓
 [auto-filter]          — analyze select-agent runs automatically (skip with --no-auto-filter)
   ↓
@@ -172,10 +181,12 @@ Pass `--select-prompt-path <path>` and/or `--generate-prompt-path <path>` to swa
 | `--model <name>`                  | agent default                          | Model name                                                                                                   |
 | `--tokens <path>`                 | —                                      | DTCG `tokens.json` to push alongside generated components                                                    |
 | `--auto-accept-scope`             | off                                    | Accept all extracted components without prompting (required for non-TTY without other headless flags)        |
-| `--composition-map <path>`        | —                                      | Consume a hand-authored parent→children interchange map                                                      |
-| `--generate-map <path>`           | —                                      | Write a composition-map skeleton from the resolved composition                                                |
-| `--composition-agent`             | —                                      | Opt into agentic resolution when deterministic sources find no groups                                         |
-| `--composition-refresh`           | —                                      | Bypass the composition cache and re-resolve from scratch, forcing the agent to run                            |
+| `--atomic`                        | **default**                            | Flat import, no embedded-component hierarchy (composition stripped on push)                                   |
+| `--composite`                     | —                                      | Import the embedded-component hierarchy (any composition flag implies this)                                   |
+| `--composition-map <path>`        | —                                      | Consume a hand-authored parent→children interchange map (implies `--composite`)                              |
+| `--generate-map <path>`           | —                                      | Also write a composition-map skeleton from the resolved composition (implies `--composite`)                  |
+| `--composition-agent`             | —                                      | Opt into agentic resolution when deterministic sources find no groups (implies `--composite`)                |
+| `--composition-refresh`           | —                                      | Bypass the composition cache and re-resolve from scratch, forcing the agent to run (implies `--composite`)   |
 | `--composition-agent-mode <mode>` | `parser`                               | `parser` (agent writes a sandboxed parser) or `edges` (agent lists edges directly)                           |
 | `--prompt <stage=value>`          | —                                      | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt composition=./p.md` |
 | `--auto-reject-cycles`            | off (fail loud)                        | Auto-reject components in slot cycles and retry, instead of stopping with the cycle path                     |
@@ -274,10 +285,12 @@ experiences analyze extract --project <path> [--dir <src-dir>] [composition flag
 | `--project <path>` | _(required)_ | Path to the project root |
 | `--dir <path>` | `src` (falls back to project root) | Source directory relative to project root |
 | `--resolve-unreachable <mode>` | `auto` | Retry pass for unresolved Svelte `Props` types: `auto`, `always`, or `never` |
-| `--composition-map <path>` | — | Consume a hand-authored parent→children interchange map |
-| `--generate-map <path>` | — | Write a skeleton interchange map from the resolved composition |
-| `--composition-agent` | — | Opt into agentic resolution when deterministic sources find no groups |
-| `--composition-refresh` | — | Bypass the composition cache and re-resolve from scratch, forcing the agent to run |
+| `--atomic` | **default** | Skip composition resolution — flat components only |
+| `--composite` | — | Resolve embedded-component composition (any composition flag implies this) |
+| `--composition-map <path>` | — | Consume a hand-authored parent→children interchange map (implies `--composite`) |
+| `--generate-map <path>` | — | Write a skeleton interchange map from the resolved composition (implies `--composite`) |
+| `--composition-agent` | — | Opt into agentic resolution when deterministic sources find no groups (implies `--composite`) |
+| `--composition-refresh` | — | Bypass the composition cache and re-resolve from scratch, forcing the agent to run (implies `--composite`) |
 | `--composition-agent-mode <mode>` | `parser` | `parser` (agent writes a sandboxed parser — deterministic) or `edges` (agent lists edges directly) |
 | `--agent <name>` | saved by setup | Coding agent for composition resolution: `claude`, `codex`, `opencode`, `cursor`, `copilot` |
 | `--prompt <stage=value>` | — | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt composition=./p.md` |
@@ -288,7 +301,7 @@ Writes extracted components to the session database and prints `session=<id>` to
 
 The deterministic non-authorable filter drops infrastructure components with no authoring surface (Context providers, refs-only wrappers, etc.); each drop is reported as a warning so the operator can audit.
 
-See [Composite components & composition](#composite-components--composition) for how the composition flags resolve parent→child relationships.
+Extraction is **atomic by default** — flat components, no embedded hierarchy. See [Composite components & composition](#composite-components--composition) for how `--composite` and the composition flags resolve parent→child relationships.
 
 ---
 

package/bin/cli.js

@@ -11,6 +11,7 @@ process.on("warning", (w) => {
 // 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 { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve, join } from "node:path";
 
@@ -42,12 +43,19 @@ if (
   const distMtime = statSync(distEntry).mtimeMs;
   if (newestMtime(srcDir) > distMtime) {
     process.stderr.write("⚙ Source changed — rebuilding...\n");
-    const tsc = join(pkgRoot, "node_modules", ".bin", "tsc");
+    // Run the compiler's own entry script with this Node rather than the
+    // node_modules/.bin/tsc shim: on Windows the extensionless shim is a POSIX
+    // sh script (the runnable one is tsc.CMD), so exec'ing it fails there.
+    const tsc = createRequire(import.meta.url).resolve("typescript/bin/tsc");
     try {
-      execFileSync(tsc, ["-p", join(pkgRoot, "tsconfig.build.json")], {
-        stdio: ["ignore", "ignore", "inherit"],
-        cwd: pkgRoot,
-      });
+      execFileSync(
+        process.execPath,
+        [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");

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.4-dev-build-f08fbb9.0",
+  "version": "2.34.5-dev-build-a88e62a.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;
@@ -14,6 +15,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/orchestrator.d.ts

@@ -1,3 +1,4 @@
+import type { CompositionMode } from '../lib/composition-mode.js';
 export interface PipelineOptions {
     project: string;
     out: string;
@@ -27,6 +28,7 @@ export interface PipelineOptions {
     /** When true, auto-reject cycle participants and retry push instead of surfacing an error. */
     autoRejectCycles?: boolean;
     allowDeletions?: boolean;
+    compositionMode?: CompositionMode;
     compositionMap?: string;
     compositionAgent?: boolean;
     compositionAgentMode?: string;

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
+ * manifest. 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

@@ -2,6 +2,7 @@ import React from 'react';
 import { type RunPickerSelection } from '../../runs/run-picker.js';
 import type { RunRecord } from '../../runs/store.js';
 import { type ConflictMode } from '../../runs/save-path-resolver.js';
+import type { CompositionMode } from '../../lib/composition-mode.js';
 export declare function buildSelectAgentArgs(opts: {
     sessionId: string;
     agent: string;
@@ -58,6 +59,7 @@ export type WizardAppProps = {
     host?: string;
     autoAcceptScope?: boolean;
     autoRejectCycles?: boolean;
+    compositionMode?: CompositionMode;
     compositionMap?: string;
     compositionAgent?: boolean;
     compositionAgentMode?: string;
@@ -84,4 +86,4 @@ export type WizardAppProps = {
     onRunPicked?: (selection: RunPickerSelection) => void;
     allowDeletions?: boolean;
 };
-export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, autoAcceptScope, autoRejectCycles, compositionMap, compositionAgent, compositionAgentMode, compositionRefresh, generateMap, promptOverrides, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, skipMapTokens, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, allowDeletions, }?: WizardAppProps): React.ReactElement;
+export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, autoAcceptScope, autoRejectCycles, compositionMode, compositionMap, compositionAgent, compositionAgentMode, compositionRefresh, generateMap, promptOverrides, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, skipMapTokens, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, allowDeletions, }?: WizardAppProps): React.ReactElement;

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

@@ -1,8 +1,10 @@
 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;
     generatedCount: number;
     autoAccept: boolean;
+    compositionMode?: CompositionMode;
 };
-export declare function FinalReviewHost({ extractSessionId, tokenSessionId, generatedCount, autoAccept, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, allowDeletions, }: FinalReviewHostProps): React.ReactElement;
+export declare function FinalReviewHost({ extractSessionId, tokenSessionId, generatedCount, autoAccept, compositionMode, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, allowDeletions, }: FinalReviewHostProps): React.ReactElement;

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

@@ -1,10 +1,12 @@
 import React from 'react';
 import type { ScopeComponent } from './steps/ScopeGateStep.js';
+import type { CompositionMode } from '../../lib/composition-mode.js';
 export type { ScopeComponent };
 type AutoFilterStatus = 'idle' | 'running' | 'complete' | 'cancelled' | 'failed';
 export type ScopeGateHostProps = {
     components: ReadonlyArray<ScopeComponent>;
     autoAccept: boolean;
+    compositionMode?: CompositionMode;
     onConfirm: (decisions: {
         accepted: string[];
         rejected: string[];
@@ -18,4 +20,4 @@ export type ScopeGateHostProps = {
     aiFilterError?: string | null;
     onCancelAutoFilter?: () => void;
 };
-export declare function ScopeGateHost({ components, autoAccept, onConfirm, onQuit, aiFilterStatus, aiFilterProgress, aiFilterError, onCancelAutoFilter, }: ScopeGateHostProps): React.ReactElement;
+export declare function ScopeGateHost({ components, autoAccept, compositionMode, onConfirm, onQuit, aiFilterStatus, aiFilterProgress, aiFilterError, onCancelAutoFilter, }: 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.
+     * Operator opts out via `experiences import --no-live-preview`.
+     */
+    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, aiFilterStatus, aiFilterProgress, aiFilterError, onCancelAutoFilter, }: ScopeGateStepProps): React.ReactElement;