@contentful/experience-design-system-cli 2.37.1-dev-build-12711902.0 → 2.37.1-dev-build-aa3ffe6f.0

package/dist/src/tui/import/steps/10-flow/flow/controller.d.ts

@@ -0,0 +1,65 @@
+import { type PreviewValidationError } from '@contentful/experience-design-system-backend-pipeline';
+import type { ImportHandoff } from '@contentful/experience-design-system-types/handoff';
+import { type PreviewDeps } from './preview.js';
+import { type PushDeps } from './push.js';
+import { type SaveDeps } from './save.js';
+import { type FlowPatch, type FlowState } from './types.js';
+/** What the flow starts from: what the earlier stages produced, and the user's saved settings. */
+export interface FlowStart {
+    handoff: ImportHandoff;
+    agent: string;
+    projectPath: string;
+    /** Where the files are saved by default. */
+    outDir: string;
+    rawTokensPath: string;
+    credentials: {
+        spaceId: string;
+        environmentId: string;
+        cmaToken: string;
+        host: string;
+    };
+    /** A custom prompt for `generate components`, shown as a warning above every step. */
+    generatePromptPath?: string;
+}
+/** The outside world the flow talks to besides the preview, push and save steps. */
+export interface FlowDeps {
+    preview: PreviewDeps;
+    push: PushDeps;
+    save: SaveDeps;
+    /** Reads the accepted components, for the cycle check at finalize. */
+    loadAcceptedComponents: (sessionId: string) => Array<{
+        key: string;
+        entry: unknown;
+    }>;
+    mkdir: (path: string) => Promise<void>;
+    detectSaveConflict: (path: string) => Promise<boolean>;
+    buildTimestampedSubdir: (path: string) => string;
+    rejectComponentsByName: (sessionId: string, names: string[]) => Promise<unknown>;
+    /** Writes one line of the wizard's step log. */
+    log: (entry: Record<string, unknown>) => void;
+    stderr: (text: string) => void;
+}
+export declare function startWizardLog(): void;
+export declare function realFlowDeps(): FlowDeps;
+/** The state the flow begins in, from what the earlier stages handed over. */
+export declare function initialFlowState(start: FlowStart): FlowState;
+/** What the log gets: the state change without the token, the document, or the whole of a large server response. */
+export declare function sanitizeForLog(partial: FlowPatch): Record<string, unknown>;
+/** The names of the components the errors are about, once each. */
+export declare function namesToSkip(errors: readonly PreviewValidationError[]): string[];
+export interface FlowController {
+    getState(): FlowState;
+    subscribe(listener: () => void): () => void;
+    finalize(accepted: number, rejected: number, unresolved: number): void;
+    submitPath(path: string): Promise<void>;
+    confirmPreview(acknowledgeBreakingChanges: boolean): void;
+    acknowledgeBreakingChanges(): void;
+    editDefinitions(): void;
+    skipValidationErrors(): Promise<void>;
+}
+/**
+ * The wizard's state machine, taken out of the screen so each transition can be tested without a terminal. It holds the
+ * state, applies the patches the steps return, and decides what runs next. It never exits the process: leaving is the
+ * screen's decision.
+ */
+export declare function createFlowController(start: FlowStart, deps: FlowDeps): FlowController;

package/dist/src/tui/import/steps/10-flow/flow/preview.d.ts

@@ -0,0 +1,56 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { ApiError, patchReviewStateWithValidationErrors, type PreviewValidationError } from '@contentful/experience-design-system-backend-pipeline';
+import { type CDFDocument, type DTCGTokenEntry, type ServerPreviewResponse } from '@contentful/experience-design-system-types';
+import type { FlowPatch, FlowState } from './types.js';
+type PreviewClient = {
+    previewImport(cdf: CDFDocument): Promise<ServerPreviewResponse>;
+};
+/** The outside world `runPreview` talks to, so each branch can be tested without a database or a network. */
+export interface PreviewDeps {
+    createClient: (options: {
+        cmaToken: string;
+        spaceId: string;
+        environmentId: string;
+        host: string;
+    }) => PreviewClient;
+    openDb: () => DatabaseSync;
+    readTokens: (path: string) => Promise<DTCGTokenEntry[]>;
+    patchReviewState: typeof patchReviewStateWithValidationErrors;
+    verboseErrors: boolean;
+}
+export declare const realPreviewDeps: () => PreviewDeps;
+export interface RunPreviewInput {
+    state: Pick<FlowState, 'credentialsSkipped'>;
+    extractSessionId: string | null;
+    tokensPath: string;
+    spaceId: string;
+    environmentId: string;
+    cmaToken: string;
+    host: string;
+    /** Set when nothing was accepted, so the document is present but empty and the server shows what would be deleted. */
+    deleteAll: boolean;
+}
+/** What to do with a 422 from the preview: show the components that failed, or fall through to the generic error. */
+type Preview422Outcome = {
+    kind: 'validation-error';
+    errors: PreviewValidationError[];
+    missingNames: string[];
+} | {
+    kind: 'unparseable';
+    message: string;
+} | {
+    kind: 'not-422';
+};
+export declare function handlePreview422(err: ApiError, extractSessionId: string | null, patchFn: PreviewDeps['patchReviewState']): Promise<Preview422Outcome>;
+/** The patch to spread into any update that leaves the validation error step, so stale errors do not linger. */
+export declare function clearedValidationErrorState(): Pick<FlowState, 'previewValidationErrors' | 'previewValidationMissingNames'>;
+/**
+ * Loads what would be pushed and asks the server what that would change. Returns the patch the wizard applied: the
+ * preview gate, a terminal "done" when nothing would change, the validation error step for a 422, or an error.
+ *
+ * It also repairs two things the server's answer can reveal: components it says would be removed that are in fact local
+ * (the review dropped their CDF), and defaults it would change. Both are re-seeded from the response, and the preview is
+ * taken again.
+ */
+export declare function runPreview(input: RunPreviewInput, deps: PreviewDeps): Promise<FlowPatch>;
+export {};

package/dist/src/tui/import/steps/10-flow/flow/push.d.ts

@@ -0,0 +1,43 @@
+import { updateRun } from '@contentful/experience-design-system-backend-pipeline';
+import { type ApplyOperationResponse, type CDFDocument, type ServerPreviewResponse } from '@contentful/experience-design-system-types';
+import type { FlowPatch, FlowState } from './types.js';
+type PushClient = {
+    applyImport(cdf: CDFDocument, options: {
+        acknowledgeBreakingChanges: boolean;
+    }): Promise<ApplyOperationResponse>;
+    pollOperation(operationId: string, options: {
+        onProgress?: (operation: ApplyOperationResponse) => void;
+    }): Promise<ApplyOperationResponse>;
+};
+/** The outside world `runPush` talks to, so each branch can be tested without a network or a run history. */
+export interface PushDeps {
+    createClient: (options: {
+        cmaToken: string;
+        spaceId: string;
+        environmentId: string;
+        host: string;
+    }) => PushClient;
+    updateRun: typeof updateRun;
+    /** Where the wizard's step log goes. A log that cannot be written is reported on stderr and never stops the push. */
+    log: (entry: Record<string, unknown>) => void;
+    warn: (message: string) => void;
+    verboseErrors: boolean;
+}
+export declare const realPushDeps: (log: PushDeps["log"]) => PushDeps;
+export interface RunPushInput {
+    state: Pick<FlowState, 'credentialsSkipped' | 'lastRunId'>;
+    cdf: CDFDocument;
+    spaceId: string;
+    environmentId: string;
+    cmaToken: string;
+    host: string;
+    acknowledgeBreakingChanges: boolean;
+    preview?: ServerPreviewResponse | null;
+}
+/**
+ * Pushes the previewed document: the checks that refuse a push that cannot work, then the apply, polling its progress,
+ * and the result as the counts the done screen shows. `onPatch` receives the progress while it polls; the returned patch
+ * is where the flow ends up.
+ */
+export declare function runPush(input: RunPushInput, deps: PushDeps, onPatch: (patch: FlowPatch) => void): Promise<FlowPatch>;
+export {};

package/dist/src/tui/import/steps/10-flow/flow/save.d.ts

@@ -0,0 +1,50 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { appendRun, buildSourceFingerprint } from '@contentful/experience-design-system-backend-pipeline';
+import { type CDFComponentEntry, type CDFDocument, type DTCGTokenEntry } from '@contentful/experience-design-system-types';
+import type { FlowPatch, FlowState } from './types.js';
+/** How long the confirmation of a written file stays up before the flow moves on to the preview. */
+export declare const SAVE_CONFIRMATION_DELAY_MS = 1000;
+/** The document written to `components.json`: the components and tokens as one schema-valid CDF. */
+export declare function buildSavedCDF(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>, tokens: DTCGTokenEntry[], opts?: {
+    deleteAll?: boolean;
+}): CDFDocument;
+/** The outside world saving talks to, so each branch can be tested without a disk, a database or a clock. */
+export interface SaveDeps {
+    openDb: () => DatabaseSync;
+    readTokens: (path: string) => Promise<DTCGTokenEntry[]>;
+    writeFile: (path: string, contents: string) => Promise<void>;
+    appendRun: typeof appendRun;
+    buildSourceFingerprint: typeof buildSourceFingerprint;
+    sleep: (ms: number) => Promise<void>;
+    warn: (message: string) => void;
+}
+export declare const realSaveDeps: () => SaveDeps;
+export interface WriteFilesInput {
+    extractSessionId: string | null;
+    outDir: string;
+    tokenSessionId?: string | null;
+    tokensPath?: string;
+    skipGate?: boolean;
+    allowEmpty?: boolean;
+}
+/**
+ * Writes `components.json` to `outDir`. Returns the patch for the step after (the print gate, or nothing when the save
+ * is part of a push and goes straight on), or an error patch when the document could not be built or written.
+ * `onPatch` receives the "printing" step while it works.
+ */
+export declare function runPrintFiles(input: WriteFilesInput, deps: SaveDeps, onPatch: (patch: FlowPatch) => void): Promise<{
+    ok: true;
+    patch: FlowPatch;
+} | {
+    ok: false;
+    patch: FlowPatch;
+}>;
+export interface RecordRunInput {
+    state: Pick<FlowState, 'extractSessionId' | 'rawTokensPath' | 'projectPath' | 'generatedAcceptedCount' | 'generatedCount' | 'tokenCount' | 'tokenSessionId' | 'tokensPath' | 'agent' | 'generateSessionId'>;
+    savePath: string;
+}
+/** Records the run, so it can be found and pushed later. A run that cannot be recorded is warned about, never fatal. */
+export declare function recordRun(input: RecordRunInput, deps: SaveDeps): Promise<string | null>;

package/dist/src/tui/import/steps/10-flow/flow/screen.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { FlowController } from './controller.js';
+import type { FlowState } from './types.js';
+interface FlowScreenProps {
+    state: FlowState;
+    controller: FlowController;
+    livePreview?: boolean;
+    generatePromptPath?: string;
+    /** Leaves the import with the exit code the wizard would have exited with. */
+    onExit: (exitCode: number) => void;
+}
+/** How many steps the import has, as the wizard counted them. */
+export declare function totalStepsFor(state: Pick<FlowState, 'tokensPath' | 'rawTokensPath' | 'mapTokensEligible'>): number;
+/** Whether the preview gate offers "[e] Edit definitions": only when the document has components to edit. */
+export declare function canEditFromPreview(cdf: FlowState['cdf']): boolean;
+export declare function FlowScreen({ state, controller, livePreview, generatePromptPath, onExit, }: FlowScreenProps): React.ReactElement;
+export {};

package/dist/src/tui/import/steps/10-flow/flow/types.d.ts

@@ -0,0 +1,71 @@
+import type { CDFDocument, ServerPreviewResponse } from '@contentful/experience-design-system-types';
+import type { PreviewValidationError } from '@contentful/experience-design-system-backend-pipeline';
+import type { PushProgress } from '../support/push-progress.js';
+/**
+ * The steps of the import after the review, as the wizard had them. The ones that came before (credentials, extraction,
+ * the scope gate, generation) are v2 stages of their own now.
+ */
+type FlowStep = 'final-review' | 'previewing' | 'preview-gate' | 'pushing' | 'path-prompt' | 'printing' | 'print-gate' | 'done' | 'error' | 'preview-validation-error';
+export type PushResult = {
+    componentTypes: {
+        created: number;
+        updated: number;
+        removed: number;
+        failed: number;
+    };
+    designTokens: {
+        created: number;
+        updated: number;
+        removed: number;
+        failed: number;
+    };
+    summary?: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+    failures?: Array<{
+        entityType: string;
+        entityId: string;
+        message: string;
+    }>;
+};
+/** Everything the flow keeps between steps. The same fields the wizard kept, minus those only the early stages used. */
+export type FlowState = {
+    step: FlowStep;
+    agent: string;
+    projectPath: string;
+    outDir: string;
+    rawTokensPath: string;
+    tokensPath: string;
+    tokenSessionId: string | null;
+    tokenCount: number;
+    extractSessionId: string | null;
+    generateSessionId: string | null;
+    generatedCount: number;
+    generatedAcceptedCount: number;
+    componentsPath: string;
+    spaceId: string;
+    environmentId: string;
+    cmaToken: string;
+    host: string;
+    serverPreview: ServerPreviewResponse | null;
+    cdf: CDFDocument | null;
+    pushProgress: PushProgress;
+    pushResult: PushResult;
+    errorStep: string;
+    errorMessage: string;
+    errorAllowCredentialRetry: boolean;
+    errorAllowBreakingChangeAcknowledgment: boolean;
+    previewValidationErrors: PreviewValidationError[];
+    previewValidationMissingNames: string[];
+    mapTokensEligible: boolean | null;
+    credentialsSkipped: boolean;
+    lastRunId: string | null;
+    finalizeErrorBanner: string | null;
+    finalReviewPassed: boolean;
+};
+/** A change to the state. The steps of the flow return these instead of changing the state themselves. */
+export type FlowPatch = Partial<FlowState>;
+export declare const EMPTY_PUSH_RESULT: PushResult;
+export {};

package/dist/src/tui/import/steps/10-flow/flow/use-flow.d.ts

@@ -0,0 +1,9 @@
+import { type FlowController, type FlowDeps, type FlowStart } from './controller.js';
+/**
+ * The flow for a start, once. `start` is undefined until the generation stage has finished, so the hook can be called
+ * unconditionally; the step log is started with the controller, as the wizard started it with its first render.
+ */
+export declare function useFlow(start: FlowStart | undefined, deps?: () => FlowDeps): {
+    controller: FlowController;
+    state: ReturnType<FlowController['getState']>;
+} | undefined;

package/{legacy/dist/src/import/tui/steps → dist/src/tui/import/steps/10-flow/screens}/PushingStep.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { PushProgress } from '../push-progress.js';
+import type { PushProgress } from '../support/push-progress.js';
 type PushingStepProps = {
     stepNumber: number;
     totalSteps: number;

package/{legacy/dist/src/import/tui/steps → dist/src/tui/import/steps/10-flow/screens}/WizardPreviewStep.d.ts

@@ -6,7 +6,6 @@ export interface PreviewDiffLine {
     text: string;
 }
 export declare function buildPreviewSummaryLines(preview: ServerPreviewResponse): PreviewDiffLine[];
-export declare function buildPreviewDiffLines(preview: ServerPreviewResponse): PreviewDiffLine[];
 type WizardPreviewStepProps = {
     preview: ServerPreviewResponse;
     spaceId: string;

package/dist/src/tui/import/steps/10-flow/support/contentful-urls.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared Contentful webapp URL builders.
+ *
+ * This module centralizes the formatter so the wizard and `apply` emit
+ * the same URL shape.
+ */
+type PostPushView = 'components' | 'design_tokens';
+export interface BuildPostPushUrlInput {
+    host: string;
+    spaceId: string;
+    environmentId: string;
+    view?: PostPushView;
+}
+export declare function buildPostPushUrl({ host, spaceId, environmentId, view }: BuildPostPushUrlInput): string;
+export {};

package/{legacy/dist/src/import/tui → dist/src/tui/import/steps/10-flow/support}/wizard-state-transitions.d.ts

@@ -1,16 +1,3 @@
-export declare function shouldGenerateAfterScopeGate(opts: {
-    acceptedCount: number;
-}): boolean;
-export declare function shouldGenerateAfterCredentialsValidated(opts: {
-    acceptedCount: number;
-}): boolean;
-export declare function shouldSkipFinalReviewAfterCredentials(state: {
-    generateSessionId: string | null;
-    finalReviewPassed: boolean;
-}): boolean;
-export declare function resolveNoCacheForGenerate(opts: {
-    cliNoCache: boolean;
-}): boolean;
 export declare function shouldBypassPreview(state: {
     credentialsSkipped: boolean;
 }): boolean;

package/dist/src/tui/import/steps/10-flow/theme.d.ts

@@ -0,0 +1,13 @@
+export declare const PALETTE: {
+    readonly link: "#58A6FF";
+    readonly info: "#1773EB";
+    readonly success: "#00C459";
+    readonly error: "#E44F20";
+    readonly warning: "#FFDA00";
+    readonly muted: "#8B8D91";
+    readonly border: "#C4D1DE";
+    readonly inverse: "#FFFFFF";
+};
+export declare const INK_UI_THEME: {
+    components: Record<string, import("@inkjs/ui").ComponentTheme>;
+};

package/dist/src/tui/import/steps/preview-validation-error/logic.d.ts

@@ -0,0 +1,12 @@
+export interface PreviewValidationError {
+    componentName: string;
+    path: string;
+    message: string;
+}
+export declare function failedComponentNames(errors: readonly PreviewValidationError[]): string[];
+export declare function matchedComponentNames(errors: readonly PreviewValidationError[], missingNames: readonly string[]): string[];
+export declare function formatErrorLine(error: PreviewValidationError): string;
+export declare function formatErrorLines(errors: readonly PreviewValidationError[]): string;
+export declare function missingNote(missingNames: readonly string[]): string;
+export declare function contextText(errors: readonly PreviewValidationError[], missingNames: readonly string[]): string;
+export declare function skipLabel(matchedNames: readonly string[]): string;

package/dist/src/tui/import/steps/preview-validation-error/screen.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { type PreviewValidationError } from './logic.js';
+interface PreviewValidationErrorScreenProps {
+    errors: readonly PreviewValidationError[];
+    missingNames: readonly string[];
+    onEdit: () => void;
+    onSkip: () => void;
+    onQuit: () => void;
+}
+export declare function PreviewValidationErrorScreen({ errors, missingNames, onEdit, onSkip, onQuit, }: PreviewValidationErrorScreenProps): React.ReactElement;
+export {};