@contentful/experience-design-system-cli 2.32.1-dev-build-2277e1e.0 → 2.32.1-dev-build-1c6a348.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.32.1-dev-build-2277e1e.0",
+  "version": "2.32.1-dev-build-1c6a348.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 validateToken flow that both clients need.
+ * Subclasses override validateToken() 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>;
+    validateToken(): Promise<void>;
+    protected onValidateTokenResponse(_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,44 @@
+import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse, BreakingChange } 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 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 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 EdsiApiClient extends AbstractApiClient {
+    private retry;
+    private lastRequestId?;
+    getLastRequestId(): string | undefined;
+    private noteRequestId;
+    protected onValidateTokenResponse(res: Response): void;
+    constructor(opts: EdsiClientOptions);
+    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?: PollOptions): Promise<ApplyOperationResponse>;
+}

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

@@ -0,0 +1,10 @@
+export { CmaApiClient } from './clients/cma-client.js';
+export { EdsiApiClient, DEFAULT_HOST, PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE, parsePreviewValidationErrors, sanitizeBreakingChanges, } from './clients/edsi-client.js';
+export type { PreviewValidationError } from './clients/edsi-client.js';
+export { ApiError } from '../errors/api-error.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 { 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';

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

@@ -1,68 +1,4 @@
-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, DEFAULT_HOST, PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE, parsePreviewValidationErrors, sanitizeBreakingChanges, } from '../api/clients/edsi-client.js';
+export type { PreviewValidationError } from '../api/clients/edsi-client.js';
+export { ApiError } from '../errors/api-error.js';
+export type { EdsiClientOptions as ApiClientOptions } from '../interfaces/clients/edsi-client-options.js';

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/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/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,7 +12603,7 @@ var init_src3 = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/host-utils.ts
+// packages/experience-design-system-cli/src/helpers/url.ts
 function trimTrailingSlashes(value) {
   return value.replace(/\/+$/, "");
 }
@@ -12626,8 +12626,8 @@ function toApiHost(host) {
   return `https://${normalized}`;
 }
 var DEFAULT_API_HOST, DEFAULT_CONFIGURED_HOST;
-var init_host_utils = __esm({
-  "packages/experience-design-system-cli/src/host-utils.ts"() {
+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";
@@ -12834,7 +12834,99 @@ 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/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";
+    ERROR_BODY_LOG_CAP = 16384;
+    ApiError = class extends Error {
+      constructor(message, status, body, guidance) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.guidance = guidance;
+        if (body) {
+          const trimmed = body.length > ERROR_BODY_LOG_CAP ? body.slice(0, ERROR_BODY_LOG_CAP) + "\u2026" : body;
+          this.message = `${message}
+${trimmed}`;
+        }
+      }
+      status;
+      body;
+      guidance;
+    };
+  }
+});
+
+// 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 validateToken() {
+        const url = `${this.host}/users/me`;
+        const res = await request(url, { token: this.token });
+        this.onValidateTokenResponse(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.
+      onValidateTokenResponse(_res) {
+      }
+    };
+  }
+});
+
+// packages/experience-design-system-cli/src/api/clients/edsi-client.ts
 function defaultSleep(delayMs) {
   return new Promise((resolve27) => setTimeout(resolve27, delayMs));
 }
@@ -12917,48 +13009,20 @@ 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 PREVIEW_ERROR_PREFIX, APPLY_ERROR_PREFIX, VALIDATION_FAILED_CODE, MAX_RETRY_AFTER_MS, COMPONENT_PATH_PREFIX, PROPERTY_BREAKING_REASONS, SLOT_BREAKING_REASONS, EdsiApiClient;
+var init_edsi_client = __esm({
+  "packages/experience-design-system-cli/src/api/clients/edsi-client.ts"() {
     "use strict";
     init_src3();
-    init_host_utils();
+    init_url();
     init_debug_logger();
-    init_user_agent();
+    init_http();
+    init_api_error();
+    init_abstract_api_client();
     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) {
-        super(message);
-        this.status = status;
-        this.body = body;
-        this.guidance = guidance;
-        if (body) {
-          const trimmed = body.length > ERROR_BODY_LOG_CAP ? body.slice(0, ERROR_BODY_LOG_CAP) + "\u2026" : body;
-          this.message = `${message}
-${trimmed}`;
-        }
-      }
-      status;
-      body;
-      guidance;
-    };
     COMPONENT_PATH_PREFIX = "manifest:components/";
     PROPERTY_BREAKING_REASONS = /* @__PURE__ */ new Set([
       "removed",
@@ -12967,11 +13031,7 @@ ${trimmed}`;
       "validation_narrowed"
     ]);
     SLOT_BREAKING_REASONS = /* @__PURE__ */ new Set(["slot_removed", "slot_allowed_components_narrowed"]);
-    ImportApiClient = class {
-      host;
-      token;
-      spaceId;
-      environmentId;
+    EdsiApiClient = class extends AbstractApiClient {
       retry;
       lastRequestId;
       getLastRequestId() {
@@ -12981,11 +13041,11 @@ ${trimmed}`;
         const requestId = response.headers.get("x-contentful-request-id");
         if (requestId) this.lastRequestId = requestId;
       }
+      onValidateTokenResponse(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 +13054,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();
@@ -13069,15 +13122,7 @@ ${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());
-        }
+        await super.validateToken();
         await this.checkPreflight();
       }
       // Probe the sources-api preflight endpoint to catch APS-denied users up-front,
@@ -13233,6 +13278,15 @@ ${trimmed}`;
   }
 });
 
+// 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_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 +14275,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 +14898,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,
@@ -15576,7 +15638,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 +16660,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 +16723,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 +24205,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,7 +28425,7 @@ 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,
@@ -28437,7 +28499,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 +28661,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 +34427,52 @@ 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();
+var CMA_PAGE_LIMIT = 100;
+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 +34580,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 +35594,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 +35944,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/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/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-2277e1e.0",
+  "version": "2.32.1-dev-build-1c6a348.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-2277e1e.0",
-    "@contentful/experience-design-system-types": "2.32.1-dev-build-2277e1e.0"
+    "@contentful/experience-design-system-cli-v2": "2.32.1-dev-build-1c6a348.0",
+    "@contentful/experience-design-system-types": "2.32.1-dev-build-1c6a348.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-extraction": "2.32.1-dev-build-2277e1e.0",
-    "@contentful/experience-design-system-client": "2.32.1-dev-build-2277e1e.0",
-    "@contentful/experience-design-system-generation": "2.32.1-dev-build-2277e1e.0"
+    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-1c6a348.0",
+    "@contentful/experience-design-system-generation": "2.32.1-dev-build-1c6a348.0",
+    "@contentful/experience-design-system-client": "2.32.1-dev-build-1c6a348.0"
   },
   "repository": {
     "type": "git",