@contentful/experience-design-system-cli 2.32.1-dev-build-7d7e3cc.0 → 2.32.1-dev-build-81eb804.0

package/dist/package.json

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

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

@@ -0,0 +1,13 @@
+import type { CmaClientOptions } from '../../interfaces/clients/cma-client-options.js';
+import type { ExistingEntitiesResponse } from '../../interfaces/responses/existing-entities-response.js';
+export declare class CmaApiClient {
+    private host;
+    private token;
+    private spaceId;
+    private environmentId;
+    constructor(opts: CmaClientOptions);
+    private base;
+    validateToken(): Promise<void>;
+    listExistingEntities(): Promise<ExistingEntitiesResponse>;
+    private listAll;
+}

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

@@ -0,0 +1,47 @@
+import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse, BreakingChange } from '@contentful/experience-design-system-types';
+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 {
+    private host;
+    private token;
+    private spaceId;
+    private environmentId;
+    private retry;
+    private lastRequestId?;
+    getLastRequestId(): string | undefined;
+    private noteRequestId;
+    constructor(opts: EdsiClientOptions);
+    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?: 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

@@ -27,6 +27,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

@@ -12576,7 +12576,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(/\/+$/, "");
 }
@@ -12599,8 +12599,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";
@@ -12807,7 +12807,55 @@ 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/edsi-client.ts
 function defaultSleep(delayMs) {
   return new Promise((resolve27) => setTimeout(resolve27, delayMs));
 }
@@ -12890,48 +12938,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();
     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",
@@ -12940,7 +12960,7 @@ ${trimmed}`;
       "validation_narrowed"
     ]);
     SLOT_BREAKING_REASONS = /* @__PURE__ */ new Set(["slot_removed", "slot_allowed_components_narrowed"]);
-    ImportApiClient = class {
+    EdsiApiClient = class {
       host;
       token;
       spaceId;
@@ -13206,6 +13226,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, "");
@@ -14194,6 +14223,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, {
@@ -14809,7 +14846,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,
@@ -15549,7 +15586,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) {
@@ -16571,7 +16608,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";
@@ -16634,7 +16671,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) {
@@ -24116,7 +24153,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) => {
@@ -28327,7 +28364,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,
@@ -28401,7 +28438,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,
@@ -28563,7 +28600,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,
@@ -34308,14 +34345,72 @@ 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_url();
+init_http();
+init_api_error();
+var CMA_PAGE_LIMIT = 100;
+var CmaApiClient = 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}`;
+  }
+  async validateToken() {
+    const url = `${this.host}/users/me`;
+    const res = await request(url, { token: this.token });
+    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 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();
@@ -34423,11 +34518,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;
@@ -35379,7 +35529,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(
@@ -35714,6 +35867,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-7d7e3cc.0",
+  "version": "2.32.1-dev-build-81eb804.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-7d7e3cc.0",
-    "@contentful/experience-design-system-types": "2.32.1-dev-build-7d7e3cc.0"
+    "@contentful/experience-design-system-cli-v2": "2.32.1-dev-build-81eb804.0",
+    "@contentful/experience-design-system-types": "2.32.1-dev-build-81eb804.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-7d7e3cc.0",
-    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-7d7e3cc.0",
-    "@contentful/experience-design-system-generation": "2.32.1-dev-build-7d7e3cc.0"
+    "@contentful/experience-design-system-client": "2.32.1-dev-build-81eb804.0",
+    "@contentful/experience-design-system-generation": "2.32.1-dev-build-81eb804.0",
+    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-81eb804.0"
   },
   "repository": {
     "type": "git",