@contentful/experience-design-system-cli 2.32.1-dev-build-f054f94.0 → 2.32.1-dev-build-47de682.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.32.1-dev-build-f054f94.0",
+  "version": "2.32.1-dev-build-47de682.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/api/clients/abstract-api-client.d.ts

@@ -0,0 +1,24 @@
+export interface AbstractApiClientOptions {
+    host?: string;
+    cmaToken: string;
+    spaceId: string;
+    environmentId: string;
+}
+/**
+ * Shared base for CmaApiClient + EdsiApiClient. Owns the fields, URL
+ * helpers, and the /users/me validateCmaToken flow that both clients need.
+ * Subclasses override validateCmaToken() when they need to add
+ * service-specific follow-ups (e.g. EdsiApiClient calls checkPreflight()
+ * after the base check).
+ */
+export declare abstract class AbstractApiClient {
+    protected readonly host: string;
+    protected readonly token: string;
+    protected readonly spaceId: string;
+    protected readonly environmentId: string;
+    constructor(opts: AbstractApiClientOptions);
+    protected base(): string;
+    protected buildHeaders(): Record<string, string>;
+    validateCmaToken(): Promise<void>;
+    protected onValidateCmaTokenResponse(_res: Response): void;
+}

package/dist/src/api/clients/cma-client.d.ts

@@ -0,0 +1,8 @@
+import { AbstractApiClient } from './abstract-api-client.js';
+import type { CmaClientOptions } from '../../interfaces/clients/cma-client-options.js';
+import type { ExistingEntitiesResponse } from '../../interfaces/responses/existing-entities-response.js';
+export declare class CmaApiClient extends AbstractApiClient {
+    constructor(opts: CmaClientOptions);
+    listExistingEntities(): Promise<ExistingEntitiesResponse>;
+    private listAll;
+}

package/dist/src/api/clients/edsi-client.d.ts

@@ -0,0 +1,22 @@
+import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse } from '@contentful/experience-design-system-types';
+import { AbstractApiClient } from './abstract-api-client.js';
+import type { EdsiClientOptions } from '../../interfaces/clients/edsi-client-options.js';
+import type { PollOptions } from '../../interfaces/clients/poll-options.js';
+export declare class EdsiApiClient extends AbstractApiClient {
+    private retry;
+    private lastRequestId?;
+    getLastRequestId(): string | undefined;
+    private noteRequestId;
+    protected onValidateCmaTokenResponse(res: Response): void;
+    constructor(opts: EdsiClientOptions);
+    private headers;
+    private requestWithRetry;
+    validateCmaToken(): Promise<void>;
+    checkPreflight(): Promise<void>;
+    previewImport(manifest: ManifestPayload, allowDeletions?: boolean): Promise<ServerPreviewResponse>;
+    applyImport(manifest: ManifestPayload, options: {
+        acknowledgeBreakingChanges: boolean;
+        allowDeletions?: boolean;
+    }): Promise<ApplyOperationResponse>;
+    pollOperation(operationId: string, opts?: PollOptions): Promise<ApplyOperationResponse>;
+}

package/dist/src/api/index.d.ts

@@ -0,0 +1,16 @@
+export { CmaApiClient } from './clients/cma-client.js';
+export { EdsiApiClient } from './clients/edsi-client.js';
+export { AbstractApiClient } from './clients/abstract-api-client.js';
+export { ApiError } from '../errors/api-error.js';
+export { DEFAULT_HOST } from '../constants/edsi/host.js';
+export { PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE } from '../constants/edsi/errors.js';
+export { parsePreviewValidationErrors, sanitizeBreakingChanges } from '../helpers/edsi-response.js';
+export type { CmaClientOptions } from '../interfaces/clients/cma-client-options.js';
+export type { EdsiClientOptions } from '../interfaces/clients/edsi-client-options.js';
+export type { PollOptions } from '../interfaces/clients/poll-options.js';
+export type { RetryOptions } from '../interfaces/clients/retry-options.js';
+export type { ExistingComponentEntity } from '../interfaces/responses/existing-component-entity.js';
+export type { ExistingTokenEntity } from '../interfaces/responses/existing-token-entity.js';
+export type { ExistingEntitiesResponse } from '../interfaces/responses/existing-entities-response.js';
+export type { PreviewValidationError } from '../interfaces/responses/preview-validation-error.js';
+export type { CmaCollection } from '../interfaces/responses/cma-collection.js';

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

@@ -1,68 +1,7 @@
-import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse, BreakingChange } from '@contentful/experience-design-system-types';
-export declare const DEFAULT_HOST = "https://api.contentful.com";
-export declare const PREVIEW_ERROR_PREFIX = "preview failed:";
-export declare const APPLY_ERROR_PREFIX = "apply failed:";
-export declare const VALIDATION_FAILED_CODE = "\"ValidationFailed\"";
-export interface ApiClientOptions {
-    host?: string;
-    cmaToken: string;
-    spaceId: string;
-    environmentId: string;
-    retry?: {
-        maxAttempts?: number;
-        initialDelayMs?: number;
-        maxDelayMs?: number;
-        sleep?: (delayMs: number) => Promise<void>;
-    };
-}
-export declare class ApiError extends Error {
-    readonly status: number;
-    readonly body: string;
-    readonly guidance?: string | undefined;
-    constructor(message: string, status: number, body: string, guidance?: string | undefined);
-}
-export interface PreviewValidationError {
-    componentName: string;
-    path: string;
-    message: string;
-}
-/**
- * Parse the JSON body of a 422 from `previewImport()` into structured
- * per-component validation errors. Returns [] for any malformed input
- * so callers can fall back to the generic error path without try/catch.
- *
- * Path shape: `manifest:components/<Name>/$slots/<key>` or
- * `manifest:components/<Name>/$properties/<key>`. Only the component
- * name is extracted today; `path` and `message` are kept verbatim so
- * future surfaces (debug logging, headless retry in SP-4) can render
- * the field-level detail.
- */
-export declare function parsePreviewValidationErrors(body: string): PreviewValidationError[];
-export declare function sanitizeBreakingChanges(raw: unknown): BreakingChange[];
-export declare class ImportApiClient {
-    private host;
-    private token;
-    private spaceId;
-    private environmentId;
-    private retry;
-    private lastRequestId?;
-    getLastRequestId(): string | undefined;
-    private noteRequestId;
-    constructor(opts: ApiClientOptions);
-    private base;
-    private headers;
-    private requestWithRetry;
-    validateToken(): Promise<void>;
-    checkPreflight(): Promise<void>;
-    previewImport(manifest: ManifestPayload, allowDeletions?: boolean): Promise<ServerPreviewResponse>;
-    applyImport(manifest: ManifestPayload, options: {
-        acknowledgeBreakingChanges: boolean;
-        allowDeletions?: boolean;
-    }): Promise<ApplyOperationResponse>;
-    pollOperation(operationId: string, opts?: {
-        intervalMs?: number;
-        maxIntervalMs?: number;
-        maxAttempts?: number;
-        onProgress?: (op: ApplyOperationResponse) => void;
-    }): Promise<ApplyOperationResponse>;
-}
+export { EdsiApiClient, EdsiApiClient as ImportApiClient } from '../api/clients/edsi-client.js';
+export { DEFAULT_HOST } from '../constants/edsi/host.js';
+export { PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE } from '../constants/edsi/errors.js';
+export { parsePreviewValidationErrors, sanitizeBreakingChanges } from '../helpers/edsi-response.js';
+export type { PreviewValidationError } from '../interfaces/responses/preview-validation-error.js';
+export { ApiError } from '../errors/api-error.js';
+export type { EdsiClientOptions as ApiClientOptions } from '../interfaces/clients/edsi-client-options.js';

package/dist/src/constants/cma/pagination.d.ts

@@ -0,0 +1 @@
+export declare const CMA_PAGE_LIMIT = 100;

package/dist/src/constants/edsi/breaking-changes.d.ts

@@ -0,0 +1,3 @@
+export declare const PROPERTY_BREAKING_REASONS: Set<string>;
+export declare const SLOT_BREAKING_REASONS: Set<string>;
+export declare const COMPONENT_PATH_PREFIX = "manifest:components/";

package/dist/src/constants/edsi/errors.d.ts

@@ -0,0 +1,3 @@
+export declare const PREVIEW_ERROR_PREFIX = "preview failed:";
+export declare const APPLY_ERROR_PREFIX = "apply failed:";
+export declare const VALIDATION_FAILED_CODE = "\"ValidationFailed\"";

package/dist/src/constants/edsi/host.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_HOST = "https://api.contentful.com";

package/dist/src/constants/shared/retry.d.ts

@@ -0,0 +1 @@
+export declare const MAX_RETRY_AFTER_MS = 60000;

package/dist/src/errors/api-error.d.ts

@@ -0,0 +1,6 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly guidance?: string | undefined;
+    constructor(message: string, status: number, body: string, guidance?: string | undefined);
+}

package/dist/src/helpers/edsi-response.d.ts

@@ -0,0 +1,17 @@
+import type { BreakingChange, ServerPreviewResponse } from '@contentful/experience-design-system-types';
+import type { PreviewValidationError } from '../interfaces/responses/preview-validation-error.js';
+/**
+ * Parse the JSON body of a 422 from `previewImport()` into structured
+ * per-component validation errors. Returns [] for any malformed input
+ * so callers can fall back to the generic error path without try/catch.
+ *
+ * Path shape: `manifest:components/<Name>/$slots/<key>` or
+ * `manifest:components/<Name>/$properties/<key>`. Only the component
+ * name is extracted today; `path` and `message` are kept verbatim so
+ * future surfaces (debug logging, headless retry in SP-4) can render
+ * the field-level detail.
+ */
+export declare function parsePreviewValidationErrors(body: string): PreviewValidationError[];
+export declare function sanitizeBreakingChanges(raw: unknown): BreakingChange[];
+export declare function sanitizePreviewResponse(res: ServerPreviewResponse): ServerPreviewResponse;
+export declare function isApsDenialBody(body: string): boolean;

package/dist/src/helpers/http.d.ts

@@ -0,0 +1,4 @@
+export declare function buildHeaders(token: string): Record<string, string>;
+export declare function request(url: string, options: RequestInit & {
+    token: string;
+}): Promise<Response>;

package/dist/src/helpers/retry.d.ts

@@ -0,0 +1,5 @@
+export declare function defaultSleep(delayMs: number): Promise<void>;
+export declare function isTransientStatus(status: number): boolean;
+export declare function retryAfterMs(response: Response): number | undefined;
+export declare function errorMessage(error: unknown): string;
+export declare function stringifyError(error: unknown): string;

package/dist/src/helpers/url.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_API_HOST = "https://api.contentful.com";
+export declare const DEFAULT_CONFIGURED_HOST = "api.contentful.com";
+export declare function toConfiguredHost(host?: string): string | undefined;
+export declare function toApiHost(host?: string): string;

package/dist/src/host-utils.d.ts

@@ -1,4 +1 @@
-export declare const DEFAULT_API_HOST = "https://api.contentful.com";
-export declare const DEFAULT_CONFIGURED_HOST = "api.contentful.com";
-export declare function toConfiguredHost(host?: string): string | undefined;
-export declare function toApiHost(host?: string): string;
+export { DEFAULT_API_HOST, DEFAULT_CONFIGURED_HOST, toConfiguredHost, toApiHost } from './helpers/url.js';

package/dist/src/import/orchestrator.d.ts

@@ -28,6 +28,15 @@ export interface PipelineOptions {
     /** When true, auto-reject cycle participants and retry push instead of surfacing an error. */
     autoRejectCycles?: boolean;
     allowDeletions?: boolean;
+    /**
+     * Fetch existing Components + DesignTokens from the target space+env
+     * and persist them under outDir/.existing-entities.json so downstream
+     * agent steps can consume them as context. Requires spaceId +
+     * environmentId + cmaToken; skipped with a warning otherwise. No-op
+     * for the agent flow in this PR — the file is written but nothing
+     * reads it yet.
+     */
+    withSpaceContext?: boolean;
     compositionMode?: CompositionMode;
     compositionMap?: string;
     compositionAgent?: boolean;

package/dist/src/index.js

@@ -12603,37 +12603,6 @@ var init_src3 = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/host-utils.ts
-function trimTrailingSlashes(value) {
-  return value.replace(/\/+$/, "");
-}
-function normalizeHostInput(host) {
-  const value = host?.trim();
-  if (!value) return void 0;
-  return trimTrailingSlashes(value);
-}
-function toConfiguredHost(host) {
-  const normalized = normalizeHostInput(host);
-  if (!normalized) return void 0;
-  return normalized.replace(/^https:\/\//i, "");
-}
-function toApiHost(host) {
-  const normalized = normalizeHostInput(host);
-  if (!normalized) return DEFAULT_API_HOST;
-  if (/^[a-z][a-z\d+\-.]*:\/\//i.test(normalized)) {
-    return normalized;
-  }
-  return `https://${normalized}`;
-}
-var DEFAULT_API_HOST, DEFAULT_CONFIGURED_HOST;
-var init_host_utils = __esm({
-  "packages/experience-design-system-cli/src/host-utils.ts"() {
-    "use strict";
-    DEFAULT_API_HOST = "https://api.contentful.com";
-    DEFAULT_CONFIGURED_HOST = "api.contentful.com";
-  }
-});
-
 // packages/experience-design-system-cli/src/lib/debug-logger.ts
 import { mkdirSync as mkdirSync2, appendFileSync } from "node:fs";
 import { join as join8, dirname as dirname8 } from "node:path";
@@ -12834,7 +12803,39 @@ var init_user_agent = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/apply/api-client.ts
+// packages/experience-design-system-cli/src/helpers/http.ts
+function buildHeaders(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "X-Contentful-User-Agent": buildUserAgent()
+  };
+}
+async function request(url, options) {
+  const init = {
+    method: options.method ?? "GET",
+    headers: buildHeaders(options.token)
+  };
+  if (options.body) init.body = options.body;
+  return fetch(url, init);
+}
+var init_http = __esm({
+  "packages/experience-design-system-cli/src/helpers/http.ts"() {
+    "use strict";
+    init_user_agent();
+  }
+});
+
+// packages/experience-design-system-cli/src/constants/shared/retry.ts
+var MAX_RETRY_AFTER_MS;
+var init_retry = __esm({
+  "packages/experience-design-system-cli/src/constants/shared/retry.ts"() {
+    "use strict";
+    MAX_RETRY_AFTER_MS = 6e4;
+  }
+});
+
+// packages/experience-design-system-cli/src/helpers/retry.ts
 function defaultSleep(delayMs) {
   return new Promise((resolve27) => setTimeout(resolve27, delayMs));
 }
@@ -12855,6 +12856,30 @@ function errorMessage(error) {
 function stringifyError(error) {
   return typeof error === "string" ? error : JSON.stringify(error ?? {});
 }
+var init_retry2 = __esm({
+  "packages/experience-design-system-cli/src/helpers/retry.ts"() {
+    "use strict";
+    init_retry();
+  }
+});
+
+// packages/experience-design-system-cli/src/constants/edsi/breaking-changes.ts
+var PROPERTY_BREAKING_REASONS, SLOT_BREAKING_REASONS, COMPONENT_PATH_PREFIX;
+var init_breaking_changes = __esm({
+  "packages/experience-design-system-cli/src/constants/edsi/breaking-changes.ts"() {
+    "use strict";
+    PROPERTY_BREAKING_REASONS = /* @__PURE__ */ new Set([
+      "removed",
+      "added_required_no_default",
+      "type_changed",
+      "validation_narrowed"
+    ]);
+    SLOT_BREAKING_REASONS = /* @__PURE__ */ new Set(["slot_removed", "slot_allowed_components_narrowed"]);
+    COMPONENT_PATH_PREFIX = "manifest:components/";
+  }
+});
+
+// packages/experience-design-system-cli/src/helpers/edsi-response.ts
 function parsePreviewValidationErrors(body) {
   if (!body) return [];
   let parsed;
@@ -12917,31 +12942,18 @@ function isApsDenialBody(body) {
     return false;
   }
 }
-async function request(url, options) {
-  const headers = {
-    Authorization: `Bearer ${options.token}`,
-    "Content-Type": "application/json",
-    "X-Contentful-User-Agent": buildUserAgent()
-  };
-  const init = {
-    method: options.method ?? "GET",
-    headers
-  };
-  if (options.body) init.body = options.body;
-  return fetch(url, init);
-}
-var PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE, MAX_RETRY_AFTER_MS, ERROR_BODY_LOG_CAP, ApiError, COMPONENT_PATH_PREFIX, PROPERTY_BREAKING_REASONS, SLOT_BREAKING_REASONS, ImportApiClient;
-var init_api_client = __esm({
-  "packages/experience-design-system-cli/src/apply/api-client.ts"() {
+var init_edsi_response = __esm({
+  "packages/experience-design-system-cli/src/helpers/edsi-response.ts"() {
+    "use strict";
+    init_breaking_changes();
+  }
+});
+
+// packages/experience-design-system-cli/src/errors/api-error.ts
+var ERROR_BODY_LOG_CAP, ApiError;
+var init_api_error = __esm({
+  "packages/experience-design-system-cli/src/errors/api-error.ts"() {
     "use strict";
-    init_src3();
-    init_host_utils();
-    init_debug_logger();
-    init_user_agent();
-    PREVIEW_ERROR_PREFIX = "preview failed:";
-    APPLY_ERROR_PREFIX = "apply failed:";
-    VALIDATION_FAILED_CODE = '"ValidationFailed"';
-    MAX_RETRY_AFTER_MS = 6e4;
     ERROR_BODY_LOG_CAP = 16384;
     ApiError = class extends Error {
       constructor(message, status, body, guidance) {
@@ -12959,19 +12971,109 @@ ${trimmed}`;
       body;
       guidance;
     };
-    COMPONENT_PATH_PREFIX = "manifest:components/";
-    PROPERTY_BREAKING_REASONS = /* @__PURE__ */ new Set([
-      "removed",
-      "added_required_no_default",
-      "type_changed",
-      "validation_narrowed"
-    ]);
-    SLOT_BREAKING_REASONS = /* @__PURE__ */ new Set(["slot_removed", "slot_allowed_components_narrowed"]);
-    ImportApiClient = class {
+  }
+});
+
+// packages/experience-design-system-cli/src/helpers/url.ts
+function trimTrailingSlashes(value) {
+  return value.replace(/\/+$/, "");
+}
+function normalizeHostInput(host) {
+  const value = host?.trim();
+  if (!value) return void 0;
+  return trimTrailingSlashes(value);
+}
+function toConfiguredHost(host) {
+  const normalized = normalizeHostInput(host);
+  if (!normalized) return void 0;
+  return normalized.replace(/^https:\/\//i, "");
+}
+function toApiHost(host) {
+  const normalized = normalizeHostInput(host);
+  if (!normalized) return DEFAULT_API_HOST;
+  if (/^[a-z][a-z\d+\-.]*:\/\//i.test(normalized)) {
+    return normalized;
+  }
+  return `https://${normalized}`;
+}
+var DEFAULT_API_HOST, DEFAULT_CONFIGURED_HOST;
+var init_url = __esm({
+  "packages/experience-design-system-cli/src/helpers/url.ts"() {
+    "use strict";
+    DEFAULT_API_HOST = "https://api.contentful.com";
+    DEFAULT_CONFIGURED_HOST = "api.contentful.com";
+  }
+});
+
+// packages/experience-design-system-cli/src/api/clients/abstract-api-client.ts
+var AbstractApiClient;
+var init_abstract_api_client = __esm({
+  "packages/experience-design-system-cli/src/api/clients/abstract-api-client.ts"() {
+    "use strict";
+    init_url();
+    init_http();
+    init_api_error();
+    AbstractApiClient = class {
       host;
       token;
       spaceId;
       environmentId;
+      constructor(opts) {
+        this.host = toApiHost(opts.host);
+        this.token = opts.cmaToken;
+        this.spaceId = opts.spaceId;
+        this.environmentId = opts.environmentId;
+      }
+      base() {
+        return `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
+      }
+      buildHeaders() {
+        return buildHeaders(this.token);
+      }
+      async validateCmaToken() {
+        const url = `${this.host}/users/me`;
+        const res = await request(url, { token: this.token });
+        this.onValidateCmaTokenResponse(res);
+        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 token: ${res.status}`, res.status, await res.text());
+        }
+      }
+      // Hook for subclasses to observe the raw /users/me response (e.g. capture
+      // x-contentful-request-id). Default is a no-op.
+      onValidateCmaTokenResponse(_res) {
+      }
+    };
+  }
+});
+
+// packages/experience-design-system-cli/src/constants/edsi/errors.ts
+var PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE;
+var init_errors = __esm({
+  "packages/experience-design-system-cli/src/constants/edsi/errors.ts"() {
+    "use strict";
+    PREVIEW_ERROR_PREFIX = "preview failed:";
+    APPLY_ERROR_PREFIX = "apply failed:";
+    VALIDATION_FAILED_CODE = '"ValidationFailed"';
+  }
+});
+
+// packages/experience-design-system-cli/src/api/clients/edsi-client.ts
+var EdsiApiClient;
+var init_edsi_client = __esm({
+  "packages/experience-design-system-cli/src/api/clients/edsi-client.ts"() {
+    "use strict";
+    init_src3();
+    init_debug_logger();
+    init_http();
+    init_retry2();
+    init_edsi_response();
+    init_api_error();
+    init_abstract_api_client();
+    init_errors();
+    EdsiApiClient = class extends AbstractApiClient {
       retry;
       lastRequestId;
       getLastRequestId() {
@@ -12981,11 +13083,11 @@ ${trimmed}`;
         const requestId = response.headers.get("x-contentful-request-id");
         if (requestId) this.lastRequestId = requestId;
       }
+      onValidateCmaTokenResponse(res) {
+        this.noteRequestId(res);
+      }
       constructor(opts) {
-        this.host = toApiHost(opts.host);
-        this.token = opts.cmaToken;
-        this.spaceId = opts.spaceId;
-        this.environmentId = opts.environmentId;
+        super(opts);
         const initialDelayMs = Math.max(0, opts.retry?.initialDelayMs ?? 250);
         this.retry = {
           maxAttempts: Math.max(1, Math.floor(opts.retry?.maxAttempts ?? 3)),
@@ -12994,15 +13096,8 @@ ${trimmed}`;
           sleep: opts.retry?.sleep ?? defaultSleep
         };
       }
-      base() {
-        return `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
-      }
       headers() {
-        return {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json",
-          "X-Contentful-User-Agent": buildUserAgent()
-        };
+        return this.buildHeaders();
       }
       async requestWithRetry(phase, errorPrefix, makeCall, context = {}) {
         const debug = getDebugLogger();
@@ -13068,16 +13163,8 @@ ${trimmed}`;
         }
         throw new Error("Retry attempts exhausted");
       }
-      async validateToken() {
-        const url = `${this.host}/users/me`;
-        const res = await request(url, { token: this.token });
-        this.noteRequestId(res);
-        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 token: ${res.status}`, res.status, await res.text());
-        }
+      async validateCmaToken() {
+        await super.validateCmaToken();
         await this.checkPreflight();
       }
       // Probe the sources-api preflight endpoint to catch APS-denied users up-front,
@@ -13089,7 +13176,7 @@ ${trimmed}`;
       //   404 without a NotFound envelope → older backend deployment; treat as pass
       //   5xx / network                → backend flake; treat as pass, do not block
       async checkPreflight() {
-        const url = `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}/design_systems/preflight`;
+        const url = `${this.base()}/design_systems/preflight`;
         let res;
         try {
           res = await request(url, { token: this.token });
@@ -13233,6 +13320,26 @@ ${trimmed}`;
   }
 });
 
+// packages/experience-design-system-cli/src/constants/edsi/host.ts
+var init_host = __esm({
+  "packages/experience-design-system-cli/src/constants/edsi/host.ts"() {
+    "use strict";
+    init_url();
+  }
+});
+
+// packages/experience-design-system-cli/src/apply/api-client.ts
+var init_api_client = __esm({
+  "packages/experience-design-system-cli/src/apply/api-client.ts"() {
+    "use strict";
+    init_edsi_client();
+    init_host();
+    init_errors();
+    init_edsi_response();
+    init_api_error();
+  }
+});
+
 // packages/experience-design-system-cli/src/lib/error-parser.ts
 function stripLambdaLogPrefix(body) {
   let out = body.replace(LAMBDA_LOG_PREFIX_RE, "");
@@ -14221,6 +14328,14 @@ var init_strip_allowed_components = __esm({
   }
 });
 
+// packages/experience-design-system-cli/src/host-utils.ts
+var init_host_utils = __esm({
+  "packages/experience-design-system-cli/src/host-utils.ts"() {
+    "use strict";
+    init_url();
+  }
+});
+
 // packages/experience-design-system-cli/src/credentials-store.ts
 var credentials_store_exports = {};
 __export(credentials_store_exports, {
@@ -14836,7 +14951,7 @@ async function resolveSharedInputs(opts) {
   if (opts.tokens) {
     tokens = await readTokensFromPath("--tokens", opts.tokens);
   }
-  const client2 = new ImportApiClient({
+  const client2 = new EdsiApiClient({
     host: opts.host,
     cmaToken,
     spaceId,
@@ -15077,7 +15192,7 @@ function registerApplyCommand(program) {
       environment_key: environmentId
     });
     try {
-      await client2.validateToken();
+      await client2.validateCmaToken();
     } catch (e) {
       if (e instanceof ApiError) return await die(`Error: ${formatApiError(e)}`, failureFromApiError(e));
       const cause = e instanceof Error && e.cause instanceof Error ? e.cause.message : "";
@@ -15135,7 +15250,7 @@ function registerApplyCommand(program) {
     });
     await assertNoSlotCycles(components);
     try {
-      await client2.validateToken();
+      await client2.validateCmaToken();
     } catch (e) {
       if (e instanceof ApiError)
         return await die(`Error: ${formatApiError(e, opts.verbose)}`, failureFromApiError(e));
@@ -15320,7 +15435,7 @@ function registerApplyCommand(program) {
     const { components, tokens, client: client2 } = inputs;
     await assertNoSlotCycles(components);
     try {
-      await client2.validateToken();
+      await client2.validateCmaToken();
     } catch (e) {
       if (e instanceof ApiError) return await die(`Error: ${formatApiError(e)}`, failureFromApiError(e));
       throw e;
@@ -15576,7 +15691,7 @@ function App({ sessionId: sessionId2, artifactsRoot, reviewRoot }) {
         tokens
       );
       if (!manifest.componentsManifest) manifest.componentsManifest = {};
-      const client2 = new ImportApiClient({ cmaToken, spaceId, environmentId });
+      const client2 = new EdsiApiClient({ cmaToken, spaceId, environmentId });
       const preview = await client2.previewImport(manifest, true);
       const annotations = {};
       for (const item of preview.components.new) {
@@ -16598,7 +16713,7 @@ var init_save_path_resolver = __esm({
 });
 
 // packages/experience-design-system-cli/src/runs/store.ts
-import { readFile as readFile22, writeFile as writeFile5, mkdir as mkdir6, rename } from "node:fs/promises";
+import { readFile as readFile22, writeFile as writeFile6, mkdir as mkdir6, rename } from "node:fs/promises";
 import { join as join20 } from "node:path";
 import { homedir as homedir7 } from "node:os";
 import { randomBytes as randomBytes2 } from "node:crypto";
@@ -16661,7 +16776,7 @@ async function writeAtomic(file) {
   await mkdir6(RUNS_DIR, { recursive: true });
   const body = JSON.stringify(file, null, 2) + "\n";
   const tmp = `${RUNS_PATH}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile5(tmp, body, { mode: 384 });
+  await writeFile6(tmp, body, { mode: 384 });
   await rename(tmp, RUNS_PATH);
 }
 async function appendRun(input) {
@@ -24143,7 +24258,7 @@ async function runLivePreview(opts) {
     tokens = await readTokensFromPath("tokens", tokensPath);
   }
   const manifest = buildManifest3(components, tokens, { deleteAllComponents: opts.deleteAllComponents === true });
-  const client2 = new ImportApiClient({ host, cmaToken, spaceId, environmentId });
+  const client2 = new EdsiApiClient({ host, cmaToken, spaceId, environmentId });
   const startedAt = Date.now();
   let timeoutHandle;
   const timeoutPromise = new Promise((_resolve, reject) => {
@@ -28363,13 +28478,13 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
     update({ step: "credentials", credentialsValidating: true, credentialsError: "" });
     try {
       const resolvedHost = resolveWizardHost(host2);
-      const client2 = new ImportApiClient({
+      const client2 = new EdsiApiClient({
         cmaToken,
         spaceId,
         environmentId,
         host: resolvedHost
       });
-      await client2.validateToken();
+      await client2.validateCmaToken();
       update({ spaceId, environmentId, cmaToken, host: resolvedHost, credentialsValidating: false });
       await advanceAfterCredentialsValidated();
     } catch (e) {
@@ -28437,7 +28552,7 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
     update({ step: "previewing" });
     const resolvedHost = resolveWizardHost(host2);
     try {
-      const client2 = new ImportApiClient({
+      const client2 = new EdsiApiClient({
         cmaToken,
         spaceId,
         environmentId,
@@ -28599,7 +28714,7 @@ If using a custom --host, make sure the space exists on that host.`
     update({ step: "pushing", pushProgress: null });
     try {
       const resolvedHost = resolveWizardHost(host2);
-      const client2 = new ImportApiClient({
+      const client2 = new EdsiApiClient({
         cmaToken,
         spaceId,
         environmentId,
@@ -34365,14 +34480,56 @@ init_db();
 init_command();
 init_manifest();
 init_api_client();
+import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join18, resolve as resolve21 } from "node:path";
+import { execFile as execFile2 } from "node:child_process";
+
+// packages/experience-design-system-cli/src/api/clients/cma-client.ts
+init_http();
+init_api_error();
+init_abstract_api_client();
+
+// packages/experience-design-system-cli/src/constants/cma/pagination.ts
+var CMA_PAGE_LIMIT = 100;
+
+// packages/experience-design-system-cli/src/api/clients/cma-client.ts
+var CmaApiClient = class extends AbstractApiClient {
+  constructor(opts) {
+    super(opts);
+  }
+  async listExistingEntities() {
+    const [components, tokens] = await Promise.all([
+      this.listAll("component_types", "component_types"),
+      this.listAll("design_tokens", "design_tokens")
+    ]);
+    return { components, tokens };
+  }
+  async listAll(resourcePath, opName) {
+    const items = [];
+    let skip = 0;
+    while (true) {
+      const url = `${this.base()}/${resourcePath}?limit=${CMA_PAGE_LIMIT}&skip=${skip}`;
+      const res = await request(url, { token: this.token });
+      if (!res.ok) {
+        throw new ApiError(`${opName} list failed: ${res.status}`, res.status, await res.text());
+      }
+      const page = await res.json();
+      items.push(...page.items);
+      const returned = page.items.length;
+      const total = page.total ?? items.length;
+      if (returned === 0 || items.length >= total) break;
+      skip += returned;
+    }
+    return items;
+  }
+};
+
+// packages/experience-design-system-cli/src/import/orchestrator.ts
 init_contentful_urls();
 init_debug_logger();
 init_analytics();
 init_env();
 init_cli_path();
-import { mkdir as mkdir5 } from "node:fs/promises";
-import { join as join18, resolve as resolve21 } from "node:path";
-import { execFile as execFile2 } from "node:child_process";
 async function runStep(args, cliPath, analyticsSessionId, env = {}, streamStderr = false) {
   const debug = getDebugLogger();
   const startedAt = Date.now();
@@ -34480,11 +34637,66 @@ async function runPipeline(opts, progressWriter, cliPathOverride) {
   await mkdir5(outDir, { recursive: true });
   const steps = [];
   let stepNum = 0;
-  const totalSteps = 5 + (opts.print ? 1 : 0);
+  const wantsSpaceContext = opts.withSpaceContext === true;
+  const canFetchSpaceContext = wantsSpaceContext && !!opts.spaceId && !!opts.environmentId && !!opts.cmaToken;
+  const totalSteps = 5 + (opts.print ? 1 : 0) + (canFetchSpaceContext ? 1 : 0);
   function stepLabel(name) {
     stepNum++;
     return `  Step ${stepNum}/${totalSteps}  ${name}  `;
   }
+  if (wantsSpaceContext && !canFetchSpaceContext) {
+    progressWriter(
+      "  Note: --with-space-context requires --space-id, --environment-id, and --cma-token; skipping context fetch."
+    );
+  }
+  if (canFetchSpaceContext) {
+    const fetchLabel = stepLabel("Fetching existing components + design tokens");
+    const fetchStepId = createStep(db, sessionId2, "fetch existing entities", {
+      spaceId: opts.spaceId,
+      environmentId: opts.environmentId
+    });
+    const t0 = Date.now();
+    try {
+      const cma = new CmaApiClient({
+        host: opts.host,
+        cmaToken: opts.cmaToken,
+        spaceId: opts.spaceId,
+        environmentId: opts.environmentId
+      });
+      const result = await cma.listExistingEntities();
+      const fetchDurationMs = Date.now() - t0;
+      const existingEntitiesPath = join18(outDir, ".existing-entities.json");
+      await writeFile5(existingEntitiesPath, JSON.stringify(result, null, 2), "utf8");
+      updateStep(db, fetchStepId, "complete", {
+        components: String(result.components.length),
+        tokens: String(result.tokens.length),
+        path: existingEntitiesPath
+      });
+      progressWriter(
+        `${fetchLabel}\u2713  ${result.components.length} component${result.components.length === 1 ? "" : "s"}, ${result.tokens.length} token${result.tokens.length === 1 ? "" : "s"}  (${(fetchDurationMs / 1e3).toFixed(1)}s)`
+      );
+      steps.push({
+        step: "fetch existing entities",
+        status: "complete",
+        durationMs: fetchDurationMs,
+        detail: { components: result.components.length, tokens: result.tokens.length }
+      });
+    } catch (error) {
+      const fetchDurationMs = Date.now() - t0;
+      const message = error instanceof Error ? error.message : String(error);
+      updateStep(db, fetchStepId, "failed", {}, message);
+      progressWriter(
+        `${fetchLabel}\u26A0  fetch failed, continuing without space context  (${(fetchDurationMs / 1e3).toFixed(1)}s)`
+      );
+      progressWriter(`    ${message.split("\n")[0]}`);
+      steps.push({
+        step: "fetch existing entities",
+        status: "failed",
+        durationMs: fetchDurationMs,
+        error: message
+      });
+    }
+  }
   const analyzeLabel = stepLabel("Statically analyzing project");
   const analyzeSkipped = !opts.noCache && opts.skipAnalyze;
   let extractSessionId = null;
@@ -35439,7 +35651,10 @@ function registerImportCommand(program) {
     "Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md",
     (v, acc) => [...acc, v],
     []
-  ).option("--auto-reject-cycles", "Automatically reject components involved in slot cycles and retry").option("--auto-filter", "Force the AI auto-filter ON (overrides the credentials.json autoFilter preference)").option(
+  ).option("--auto-reject-cycles", "Automatically reject components involved in slot cycles and retry").option(
+    "--with-space-context",
+    "Fetch existing Components + DesignTokens from the target space+env and persist them under <out>/.existing-entities.json for future agent-context enrichment. Requires --space-id, --environment-id, and --cma-token."
+  ).option("--auto-filter", "Force the AI auto-filter ON (overrides the credentials.json autoFilter preference)").option(
     "--no-auto-filter",
     "Skip the automatic AI pre-filter; jump straight to manual scope-gate (overrides the credentials.json autoFilter preference; no-op when paired with --auto-accept-scope)"
   ).option(
@@ -35786,6 +36001,7 @@ function registerImportCommand(program) {
           dryRun: dryRunForward,
           selectPromptPath: opts.selectPromptPath,
           autoRejectCycles: opts.autoRejectCycles ?? false,
+          withSpaceContext: opts.withSpaceContext ?? false,
           allowDeletions: opts.allowDeletions ?? false,
           compositionMode: headlessCompositionMode,
           ...opts.compositionMap ? { compositionMap: opts.compositionMap } : {},

package/dist/src/interfaces/clients/cma-client-options.d.ts

@@ -0,0 +1,6 @@
+export interface CmaClientOptions {
+    host?: string;
+    cmaToken: string;
+    spaceId: string;
+    environmentId: string;
+}

package/dist/src/interfaces/clients/edsi-client-options.d.ts

@@ -0,0 +1,12 @@
+export interface EdsiClientOptions {
+    host?: string;
+    cmaToken: string;
+    spaceId: string;
+    environmentId: string;
+    retry?: {
+        maxAttempts?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        sleep?: (delayMs: number) => Promise<void>;
+    };
+}

package/dist/src/interfaces/clients/poll-options.d.ts

@@ -0,0 +1,7 @@
+import type { ApplyOperationResponse } from '@contentful/experience-design-system-types';
+export interface PollOptions {
+    intervalMs?: number;
+    maxIntervalMs?: number;
+    maxAttempts?: number;
+    onProgress?: (op: ApplyOperationResponse) => void;
+}

package/dist/src/interfaces/clients/retry-options.d.ts

@@ -0,0 +1,6 @@
+export interface RetryOptions {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    sleep: (delayMs: number) => Promise<void>;
+}

package/dist/src/interfaces/responses/cma-collection.d.ts

@@ -0,0 +1,6 @@
+export interface CmaCollection<T> {
+    items: T[];
+    total?: number;
+    skip?: number;
+    limit?: number;
+}

package/dist/src/interfaces/responses/existing-component-entity.d.ts

@@ -0,0 +1,8 @@
+export interface ExistingComponentEntity {
+    id: string;
+    name: string;
+    description?: string;
+    contentProperties?: unknown[];
+    designProperties?: unknown[];
+    slots?: unknown[];
+}

package/dist/src/interfaces/responses/existing-entities-response.d.ts

@@ -0,0 +1,6 @@
+import type { ExistingComponentEntity } from './existing-component-entity.js';
+import type { ExistingTokenEntity } from './existing-token-entity.js';
+export interface ExistingEntitiesResponse {
+    components: ExistingComponentEntity[];
+    tokens: ExistingTokenEntity[];
+}

package/dist/src/interfaces/responses/existing-token-entity.d.ts

@@ -0,0 +1,6 @@
+export interface ExistingTokenEntity {
+    id: string;
+    name: string;
+    kind: string;
+    value?: unknown;
+}

package/dist/src/interfaces/responses/preview-validation-error.d.ts

@@ -0,0 +1,5 @@
+export interface PreviewValidationError {
+    componentName: string;
+    path: string;
+    message: string;
+}

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

@@ -5,7 +5,7 @@ import type { ToolCall, TokenToolCall, ComponentSourceRef } from '@contentful/ex
 import type { ComponentTypeSummary } from '@contentful/experience-design-system-types';
 import type { SlotCycle, SlotEdge } from '../analyze/cycle-detection.js';
 export type StepStatus = 'pending' | 'complete' | 'failed' | 'interrupted';
-export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'map tokens' | 'import';
+export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'map tokens' | 'fetch existing entities' | 'import';
 export interface SessionRow {
     id: string;
     name: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.32.1-dev-build-f054f94.0",
+  "version": "2.32.1-dev-build-47de682.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -39,8 +39,8 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-cli-v2": "2.32.1-dev-build-f054f94.0",
-    "@contentful/experience-design-system-types": "2.32.1-dev-build-f054f94.0"
+    "@contentful/experience-design-system-cli-v2": "2.32.1-dev-build-47de682.0",
+    "@contentful/experience-design-system-types": "2.32.1-dev-build-47de682.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
@@ -52,9 +52,9 @@
     "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16",
-    "@contentful/experience-design-system-client": "2.32.1-dev-build-f054f94.0",
-    "@contentful/experience-design-system-generation": "2.32.1-dev-build-f054f94.0",
-    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-f054f94.0"
+    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-47de682.0",
+    "@contentful/experience-design-system-generation": "2.32.1-dev-build-47de682.0",
+    "@contentful/experience-design-system-client": "2.32.1-dev-build-47de682.0"
   },
   "repository": {
     "type": "git",