@contentful/experience-design-system-cli 2.2.1

package/dist/src/analyze/select/tui/hooks/useSession.d.ts

@@ -0,0 +1,19 @@
+import type { ReviewSessionPaths, ReviewSessionSnapshot } from '../../types.js';
+type UseSessionInput = {
+    sessionId: string;
+    artifactsRoot: string;
+    reviewRoot?: string;
+};
+type UseSessionResult = {
+    session: ReviewSessionSnapshot | null;
+    paths: ReviewSessionPaths | null;
+    loading: boolean;
+    error: string | null;
+    saveState: (updatedSession: ReviewSessionSnapshot) => Promise<void>;
+    appendEvent: (event: {
+        type: string;
+        payload: Record<string, unknown>;
+    }) => Promise<void>;
+};
+export declare function useSession({ sessionId, artifactsRoot, reviewRoot }: UseSessionInput): UseSessionResult;
+export {};

package/dist/src/analyze/select/tui/hooks/useSession.js

@@ -0,0 +1,52 @@
+import { useEffect, useState } from 'react';
+import { loadReviewInput } from '../../parser.js';
+import { appendReviewEvent, ensureRefineSession, getRefineSessionPaths, saveReviewState } from '../../persistence.js';
+import { openPipelineDb, loadRawComponents } from '../../../../session/db.js';
+export function useSession({ sessionId, artifactsRoot, reviewRoot }) {
+    const [state, setState] = useState({ session: null, paths: null, loading: true, error: null });
+    useEffect(() => {
+        async function load() {
+            const db = openPipelineDb();
+            let rawComponents;
+            try {
+                rawComponents = loadRawComponents(db, sessionId);
+            }
+            finally {
+                db.close();
+            }
+            const initialSnapshot = await loadReviewInput(rawComponents, { reviewRoot });
+            const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+            const session = await ensureRefineSession(sessionId, artifactsRoot, initialSnapshot);
+            const isResume = session.components.some((c) => c.status !== 'needs-review');
+            await appendReviewEvent(paths.eventsPath, {
+                type: isResume ? 'session_resumed' : 'session_started',
+                payload: { componentCount: session.components.length },
+            });
+            setState({ session, paths, loading: false, error: null });
+        }
+        load().catch((err) => setState({
+            session: null,
+            paths: null,
+            loading: false,
+            error: String(err),
+        }));
+    }, []);
+    const saveState = async (updatedSession) => {
+        if (!state.paths)
+            return;
+        await saveReviewState(state.paths.statePath, updatedSession);
+    };
+    const appendEvent = async (event) => {
+        if (!state.paths)
+            return;
+        await appendReviewEvent(state.paths.eventsPath, event);
+    };
+    return {
+        session: state.session,
+        paths: state.paths,
+        loading: state.loading,
+        error: state.error,
+        saveState,
+        appendEvent,
+    };
+}

package/dist/src/analyze/select/tui/hooks/useUndo.d.ts

@@ -0,0 +1,8 @@
+export type UseUndoResult<T> = {
+    current: T;
+    push: (next: T) => void;
+    undo: () => void;
+    canUndo: boolean;
+    clear: () => void;
+};
+export declare function useUndo<T>(initial: T, maxSize?: number): UseUndoResult<T>;

package/dist/src/analyze/select/tui/hooks/useUndo.js

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+export function useUndo(initial, maxSize = 50) {
+    const [stack, setStack] = useState([]);
+    const [current, setCurrent] = useState(initial);
+    return {
+        current,
+        push: (next) => {
+            setStack((prev) => {
+                const newStack = [...prev, current];
+                return newStack.length > maxSize ? newStack.slice(1) : newStack;
+            });
+            setCurrent(next);
+        },
+        undo: () => {
+            setStack((prev) => {
+                if (prev.length === 0)
+                    return prev;
+                const newStack = prev.slice(0, -1);
+                setCurrent(prev[prev.length - 1]);
+                return newStack;
+            });
+        },
+        canUndo: stack.length > 0,
+        clear: () => setStack([]),
+    };
+}

package/dist/src/analyze/select/types.d.ts

@@ -0,0 +1,46 @@
+import type { RawComponentDefinition } from '../../types.js';
+export type PreviewAnnotation = 'new' | 'changed' | 'removed' | 'breaking';
+export type ReviewComponentStatus = 'needs-review' | 'reviewed' | 'accepted' | 'rejected';
+export type ReviewComponentRecord = {
+    id: string;
+    name: string;
+    resolvedSourcePath: string;
+    sourceCode: string | null;
+    originalProposal: RawComponentDefinition;
+    editedProposal: RawComponentDefinition;
+    status: ReviewComponentStatus;
+};
+export type ReviewComponentDetail = {
+    id: string;
+    name: string;
+    originalProposal: RawComponentDefinition;
+    editedProposal: RawComponentDefinition;
+    status: ReviewComponentStatus;
+};
+export type ReviewComponentSummary = {
+    id: string;
+    name: string;
+    status: ReviewComponentStatus;
+    previewAnnotation?: PreviewAnnotation;
+};
+export type ReviewSessionSnapshot = {
+    components: ReviewComponentRecord[];
+};
+export type ReviewSessionDetail = {
+    components: ReviewComponentDetail[];
+};
+export type ReviewSessionSummary = {
+    components: ReviewComponentSummary[];
+};
+export type ReviewEvent = {
+    type: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+};
+export type ReviewSessionPaths = {
+    sessionDir: string;
+    eventsPath: string;
+    statePath: string;
+};
+export declare function createReviewSessionSummary(session: ReviewSessionSnapshot): ReviewSessionSummary;
+export declare function createReviewSessionDetail(session: ReviewSessionSnapshot): ReviewSessionDetail;

package/dist/src/analyze/select/types.js

@@ -0,0 +1,20 @@
+export function createReviewSessionSummary(session) {
+    return {
+        components: session.components.map((component) => ({
+            id: component.id,
+            name: component.name,
+            status: component.status,
+        })),
+    };
+}
+export function createReviewSessionDetail(session) {
+    return {
+        components: session.components.map((component) => ({
+            id: component.id,
+            name: component.name,
+            originalProposal: component.originalProposal,
+            editedProposal: component.editedProposal,
+            status: component.status,
+        })),
+    };
+}

package/dist/src/analyze/select-agent/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerAnalyzeSelectAgentCommand(program: Command): void;

package/dist/src/analyze/select-agent/command.js

@@ -0,0 +1,208 @@
+import { openPipelineDb, loadRawComponents, createStep, updateStep } from '../../session/db.js';
+import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState, } from '../select/persistence.js';
+import { loadReviewInput } from '../select/parser.js';
+import { buildPrompt } from '../../generate/prompt-builder.js';
+import { parseSelectToolCallLines, runAgent } from '../../generate/agent-runner.js';
+import { OutputFormatter, c } from '../../output/format.js';
+const VALID_AGENTS = new Set(['claude', 'codex', 'opencode', 'cursor']);
+const DEFAULT_TIMEOUT_MS = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 3 * 60 * 1000);
+const DEFAULT_CONCURRENCY = 5;
+function resolveSessionId(sessionFlag) {
+    if (sessionFlag)
+        return sessionFlag;
+    const db = openPipelineDb();
+    try {
+        const row = db
+            .prepare(`SELECT s.id FROM sessions s
+         JOIN steps st ON st.session_id = s.id
+         WHERE st.command = 'analyze extract'
+           AND st.status = 'complete'
+         ORDER BY st.started_at DESC
+         LIMIT 1`)
+            .get();
+        if (!row) {
+            process.stderr.write('Error: no completed analyze extract session found. Run analyze extract first, or pass --session <id>.\n');
+            process.exit(1);
+        }
+        return row.id;
+    }
+    finally {
+        db.close();
+    }
+}
+function buildComponentData(component) {
+    return {
+        name: component.name,
+        source: component.source,
+        framework: component.framework,
+        propCount: component.props.length,
+        slotCount: component.slots.length,
+        propNames: component.props.slice(0, 8).map((p) => p.name),
+        props: component.props,
+        slots: component.slots,
+    };
+}
+async function selectOneComponent(agent, model, component, index, total, verbose) {
+    const prompt = await buildPrompt({
+        skill: 'select',
+        mode: 'autonomous',
+        rawComponentsInline: JSON.stringify([buildComponentData(component)], null, 2),
+        outDir: process.cwd(),
+    });
+    const pos = c.dim(`[${index + 1}/${total}]`);
+    let outputBuf = '';
+    const formatter = new OutputFormatter(verbose, (s) => {
+        outputBuf += s;
+    });
+    const result = await runAgent({
+        agent,
+        model,
+        prompt,
+        interactive: false,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        onOutput: (chunk) => formatter.push(chunk),
+    });
+    formatter.flush();
+    process.stderr.write(`  ${pos}  ${c.bold(component.name)}\n${outputBuf}`);
+    if (result.timedOut) {
+        return { componentName: component.name, decision: null, failed: true, error: 'timed out' };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            componentName: component.name,
+            decision: null,
+            failed: true,
+            error: `agent exited with code ${result.exitCode}`,
+        };
+    }
+    const { calls, warnings } = parseSelectToolCallLines(result.stdout);
+    if (warnings.length > 0) {
+        for (const w of warnings)
+            process.stderr.write(`  ${c.yellow('⚠')}  ${component.name}: ${w}\n`);
+    }
+    const call = calls.find((call) => call.name === component.name) ?? calls[0];
+    if (!call) {
+        return {
+            componentName: component.name,
+            decision: null,
+            failed: true,
+            error: 'agent produced no tool call for this component',
+        };
+    }
+    const decision = call.tool === 'select_component' ? 'accepted' : 'rejected';
+    return { componentName: component.name, decision, reason: call.reason, failed: false };
+}
+async function selectAllComponents(agent, model, components, verbose) {
+    const concurrency = Number(process.env.EDS_GENERATE_CONCURRENCY ?? DEFAULT_CONCURRENCY);
+    process.stderr.write(`Validating ${c.bold(String(components.length))} component${components.length === 1 ? '' : 's'}` +
+        c.dim(`  (concurrency: ${concurrency})`) +
+        '\n');
+    const results = new Array(components.length);
+    let next = 0;
+    async function worker() {
+        while (next < components.length) {
+            const i = next++;
+            results[i] = await selectOneComponent(agent, model, components[i], i, components.length, verbose);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, components.length) }, worker));
+    return results;
+}
+export function registerAnalyzeSelectAgentCommand(program) {
+    program
+        .command('select-agent')
+        .description('Use an AI agent to select components for Contentful Experience Orchestration')
+        .option('--session <id>', 'Session ID from analyze extract (defaults to most recent)')
+        .option('--project-root <path>', 'Project root for resolving component source files')
+        .requiredOption('--agent <name>', 'Agent to use: claude, codex, opencode, cursor')
+        .option('--model <name>', 'Model to use (defaults to a small/fast model per agent)')
+        .option('--verbose', 'Show full agent output including reasoning text')
+        .option('--dry-run', 'Print the prompt for the first component without invoking the agent')
+        .action(async (opts) => {
+        if (!VALID_AGENTS.has(opts.agent)) {
+            process.stderr.write(`Error: unknown agent '${opts.agent}'. Accepted values: claude, codex, opencode, cursor\n`);
+            process.exit(1);
+            return;
+        }
+        const agent = opts.agent;
+        const sessionId = resolveSessionId(opts.session);
+        const db = openPipelineDb();
+        let rawComponents;
+        try {
+            rawComponents = loadRawComponents(db, sessionId);
+        }
+        finally {
+            db.close();
+        }
+        if (rawComponents.length === 0) {
+            process.stderr.write(`Error: session '${sessionId}' has no raw components. Run analyze extract first.\n`);
+            process.exit(1);
+            return;
+        }
+        if (opts.dryRun) {
+            const first = rawComponents[0];
+            const prompt = await buildPrompt({
+                skill: 'select',
+                mode: 'autonomous',
+                rawComponentsInline: JSON.stringify([buildComponentData(first)], null, 2),
+                outDir: process.cwd(),
+            });
+            process.stdout.write(prompt + '\n');
+            process.exit(0);
+            return;
+        }
+        const selectResults = await selectAllComponents(agent, opts.model, rawComponents, opts.verbose ?? false);
+        // Build decision map from results
+        const decisions = new Map();
+        for (const r of selectResults) {
+            if (!r.failed && r.decision) {
+                decisions.set(r.componentName, r.decision);
+            }
+        }
+        // Load existing snapshot and apply decisions
+        const artifactsRoot = getRefineArtifactsRoot();
+        let snapshot;
+        try {
+            snapshot = await loadReviewInput(rawComponents, {
+                reviewRoot: opts.projectRoot,
+            });
+            snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
+        }
+        catch (error) {
+            process.stderr.write(`Error: unable to initialize select session.\n${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+            return;
+        }
+        const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+        const updated = {
+            ...snapshot,
+            components: snapshot.components.map((comp) => {
+                const decision = decisions.get(comp.name);
+                if (!decision)
+                    return comp;
+                return { ...comp, status: decision };
+            }),
+        };
+        await saveReviewState(paths.statePath, updated);
+        const accepted = updated.components.filter((comp) => comp.status === 'accepted');
+        const rejected = updated.components.filter((comp) => comp.status === 'rejected');
+        const failed = selectResults.filter((r) => r.failed);
+        if (failed.length > 0) {
+            process.stderr.write(c.red(`Failed (${failed.length}/${selectResults.length}):`) + '\n');
+            for (const f of failed) {
+                process.stderr.write(`  ${c.red('✗')}  ${f.componentName}  ${c.dim(f.error ?? 'unknown error')}\n`);
+            }
+        }
+        // Write step to DB
+        const stepDb = openPipelineDb();
+        const stepId = createStep(stepDb, sessionId, 'analyze select', { sessionId });
+        try {
+            const status = failed.length === selectResults.length ? 'failed' : 'complete';
+            updateStep(stepDb, stepId, status, { sessionId });
+        }
+        finally {
+            stepDb.close();
+        }
+        process.stderr.write(`Accepted: ${accepted.length}  Rejected: ${rejected.length}\n`);
+    });
+}

package/dist/src/analyze/tui/AnalyzeView.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+export type AnalyzeViewResult = {
+    sourceDirectory: string;
+    sessionId: string;
+    fileCount: number;
+    components: Array<{
+        name: string;
+        framework: 'react' | 'next' | 'vue' | 'astro' | 'web-component' | 'stencil';
+        propCount: number;
+        slotCount: number;
+        warnings: string[];
+    }>;
+    totalWarnings: number;
+    zeroPropComponents?: Array<{
+        name: string;
+        source: string;
+    }>;
+};
+type AnalyzeViewProps = {
+    result: AnalyzeViewResult;
+    onExit: () => void;
+};
+export declare function AnalyzeView({ result, onExit }: AnalyzeViewProps): React.ReactElement;
+export {};

package/dist/src/analyze/tui/AnalyzeView.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from 'ink';
+import { TopBar } from '../select/tui/components/TopBar.js';
+import { useImmediateInput } from '../select/tui/hooks/useImmediateInput.js';
+function truncateName(name, maxLen = 30) {
+    if (name.length <= maxLen)
+        return name;
+    return name.slice(0, maxLen - 1) + '…';
+}
+export function AnalyzeView({ result, onExit }) {
+    const [scrollOffset, setScrollOffset] = useState(0);
+    useImmediateInput((input, key) => {
+        if (input === 'q' || key.return) {
+            onExit();
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            setScrollOffset((o) => Math.max(0, o - 1));
+        }
+        else if (key.downArrow || input === 'j') {
+            setScrollOffset((o) => o + 1);
+        }
+        else if (input === 'g') {
+            setScrollOffset(0);
+        }
+        else if (input === 'G') {
+            setScrollOffset(Math.max(0, result.components.length + 10));
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(TopBar, { subcommand: "analyze", hints: [
+                    { key: '?', label: 'help' },
+                    { key: 'q', label: 'quit' },
+                ] }), _jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { children: 'Scanned ' + result.fileCount + ' source files in ' + result.sourceDirectory }), _jsx(Text, { children: 'Extracted ' + result.components.length + ' components' }), _jsx(Text, { dimColor: true, children: 'Session: ' + result.sessionId }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, children: "Components" }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components.slice(scrollOffset).map((component) => (_jsxs(Box, { children: [component.warnings.length > 0 && _jsx(Text, { color: "yellow", children: "\u26A0 " }), component.warnings.length === 0 && _jsx(Text, { children: " " }), _jsx(Text, { children: truncateName(component.name).padEnd(20) }), _jsx(Text, { dimColor: true, children: component.framework.padEnd(10) }), _jsx(Text, { children: (component.propCount + ' props').padEnd(10) }), _jsx(Text, { children: component.slotCount + ' ' + (component.slotCount === 1 ? 'slot' : 'slots') }), component.warnings.length > 0 && (_jsx(Text, { color: "yellow", children: '  ' + component.warnings.length + ' warning' + (component.warnings.length === 1 ? '' : 's') }))] }, component.name))), result.zeroPropComponents && result.zeroPropComponents.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Zero-prop components (' + result.zeroPropComponents.length + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { color: "yellow", children: '  These may be Storybook stories, context providers, or SSR utilities.' }), _jsx(Text, { color: "yellow", children: '  Review them in `analyze select` before generating.' }), _jsx(Text, { children: " " }), result.zeroPropComponents.map((c) => (_jsx(Text, { color: "yellow", children: '  ' + c.name + ' (' + c.source + ')' }, c.name)))] })), result.totalWarnings > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Warnings (' + result.totalWarnings + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
+                                .filter((c) => c.warnings.length > 0)
+                                .flatMap((c) => c.warnings.map((w) => ({ component: c.name, warning: w })))
+                                .map((w, i) => (_jsx(Text, { color: "yellow", children: '  ⚠ ' + w.component + ': ' + w.warning }, i)))] })), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: 'Run: analyze select --session ' + result.sessionId }), _jsx(Text, { children: " " })] }), _jsx(Box, { borderStyle: "single", paddingX: 1, children: _jsx(Text, { dimColor: true, children: "Press Enter or q to exit" }) })] }));
+}

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

@@ -0,0 +1,35 @@
+import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse } from '@contentful/experience-design-system-types';
+export declare const DEFAULT_HOST = "https://api.contentful.com";
+export interface ApiClientOptions {
+    host?: string;
+    cmaToken: string;
+    spaceId: string;
+    environmentId: string;
+    organizationId?: string;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export declare class ImportApiClient {
+    private host;
+    private token;
+    private spaceId;
+    private environmentId;
+    private organizationId;
+    constructor(opts: ApiClientOptions);
+    setOrganizationId(orgId: string | null): void;
+    private base;
+    private headers;
+    resolveOrganizationId(): Promise<string | null>;
+    validateEnvironment(): Promise<void>;
+    previewImport(manifest: ManifestPayload): Promise<ServerPreviewResponse>;
+    applyImport(manifest: ManifestPayload, acknowledgeBreakingChanges: boolean): Promise<ApplyOperationResponse>;
+    pollOperation(operationId: string, opts?: {
+        intervalMs?: number;
+        maxIntervalMs?: number;
+        maxAttempts?: number;
+        onProgress?: (op: ApplyOperationResponse) => void;
+    }): Promise<ApplyOperationResponse>;
+}

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

@@ -0,0 +1,143 @@
+export const DEFAULT_HOST = 'https://api.contentful.com';
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        if (body) {
+            // Append a trimmed version of the response body so callers that only
+            // log e.message don't silently swallow the server's error detail.
+            const trimmed = body.length > 1000 ? body.slice(0, 1000) + '…' : body;
+            this.message = `${message}\n${trimmed}`;
+        }
+    }
+}
+async function request(url, options) {
+    const headers = {
+        Authorization: `Bearer ${options.token}`,
+        'Content-Type': 'application/json',
+    };
+    if (options.orgId)
+        headers['x-contentful-organization-id'] = options.orgId;
+    const init = {
+        method: options.method ?? 'GET',
+        headers,
+    };
+    if (options.body)
+        init.body = options.body;
+    return fetch(url, init);
+}
+export class ImportApiClient {
+    host;
+    token;
+    spaceId;
+    environmentId;
+    organizationId;
+    constructor(opts) {
+        this.host = opts.host ?? DEFAULT_HOST;
+        this.token = opts.cmaToken;
+        this.spaceId = opts.spaceId;
+        this.environmentId = opts.environmentId;
+        this.organizationId = opts.organizationId;
+    }
+    setOrganizationId(orgId) {
+        if (orgId)
+            this.organizationId = orgId;
+    }
+    base() {
+        return `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
+    }
+    headers() {
+        const h = {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+        };
+        if (this.organizationId)
+            h['x-contentful-organization-id'] = this.organizationId;
+        return h;
+    }
+    async resolveOrganizationId() {
+        const url = `${this.host}/spaces/${this.spaceId}`;
+        const res = await request(url, { token: this.token });
+        if (res.status === 401 || res.status === 403) {
+            throw new ApiError(`space '${this.spaceId}' not found or CMA token lacks access`, res.status, await res.text());
+        }
+        if (res.status === 404) {
+            // Custom host (e.g. staging) may not expose the spaces API or the space may not
+            // exist there. Skip the org ID — the design systems API may not require it.
+            return null;
+        }
+        if (!res.ok) {
+            throw new ApiError(`unexpected error fetching space: ${res.status}`, res.status, await res.text());
+        }
+        const json = (await res.json());
+        return json.sys.organization.sys.id;
+    }
+    async validateEnvironment() {
+        const url = `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
+        const res = await request(url, { token: this.token });
+        if (res.status === 404) {
+            throw new ApiError(`environment '${this.environmentId}' not found in space '${this.spaceId}'`, 404, await res.text());
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new ApiError(`space '${this.spaceId}' not found or CMA token lacks access`, res.status, await res.text());
+        }
+        if (!res.ok) {
+            throw new ApiError(`unexpected error validating environment: ${res.status}`, res.status, await res.text());
+        }
+    }
+    async previewImport(manifest) {
+        const url = `${this.base()}/design_systems/imports/preview`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(manifest),
+        });
+        if (!res.ok) {
+            throw new ApiError(`preview failed: ${res.status}`, res.status, await res.text());
+        }
+        return (await res.json());
+    }
+    async applyImport(manifest, acknowledgeBreakingChanges) {
+        const url = `${this.base()}/design_systems/imports/apply`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ ...manifest, acknowledgeBreakingChanges }),
+        });
+        if (!res.ok) {
+            throw new ApiError(`apply failed: ${res.status}`, res.status, await res.text());
+        }
+        return (await res.json());
+    }
+    async pollOperation(operationId, opts = {}) {
+        const intervalMs = opts.intervalMs ?? 2000;
+        const maxIntervalMs = opts.maxIntervalMs ?? Math.round(intervalMs * 2.5);
+        const maxAttempts = opts.maxAttempts ?? 150;
+        const terminalStatuses = new Set(['succeeded', 'partial', 'failed']);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const url = `${this.base()}/design_systems/imports/apply/${encodeURIComponent(operationId)}`;
+            const res = await fetch(url, {
+                method: 'GET',
+                headers: this.headers(),
+            });
+            if (!res.ok) {
+                throw new ApiError(`poll failed: ${res.status}`, res.status, await res.text());
+            }
+            const op = (await res.json());
+            opts.onProgress?.(op);
+            if (terminalStatuses.has(op.sys.status)) {
+                return op;
+            }
+            if (attempt < maxAttempts - 1) {
+                const progress = maxAttempts > 1 ? attempt / (maxAttempts - 1) : 0;
+                const baseDelay = intervalMs + (maxIntervalMs - intervalMs) * progress;
+                const jitter = Math.random() * baseDelay * 0.15;
+                await new Promise((resolve) => setTimeout(resolve, baseDelay + jitter));
+            }
+        }
+        throw new Error(`Operation ${operationId} timed out after ${maxAttempts} attempts`);
+    }
+}

package/dist/src/apply/command.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+import type { DTCGTokenEntry } from '@contentful/experience-design-system-types';
+import type { ServerPreviewResponse } from '@contentful/experience-design-system-types';
+export declare function readTokensFromPath(flag: string, p: string): Promise<DTCGTokenEntry[]>;
+export declare function hasBreakingChangesWithImpact(preview: ServerPreviewResponse): boolean;
+export declare function registerApplyCommand(program: Command): void;