@contentful/experience-design-system-cli 2.32.1-dev-build-b78fe18.0 → 2.32.1-dev-build-d28a6f8.0

package/dist/src/session/cache-keys.d.ts

@@ -19,4 +19,4 @@ export declare function hashFile(filePath: string): Promise<string>;
  * @param model — resolved model for this run (undefined resolves to the agent's default)
  * @param skillPathOverride — optional absolute/relative path to a custom prompt
  */
-export declare function hashPromptForSkill(skill: Skill, agent: string, model: string | undefined, skillPathOverride?: string): Promise<string>;
+export declare function hashPromptForSkill(skill: Skill, agent: string, model: string | undefined, skillPathOverride?: string, extraInputs?: string[]): Promise<string>;

package/dist/src/session/core/cdf/server-type-map.d.ts

@@ -0,0 +1,3 @@
+export type CdfCategory = 'content' | 'design' | 'state';
+export declare function mapServerTypeToCdfType(serverType: string): string;
+export declare function resolveCdfCategory(serverCategory: string | null | undefined, propName: string, contentProps: Set<string>, designProps: Set<string>): CdfCategory;

package/dist/src/session/core/components/component-id.d.ts

@@ -0,0 +1 @@
+export declare function deriveComponentId(name: string, source: string): string;

package/dist/src/session/core/components/input-hash.d.ts

@@ -0,0 +1,5 @@
+import type { RawComponentDefinition } from '../../../types.js';
+export type RawComponentForHash = RawComponentDefinition & {
+    component_id?: string;
+};
+export declare function computeComponentInputHash(component: RawComponentForHash): string;

package/dist/src/session/core/shared/group-by.d.ts

@@ -0,0 +1 @@
+export declare function groupBy<T>(items: T[], key: (item: T) => string): Map<string, T[]>;

package/dist/src/session/core/tokens/input-hash.d.ts

@@ -0,0 +1 @@
+export declare function computeTokenInputHash(rawTokenContent: string): string;

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

@@ -4,6 +4,12 @@ import type { CDFComponentEntry, DTCGTokenEntry, DTCGTokenGroup } from '@content
 import type { ToolCall, TokenToolCall, ComponentSourceRef } from '@contentful/experience-design-system-generation';
 import type { ComponentTypeSummary } from '@contentful/experience-design-system-types';
 import type { SlotCycle, SlotEdge } from '../analyze/cycle-detection.js';
+import { type MatchHints as SessionMatchHints } from './repositories/sessions/read.js';
+import { type SessionResolution } from './services/session-resolver.js';
+export { deriveComponentId } from './core/components/component-id.js';
+export { computeComponentInputHash } from './core/components/input-hash.js';
+export { computeTokenInputHash } from './core/tokens/input-hash.js';
+export { mapServerTypeToCdfType, resolveCdfCategory } from './core/cdf/server-type-map.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' | 'fetch existing entities' | 'import';
 export interface SessionRow {
@@ -86,17 +92,9 @@ export interface ComponentRationale {
 }
 export declare function loadComponentRationale(db: DatabaseSync, sessionId: string, componentName: string): ComponentRationale | null;
 export declare function applyToolCalls(db: DatabaseSync, sessionId: string, componentId: string, componentName: string, calls: ToolCall[], incomingWarnings: string[]): ApplyToolCallsResult;
-export interface MatchHints {
-    command: CommandName;
-    inputPath?: string;
-    outDir?: string;
-}
-export interface SessionResolution {
-    sessionId: string;
-    isNew: boolean;
-    isResumed: boolean;
-}
-export declare function getOrCreateSession(db: DatabaseSync, sessionFlag: string | undefined, sessionName: string | undefined, _hints: MatchHints): SessionResolution;
+export type MatchHints = SessionMatchHints;
+export type { SessionResolution };
+export declare function getOrCreateSession(db: DatabaseSync, sessionFlag: string | undefined, sessionName: string | undefined, hints: MatchHints): SessionResolution;
 export declare function createStep(db: DatabaseSync, sessionId: string, command: CommandName, inputs: Record<string, string>): number;
 export declare function updateStep(db: DatabaseSync, stepId: number, status: 'complete' | 'failed', outputs: Record<string, string>, error?: string): void;
 export declare function storeRawComponents(db: DatabaseSync, sessionId: string, components: RawComponentDefinition[], options?: {
@@ -170,8 +168,6 @@ export interface CacheEntry {
     createdAt: string;
     updatedAt: string;
 }
-export declare function computeComponentInputHash(component: RawComponentWithId): string;
-export declare function computeTokenInputHash(rawTokenContent: string): string;
 export declare function computeMapTokensInputHash(db: DatabaseSync, sessionId: string, componentSourceRefs?: readonly ComponentSourceRef[]): string;
 export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: CacheEntityType, entityId: string, promptHash?: string): CacheEntry | null;
 export declare function lookupCacheByEntity(db: DatabaseSync, entityType: CacheEntityType, entityId: string): CacheEntry | null;

package/dist/src/session/repositories/sessions/read.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { CommandName } from '../../db.js';
+export interface MatchHints {
+    command: CommandName;
+    inputPath?: string;
+    outDir?: string;
+}
+export declare function findSession(db: DatabaseSync, sessionId: string): {
+    id: string;
+} | null;
+export declare function findLatestSessionForCommand(db: DatabaseSync, command: CommandName): string | null;

package/dist/src/session/repositories/sessions/write.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare function createSession(db: DatabaseSync, id: string, name: string | null, timestamp: string): void;
+export declare function touchSession(db: DatabaseSync, sessionId: string, timestamp: string): void;

package/dist/src/session/repositories/steps/read.d.ts

@@ -0,0 +1,2 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare function findStepSessionId(db: DatabaseSync, stepId: number): string | null;

package/dist/src/session/repositories/steps/write.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { CommandName } from '../../db.js';
+export declare function markPendingStepsInterrupted(db: DatabaseSync, sessionId: string, command: CommandName, timestamp: string): void;
+export declare function insertPendingStep(db: DatabaseSync, sessionId: string, command: CommandName, inputs: Record<string, string>, timestamp: string): number;
+export declare function updateStepResult(db: DatabaseSync, stepId: number, status: 'complete' | 'failed', outputs: Record<string, string>, error: string | null, timestamp: string): void;

package/dist/src/session/services/session-resolver.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { CommandName } from '../db.js';
+export interface MatchHints {
+    command: CommandName;
+    inputPath?: string;
+    outDir?: string;
+}
+export interface SessionResolution {
+    sessionId: string;
+    isNew: boolean;
+    isResumed: boolean;
+}
+/**
+ * Resolve which session the caller should operate on:
+ *   - `sessionFlag === 'new'` or undefined → create a new session
+ *   - explicit id → verify it exists and reuse it (throws if missing)
+ *
+ * `MatchHints` is accepted for signature stability (callers pass it today) but
+ * is not currently used — hint-based session resumption was removed upstream.
+ */
+export declare function resolveSession(db: DatabaseSync, sessionFlag: string | undefined, sessionName: string | undefined, _hints: MatchHints): SessionResolution;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.32.1-dev-build-b78fe18.0",
+  "version": "2.32.1-dev-build-d28a6f8.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -40,8 +40,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-b78fe18.0",
-    "@contentful/experience-design-system-types": "2.32.1-dev-build-b78fe18.0"
+    "@contentful/experience-design-system-cli-v2": "2.32.1-dev-build-d28a6f8.0",
+    "@contentful/experience-design-system-types": "2.32.1-dev-build-d28a6f8.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
@@ -53,9 +53,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-b78fe18.0",
-    "@contentful/experience-design-system-generation": "2.32.1-dev-build-b78fe18.0",
-    "@contentful/experience-design-system-client": "2.32.1-dev-build-b78fe18.0"
+    "@contentful/experience-design-system-client": "2.32.1-dev-build-d28a6f8.0",
+    "@contentful/experience-design-system-generation": "2.32.1-dev-build-d28a6f8.0",
+    "@contentful/experience-design-system-extraction": "2.32.1-dev-build-d28a6f8.0"
   },
   "repository": {
     "type": "git",

package/skills/generate-components.md

@@ -549,3 +549,30 @@ If you are genuinely uncertain about every prop, classify each as:
 An imperfect classification is infinitely better than no classification. That is
 about **classifying a prop rather than dropping it** — it is not a licence to
 invent a `values` list. The uncertain answer is `cdf_type: "string"`, every time.
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing components in the target Contentful space" JSON block with a `likelyMatch` (a fuzzy-matched space component that likely corresponds to the codebase component you're classifying), an `otherComponents` list, and a rolled-up token summary. Use it to align your classifications with what the customer already has.
+
+### When `likelyMatch` is present — align rename intent + categories + slot names
+
+Your goal is **consistency**: the customer will see the diff between what you propose and what already exists, and every unnecessary category flip or slot-shape mismatch becomes review friction.
+
+1. **Prop names**: `classify_prop.prop` MUST always be the codebase prop name — that's the DB lookup key. When a codebase prop looks like it corresponds to an existing space prop (e.g. codebase `kind` ↔ space `variant`, codebase `text` ↔ space `label`), keep `prop` as the codebase name and put the alignment note in `reason`, e.g. `"looks like existing space prop 'variant' — customer may want to reconcile at review"`. Never rewrite `prop` itself; reconciliation happens downstream, not in this tool call.
+2. **Categories**: match the space's category (`design` / `content`) for equivalent props, even if you'd normally categorize differently. Note the alignment in `reason`.
+3. **Slot names**: match slot IDs / names when the shape is equivalent.
+4. **Enum values**: never invent new values to bridge a mismatch. If the codebase's enum diverges from the space's, classify against your best-effort mapping and cite the divergence in `reason` — this is a signal for human review, not a green light to rewrite the space's enum.
+5. **Never realign silently.** Every classification influenced by the `likelyMatch` MUST cite it in `reason`.
+
+### When only `otherComponents` is present (no direct match)
+
+Use the list to constrain slot `allowed_components` — do not propose a slot that accepts component types the space doesn't have.
+
+### Token binding
+
+The preamble's "Existing design tokens" section lists tokens (by name + DTCG type) already in the space.
+
+1. When classifying a `design`-category, `token`-typed prop, prefer binding to an existing token name over inventing a new one. Cite the target token in `reason`.
+2. If no existing token semantically matches, proceed with the current rules — propose a new token. The diff surfaces this for review.

package/skills/map-tokens.md

@@ -88,3 +88,15 @@ Before emitting any tool calls, verify:
 3. `token_allowed` is never empty.
 4. Every emitted list includes the prop's own default token when it has one.
 5. No list was emitted on the strength of a default alone, and none targets a prop whose type is a union of variant names.
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing design tokens in the target Contentful space" JSON block listing tokens already present in the target space (by name + DTCG type).
+
+Prefer restricting to existing tokens over proposing new ones:
+
+1. When the source has restriction evidence AND a candidate maps semantically to an existing token by name/type, favor the existing token in the emitted `token_allowed` list.
+2. Never emit a `token_allowed` entry that contradicts the "path exists verbatim" rule above — the existing-tokens block is guidance, not a substitute for the token path index. If a token appears in the existing-entities list but not in the token path index, do not use it.
+3. If none of the existing tokens fit and the source's evidence is specific, proceed as usual — the diff will surface the new proposal.

package/skills/select-components.md

@@ -222,3 +222,14 @@ TextImageCard — card with rich text and background image
 SearchInput — search field with dropdown
 {"tool":"select_component","name":"SearchInput","reason":"search UI — configurable placeholder and state"}
 ```
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing components in the target Contentful space" JSON block and a rolled-up token summary. Use them as **signal, not as a filter**. Rules:
+
+1. Never let a name overlap force a decision. Acceptance is still driven purely by "does the codebase component render visible, authorable UI?" — a name match does not auto-accept, and a name conflict does not auto-reject.
+2. When a codebase component appears to correspond to an existing space component (name overlap, semantic overlap in the description), note it in your `reason` — e.g. `"accepted; likely maps to existing space component 'Button'"`. This surfaces the mapping for downstream review.
+3. When the space is mature (many existing components, dozens of tokens) and the codebase has thin wrappers with no visible UI difference, lean harder toward rejecting the wrappers. Extra noise in a mature space is more costly than in an empty one.
+4. When no overlap exists, the acceptance decision is unchanged from the rules above.

package/dist/src/helpers/cma-client.d.ts

@@ -1,17 +0,0 @@
-import { type PlainClientAPI } from 'contentful-management';
-interface CreateCmaClientOptions {
-    cmaToken: string;
-    /**
-     * Optional CMA host override. Accepts either a full URL
-     * (`https://api.contentful.com`) or a bare hostname (`api.contentful.com`);
-     * contentful-management wants the bare form so we normalize here.
-     */
-    host?: string;
-}
-/**
- * Build a plain contentful-management client. Single place that picks the
- * `{ type: 'plain' }` overload so callers never have to think about it,
- * and normalizes host into the bare-hostname shape the SDK expects.
- */
-export declare function createCmaClient(opts: CreateCmaClientOptions): PlainClientAPI;
-export {};

package/dist/src/helpers/fetch-existing-entities.d.ts

@@ -1,16 +0,0 @@
-import { type ComponentProps, type DesignTokenProps, type PlainClientAPI } from 'contentful-management';
-export interface ExistingEntities {
-    components: ComponentProps[];
-    tokens: DesignTokenProps[];
-}
-interface FetchExistingEntitiesParams {
-    spaceId: string;
-    environmentId: string;
-}
-/**
- * Fetch all existing Components + DesignTokens for a space+env. Pagination
- * is delegated to the SDK's `fetchAll()` helper. Caller supplies the
- * pre-built plain client (see `createCmaClient()`).
- */
-export declare function fetchExistingEntities(client: PlainClientAPI, params: FetchExistingEntitiesParams): Promise<ExistingEntities>;
-export {};