@contentful/experience-design-system-cli 2.16.1-dev-build-2b79e46.0 → 2.16.1-dev-build-d068963.0

package/README.md

@@ -444,7 +444,9 @@ Wizard run history is separate: `~/.config/experiences/runs.json`.
 - 80+ columns recommended for full sidebar + detail view
 - 120+ columns required to show the source code panel in `analyze select`
 - `NO_COLOR=1` suppresses all ANSI color output
-- Windows: supported via Ink v4; known limitations with older ConEmu and cmd.exe
+- Interactive views require both stdin and stdout to be TTYs and stdin to support raw mode. Read-only views fall back to plain or JSON output when those capabilities are unavailable; commands that require input stop with the relevant non-interactive flags in the error message.
+- On Windows, use Windows Terminal with PowerShell. Older ConEmu and cmd.exe hosts may not provide the raw-mode support the interactive UI needs.
+- To avoid the interactive UI, use the command's non-interactive options: `import --yes` (with credentials) or `import --no-push --auto-accept-scope`, `analyze select --select-all`, `apply select --select-all`, and `apply push --yes`.
 
 ---
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.16.1-dev-build-2b79e46.0",
+  "version": "2.16.1-dev-build-d068963.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/command.js

@@ -22,6 +22,7 @@ import { parsePromptOverrides, resolvePromptOverride } from '../lib/prompt-overr
 import { runAgent } from '../generate/agent-runner.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
 import { buildAnalyzeViewRows, partitionGlobalWarnings } from './build-analyze-view-rows.js';
+import { getInteractiveTerminalSupport } from '../lib/terminal-capabilities.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.svelte', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
     '.git',
@@ -505,7 +506,7 @@ export function registerAnalyzeCommand(program) {
             totalErrors,
             globalWarnings,
         };
-        if (process.stdout.isTTY) {
+        if (getInteractiveTerminalSupport().supported) {
             const { waitUntilExit } = render(createElement(AnalyzeView, {
                 result: analyzeResult,
                 onExit: () => process.exit(0),

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

@@ -2,6 +2,7 @@ import { access, readFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { createElement } from 'react';
 import { render } from 'ink';
+import { requireInteractiveTerminal } from '../../lib/terminal-capabilities.js';
 import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState } from './persistence.js';
 import { loadReviewInput } from './parser.js';
 import { App } from './tui/App.js';
@@ -459,10 +460,9 @@ export function registerAnalyzeEditCommand(program) {
                 `current-review-state.json=${paths.statePath}\n`);
             return;
         }
-        if (!process.stdout.isTTY) {
-            process.stderr.write('Error: analyze select requires an interactive terminal\n');
-            process.exit(1);
-        }
+        requireInteractiveTerminal({
+            alternative: 'pass `--accept-all`, `--select-all`, `--reject`, `--deselect`, `--select`, or `--patch`',
+        });
         if (process.stdout.columns !== undefined && process.stdout.columns < 60) {
             process.stderr.write(`Error: terminal too narrow (${process.stdout.columns} cols). Resize to 60+ columns.\n`);
             process.exit(1);

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

@@ -8,11 +8,18 @@ export interface ApiClientOptions {
     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;
-    constructor(message: string, status: number, body: string);
+    readonly guidance?: string | undefined;
+    constructor(message: string, status: number, body: string, guidance?: string | undefined);
 }
 export interface PreviewValidationError {
     componentName: string;
@@ -37,9 +44,11 @@ export declare class ImportApiClient {
     private token;
     private spaceId;
     private environmentId;
+    private retry;
     constructor(opts: ApiClientOptions);
     private base;
     private headers;
+    private fetchWithRetry;
     validateToken(): Promise<void>;
     previewImport(manifest: ManifestPayload): Promise<ServerPreviewResponse>;
     applyImport(manifest: ManifestPayload, acknowledgeBreakingChanges: boolean): Promise<ApplyOperationResponse>;

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

@@ -12,6 +12,26 @@ export const APPLY_ERROR_PREFIX = 'apply failed:';
 // to the prefixes as a deliberate, named contract rather than an inline
 // magic string in the orchestrator.
 export const VALIDATION_FAILED_CODE = '"ValidationFailed"';
+const MAX_RETRY_AFTER_MS = 60_000;
+function defaultSleep(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function isTransientStatus(status) {
+    return status >= 500 && status <= 599;
+}
+function retryAfterMs(response) {
+    const value = response.headers?.get('retry-after')?.trim();
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    const delayMs = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(value) - Date.now();
+    if (!Number.isFinite(delayMs) || delayMs < 0 || delayMs > MAX_RETRY_AFTER_MS)
+        return undefined;
+    return Math.round(delayMs);
+}
+function errorMessage(error) {
+    return error instanceof Error && error.message ? error.message : String(error);
+}
 // Cap on the body slice appended to ApiError.message. Bumped from 1000 →
 // 16384 so realistic 422 ValidationFailed reports (which list every
 // offending component, ~100 chars per error, easily exceeds 1KB once you
@@ -24,10 +44,12 @@ const ERROR_BODY_LOG_CAP = 16384;
 export class ApiError extends Error {
     status;
     body;
-    constructor(message, status, body) {
+    guidance;
+    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) + '…' : body;
             this.message = `${message}\n${trimmed}`;
@@ -136,11 +158,19 @@ export class ImportApiClient {
     token;
     spaceId;
     environmentId;
+    retry;
     constructor(opts) {
         this.host = toApiHost(opts.host);
         this.token = opts.cmaToken;
         this.spaceId = opts.spaceId;
         this.environmentId = opts.environmentId;
+        const initialDelayMs = Math.max(0, opts.retry?.initialDelayMs ?? 250);
+        this.retry = {
+            maxAttempts: Math.max(1, Math.floor(opts.retry?.maxAttempts ?? 3)),
+            initialDelayMs,
+            maxDelayMs: Math.max(initialDelayMs, opts.retry?.maxDelayMs ?? 2000),
+            sleep: opts.retry?.sleep ?? defaultSleep,
+        };
     }
     base() {
         return `${this.host}/spaces/${this.spaceId}/environments/${this.environmentId}`;
@@ -152,6 +182,72 @@ export class ImportApiClient {
             'X-Contentful-User-Agent': buildUserAgent(),
         };
     }
+    async fetchWithRetry(phase, url, init, context = {}) {
+        const debug = getDebugLogger();
+        const errorPrefix = phase === 'preview' ? PREVIEW_ERROR_PREFIX : 'poll failed:';
+        const startedAt = Date.now();
+        for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt++) {
+            try {
+                const response = await fetch(url, init);
+                if (!isTransientStatus(response.status))
+                    return response;
+                const body = await response.text();
+                if (attempt === this.retry.maxAttempts) {
+                    const guidance = `The ${phase} request failed after ${attempt} attempts because the service remained unavailable. ` +
+                        'Wait a moment and try again.';
+                    debug.event('apply', `${phase}.error`, {
+                        ...context,
+                        attempt,
+                        maxAttempts: this.retry.maxAttempts,
+                        status: response.status,
+                        reason: 'retry_exhausted',
+                        durationMs: Date.now() - startedAt,
+                        bodyHead: body.slice(0, 2000),
+                    });
+                    throw new ApiError(`${errorPrefix} ${response.status}`, response.status, body, guidance);
+                }
+                const backoffMs = Math.min(this.retry.initialDelayMs * 2 ** (attempt - 1), this.retry.maxDelayMs);
+                const delayMs = retryAfterMs(response) ?? backoffMs;
+                debug.event('apply', `${phase}.retry`, {
+                    ...context,
+                    attempt,
+                    maxAttempts: this.retry.maxAttempts,
+                    status: response.status,
+                    reason: 'http_5xx',
+                    delayMs,
+                });
+                await this.retry.sleep(delayMs);
+            }
+            catch (error) {
+                if (error instanceof ApiError)
+                    throw error;
+                if (attempt === this.retry.maxAttempts) {
+                    const body = `The request failed after ${attempt} attempts because of a network error: ${errorMessage(error)}. ` +
+                        'Check your connection and try again.';
+                    debug.event('apply', `${phase}.error`, {
+                        ...context,
+                        attempt,
+                        maxAttempts: this.retry.maxAttempts,
+                        status: 0,
+                        reason: 'transport_retry_exhausted',
+                        durationMs: Date.now() - startedAt,
+                    });
+                    throw new ApiError(`${errorPrefix} 0`, 0, body);
+                }
+                const delayMs = Math.min(this.retry.initialDelayMs * 2 ** (attempt - 1), this.retry.maxDelayMs);
+                debug.event('apply', `${phase}.retry`, {
+                    ...context,
+                    attempt,
+                    maxAttempts: this.retry.maxAttempts,
+                    status: 0,
+                    reason: 'transport_error',
+                    delayMs,
+                });
+                await this.retry.sleep(delayMs);
+            }
+        }
+        throw new Error('Retry attempts exhausted');
+    }
     async validateToken() {
         // /users/me is the canonical token-validity endpoint — avoids space-membership
         // false positives that don't apply to the design-systems API authorization path.
@@ -173,7 +269,7 @@ export class ImportApiClient {
             componentCount: manifest.components?.length ?? 0,
             tokenCount: manifest.designTokens?.length ?? 0,
         });
-        const res = await fetch(url, {
+        const res = await this.fetchWithRetry('preview', url, {
             method: 'POST',
             headers: this.headers(),
             body: JSON.stringify(manifest),
@@ -196,19 +292,35 @@ export class ImportApiClient {
         const debug = getDebugLogger();
         const startedAt = Date.now();
         debug.event('apply', 'apply.request', { url, acknowledgeBreakingChanges });
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify({ ...manifest, acknowledgeBreakingChanges }),
-        });
+        let res;
+        try {
+            res = await fetch(url, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify({ ...manifest, acknowledgeBreakingChanges }),
+            });
+        }
+        catch (error) {
+            const body = `The apply request was not retried because its outcome is unknown and retrying could start a duplicate operation. ` +
+                `Check for an existing operation before trying again. Cause: ${errorMessage(error)}`;
+            debug.event('apply', 'apply.error', {
+                status: 0,
+                durationMs: Date.now() - startedAt,
+                reason: 'transport_error_not_retried',
+            });
+            throw new ApiError(`${APPLY_ERROR_PREFIX} 0`, 0, body);
+        }
         if (!res.ok) {
             const body = await res.text();
+            const guidance = isTransientStatus(res.status)
+                ? 'The apply request was not retried because the server may already have started an operation and retrying could create a duplicate. Check for an existing operation before trying again.'
+                : undefined;
             debug.event('apply', 'apply.error', {
                 status: res.status,
                 durationMs: Date.now() - startedAt,
                 bodyHead: body.slice(0, 2000),
             });
-            throw new ApiError(`${APPLY_ERROR_PREFIX} ${res.status}`, res.status, body);
+            throw new ApiError(`${APPLY_ERROR_PREFIX} ${res.status}`, res.status, body, guidance);
         }
         const parsed = (await res.json());
         debug.event('apply', 'apply.accepted', {
@@ -225,10 +337,10 @@ export class ImportApiClient {
         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, {
+            const res = await this.fetchWithRetry('poll', url, {
                 method: 'GET',
                 headers: this.headers(),
-            });
+            }, { operationId });
             if (!res.ok) {
                 throw new ApiError(`poll failed: ${res.status}`, res.status, await res.text());
             }

package/dist/src/apply/command.js

@@ -14,6 +14,7 @@ import { buildPostPushUrl } from '../lib/contentful-urls.js';
 import { resolveCompositionMode } from '../lib/composition-mode.js';
 import { stripAllowedComponents } from '../import/strip-allowed-components.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
+import { getInteractiveTerminalSupport, requireInteractiveTerminal } from '../lib/terminal-capabilities.js';
 function die(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);
@@ -461,7 +462,7 @@ export function registerApplyCommand(program) {
         }
         const spaceId = opts.spaceId;
         const environmentId = opts.environmentId;
-        if (process.stdout.isTTY) {
+        if (getInteractiveTerminalSupport().supported) {
             const { waitUntilExit } = render(createElement(ServerPreviewApp, {
                 preview,
                 spaceId,
@@ -491,7 +492,7 @@ export function registerApplyCommand(program) {
         .option('--force', 'Skip confirmation for breaking changes (for CI)')
         .option('--dry-run', 'Run preview only without applying')
         .action(async (opts) => {
-        const isTTY = process.stdout.isTTY;
+        const isTTY = getInteractiveTerminalSupport().supported;
         if (!isTTY && !opts.yes) {
             process.stderr.write('Error: apply push requires --yes in non-interactive mode\n');
             process.exit(1);
@@ -669,8 +670,10 @@ export function registerApplyCommand(program) {
         .option('--force', 'Skip confirmation for breaking changes')
         .action(async (opts) => {
         const nonInteractive = opts.selectAll || (opts.select ?? []).length > 0 || (opts.deselect ?? []).length > 0;
-        if (!nonInteractive && !process.stdout.isTTY) {
-            die('Error: apply select requires an interactive terminal unless --select-all, --select, or --deselect is provided');
+        if (!nonInteractive) {
+            requireInteractiveTerminal({
+                alternative: 'pass `--select-all`, `--select`, or `--deselect`',
+            });
         }
         let inputs;
         try {

package/dist/src/import/command.js

@@ -11,6 +11,7 @@ import { pickerPushRun } from '../runs/push-launcher.js';
 import { resolvePromptFlags } from './print-prompt.js';
 import { shouldShowRunPicker } from '../runs/run-picker-mount.js';
 import { dispatchPickerSelection } from './picker-dispatch.js';
+import { getInteractiveTerminalSupport, requireInteractiveTerminal } from '../lib/terminal-capabilities.js';
 export function registerImportCommand(program) {
     const cmd = program
         .command('import')
@@ -72,6 +73,7 @@ export function registerImportCommand(program) {
         .option('--save-as-new', 'Only valid with --modify: always save to a new path (prompts for one)')
         .option('--force', 'Bypass staleness checks when paired with --push-from-run or --modify.')
         .action(async (opts) => {
+        const interactiveTerminalSupported = getInteractiveTerminalSupport().supported;
         // --modify and --push-from-run resume a recorded session; the composition
         // mode comes from that run's record, so composition flags on the command
         // line don't apply. Warn and clear them rather than let them mislead.
@@ -130,7 +132,7 @@ export function registerImportCommand(program) {
                     ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
                     ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
                     ...(opts.host ? { host: opts.host } : {}),
-                    interactive: !!process.stdout.isTTY,
+                    interactive: interactiveTerminalSupported,
                     ...(opts.force ? { force: true } : {}),
                 });
                 return;
@@ -152,6 +154,9 @@ export function registerImportCommand(program) {
                 process.exit(1);
                 return;
             }
+            requireInteractiveTerminal({
+                alternative: 'start a fresh headless import with `--yes` and the required credentials',
+            });
             try {
                 await modifyRun({
                     runIdOrPath: opts.modify,
@@ -221,7 +226,7 @@ export function registerImportCommand(program) {
             opts.skipGenerate ||
             // A "don't push" request on a non-TTY is a headless intent (the wizard
             // needs a TTY); in a TTY it stays interactive and is NOT headless.
-            (noPushRequested && !process.stdout.isTTY) ||
+            (noPushRequested && !interactiveTerminalSupported) ||
             !!opts.spaceId ||
             !!opts.environmentId ||
             !!opts.cmaToken ||
@@ -229,12 +234,12 @@ export function registerImportCommand(program) {
             dryRunForward ||
             false;
         const autoAcceptScope = opts.autoAcceptScope ?? false;
-        if (!process.stdout.isTTY && !isHeadless && !autoAcceptScope) {
-            process.stderr.write('Error: experiences import is interactive. Pass --auto-accept-scope, or use a headless mode by providing credentials (--space-id, --environment-id, --cma-token) or one of --no-push, --skip-analyze, --skip-generate, --yes, --dry-run, --print-prompt.\n');
-            process.exit(1);
-            return;
+        if (!interactiveTerminalSupported && !isHeadless && !autoAcceptScope) {
+            requireInteractiveTerminal({
+                alternative: 'use headless flags such as `--yes` with credentials, or `--no-push --auto-accept-scope`',
+            });
         }
-        if (process.stdout.isTTY && !isHeadless) {
+        if (interactiveTerminalSupported && !isHeadless) {
             const { render } = await import('ink');
             const { createElement } = await import('react');
             const { WizardApp } = await import('./tui/WizardApp.js');
@@ -300,7 +305,7 @@ export function registerImportCommand(program) {
                     ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
                     ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
                     ...(opts.host ? { host: opts.host } : {}),
-                    interactive: !!process.stdout.isTTY,
+                    interactive: true,
                     ...(opts.outDir ? { outDir: opts.outDir } : {}),
                     ...(opts.overwrite ? { overwrite: true } : {}),
                     ...(opts.saveAsNew ? { saveAsNew: true } : {}),

package/dist/src/import/tui/WizardApp.js

@@ -37,7 +37,7 @@ import { ImportApiClient, ApiError } from '../../apply/api-client.js';
 import { detectSlotCycles, extractComponentsFromManifest, formatSlotCycleReport } from '../../apply/command.js';
 import { findSlotCycles } from '../../analyze/cycle-detection.js';
 import { buildComponentGraph } from '../../analyze/slot-graph.js';
-import { parseEdsiError, formatEdsiError, formatParsedEdsiError } from '../../lib/error-parser.js';
+import { formatApiError, formatEdsiError } from '../../lib/error-parser.js';
 import { handlePreview422, applySkipValidationErrors, clearedValidationErrorState } from './wizard-422-helpers.js';
 import { parseGenerateStderrChunk } from './wizard-generate-progress.js';
 import { spawnGenerateChild } from './spawn-generate.js';
@@ -924,13 +924,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     });
                     return;
                 }
+                const formatted = formatApiError(e, process.env['EDSI_VERBOSE_ERRORS'] === '1');
                 update({
                     step: 'error',
                     errorStep: 'apply preview',
-                    errorMessage: formatParsedEdsiError(parseEdsiError(e.body || e.message), {
-                        verbose: process.env['EDSI_VERBOSE_ERRORS'] === '1',
-                        raw: e.body,
-                    }) || e.message,
+                    errorMessage: formatted,
                     errorAllowCredentialRetry: true,
                 });
                 return;
@@ -1092,13 +1090,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         catch (e) {
             let msg;
             if (e instanceof ApiError) {
-                const parsed = parseEdsiError(e.body || e.message);
-                msg = formatParsedEdsiError(parsed, {
-                    verbose: process.env['EDSI_VERBOSE_ERRORS'] === '1',
-                    raw: e.body,
-                });
-                if (!msg)
-                    msg = e.message;
+                msg = formatApiError(e, process.env['EDSI_VERBOSE_ERRORS'] === '1');
             }
             else if (e instanceof Error) {
                 msg = e.message;

package/dist/src/lib/error-parser.d.ts

@@ -23,6 +23,7 @@ export interface ErrorDiagnostic {
 }
 export interface ApiErrorLike {
     body?: string;
+    guidance?: string;
     message: string;
 }
 export declare function stripLambdaLogPrefix(body: string): string;

package/dist/src/lib/error-parser.js

@@ -258,7 +258,6 @@ export function formatEdsiError(raw, opts = {}) {
 export function formatApiError(error, verbose = false) {
     const formatted = formatEdsiError(error.body || error.message, { verbose, raw: error.body }) || error.message;
     const phase = error.message.split('\n', 1)[0];
-    return /^(?:apply|preview|poll) failed: \d+$/.test(phase) && formatted !== phase
-        ? `${phase}\n${formatted}`
-        : formatted;
+    const withPhase = /^(?:apply|preview|poll) failed: \d+$/.test(phase) && formatted !== phase ? `${phase}\n${formatted}` : formatted;
+    return error.guidance ? `${withPhase}\n${error.guidance}` : withPhase;
 }

package/dist/src/lib/terminal-capabilities.d.ts

@@ -0,0 +1,28 @@
+export type TerminalInput = {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?: (enabled: boolean) => unknown;
+};
+export type TerminalOutput = {
+    isTTY?: boolean;
+};
+export type InteractiveTerminalSupport = {
+    supported: true;
+} | {
+    supported: false;
+    reason: 'input-not-tty' | 'output-not-tty' | 'raw-mode-unavailable';
+};
+export type TerminalCapabilityOptions = {
+    stdin?: TerminalInput;
+    stdout?: TerminalOutput;
+};
+/**
+ * Check the capabilities Ink's interactive input hooks require before the UI
+ * mounts. A stream can report itself as a TTY while its terminal host still
+ * rejects raw mode, so the check briefly enables and restores raw mode.
+ */
+export declare function getInteractiveTerminalSupport(options?: TerminalCapabilityOptions): InteractiveTerminalSupport;
+export type RequireInteractiveTerminalOptions = TerminalCapabilityOptions & {
+    alternative?: string;
+};
+export declare function requireInteractiveTerminal(options?: RequireInteractiveTerminalOptions): void;

package/dist/src/lib/terminal-capabilities.js

@@ -0,0 +1,51 @@
+/**
+ * Check the capabilities Ink's interactive input hooks require before the UI
+ * mounts. A stream can report itself as a TTY while its terminal host still
+ * rejects raw mode, so the check briefly enables and restores raw mode.
+ */
+export function getInteractiveTerminalSupport(options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    if (stdout.isTTY !== true)
+        return { supported: false, reason: 'output-not-tty' };
+    if (stdin.isTTY !== true)
+        return { supported: false, reason: 'input-not-tty' };
+    if (typeof stdin.setRawMode !== 'function') {
+        return { supported: false, reason: 'raw-mode-unavailable' };
+    }
+    const wasRaw = stdin.isRaw === true;
+    try {
+        stdin.setRawMode(true);
+        if (!wasRaw)
+            stdin.setRawMode(false);
+    }
+    catch {
+        if (!wasRaw) {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch {
+                // The original capability failure is the actionable result.
+            }
+        }
+        return { supported: false, reason: 'raw-mode-unavailable' };
+    }
+    return { supported: true };
+}
+export function requireInteractiveTerminal(options = {}) {
+    const support = getInteractiveTerminalSupport(options);
+    if (support.supported)
+        return;
+    const reason = support.reason === 'output-not-tty'
+        ? 'standard output is not a TTY'
+        : support.reason === 'input-not-tty'
+            ? 'standard input is not a TTY'
+            : 'standard input cannot enter raw mode';
+    const lines = [
+        `Interactive terminal UI is unavailable because ${reason}.`,
+        'On Windows, run this command in Windows Terminal with PowerShell.',
+    ];
+    if (options.alternative)
+        lines.push(`To continue without the UI, ${options.alternative}.`);
+    throw new Error(lines.join('\n'));
+}

package/dist/src/print/command.js

@@ -7,6 +7,7 @@ import { validateCDFFile } from './validate/validators/cdf-validator.js';
 import { validateDTCGTokenFile } from './validate/validators/dtcg-validator.js';
 import { formatDiagnostics } from './validate/validators/format-errors.js';
 import { ValidateView } from './validate/tui/ValidateView.js';
+import { getInteractiveTerminalSupport } from '../lib/terminal-capabilities.js';
 function die(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);
@@ -195,7 +196,7 @@ export function registerPrintCommand(program) {
         }
         const failed = viewResults.some((r) => !r.valid);
         const exitCode = failed ? 1 : 0;
-        if (process.stdout.isTTY) {
+        if (getInteractiveTerminalSupport().supported) {
             const { waitUntilExit } = render(createElement(ValidateView, {
                 results: viewResults,
                 onExit: () => process.exit(exitCode),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.16.1-dev-build-2b79e46.0",
+  "version": "2.16.1-dev-build-d068963.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -34,8 +34,8 @@
     "react": "^18.3.1",
     "react-devtools-core": "^4.19.1",
     "react-dom": "^18.3.1",
-    "@contentful/experience-design-system-extraction": "2.16.1-dev-build-2b79e46.0",
-    "@contentful/experience-design-system-types": "2.16.1-dev-build-2b79e46.0"
+    "@contentful/experience-design-system-extraction": "2.16.1-dev-build-d068963.0",
+    "@contentful/experience-design-system-types": "2.16.1-dev-build-d068963.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",