@contentful/experience-design-system-cli 2.12.1-dev-build-0b7de73.0 → 2.12.1-dev-build-c47114b.0

package/dist/src/lib/debug-logger.js

@@ -0,0 +1,229 @@
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+// ── Redaction ────────────────────────────────────────────────────────────────
+// Blocklist of secret-shaped keys; matched case-insensitively.
+const SECRET_KEY_PATTERNS = [
+    /token/i,
+    /secret/i,
+    /password/i,
+    /authorization/i,
+    /^auth$/i,
+    /apikey/i,
+    /api_key/i,
+    /credential/i,
+    /bearer/i,
+    /^cma$/i,
+    /cmaToken/i,
+];
+// Value-side patterns for strings that look like tokens even under innocuous keys.
+const SECRET_VALUE_PATTERNS = [
+    /^Bearer\s+\S+/i,
+    /CFPAT-[A-Za-z0-9_-]{20,}/,
+    /sk-[A-Za-z0-9_-]{20,}/,
+    /xox[baprs]-[A-Za-z0-9-]{10,}/,
+];
+const REDACTED = '«redacted»';
+const MAX_STRING_LEN = 4000;
+function redactValue(value, seen) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string') {
+        if (SECRET_VALUE_PATTERNS.some((r) => r.test(value)))
+            return REDACTED;
+        return value.length > MAX_STRING_LEN
+            ? value.slice(0, MAX_STRING_LEN) + `…«+${value.length - MAX_STRING_LEN}»`
+            : value;
+    }
+    if (typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '«cycle»';
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, seen));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (SECRET_KEY_PATTERNS.some((r) => r.test(k))) {
+            out[k] = REDACTED;
+        }
+        else {
+            out[k] = redactValue(v, seen);
+        }
+    }
+    return out;
+}
+export function redactForDebug(payload) {
+    return redactValue(payload, new WeakSet());
+}
+// ── Path resolution ──────────────────────────────────────────────────────────
+const DEBUG_ROOT_ENV = 'EDSI_DEBUG_ROOT';
+const DEBUG_LOG_ENV = 'EDSI_DEBUG_LOG';
+function defaultDebugRoot() {
+    return process.env[DEBUG_ROOT_ENV] ?? join(homedir(), '.contentful', 'experience-design-system-cli', 'debug');
+}
+// Session timestamp source. Deterministic-friendly: honors EDSI_DEBUG_TS for tests.
+function makeSessionTimestamp() {
+    const override = process.env['EDSI_DEBUG_TS'];
+    if (override)
+        return override;
+    const now = new Date();
+    const pad = (n, w = 2) => n.toString().padStart(w, '0');
+    return (`${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}` +
+        `T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}Z`);
+}
+// ── Singleton ───────────────────────────────────────────────────────────────
+let singleton = null;
+class NoopDebugLogger {
+    enabled = false;
+    path = null;
+    event() {
+        /* no-op */
+    }
+}
+class FileDebugLogger {
+    enabled = true;
+    path;
+    sessionStart;
+    constructor(path) {
+        this.path = path;
+        this.sessionStart = Date.now();
+        mkdirSync(dirname(path), { recursive: true });
+        // Header event — records the process context.
+        this.write({
+            ts: new Date().toISOString(),
+            category: 'config',
+            name: 'session.open',
+            pid: process.pid,
+            ppid: process.ppid,
+            cwd: process.cwd(),
+            argv: process.argv.slice(1),
+            node: process.version,
+            platform: process.platform,
+        });
+    }
+    event(category, name, payload = {}) {
+        const redacted = redactForDebug(payload);
+        this.write({
+            ts: new Date().toISOString(),
+            elapsedMs: Date.now() - this.sessionStart,
+            category,
+            name,
+            pid: process.pid,
+            ...redacted,
+        });
+    }
+    write(record) {
+        try {
+            appendFileSync(this.path, JSON.stringify(record) + '\n', { encoding: 'utf8' });
+        }
+        catch {
+            // Debug logging must never crash the CLI. Swallow.
+        }
+    }
+}
+/**
+ * Initialize the process-wide debug logger. Safe to call multiple times —
+ * subsequent calls return the existing instance.
+ *
+ * If EDSI_DEBUG_LOG is already set in the environment, this process joins
+ * that log file (used by spawned subprocesses so a whole `experiences import`
+ * flow lands in a single file).
+ */
+export function initDebugLogger(opts) {
+    if (singleton)
+        return singleton;
+    // Inherited from parent process — always join the existing file, regardless
+    // of the local flag/env decision. Parent already made the choice.
+    const inherited = process.env[DEBUG_LOG_ENV];
+    if (inherited) {
+        singleton = new FileDebugLogger(inherited);
+        if (opts.command)
+            singleton.event('config', 'subprocess.start', { command: opts.command });
+        return singleton;
+    }
+    if (!opts.enabled) {
+        singleton = new NoopDebugLogger();
+        return singleton;
+    }
+    const root = opts.root ?? defaultDebugRoot();
+    const ts = makeSessionTimestamp();
+    const suffix = opts.command ? `-${opts.command}` : '';
+    const path = join(root, `${ts}${suffix}.jsonl`);
+    singleton = new FileDebugLogger(path);
+    process.env[DEBUG_LOG_ENV] = path; // propagate to spawned children
+    if (opts.command)
+        singleton.event('config', 'command.start', { command: opts.command });
+    // Emit a close event on process exit. Best-effort — writeFileSync-based, so
+    // it works from within an 'exit' handler.
+    process.on('exit', (code) => {
+        if (singleton && singleton.enabled) {
+            singleton.event('config', 'session.close', { exitCode: code });
+        }
+    });
+    return singleton;
+}
+export function getDebugLogger() {
+    return singleton ?? new NoopDebugLogger();
+}
+/** Test-only: reset the singleton. */
+export function __resetDebugLoggerForTest() {
+    singleton = null;
+    delete process.env[DEBUG_LOG_ENV];
+}
+// ── Resolver ────────────────────────────────────────────────────────────────
+/**
+ * Resolve effective debug-mode setting from three sources.
+ *
+ * Precedence (highest first):
+ *   1. `--debug` / `--no-debug` CLI flag
+ *   2. `EDSI_DEBUG` env var (truthy: 1, true, yes, on)
+ *   3. Persisted `debug` field in credentials.json
+ *   4. Default: OFF
+ */
+export function resolveDebugMode(opts, configDebug) {
+    if (opts.debug !== undefined)
+        return opts.debug;
+    const env = process.env['EDSI_DEBUG'];
+    if (env !== undefined && env !== '') {
+        const v = env.toLowerCase();
+        if (v === '1' || v === 'true' || v === 'yes' || v === 'on')
+            return true;
+        if (v === '0' || v === 'false' || v === 'no' || v === 'off')
+            return false;
+    }
+    if (configDebug !== undefined)
+        return configDebug;
+    return false;
+}
+// ── Bright-green banner ─────────────────────────────────────────────────────
+/**
+ * Emit the bright-green "debug logs at <path>" banner to stderr.
+ * No-op when debug is disabled or stderr is not a TTY-friendly stream.
+ * Callers should invoke this once at start and once at end of the command.
+ */
+export function printDebugBanner(logger, phase) {
+    if (!logger.enabled || !logger.path)
+        return;
+    const prefix = phase === 'start' ? '\x1b[92m[debug]\x1b[0m ' : '\x1b[92m[debug]\x1b[0m ';
+    const label = phase === 'start' ? 'debug logs at' : 'debug logs written to';
+    // Bright green (92) + bold (1); reset with 0.
+    const line = `${prefix}\x1b[1m\x1b[92m${label} ${logger.path}\x1b[0m\n`;
+    try {
+        process.stderr.write(line);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Directory that contains the current process's debug log, if any. */
+export function debugLogPath() {
+    return singleton?.path ?? process.env[DEBUG_LOG_ENV] ?? null;
+}
+/** Ensure spawned children join the same debug log by including EDSI_DEBUG_LOG in their env. */
+export function debugEnvForSubprocess(env = process.env) {
+    const path = debugLogPath();
+    if (!path)
+        return env;
+    return { ...env, [DEBUG_LOG_ENV]: path };
+}

package/dist/src/lib/debug-preamble.d.ts

@@ -0,0 +1,14 @@
+import { type DebugLogger } from './debug-logger.js';
+/**
+ * Preamble every top-level command action should call before doing work.
+ *
+ * Resolves the effective debug decision (flag > env > persisted config),
+ * initializes the singleton, and prints the bright-green start banner.
+ * Registers a process-exit handler that prints the end banner once.
+ *
+ * Returns the logger so the caller can emit events without a second import.
+ * When debug is disabled, the returned logger is a no-op.
+ */
+export declare function beginCommand(command: string, opts: {
+    debug?: boolean;
+}): Promise<DebugLogger>;

package/dist/src/lib/debug-preamble.js

@@ -0,0 +1,33 @@
+import { initDebugLogger, printDebugBanner, resolveDebugMode } from './debug-logger.js';
+import { readExperiencesCredentials } from '../credentials-store.js';
+let endBannerRegistered = false;
+/**
+ * Preamble every top-level command action should call before doing work.
+ *
+ * Resolves the effective debug decision (flag > env > persisted config),
+ * initializes the singleton, and prints the bright-green start banner.
+ * Registers a process-exit handler that prints the end banner once.
+ *
+ * Returns the logger so the caller can emit events without a second import.
+ * When debug is disabled, the returned logger is a no-op.
+ */
+export async function beginCommand(command, opts) {
+    let configDebug;
+    try {
+        const creds = await readExperiencesCredentials();
+        configDebug = creds.debug;
+    }
+    catch {
+        // Missing credentials.json is fine — the resolver falls through to default OFF.
+    }
+    const enabled = resolveDebugMode(opts, configDebug);
+    const logger = initDebugLogger({ enabled, command });
+    if (logger.enabled) {
+        printDebugBanner(logger, 'start');
+        if (!endBannerRegistered) {
+            endBannerRegistered = true;
+            process.on('exit', () => printDebugBanner(logger, 'end'));
+        }
+    }
+    return logger;
+}

package/dist/src/program.js

@@ -11,6 +11,7 @@ import { registerPrintCommand } from './print/command.js';
 import { registerImportCommand } from './import/command.js';
 import { registerSetupCommand } from './setup/command.js';
 import { registerRunsCommand } from './runs/ls-command.js';
+import { beginCommand } from './lib/debug-preamble.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 /**
@@ -65,5 +66,30 @@ export function createProgram() {
     registerSetupCommand(program);
     registerRunsCommand(program);
     registerBuildCommand(program);
+    // Expose --debug on every subcommand. The flag is inherited automatically
+    // via `option()` at program scope + `preAction` reading merged opts from all
+    // ancestors. When set (or when EDSI_DEBUG / persisted config is on), the
+    // process-wide DebugLogger is initialized before the subcommand action runs
+    // and a bright-green "debug logs at <path>" banner is printed to stderr.
+    program.option('--debug', 'Write a JSONL trace of every decision to ~/.contentful/experience-design-system-cli/debug/');
+    program.option('--no-debug', 'Force debug logging off (overrides EDSI_DEBUG and persisted setup preference)');
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        // Merge opts from actionCommand and all ancestors — root-level --debug
+        // set alongside a subcommand ends up on the root command's opts, not the
+        // subcommand's.
+        let debug;
+        for (let c = actionCommand; c; c = c.parent) {
+            const opts = c.opts();
+            if (opts.debug !== undefined) {
+                debug = opts.debug;
+                break;
+            }
+        }
+        // Build a `command` label out of the actual subcommand chain (e.g. "apply push").
+        const chain = [];
+        for (let c = actionCommand; c && c.parent; c = c.parent)
+            chain.unshift(c.name());
+        await beginCommand(chain.join(' ') || actionCommand.name(), { ...(debug !== undefined ? { debug } : {}) });
+    });
     return program;
 }

package/dist/src/runs/modify-launcher.d.ts

@@ -20,5 +20,7 @@ export type ModifyLauncherInput = {
     initialEnvironmentId?: string;
     /** Pre-fill host (from the run record's pushedTo). */
     initialHost?: string;
+    /** Pre-fill CMA token (from credentials.json / env). */
+    initialCmaToken?: string;
 };
 export declare function launchModifyWizard(input: ModifyLauncherInput): Promise<void>;

package/dist/src/runs/modify-launcher.js

@@ -31,6 +31,8 @@ export async function launchModifyWizard(input) {
         props.initialEnvironmentId = input.initialEnvironmentId;
     if (input.initialHost)
         props.initialHost = input.initialHost;
+    if (input.initialCmaToken)
+        props.initialCmaToken = input.initialCmaToken;
     const { waitUntilExit } = render(createElement(WizardApp, props));
     await waitUntilExit();
 }

package/dist/src/runs/push-launcher.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Push-from-picker launcher. When the operator selects "Push" from the
+ * interactive run-picker, we mount the wizard with seeded session IDs and
+ * `initialStep: 'push-from-picker'` so they see the same preview + push UX
+ * as a fresh `experiences import` (preview → diff review → pushing progress
+ * bars → done with view URL).
+ *
+ * This is deliberately parallel to `modify-launcher.ts`. The `--push-from-run`
+ * CLI flag path (headless shell-out via `replayRun`) is preserved for
+ * scripted / non-TTY use.
+ */
+export type PushLauncherInput = {
+    extractSessionId: string;
+    generateSessionId: string | null;
+    /** Token session id from the run record; null when no tokens were
+     *  generated. Forwarded to the wizard so preview picks up tokens too. */
+    tokenSessionId?: string | null;
+    projectPath: string;
+    savePath: string;
+    /** Absolute path to the run's tokens.json on disk (from the run record).
+     *  Forwarded to the wizard so runPreview can hydrate DTCG tokens without
+     *  re-emitting them to disk. Null when the run had no tokens. */
+    tokensPath?: string | null;
+    /** Pre-fill space id (from the run record's pushedTo or credentials.json). */
+    initialSpaceId?: string;
+    /** Pre-fill environment id (from the run record's pushedTo or credentials.json). */
+    initialEnvironmentId?: string;
+    /** Pre-fill host (from the run record's pushedTo or credentials.json). */
+    initialHost?: string;
+    /** Pre-fill CMA token (from credentials.json / env). */
+    initialCmaToken?: string;
+};
+export declare function launchPushWizard(input: PushLauncherInput): Promise<void>;
+export type PickerPushRunOptions = {
+    runIdOrPath: string;
+    /** From `--space-id` flag. */
+    spaceId?: string;
+    /** From `--environment-id` flag. */
+    environmentId?: string;
+    /** From `--cma-token` flag. */
+    cmaToken?: string;
+    /** From `--host` flag. */
+    host?: string;
+    /** When true, bypass the source/saved-file staleness check. */
+    force?: boolean;
+};
+/**
+ * Interactive picker-Push entry point. Resolves the run record, applies the
+ * staleness gate, layers credentials (flag → pushedTo → credentials.json),
+ * and mounts the wizard via `launchPushWizard`.
+ */
+export declare function pickerPushRun(opts: PickerPushRunOptions): Promise<void>;

package/dist/src/runs/push-launcher.js

@@ -0,0 +1,77 @@
+/**
+ * Push-from-picker launcher. When the operator selects "Push" from the
+ * interactive run-picker, we mount the wizard with seeded session IDs and
+ * `initialStep: 'push-from-picker'` so they see the same preview + push UX
+ * as a fresh `experiences import` (preview → diff review → pushing progress
+ * bars → done with view URL).
+ *
+ * This is deliberately parallel to `modify-launcher.ts`. The `--push-from-run`
+ * CLI flag path (headless shell-out via `replayRun`) is preserved for
+ * scripted / non-TTY use.
+ */
+export async function launchPushWizard(input) {
+    const { render } = await import('ink');
+    const { createElement } = await import('react');
+    const { WizardApp } = await import('../import/tui/WizardApp.js');
+    const props = {
+        initialProjectPath: input.projectPath,
+        seedExtractSessionId: input.extractSessionId,
+        initialStep: 'push-from-picker',
+    };
+    if (input.generateSessionId)
+        props.seedGenerateSessionId = input.generateSessionId;
+    if (input.tokenSessionId)
+        props.seedTokenSessionId = input.tokenSessionId;
+    if (input.tokensPath)
+        props.seedTokensPath = input.tokensPath;
+    if (input.initialSpaceId)
+        props.initialSpaceId = input.initialSpaceId;
+    if (input.initialEnvironmentId)
+        props.initialEnvironmentId = input.initialEnvironmentId;
+    if (input.initialHost)
+        props.initialHost = input.initialHost;
+    if (input.initialCmaToken)
+        props.initialCmaToken = input.initialCmaToken;
+    const { waitUntilExit } = render(createElement(WizardApp, props));
+    await waitUntilExit();
+}
+/**
+ * Interactive picker-Push entry point. Resolves the run record, applies the
+ * staleness gate, layers credentials (flag → pushedTo → credentials.json),
+ * and mounts the wizard via `launchPushWizard`.
+ */
+export async function pickerPushRun(opts) {
+    const { resolveRunTarget } = await import('./resolve-run-target.js');
+    const { readExperiencesCredentials } = await import('../credentials-store.js');
+    const { checkRunStaleness, formatStalenessDetail } = await import('./staleness.js');
+    const run = await resolveRunTarget(opts.runIdOrPath);
+    if (!opts.force) {
+        const staleness = await checkRunStaleness(run);
+        if (staleness.stale) {
+            const detail = formatStalenessDetail(staleness);
+            throw new Error([
+                `Refusing to push run ${run.id} — source or saved files have drifted since the run was recorded.`,
+                ...detail,
+                '',
+                'Re-extract with `experiences import --project <path>` for a fresh run, or pass --force to bypass.',
+            ].join('\n'));
+        }
+    }
+    const stored = await readExperiencesCredentials();
+    const spaceId = opts.spaceId || run.pushedTo?.spaceId || stored.spaceId || '';
+    const environmentId = opts.environmentId || run.pushedTo?.environmentId || stored.environmentId || '';
+    const cmaToken = opts.cmaToken || stored.cmaToken || '';
+    const host = opts.host || run.pushedTo?.host || stored.host || '';
+    await launchPushWizard({
+        extractSessionId: run.extractSessionId,
+        generateSessionId: run.generateSessionId,
+        tokenSessionId: run.tokenSessionId,
+        projectPath: run.projectPath,
+        savePath: run.savePath,
+        tokensPath: run.tokensPath,
+        ...(spaceId ? { initialSpaceId: spaceId } : {}),
+        ...(environmentId ? { initialEnvironmentId: environmentId } : {}),
+        ...(host ? { initialHost: host } : {}),
+        ...(cmaToken ? { initialCmaToken: cmaToken } : {}),
+    });
+}

package/dist/src/runs/replay-helpers.js

@@ -128,6 +128,21 @@ export async function modifyRun(opts) {
         }
     }
     const saveMode = opts.overwrite ? 'overwrite' : opts.saveAsNew ? 'new' : 'prompt';
+    // Credentials pre-fill precedence: run.pushedTo field-by-field, then
+    // credentials.json (which itself falls back to env vars). The modify entry
+    // step goes straight to final-review and does not surface the credentials
+    // step, so if `pushedTo` is null (last push failed or never happened) we
+    // must consult the on-disk store here — otherwise the wizard mounts with
+    // built-in defaults (environmentId='master', host='api.contentful.com')
+    // and preview fires against the wrong endpoint. CMA token is now included
+    // in the fallback because credentials-store.ts persists it (INTEG-4410);
+    // if it's still empty after the merge, the wizard's final-review preview
+    // will 401 and the operator sees a real gap — out of scope for this fix.
+    const stored = await readExperiencesCredentials();
+    const mergedSpaceId = run.pushedTo?.spaceId || stored.spaceId || '';
+    const mergedEnvironmentId = run.pushedTo?.environmentId || stored.environmentId || '';
+    const mergedHost = run.pushedTo?.host || stored.host || '';
+    const mergedCmaToken = stored.cmaToken || '';
     await launchModifyWizard({
         extractSessionId: run.extractSessionId,
         generateSessionId: run.generateSessionId,
@@ -137,12 +152,9 @@ export async function modifyRun(opts) {
         entryStep: 'final-review',
         saveMode,
         ...(opts.outDir ? { outDirOverride: resolve(opts.outDir) } : {}),
-        // Pre-fill credentials from the run record's last push so the operator
-        // doesn't have to re-type space/environment/host on modify. The CMA
-        // token is never persisted, so it still resolves via env var /
-        // credentials.json / interactive prompt at the credentials step.
-        ...(run.pushedTo?.spaceId ? { initialSpaceId: run.pushedTo.spaceId } : {}),
-        ...(run.pushedTo?.environmentId ? { initialEnvironmentId: run.pushedTo.environmentId } : {}),
-        ...(run.pushedTo?.host ? { initialHost: run.pushedTo.host } : {}),
+        ...(mergedSpaceId ? { initialSpaceId: mergedSpaceId } : {}),
+        ...(mergedEnvironmentId ? { initialEnvironmentId: mergedEnvironmentId } : {}),
+        ...(mergedHost ? { initialHost: mergedHost } : {}),
+        ...(mergedCmaToken ? { initialCmaToken: mergedCmaToken } : {}),
     });
 }

package/dist/src/setup/command.js

@@ -7,6 +7,7 @@ import { createInterface } from 'node:readline';
 import { promisify } from 'node:util';
 import { readExperiencesCredentials, writeExperiencesCredentials, experiencesCredentialsPath, } from '../credentials-store.js';
 import { promptAutoFilterPreference } from './auto-filter-prompt.js';
+import { promptDebugModePreference } from './debug-mode-prompt.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../host-utils.js';
 const execFileAsync = promisify(execFile);
 const REQUIRED_NODE_MAJOR = 24;
@@ -459,6 +460,20 @@ async function setupContentfulCredentials() {
     section('Step 5: Contentful credentials', '[optional]');
     info(`Saved to ${experiencesCredentialsPath()} — loaded automatically by experiences import.`);
     info('');
+    // INTEG-4410: as of the precedence flip, disk wins over env — but env vars
+    // still act as a fallback when disk is empty, so operators who have any
+    // CONTENTFUL_* / EDS_HOST env set should know the ambient value would take
+    // effect if they skip this step. Warn regardless of the choice.
+    const envShadowing = [
+        process.env['CONTENTFUL_SPACE_ID'] ? 'CONTENTFUL_SPACE_ID' : null,
+        process.env['CONTENTFUL_ENVIRONMENT_ID'] ? 'CONTENTFUL_ENVIRONMENT_ID' : null,
+        process.env['CONTENTFUL_MANAGEMENT_TOKEN'] ? 'CONTENTFUL_MANAGEMENT_TOKEN' : null,
+        process.env['EDS_HOST'] ? 'EDS_HOST' : null,
+    ].filter((v) => !!v);
+    if (envShadowing.length > 0) {
+        warn(`Env vars set: ${envShadowing.join(', ')}. Values saved here take precedence; env vars only apply where disk is empty.`);
+        info('');
+    }
     const stored = await readExperiencesCredentials();
     const currentSpace = stored.spaceId;
     const currentEnv = stored.environmentId;
@@ -599,7 +614,22 @@ async function setupQoL(profilePath) {
     else {
         dim('     skipped');
     }
-    // 6d: NO_COLOR
+    // 6d: Debug-mode default
+    info('');
+    info('Debug logging — writes a JSONL trace of every command decision (agent calls, tool calls,');
+    info('apply actions, filter decisions, etc.) to ~/.contentful/experience-design-system-cli/debug/.');
+    info('Useful for developers debugging the CLI; OFF by default because traces are verbose.');
+    const debugCreds = await readExperiencesCredentials();
+    const debugChoice = await promptDebugModePreference((q) => prompt(q), debugCreds.debug);
+    if (debugChoice !== (debugCreds.debug ?? false)) {
+        await writeExperiencesCredentials({ ...debugCreds, debug: debugChoice });
+        ok(`Debug logging default set to ${debugChoice ? 'ON' : 'OFF'}`);
+    }
+    else {
+        dim('     unchanged');
+    }
+    info('');
+    // 6e: NO_COLOR
     info('');
     info('NO_COLOR — set to 1 to disable ANSI color output (useful in CI or plain terminals).');
     const setNoColor = await confirm('Add NO_COLOR=1 (disable colors) to your profile?', false);

package/dist/src/setup/debug-mode-prompt.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ask the operator whether to enable debug logging by default.
+ *
+ * When ON, every command writes a JSONL trace of its decisions to
+ * ~/.contentful/experience-design-system-cli/debug/. Off by default because
+ * the trace file grows quickly and contains verbose per-tool-call detail
+ * intended for developers debugging the CLI.
+ *
+ * Injectable `ask` so tests can drive without a TTY.
+ */
+export declare function promptDebugModePreference(ask: (q: string) => Promise<string>, current?: boolean): Promise<boolean>;

package/dist/src/setup/debug-mode-prompt.js

@@ -0,0 +1,22 @@
+/**
+ * Ask the operator whether to enable debug logging by default.
+ *
+ * When ON, every command writes a JSONL trace of its decisions to
+ * ~/.contentful/experience-design-system-cli/debug/. Off by default because
+ * the trace file grows quickly and contains verbose per-tool-call detail
+ * intended for developers debugging the CLI.
+ *
+ * Injectable `ask` so tests can drive without a TTY.
+ */
+export async function promptDebugModePreference(ask, current) {
+    const defaultValue = current ?? false;
+    const hint = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = (await ask(`  Enable debug logging by default? ${hint} `)).trim().toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    if (answer.startsWith('y'))
+        return true;
+    if (answer.startsWith('n'))
+        return false;
+    return defaultValue;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.12.1-dev-build-0b7de73.0",
+  "version": "2.12.1-dev-build-c47114b.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.12.1-dev-build-0b7de73.0"
+    "@contentful/experience-design-system-types": "2.12.1-dev-build-c47114b.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",