@contentful/experience-design-system-cli 2.2.1 → 2.5.2-dev-build-eebccad.0

package/README.md

@@ -1,6 +1,8 @@
 # @contentful/experience-design-system-cli
 
-CLI for extracting, reviewing, generating, validating, and pushing Contentful Experience Design System component definitions.
+CLI for extracting, reviewing, generating, validating, and pushing Contentful Experience Design System component definitions into [Experience Orchestration (ExO)](https://www.contentful.com/help/experience-orchestration/).
+
+**Binary names:** `experiences` (primary), `exo` (alias), `experience-design-system-cli` (long-form). All three point to the same executable.
 
 ## Pipeline Overview
 

package/dist/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.2.1",
+  "version": "2.5.2-dev-build-eebccad.0",
   "description": "Contentful Experiences design system import CLI",
   "type": "module",
   "bin": {
     "experience-design-system-cli": "./bin/cli.js",
+    "experiences": "./bin/cli.js",
     "exo": "./bin/cli.js"
   },
   "main": "./dist/src/index.js",

package/dist/src/analyze/select/tui/App.js

@@ -78,8 +78,6 @@ export function App({ sessionId, artifactsRoot, reviewRoot }) {
             if (!manifest.componentsManifest)
                 manifest.componentsManifest = {};
             const client = new ImportApiClient({ cmaToken, spaceId, environmentId });
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
             const preview = await client.previewImport(manifest);
             const annotations = {};
             for (const item of preview.components.new) {

package/dist/src/apply/api-client.d.ts

@@ -5,7 +5,6 @@ export interface ApiClientOptions {
     cmaToken: string;
     spaceId: string;
     environmentId: string;
-    organizationId?: string;
 }
 export declare class ApiError extends Error {
     readonly status: number;
@@ -17,13 +16,10 @@ export declare class ImportApiClient {
     private token;
     private spaceId;
     private environmentId;
-    private organizationId;
     constructor(opts: ApiClientOptions);
-    setOrganizationId(orgId: string | null): void;
     private base;
     private headers;
-    resolveOrganizationId(): Promise<string | null>;
-    validateEnvironment(): Promise<void>;
+    validateToken(): Promise<void>;
     previewImport(manifest: ManifestPayload): Promise<ServerPreviewResponse>;
     applyImport(manifest: ManifestPayload, acknowledgeBreakingChanges: boolean): Promise<ApplyOperationResponse>;
     pollOperation(operationId: string, opts?: {

package/dist/src/apply/api-client.js

@@ -19,8 +19,6 @@ async function request(url, options) {
         Authorization: `Bearer ${options.token}`,
         'Content-Type': 'application/json',
     };
-    if (options.orgId)
-        headers['x-contentful-organization-id'] = options.orgId;
     const init = {
         method: options.method ?? 'GET',
         headers,
@@ -34,58 +32,35 @@ export class ImportApiClient {
     token;
     spaceId;
     environmentId;
-    organizationId;
     constructor(opts) {
         this.host = opts.host ?? DEFAULT_HOST;
         this.token = opts.cmaToken;
         this.spaceId = opts.spaceId;
         this.environmentId = opts.environmentId;
-        this.organizationId = opts.organizationId;
-    }
-    setOrganizationId(orgId) {
-        if (orgId)
-            this.organizationId = orgId;
     }
     base() {
         return `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
     }
     headers() {
-        const h = {
+        return {
             Authorization: `Bearer ${this.token}`,
             'Content-Type': 'application/json',
         };
-        if (this.organizationId)
-            h['x-contentful-organization-id'] = this.organizationId;
-        return h;
-    }
-    async resolveOrganizationId() {
-        const url = `${this.host}/spaces/${this.spaceId}`;
-        const res = await request(url, { token: this.token });
-        if (res.status === 401 || res.status === 403) {
-            throw new ApiError(`space '${this.spaceId}' not found or CMA token lacks access`, res.status, await res.text());
-        }
-        if (res.status === 404) {
-            // Custom host (e.g. staging) may not expose the spaces API or the space may not
-            // exist there. Skip the org ID — the design systems API may not require it.
-            return null;
-        }
-        if (!res.ok) {
-            throw new ApiError(`unexpected error fetching space: ${res.status}`, res.status, await res.text());
-        }
-        const json = (await res.json());
-        return json.sys.organization.sys.id;
     }
-    async validateEnvironment() {
-        const url = `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
+    async validateToken() {
+        // /users/me is the canonical "is this token valid" endpoint — it doesn't enforce
+        // space-membership rules that don't apply to the design-systems API path, so it
+        // doesn't false-positive 401 for tokens that are entitled to call import endpoints
+        // but lack the role assignments public CMA's SpacesController/EnvironmentsController
+        // require. Per-space/per-org authorization is enforced by the design-systems API itself
+        // on the actual preview/apply call.
+        const url = `${this.host}/users/me`;
         const res = await request(url, { token: this.token });
-        if (res.status === 404) {
-            throw new ApiError(`environment '${this.environmentId}' not found in space '${this.spaceId}'`, 404, await res.text());
-        }
-        if (res.status === 401 || res.status === 403) {
-            throw new ApiError(`space '${this.spaceId}' not found or CMA token lacks access`, res.status, await res.text());
+        if (res.status === 401) {
+            throw new ApiError('CMA token is invalid or revoked', res.status, await res.text());
         }
         if (!res.ok) {
-            throw new ApiError(`unexpected error validating environment: ${res.status}`, res.status, await res.text());
+            throw new ApiError(`unexpected error validating token: ${res.status}`, res.status, await res.text());
         }
     }
     async previewImport(manifest) {

package/dist/src/apply/command.js

@@ -392,9 +392,7 @@ export function registerApplyCommand(program) {
         }
         const { components, tokens, client } = inputs;
         try {
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
-            await client.validateEnvironment();
+            await client.validateToken();
         }
         catch (e) {
             if (e instanceof ApiError)
@@ -459,9 +457,7 @@ export function registerApplyCommand(program) {
         }
         const { components, tokens, client } = inputs;
         try {
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
-            await client.validateEnvironment();
+            await client.validateToken();
         }
         catch (e) {
             if (e instanceof ApiError)
@@ -638,9 +634,7 @@ export function registerApplyCommand(program) {
         }
         const { components, tokens, client } = inputs;
         try {
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
-            await client.validateEnvironment();
+            await client.validateToken();
         }
         catch (e) {
             if (e instanceof ApiError)

package/dist/src/apply/tui/ServerPreviewView.js

@@ -15,7 +15,7 @@ export function ServerPreviewView({ preview, spaceId, environmentId }) {
     const { components, tokens } = preview;
     const totalComponents = components.new.length + components.changed.length + components.unchanged.length + components.removed.length;
     const totalTokens = tokens.new.length + tokens.changed.length + tokens.unchanged.length + tokens.removed.length;
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, children: ["Preview \u2014 ", environmentId, " @ ", spaceId] }), _jsx(Text, { children: " " }), totalComponents > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [" Component Types (", totalComponents, " total)"] }), _jsxs(Text, { color: "green", children: [" \u2726 ", components.new.length, " to create"] }), _jsxs(Text, { color: "yellow", children: [" ~ ", components.changed.length, " to update"] }), _jsxs(Text, { color: "red", children: [" \u2717 ", components.removed.length, " to remove"] }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", components.unchanged.length, " unchanged"] }), components.changed.map((item, i) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: "yellow", children: [" ~ ", item.current.name] }), _jsx(DraftWarning, { hasDraft: item.hasPendingDraftChanges })] }), _jsx(BreakingBadge, { item: item })] }, i))), _jsx(Text, { children: " " })] })), totalTokens > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [" Design Tokens (", totalTokens, " total)"] }), _jsxs(Text, { color: "green", children: [" \u2726 ", tokens.new.length, " to create"] }), _jsxs(Text, { color: "yellow", children: [" ~ ", tokens.changed.length, " to update"] }), _jsxs(Text, { color: "red", children: [" \u2717 ", tokens.removed.length, " to remove"] }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", tokens.unchanged.length, " unchanged"] }), tokens.changed
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, children: ["Preview \u2014 ", environmentId, " @ ", spaceId] }), _jsx(Text, { children: " " }), totalComponents > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [" Component Types (", totalComponents, " total)"] }), _jsxs(Text, { color: "green", children: [" \u2746 ", components.new.length, " to create"] }), _jsxs(Text, { color: "yellow", children: [" ~ ", components.changed.length, " to update"] }), _jsxs(Text, { color: "red", children: [" \u2717 ", components.removed.length, " to remove"] }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", components.unchanged.length, " unchanged"] }), components.changed.map((item, i) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: "yellow", children: [" ~ ", item.current.name] }), _jsx(DraftWarning, { hasDraft: item.hasPendingDraftChanges })] }), _jsx(BreakingBadge, { item: item })] }, i))), _jsx(Text, { children: " " })] })), totalTokens > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [" Design Tokens (", totalTokens, " total)"] }), _jsxs(Text, { color: "green", children: [" \u2746 ", tokens.new.length, " to create"] }), _jsxs(Text, { color: "yellow", children: [" ~ ", tokens.changed.length, " to update"] }), _jsxs(Text, { color: "red", children: [" \u2717 ", tokens.removed.length, " to remove"] }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", tokens.unchanged.length, " unchanged"] }), tokens.changed
                         .filter((t) => t.hasPendingDraftChanges)
                         .map((item, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: "yellow", children: [" ~ ", item.current.name] }), _jsx(DraftWarning, { hasDraft: true })] }, i))), _jsx(Text, { children: " " })] })), _jsx(Text, { dimColor: true, children: " Press Q to exit." })] }));
 }

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

@@ -1,8 +1,8 @@
-export type ExoCredentials = {
+export type ExperiencesCredentials = {
     spaceId: string;
     environmentId: string;
     cmaToken: string;
 };
-export declare function readExoCredentials(): Promise<ExoCredentials>;
-export declare function writeExoCredentials(creds: ExoCredentials): Promise<void>;
-export declare function exoCredentialsPath(): string;
+export declare function readExperiencesCredentials(): Promise<ExperiencesCredentials>;
+export declare function writeExperiencesCredentials(creds: ExperiencesCredentials): Promise<void>;
+export declare function experiencesCredentialsPath(): string;

package/dist/src/credentials-store.js

@@ -1,9 +1,9 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-const CREDENTIALS_DIR = join(homedir(), '.config', 'exo');
+const CREDENTIALS_DIR = join(homedir(), '.config', 'experiences');
 const CREDENTIALS_PATH = join(CREDENTIALS_DIR, 'credentials.json');
-export async function readExoCredentials() {
+export async function readExperiencesCredentials() {
     try {
         const raw = await readFile(CREDENTIALS_PATH, 'utf8');
         const parsed = JSON.parse(raw);
@@ -21,10 +21,10 @@ export async function readExoCredentials() {
         };
     }
 }
-export async function writeExoCredentials(creds) {
+export async function writeExperiencesCredentials(creds) {
     await mkdir(CREDENTIALS_DIR, { recursive: true });
     await writeFile(CREDENTIALS_PATH, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
 }
-export function exoCredentialsPath() {
+export function experiencesCredentialsPath() {
     return CREDENTIALS_PATH;
 }

package/dist/src/import/command.js

@@ -1,6 +1,6 @@
 import { resolve, join } from 'node:path';
 import { runPipeline } from './orchestrator.js';
-import { readExoCredentials } from '../credentials-store.js';
+import { readExperiencesCredentials } from '../credentials-store.js';
 export function registerImportCommand(program) {
     program
         .command('import')
@@ -40,7 +40,7 @@ export function registerImportCommand(program) {
             const { render } = await import('ink');
             const { createElement } = await import('react');
             const { WizardApp } = await import('./tui/WizardApp.js');
-            const creds = await readExoCredentials();
+            const creds = await readExperiencesCredentials();
             const { waitUntilExit } = render(createElement(WizardApp, {
                 initialSpaceId: creds.spaceId,
                 initialEnvironmentId: creds.environmentId || 'master',

package/dist/src/import/tui/WizardApp.js

@@ -34,7 +34,7 @@ function runCli(args) {
         });
     });
 }
-const WIZARD_LOG = join(tmpdir(), 'exo-import-wizard.log');
+const WIZARD_LOG = join(tmpdir(), 'experiences-import-wizard.log');
 function logStep(entry) {
     const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n';
     appendFileSync(WIZARD_LOG, line);
@@ -45,7 +45,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const terminalWidth = stdout?.columns ?? 80;
     const logInit = useRef(false);
     if (!logInit.current) {
-        writeFileSync(WIZARD_LOG, `--- exo import session ${new Date().toISOString()} ---\n`);
+        writeFileSync(WIZARD_LOG, `--- experiences import session ${new Date().toISOString()} ---\n`);
         logInit.current = true;
     }
     const credentialsRef = useRef(null);
@@ -85,6 +85,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         },
         errorStep: '',
         errorMessage: '',
+        errorAllowCredentialRetry: false,
+        authCheckStepNumber: 1,
     });
     useEffect(() => {
         sessionRef.current = {
@@ -139,15 +141,16 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         logStep({ update: sanitized });
         setState((prev) => ({ ...prev, ...partial }));
     };
-    // ── Agent auth pre-flight ───────────────────────────────────────────────────
+    // ── Agent auth pre-flight ───────────────────────────────────────────────────────
     const runAgentAuthCheck = async (nextStep) => {
-        update({ step: 'checking-claude-auth' });
+        const authCheckStepNumber = nextStep === 'generating-tokens' ? 1 : state.tokensPath ? 4 : 3;
+        update({ step: 'checking-claude-auth', authCheckStepNumber });
         const status = await checkAgentAuth(state.agent);
         if (status === 'not-found') {
             update({
                 step: 'error',
                 errorStep: `${state.agent} auth check`,
-                errorMessage: `The \`${state.agent}\` CLI was not found on your PATH.\n\nInstall it, then re-run \`exo import\`.`,
+                errorMessage: `The \`${state.agent}\` CLI was not found on your PATH.\n\nInstall it, then re-run \`experiences import\`.`,
             });
             return false;
         }
@@ -156,7 +159,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 step: 'error',
                 errorStep: `${state.agent} auth check`,
                 errorMessage: `${state.agent} is not authenticated.\n\n` +
-                    `Run \`${state.agent}\` in your terminal to log in, then re-run \`exo import\`.\n\n` +
+                    `Run \`${state.agent}\` in your terminal to log in, then re-run \`experiences import\`.\n\n` +
                     'If you are using AWS Bedrock, run:\n' +
                     '  aws sso login --profile <your-profile>',
             });
@@ -165,7 +168,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: nextStep });
         return true;
     };
-    // ── Step runners ──────────────────────────────────────────────────────────
+    // ── Step runners ────────────────────────────────────────────────────────
     const runGenerateTokens = async (rawTokensPath, outDir) => {
         const result = await new Promise((res) => {
             const child = spawn('node', [
@@ -438,7 +441,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'validating-credentials' });
         try {
             const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: apiHost });
-            await client.resolveOrganizationId();
+            await client.validateToken();
             const { extractSessionId, tokensPath } = sessionRef.current;
             void runPreview(extractSessionId, tokensPath, spaceId, environmentId, cmaToken);
         }
@@ -448,15 +451,18 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return;
             }
             const msg = e instanceof Error ? e.message : 'Credential check failed';
-            update({ step: 'credentials', credentialsError: msg });
+            update({
+                step: 'error',
+                errorStep: 'validating-credentials',
+                errorMessage: msg,
+                errorAllowCredentialRetry: false,
+            });
         }
     };
     const runPreview = async (extractSessionId, tokensPath, spaceId, environmentId, cmaToken) => {
         update({ step: 'previewing' });
         try {
             const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: apiHost });
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
             let components = [];
             if (extractSessionId) {
                 const db = openPipelineDb();
@@ -520,21 +526,25 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     // Space-level config errors (e.g. "Design system public CMA is disabled") cannot be
                     // fixed by re-entering credentials — send to error screen.
                     if (bodyMsg && /disabled/i.test(bodyMsg)) {
-                        update({ step: 'error', errorStep: 'apply preview', errorMessage: `Preview failed: ${bodyMsg}` });
+                        update({
+                            step: 'error',
+                            errorStep: 'apply preview',
+                            errorMessage: `Preview failed: ${bodyMsg}`,
+                            errorAllowCredentialRetry: false,
+                        });
                         return;
                     }
                     update({ step: 'credentials', credentialsError: e.message });
                     return;
                 }
                 if (e.status === 404) {
-                    // 404 can come from two places:
-                    //   - resolveOrganizationId: space not found on this host (common when using --host
-                    //     with a staging/preview host but prod space IDs)
-                    //   - previewImport: design systems endpoint doesn't exist for this space/environment
-                    // Neither is a credentials problem — show a clear error instead of looping.
+                    // 404 from previewImport means the design systems endpoint doesn't exist for this
+                    // space/environment (typically wrong --host or wrong space/env). Not a credentials
+                    // problem — show a clear error instead of looping.
                     update({
                         step: 'error',
                         errorStep: 'apply preview',
+                        errorAllowCredentialRetry: true,
                         errorMessage: `Not found (404). Check that the space ID, environment ID, and host are correct.\n\n` +
                             `  Space:       ${spaceId}\n` +
                             `  Environment: ${environmentId}\n` +
@@ -543,11 +553,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     });
                     return;
                 }
-                update({ step: 'error', errorStep: 'apply preview', errorMessage: e.message });
+                update({ step: 'error', errorStep: 'apply preview', errorMessage: e.message, errorAllowCredentialRetry: true });
                 return;
             }
             const msg = e instanceof Error ? e.message : 'Preview failed';
-            update({ step: 'error', errorStep: 'apply preview', errorMessage: msg });
+            update({ step: 'error', errorStep: 'apply preview', errorMessage: msg, errorAllowCredentialRetry: true });
         }
     };
     const runPush = async (manifest, spaceId, environmentId, cmaToken, acknowledgeBreakingChanges, preview) => {
@@ -570,8 +580,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'pushing' });
         try {
             const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: apiHost });
-            const orgId = await client.resolveOrganizationId();
-            client.setOrganizationId(orgId);
             let operation = await client.applyImport(manifest, acknowledgeBreakingChanges);
             try {
                 logStep({
@@ -650,7 +658,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
         catch (e) {
             const msg = e instanceof ApiError ? e.message : e instanceof Error ? e.message : 'Push failed';
-            update({ step: 'error', errorStep: 'apply push', errorMessage: msg });
+            update({ step: 'error', errorStep: 'apply push', errorMessage: msg, errorAllowCredentialRetry: true });
         }
     };
     const runPrintFiles = async (extractSessionId, outDir) => {
@@ -667,7 +675,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         // tokensPath is already on disk from generate-tokens step; just record it
         update({ step: 'print-gate', componentsPath });
     };
-    // ── Effect: kick off automatic steps ─────────────────────────────────────
+    // ── Effect: kick off automatic steps ───────────────────────────────────────────────
     const tokenReuseChecked = useRef(false);
     useEffect(() => {
         if (state.step === 'generating-tokens') {
@@ -694,7 +702,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             })();
         }
     }, [state.step]); // intentional: only re-run when step changes
-    // ── Render ────────────────────────────────────────────────────────────────
+    // ── Render ────────────────────────────────────────────────────────────────────────────
     const noQuitSteps = [
         'checking-claude-auth',
         'validating-credentials',
@@ -734,7 +742,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         }
                     }, onQuit: () => process.exit(0) }));
             case 'checking-claude-auth':
-                return (_jsx(RunningStep, { stepNumber: 1, totalSteps: totalSteps, title: `Checking ${state.agent}`, description: `Verifying ${state.agent} is installed and authenticated...` }));
+                return (_jsx(RunningStep, { stepNumber: state.authCheckStepNumber, totalSteps: totalSteps, title: `Checking ${state.agent}`, description: `Verifying ${state.agent} is installed and authenticated...` }));
             case 'generating-tokens':
                 return (_jsx(RunningStep, { stepNumber: 1, totalSteps: totalSteps, title: "Generating token definitions", description: `${state.agent} is mapping your design tokens to DTCG format and writing tokens.json. This may take a few minutes.` }));
             case 'path-validation':
@@ -836,7 +844,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken);
                     }, onQuit: () => process.exit(0) }));
             case 'validating-credentials':
-                return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Validating credentials", description: "Checking that your space ID and CMA token are valid..." }));
+                return (_jsx(RunningStep, { stepNumber: totalSteps - 1, totalSteps: totalSteps, title: "Validating credentials", description: "Checking that your space ID and CMA token are valid..." }));
             case 'previewing':
                 return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Computing diff", description: "Computing diff against your Contentful space..." }));
             case 'preview-gate':
@@ -857,13 +865,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         hasTokens && state.tokensPath ? `tokens.json → ${state.tokensPath}` : null,
                     ]
                         .filter(Boolean)
-                        .join('\n'), context: "Your files are saved to disk. Run `exo import` again when you're ready to push to Contentful.", continueLabel: "Exit", showSkip: false, onContinue: () => process.exit(0), onQuit: () => process.exit(0) }));
+                        .join('\n'), context: "Your files are saved to disk. Run `experiences import` again when you're ready to push to Contentful.", continueLabel: "Exit", showSkip: false, onContinue: () => process.exit(0), onQuit: () => process.exit(0) }));
             case 'done': {
                 const totalFailed = state.pushResult.componentTypes.failed + state.pushResult.designTokens.failed;
                 return (_jsx(DoneStep, { componentTypes: state.pushResult.componentTypes, designTokens: state.pushResult.designTokens, summary: state.pushResult.summary, spaceId: state.spaceId, environmentId: state.environmentId, onExit: () => process.exit(totalFailed > 0 ? 1 : 0) }));
             }
             case 'error':
-                return _jsx(ErrorStep, { stepName: state.errorStep, message: state.errorMessage, onExit: () => process.exit(1) });
+                return (_jsx(ErrorStep, { stepName: state.errorStep, message: state.errorMessage, onExit: () => process.exit(1), onRetryCredentials: state.errorAllowCredentialRetry ? () => update({ step: 'credentials', credentialsError: '' }) : undefined }));
         }
     })();
     return (_jsxs(Box, { flexDirection: "column", width: terminalWidth, children: [_jsx(TopBar, { subcommand: "import", hints: hints }), stepContent] }));

package/dist/src/import/tui/steps/CredentialsStep.js

@@ -74,6 +74,6 @@ export function CredentialsStep({ summary, error: externalError, initialSpaceId
     }
     const displayError = inlineError ?? externalError ?? null;
     return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [summary && _jsxs(Text, { color: "green", children: ["\u2713 ", summary] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: initialSpaceId && initialCmaToken
-                        ? 'Credentials pre-filled from exo setup. Press Enter to continue or edit any field to update.'
-                        : 'Enter your Contentful credentials to continue.' }) }), !(initialSpaceId && initialCmaToken) && (_jsx(Text, { dimColor: true, children: "Tip: run exo setup to save these to ~/.config/exo/credentials.json so they pre-fill here automatically." })), _jsxs(Box, { flexDirection: "column", gap: 0, marginTop: 1, children: [renderField('Space ID', spaceId, 'spaceId'), renderField('Environment', environmentId, 'environmentId'), renderField('CMA Token', cmaToken, 'cmaToken', true)] }), displayError && _jsxs(Text, { color: "red", children: ["\u2717 ", displayError] }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[Enter] Next field / Submit" }), _jsx(Text, { dimColor: true, children: "[Tab] Switch field" }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
+                        ? 'Credentials pre-filled from experiences setup. Press Enter to continue or edit any field to update.'
+                        : 'Enter your Contentful credentials to continue.' }) }), !(initialSpaceId && initialCmaToken) && (_jsx(Text, { dimColor: true, children: "Tip: run experiences setup to save these to ~/.config/experiences/credentials.json so they pre-fill here automatically." })), _jsxs(Box, { flexDirection: "column", gap: 0, marginTop: 1, children: [renderField('Space ID', spaceId, 'spaceId'), renderField('Environment', environmentId, 'environmentId'), renderField('CMA Token', cmaToken, 'cmaToken', true)] }), displayError && _jsxs(Text, { color: "red", children: ["\u2717 ", displayError] }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[Enter] Next field / Submit" }), _jsx(Text, { dimColor: true, children: "[Tab] Switch field" }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
 }

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

@@ -3,6 +3,7 @@ type ErrorStepProps = {
     stepName: string;
     message: string;
     onExit: () => void;
+    onRetryCredentials?: () => void;
 };
-export declare function ErrorStep({ stepName, message, onExit }: ErrorStepProps): React.ReactElement;
+export declare function ErrorStep({ stepName, message, onExit, onRetryCredentials }: ErrorStepProps): React.ReactElement;
 export {};

package/dist/src/import/tui/steps/ErrorStep.js

@@ -1,11 +1,15 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
-export function ErrorStep({ stepName, message, onExit }) {
+export function ErrorStep({ stepName, message, onExit, onRetryCredentials }) {
     useImmediateInput((input, key) => {
+        if (input === 'r' && onRetryCredentials) {
+            onRetryCredentials();
+            return;
+        }
         if (key.return || input === 'q' || key.escape) {
             onExit();
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, color: "red", children: ["\u2717 ", stepName, " failed"] }), _jsx(Text, { color: "red", children: message }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "[Enter / q] Exit" }) })] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, color: "red", children: ["\u2717 ", stepName, " failed"] }), _jsx(Text, { color: "red", children: message }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[Enter / q] Exit" }), onRetryCredentials && _jsx(Text, { dimColor: true, children: "[r] Re-enter credentials" })] })] }));
 }

package/dist/src/session/db.d.ts

@@ -83,7 +83,7 @@ export declare function seedCDFFromPreviewResponse(db: DatabaseSync, sessionId:
  */
 export declare function seedDefaultsFromChangedItems(db: DatabaseSync, sessionId: string, changedItems: Array<{
     current: ComponentTypeSummary;
-    proposed: Record<string, unknown>;
+    proposed: object;
 }>): number;
 /**
  * Ensures all props on generated components have a cdf_type.

package/dist/src/setup/command.js

@@ -5,7 +5,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { promisify } from 'node:util';
-import { readExoCredentials, writeExoCredentials, exoCredentialsPath } from '../credentials-store.js';
+import { readExperiencesCredentials, writeExperiencesCredentials, experiencesCredentialsPath, } from '../credentials-store.js';
 const execFileAsync = promisify(execFile);
 const REQUIRED_NODE_MAJOR = 24;
 // ── Output helpers ────────────────────────────────────────────────────────────
@@ -169,7 +169,7 @@ async function setupNode() {
         info(`nvm detected. Will run: nvm install ${REQUIRED_NODE_MAJOR} && nvm use ${REQUIRED_NODE_MAJOR}`);
         const go = await confirm(`Install and switch to Node ${REQUIRED_NODE_MAJOR} via nvm?`);
         if (!go) {
-            warn(`Skipped. Re-run exo setup after switching to Node ${REQUIRED_NODE_MAJOR}.`);
+            warn(`Skipped. Re-run experiences setup after switching to Node ${REQUIRED_NODE_MAJOR}.`);
             return false;
         }
         // nvm is a shell function so we source it and run in a subshell
@@ -184,14 +184,14 @@ async function setupNode() {
             info(`Run manually: nvm install ${REQUIRED_NODE_MAJOR} && nvm use ${REQUIRED_NODE_MAJOR}`);
             return false;
         }
-        ok(`Node ${REQUIRED_NODE_MAJOR} installed via nvm. Re-run exo setup in a fresh shell to pick it up.`);
+        ok(`Node ${REQUIRED_NODE_MAJOR} installed via nvm. Re-run experiences setup in a fresh shell to pick it up.`);
         return false; // Need fresh shell to get the new node on PATH
     }
     if (hasFnm) {
         info(`fnm detected. Will run: fnm install ${REQUIRED_NODE_MAJOR} && fnm use ${REQUIRED_NODE_MAJOR}`);
         const go = await confirm(`Install and switch to Node ${REQUIRED_NODE_MAJOR} via fnm?`);
         if (!go) {
-            warn(`Skipped. Re-run exo setup after switching to Node ${REQUIRED_NODE_MAJOR}.`);
+            warn(`Skipped. Re-run experiences setup after switching to Node ${REQUIRED_NODE_MAJOR}.`);
             return false;
         }
         const result = await runSpawn('fnm', ['install', String(REQUIRED_NODE_MAJOR)]);
@@ -212,7 +212,7 @@ async function setupNode() {
                 info(`Run manually: fnm default ${REQUIRED_NODE_MAJOR}`);
             }
         }
-        ok(`Node ${REQUIRED_NODE_MAJOR} installed via fnm. Re-run exo setup in a fresh shell.`);
+        ok(`Node ${REQUIRED_NODE_MAJOR} installed via fnm. Re-run experiences setup in a fresh shell.`);
         return false;
     }
     // No version manager found — offer to install nvm
@@ -229,7 +229,7 @@ async function setupNode() {
             info('Install manually: https://github.com/nvm-sh/nvm#installing-and-updating');
             return false;
         }
-        ok('nvm installed. Open a new shell, then re-run exo setup.');
+        ok('nvm installed. Open a new shell, then re-run experiences setup.');
         return false;
     }
     info(`Install Node ${REQUIRED_NODE_MAJOR} manually from https://nodejs.org`);
@@ -308,7 +308,7 @@ async function setupBuild(repoRoot) {
 // ── Step 4: agent CLI ─────────────────────────────────────────────────────────
 async function setupAgent() {
     section('Step 4: Coding agent (claude, codex, opencode, or cursor)', '[required]');
-    info('exo import uses a coding agent to generate component definitions.');
+    info('experiences import uses a coding agent to generate component definitions.');
     info('');
     const agents = [
         { name: 'Claude Code', binary: 'claude', installHint: 'npm install -g @anthropic-ai/claude-code && claude login' },
@@ -375,15 +375,15 @@ async function setupAgent() {
         info('Run `opencode auth` to configure your provider.');
         return true;
     }
-    warn('Skipped. Install a coding agent before running exo import.');
+    warn('Skipped. Install a coding agent before running experiences import.');
     return false;
 }
 // ── Step 5: Contentful credentials ───────────────────────────────────────────
 async function setupContentfulCredentials() {
     section('Step 5: Contentful credentials', '[optional]');
-    info(`Saved to ${exoCredentialsPath()} — loaded automatically by exo import.`);
+    info(`Saved to ${experiencesCredentialsPath()} — loaded automatically by experiences import.`);
     info('');
-    const stored = await readExoCredentials();
+    const stored = await readExperiencesCredentials();
     const currentSpace = stored.spaceId;
     const currentEnv = stored.environmentId;
     const currentToken = stored.cmaToken;
@@ -417,7 +417,7 @@ async function setupContentfulCredentials() {
             ok('Credentials already configured — no changes made');
         }
         else {
-            warn('Skipped. exo import will prompt for credentials interactively.');
+            warn('Skipped. experiences import will prompt for credentials interactively.');
         }
         return true;
     }
@@ -434,15 +434,15 @@ async function setupContentfulCredentials() {
         warn('Space ID and CMA token are required. Skipped.');
         return false;
     }
-    await writeExoCredentials({ spaceId, environmentId, cmaToken });
-    ok(`Credentials saved to ${exoCredentialsPath()}`);
-    info('Run exo import — the credentials step will be pre-filled automatically.');
+    await writeExperiencesCredentials({ spaceId, environmentId, cmaToken });
+    ok(`Credentials saved to ${experiencesCredentialsPath()}`);
+    info('Run experiences import — the credentials step will be pre-filled automatically.');
     return true;
 }
 // ── Step 6: Optional quality-of-life ─────────────────────────────────────────
 async function setupQoL(profilePath) {
     section('Step 6: Optional extras', '[optional]');
-    info('These are not required for exo import but improve the experience.');
+    info('These are not required for experiences import but improve the experience.');
     info('');
     // 6a: EDS_EXTRACT_CONCURRENCY
     const hasConcurrency = await profileContains(profilePath, 'EDS_EXTRACT_CONCURRENCY');
@@ -451,7 +451,7 @@ async function setupQoL(profilePath) {
         info('Default is 4. Set higher (e.g. 8) on fast machines to speed up large codebases.');
         const setConcurrency = await confirm('Add EDS_EXTRACT_CONCURRENCY=8 to your profile?', false);
         if (setConcurrency) {
-            await appendToProfile(profilePath, '# exo performance\nexport EDS_EXTRACT_CONCURRENCY=8');
+            await appendToProfile(profilePath, '# experiences performance\nexport EDS_EXTRACT_CONCURRENCY=8');
             ok(`EDS_EXTRACT_CONCURRENCY=8 written to ${profilePath}`);
         }
         else {
@@ -595,7 +595,7 @@ async function checkAgent() {
         }
     }
     warn('No coding agent found on PATH');
-    info('The coding agent is required for the generate steps in exo import.');
+    info('The coding agent is required for the generate steps in experiences import.');
     info('Install one of:');
     info('  • Claude Code:   npm install -g @anthropic-ai/claude-code');
     info('  • OpenAI Codex:  npm install -g @openai/codex');
@@ -606,11 +606,11 @@ async function checkAgent() {
 export function registerSetupCommand(program) {
     program
         .command('doctor')
-        .description('Check prerequisites so exo import runs without errors')
+        .description('Check prerequisites so experiences import runs without errors')
         .option('--skip-build', 'Skip the pnpm install + build step (useful if already built)')
         .option('--skip-agent', 'Skip the coding agent check')
         .action(async (opts) => {
-        process.stderr.write('\x1b[1mexo doctor\x1b[0m — checking your environment\n');
+        process.stderr.write('\x1b[1mexperiences doctor\x1b[0m — checking your environment\n');
         const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
         const results = [];
         const nodeOk = await checkNode();
@@ -651,30 +651,30 @@ export function registerSetupCommand(program) {
             }
         }
         if (requiredFailed.length === 0 && failed.length === 0) {
-            process.stderr.write('\n\x1b[32m\x1b[1m✓ All checks passed. You are ready to run: exo import\x1b[0m\n\n');
+            process.stderr.write('\n\x1b[32m\x1b[1m✓ All checks passed. You are ready to run: experiences import\x1b[0m\n\n');
             process.exit(0);
         }
         else if (requiredFailed.length === 0) {
             process.stderr.write('\n\x1b[33m\x1b[1m⚠ Required checks passed, but optional checks failed.\x1b[0m\n');
-            process.stderr.write('  You can run \x1b[1mexo import\x1b[0m but the generate steps may fail without a coding agent.\n\n');
+            process.stderr.write('  You can run \x1b[1mexperiences import\x1b[0m but the generate steps may fail without a coding agent.\n\n');
             process.exit(0);
         }
         else {
             process.stderr.write(`\n\x1b[31m\x1b[1m✗ ${requiredFailed.length} required check${requiredFailed.length === 1 ? '' : 's'} failed.\x1b[0m\n`);
-            process.stderr.write('  Fix the issues above, then re-run \x1b[1mexo doctor\x1b[0m.\n\n');
+            process.stderr.write('  Fix the issues above, then re-run \x1b[1mexperiences doctor\x1b[0m.\n\n');
             process.exit(1);
         }
     });
     program
         .command('setup')
-        .description('Interactive setup wizard: installs prerequisites and configures credentials for exo import')
+        .description('Interactive setup wizard: installs prerequisites and configures credentials for experiences import')
         .option('--skip-build', 'Skip the pnpm install + build step')
         .option('--skip-agent', 'Skip the coding agent check')
         .option('--skip-credentials', 'Skip the Contentful credentials step')
         .option('--skip-optional', 'Skip optional quality-of-life extras')
         .action(async (opts) => {
-        process.stdout.write('\n\x1b[1mexo setup\x1b[0m — interactive setup wizard\n');
-        process.stdout.write('Sets up everything you need to run \x1b[1mexo import\x1b[0m.\n');
+        process.stdout.write('\n\x1b[1mexperiences setup\x1b[0m — interactive setup wizard\n');
+        process.stdout.write('Sets up everything you need to run \x1b[1mexperiences import\x1b[0m.\n');
         process.stdout.write('Required steps are marked \x1b[31m[required]\x1b[0m, optional ones \x1b[2m[optional]\x1b[0m.\n');
         const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
         const repoRoot = join(pkgRoot, '..', '..');
@@ -684,7 +684,7 @@ export function registerSetupCommand(program) {
         const nodeOk = await setupNode();
         results.push({ name: 'Node.js 24+', passed: nodeOk, required: true });
         if (!nodeOk) {
-            process.stdout.write('\n\x1b[33mNode.js setup requires a shell restart. Re-run exo setup afterwards.\x1b[0m\n\n');
+            process.stdout.write('\n\x1b[33mNode.js setup requires a shell restart. Re-run experiences setup afterwards.\x1b[0m\n\n');
             process.exit(0);
         }
         // Step 2: pnpm
@@ -736,19 +736,19 @@ export function registerSetupCommand(program) {
         }
         process.stdout.write('\n');
         if (requiredFailed.length === 0) {
-            process.stdout.write('\x1b[32m\x1b[1m✓ Setup complete. You can now run: exo import\x1b[0m\n');
+            process.stdout.write('\x1b[32m\x1b[1m✓ Setup complete. You can now run: experiences import\x1b[0m\n');
             if (optionalFailed.length > 0) {
                 process.stdout.write("  (Some optional steps were skipped — that's fine.)\n");
             }
         }
         else {
             process.stdout.write(`\x1b[33m\x1b[1m⚠ ${requiredFailed.length} required step${requiredFailed.length === 1 ? '' : 's'} incomplete.\x1b[0m\n`);
-            process.stdout.write('  Complete the steps above, then re-run \x1b[1mexo setup\x1b[0m.\n');
+            process.stdout.write('  Complete the steps above, then re-run \x1b[1mexperiences setup\x1b[0m.\n');
         }
-        // ── Offer exo doctor ───────────────────────────────────────────────────
+        // ── Offer experiences doctor ───────────────────────────────────────────────────
         process.stdout.write('\n');
         const runDoctor = process.stdout.isTTY &&
-            (await confirm('Run exo doctor now to verify your environment?', requiredFailed.length === 0));
+            (await confirm('Run experiences doctor now to verify your environment?', requiredFailed.length === 0));
         if (runDoctor) {
             process.stdout.write('\n');
             const cliBin = process.argv[1] ?? fileURLToPath(import.meta.url);
@@ -759,7 +759,7 @@ export function registerSetupCommand(program) {
             process.stderr.write(doctorResult.stderr);
             process.exit(doctorResult.exitCode);
         }
-        process.stdout.write('\nRun \x1b[1mexo doctor\x1b[0m at any time to re-check your environment.\n\n');
+        process.stdout.write('\nRun \x1b[1mexperiences doctor\x1b[0m at any time to re-check your environment.\n\n');
         process.exit(requiredFailed.length === 0 ? 0 : 1);
     });
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.2.1",
+  "version": "2.5.2-dev-build-eebccad.0",
   "description": "Contentful Experiences design system import CLI",
   "type": "module",
   "bin": {
     "experience-design-system-cli": "./bin/cli.js",
+    "experiences": "./bin/cli.js",
     "exo": "./bin/cli.js"
   },
   "main": "./dist/src/index.js",
@@ -30,7 +31,7 @@
     "react-dom": "^18.3.1",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.2.1"
+    "@contentful/experience-design-system-types": "2.5.2-dev-build-eebccad.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",