@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/telemetry/index.js

@@ -0,0 +1,217 @@
+/**
+ * Telemetry module for anonymous usage analytics.
+ *
+ * Privacy-first design:
+ * - Only tracks command name and version
+ * - No arguments, file paths, or content
+ * - Opt-out via OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, or
+ *   `freespec config set telemetry.enabled false`
+ * - Auto-disabled in CI environments
+ * - Anonymous ID is a random UUID with no relation to the user
+ *
+ * Events are sent with a plain fetch to PostHog's stable public `/batch/`
+ * endpoint — the same one posthog-node used — instead of through the SDK.
+ * The SDK's only remaining job here was the wire format: every reliability
+ * knob was already forced to "send one event immediately, time-bounded,
+ * never retry, never throw". Carrying `posthog-node` for that shipped its
+ * fast-moving transitive tree (`@posthog/core`, `@posthog/types`, multiple
+ * releases per day) to every downstream consumer, where supply-chain age
+ * policies such as pnpm's `minimumReleaseAge` rejected the freshly published
+ * versions and broke installs (#1390).
+ */
+import { randomUUID } from 'crypto';
+import { getGlobalConfig, isGlobalConfigUnreadable } from '../core/global-config.js';
+import { isCiEnvironment } from '../utils/ci.js';
+import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
+import { isTelemetryOptedOutByEnv } from './opt-out.js';
+// PostHog API key - public key for client-side analytics
+// This is safe to embed as it only allows sending events, not reading data
+const POSTHOG_API_KEY = 'phc_Hthu8YvaIJ9QaFKyTG4TbVwkbd5ktcAFzVTKeMmoW2g';
+// Using reverse proxy to avoid ad blockers and keep traffic on our domain
+const POSTHOG_HOST = 'https://edge.openspec.dev';
+const TELEMETRY_REQUEST_TIMEOUT_MS = 1000;
+let anonymousId = null;
+/**
+ * Requests started by trackCommand and not yet settled, so shutdown can
+ * flush them before the process exits. Each request is individually
+ * time-bounded, so awaiting them cannot stall exit for more than the
+ * request timeout.
+ */
+const pendingEvents = new Set();
+async function safeTelemetryFetch(url, options) {
+    try {
+        const response = await fetch(url, options);
+        // Telemetry never reads the body, but undici keeps the connection
+        // occupied until the body is consumed or canceled — dispose of it on
+        // every path so no socket outlives shutdown().
+        if (response.body) {
+            await response.body.cancel();
+        }
+        if (response.ok) {
+            return response;
+        }
+    }
+    catch {
+        // Silent failure - telemetry should never surface network noise
+    }
+    return new Response(null, { status: 204 });
+}
+/**
+ * Check if telemetry is enabled.
+ *
+ * Precedence (first match wins):
+ * 1. OPENSPEC_TELEMETRY set to anything but an on-value (1/true/yes/on) → disabled
+ * 2. DO_NOT_TRACK set to anything but an off-value (0/false/no/off) → disabled
+ * 3. CI set to a truthy/on value → disabled (same rule as version-check)
+ * 4. global config telemetry.enabled === false → disabled
+ * 5. global config file exists but cannot be parsed → disabled
+ * 6. otherwise enabled (unset config means on; opt-out model)
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
+ */
+export function isTelemetryEnabled() {
+    // Explicit opt-out, and the DO_NOT_TRACK standard. Both are read
+    // tolerantly (see opt-out.ts): an opt-out that only worked for one exact
+    // spelling would leave users tracked who believe they are not.
+    if (isTelemetryOptedOutByEnv()) {
+        return false;
+    }
+    // Auto-disable in CI environments (providers use true/1/yes/…)
+    if (isCiEnvironment()) {
+        return false;
+    }
+    // Global config opt-out (env/CI remain hard overrides above)
+    if (getGlobalConfig().telemetry?.enabled === false) {
+        return false;
+    }
+    // A config file that cannot be parsed reads as defaults, which carry no
+    // opt-out, but the file itself may hold one. Unknown is not consent.
+    if (isGlobalConfigUnreadable()) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Get or create the anonymous user ID.
+ * Lazily generates a UUID on first call and persists it.
+ */
+export async function getOrCreateAnonymousId() {
+    // Return cached value if available
+    if (anonymousId) {
+        return anonymousId;
+    }
+    // Try to load from config
+    const config = await getTelemetryConfig();
+    if (config.anonymousId) {
+        anonymousId = config.anonymousId;
+        return anonymousId;
+    }
+    // Generate new UUID and persist
+    anonymousId = randomUUID();
+    await updateTelemetryConfig({ anonymousId });
+    return anonymousId;
+}
+/**
+ * Send one capture event to PostHog's batch endpoint. Fire-and-forget:
+ * bounded by the request timeout, never throws, never retries.
+ */
+function sendEvent(distinctId, event, properties) {
+    const body = JSON.stringify({
+        api_key: POSTHOG_API_KEY,
+        batch: [
+            {
+                type: 'capture',
+                event,
+                distinct_id: distinctId,
+                properties,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    });
+    const request = safeTelemetryFetch(`${POSTHOG_HOST}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
+    }).then(() => undefined);
+    pendingEvents.add(request);
+    void request.finally(() => pendingEvents.delete(request));
+}
+/**
+ * Track a command execution.
+ *
+ * @param commandName - The command name (e.g., 'init', 'change:apply')
+ * @param version - The FreeSpec version
+ */
+export async function trackCommand(commandName, version) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        // Disclosure before collection. A --json run defers the notice (printing
+        // it would corrupt machine-readable output), and for a user whose runs
+        // are all --json it may never have appeared — so nothing is sent, and no
+        // anonymous id is created, until the notice has actually been shown.
+        if (!(await getTelemetryConfig()).noticeSeen) {
+            return;
+        }
+        const userId = await getOrCreateAnonymousId();
+        sendEvent(userId, 'command_executed', {
+            command: commandName,
+            version: version,
+            surface: 'cli',
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Show first-run telemetry notice if not already seen.
+ */
+export async function maybeShowTelemetryNotice(options = {}) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const config = await getTelemetryConfig();
+        if (config.noticeSeen) {
+            return;
+        }
+        // In --json mode the notice would pollute stdout and break parsers, so
+        // defer it: skip the notice AND leave noticeSeen unset so the disclosure
+        // still appears on the user's first later non-JSON run.
+        if (options.silent) {
+            return;
+        }
+        // Display notice on stderr, not stdout: stdout is reserved for command
+        // output (raw passthrough text, JSON, etc.) and must stay parser/pipe-safe.
+        console.error('Note: FreeSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or freespec config set telemetry.enabled false');
+        // Mark as seen
+        await updateTelemetryConfig({ noticeSeen: true });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Flush pending telemetry events.
+ * Call this before CLI exit.
+ */
+export async function shutdown() {
+    if (pendingEvents.size === 0) {
+        return;
+    }
+    try {
+        await Promise.allSettled([...pendingEvents]);
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI exit
+    }
+    finally {
+        pendingEvents.clear();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/telemetry/opt-out.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Telemetry opt-out signals, shared by telemetry and the version check so both
+ * outbound surfaces honor exactly the same values.
+ *
+ * Parsing is tolerant in the style of isCiEnvironment(): a user who wrote
+ * DO_NOT_TRACK=true meant it, and an exact-match test that silently kept
+ * sending would be a privacy control that does not work. Ambiguity fails
+ * safe — a value we cannot read as "on" suppresses the request rather than
+ * enabling it.
+ */
+/** True when `DO_NOT_TRACK` is set to anything but an explicit off-value. */
+export declare function isDoNotTrackSet(env?: NodeJS.ProcessEnv): boolean;
+/** True when `OPENSPEC_TELEMETRY` is set to anything but an explicit on-value. */
+export declare function isTelemetryDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+/** True when either opt-out signal asks us to stay off the network. */
+export declare function isTelemetryOptedOutByEnv(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=opt-out.d.ts.map

package/dist/telemetry/opt-out.js

@@ -0,0 +1,27 @@
+/**
+ * Telemetry opt-out signals, shared by telemetry and the version check so both
+ * outbound surfaces honor exactly the same values.
+ *
+ * Parsing is tolerant in the style of isCiEnvironment(): a user who wrote
+ * DO_NOT_TRACK=true meant it, and an exact-match test that silently kept
+ * sending would be a privacy control that does not work. Ambiguity fails
+ * safe — a value we cannot read as "on" suppresses the request rather than
+ * enabling it.
+ */
+const ON_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const OFF_VALUES = new Set(['', '0', 'false', 'no', 'off']);
+/** True when `DO_NOT_TRACK` is set to anything but an explicit off-value. */
+export function isDoNotTrackSet(env = process.env) {
+    const value = env.DO_NOT_TRACK;
+    return value !== undefined && !OFF_VALUES.has(value.trim().toLowerCase());
+}
+/** True when `OPENSPEC_TELEMETRY` is set to anything but an explicit on-value. */
+export function isTelemetryDisabledByEnv(env = process.env) {
+    const value = env.OPENSPEC_TELEMETRY;
+    return value !== undefined && !ON_VALUES.has(value.trim().toLowerCase());
+}
+/** True when either opt-out signal asks us to stay off the network. */
+export function isTelemetryOptedOutByEnv(env = process.env) {
+    return isTelemetryDisabledByEnv(env) || isDoNotTrackSet(env);
+}
+//# sourceMappingURL=opt-out.js.map

package/dist/ui/ascii-patterns.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ASCII art animation patterns for the welcome screen.
+ * FreeSpec logo animation - diamond/rhombus shape with hollow center "O".
+ */
+/**
+ * Welcome animation frames - FreeSpec logo building from center
+ * 7 rows × 6 columns diamond with hollow center "O"
+ * Center bar is 2 cols × 3 rows (rows 3,4,5 cols 3,4)
+ * Each frame is an array of strings (lines of ASCII art)
+ * Grid: 6 cols × 2 chars = 12 chars wide
+ */
+export declare const WELCOME_ANIMATION: {
+    interval: number;
+    frames: string[][];
+};
+//# sourceMappingURL=ascii-patterns.d.ts.map

package/dist/ui/ascii-patterns.js

@@ -0,0 +1,133 @@
+/**
+ * ASCII art animation patterns for the welcome screen.
+ * FreeSpec logo animation - diamond/rhombus shape with hollow center "O".
+ */
+// Detect if full Unicode is supported
+const supportsUnicode = process.platform !== 'win32' ||
+    !!process.env.WT_SESSION || // Windows Terminal
+    !!process.env.TERM_PROGRAM; // Modern terminal
+// Character set based on Unicode support
+// Block characters for pixel-art aesthetic
+const CHARS = supportsUnicode
+    ? { full: '██', dim: '░░', empty: '  ' }
+    : { full: '##', dim: '++', empty: '  ' };
+const _ = CHARS.empty;
+const F = CHARS.full;
+const D = CHARS.dim;
+/**
+ * Welcome animation frames - FreeSpec logo building from center
+ * 7 rows × 6 columns diamond with hollow center "O"
+ * Center bar is 2 cols × 3 rows (rows 3,4,5 cols 3,4)
+ * Each frame is an array of strings (lines of ASCII art)
+ * Grid: 6 cols × 2 chars = 12 chars wide
+ */
+export const WELCOME_ANIMATION = {
+    interval: 120,
+    frames: [
+        // Frame 1: Empty
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+        ],
+        // Frame 2: Center blocks appear (dim) - 2x3 center bar
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${D}${D}${_}${_}`,
+            `${_}${_}${_}${_}${D}${D}${_}${_}`,
+            `${_}${_}${_}${_}${D}${D}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+        ],
+        // Frame 3: Center blocks solidify
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+        ],
+        // Frame 4: Top and bottom points appear
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${D}${D}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${_}${_}${_}${_}`,
+            `${_}${_}${_}${_}${D}${D}${_}${_}`,
+        ],
+        // Frame 5: Inner ring forming
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${D}${_}${_}${D}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${D}${_}${_}${D}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+        ],
+        // Frame 6: Outer ring appearing
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${D}${_}${F}${F}${_}${D}`,
+            `${_}${_}${D}${_}${F}${F}${_}${D}`,
+            `${_}${_}${D}${_}${F}${F}${_}${D}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+        ],
+        // Frame 7: Full logo
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+        ],
+        // Frame 8: Hold complete logo
+        [
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 1
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 2
+            `${_}${_}${_}${_}${_}${_}${_}${_}`, // padding row 3
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${F}${_}${F}${F}${_}${F}`,
+            `${_}${_}${_}${F}${_}${_}${F}${_}`,
+            `${_}${_}${_}${_}${F}${F}${_}${_}`,
+        ],
+    ],
+};
+//# sourceMappingURL=ascii-patterns.js.map

package/dist/ui/welcome-screen.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Animated welcome screen for the experimental artifact workflow setup.
+ * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
+ */
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export declare function prefersReducedMotion(platform?: NodeJS.Platform): boolean;
+/**
+ * Shows the animated welcome screen.
+ * Returns when user presses Enter.
+ */
+export declare function showWelcomeScreen(workflows: readonly string[], options?: {
+    animate?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=welcome-screen.d.ts.map

package/dist/ui/welcome-screen.js

@@ -0,0 +1,199 @@
+/**
+ * Animated welcome screen for the experimental artifact workflow setup.
+ * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
+ */
+import chalk from 'chalk';
+import { execFileSync, } from 'node:child_process';
+import { WELCOME_ANIMATION } from './ascii-patterns.js';
+import { getOnboardingCommands } from '../core/onboarding-commands.js';
+// Minimum terminal width for side-by-side layout
+const MIN_WIDTH = 60;
+// Width of the ASCII art column (with padding)
+const ART_COLUMN_WIDTH = 24;
+/**
+ * Welcome text content (right column)
+ */
+function getWelcomeText(workflows) {
+    const onboardingCommands = getOnboardingCommands(workflows);
+    const quickStart = [];
+    if (onboardingCommands.length > 0) {
+        const commandWidth = Math.max(...onboardingCommands.map((c) => c.command.length));
+        quickStart.push(chalk.white('Quick start after setup:'));
+        for (const { command, description } of onboardingCommands) {
+            quickStart.push(`  ${chalk.yellow(command.padEnd(commandWidth + 1))} ${chalk.dim(description)}`);
+        }
+        // These are the canonical names. How each tool spells them differs
+        // (/freespec-新建, @freespec-新建, $freespec-新建 ...) and cannot be known
+        // until tools are picked, one prompt later — so flag it rather than let the
+        // canonical form read as the literal thing to type. "Getting started"
+        // prints the real spelling once the selection is known.
+        quickStart.push(chalk.dim('  (spelling varies by tool)'));
+        quickStart.push('');
+    }
+    return [
+        chalk.white.bold('Welcome to FreeSpec'),
+        chalk.dim('变更目录、可选文档、按技能实现'),
+        '',
+        chalk.white('This setup will configure:'),
+        chalk.dim('  • Agent Skills for AI tools'),
+        // Not "freespec slash commands": this screen runs before tool selection, and
+        // skills-only tools (Codex, Kimi Code, ...) correctly get no command files
+        // at all. The exact spelling per tool is printed in "Getting started".
+        chalk.dim('  • Workflow commands, if supported'),
+        '',
+        ...quickStart,
+        chalk.cyan('Press Enter to select tools...'),
+    ];
+}
+/**
+ * Renders a single frame with side-by-side layout
+ */
+function renderFrame(artLines, textLines) {
+    const maxLines = Math.max(artLines.length, textLines.length);
+    const lines = [];
+    for (let i = 0; i < maxLines; i++) {
+        const artLine = artLines[i] || '';
+        const textLine = textLines[i] || '';
+        // Pad the art column to fixed width
+        const paddedArt = artLine.padEnd(ART_COLUMN_WIDTH);
+        // Color the ASCII art with cyan for visual appeal
+        const coloredArt = chalk.cyan(paddedArt);
+        // Clear line before writing to prevent residual characters
+        lines.push(`\x1b[2K${coloredArt}${textLine}`);
+    }
+    return lines.join('\n');
+}
+const REDUCED_MOTION_EXEC_OPTIONS = {
+    encoding: 'utf8',
+    timeout: 500,
+    // SIGKILL so a wedged lookup can never outlive the timeout and stall init.
+    killSignal: 'SIGKILL',
+    stdio: ['ignore', 'pipe', 'ignore'],
+};
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export function prefersReducedMotion(platform = process.platform) {
+    try {
+        if (platform === 'darwin') {
+            // The key only exists once the user has toggled Reduce Motion; when it
+            // is unset `defaults` exits non-zero and lands in the catch below.
+            const out = execFileSync('defaults', ['read', 'com.apple.universalaccess', 'reduceMotion'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === '1';
+        }
+        if (platform === 'linux') {
+            const out = execFileSync('gsettings', ['get', 'org.gnome.desktop.interface', 'enable-animations'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === 'false';
+        }
+    }
+    catch {
+        // Detection is best-effort only.
+    }
+    return false;
+}
+/**
+ * Checks if the terminal supports animation
+ */
+function canAnimate() {
+    // Must be TTY
+    if (!process.stdout.isTTY)
+        return false;
+    // Respect NO_COLOR
+    if (process.env.NO_COLOR)
+        return false;
+    // Manual override for users who need reduced motion (#722). Presence is
+    // what counts: even an empty value disables the animation.
+    if (process.env.OPENSPEC_NO_ANIMATION !== undefined)
+        return false;
+    // Check terminal width
+    const columns = process.stdout.columns || 80;
+    if (columns < MIN_WIDTH)
+        return false;
+    // Last so only interactive terminals pay for the OS lookup
+    if (prefersReducedMotion())
+        return false;
+    return true;
+}
+/**
+ * Wait for Enter key press
+ */
+async function waitForEnter() {
+    if (!process.stdin.isTTY) {
+        return;
+    }
+    // Keep all interactive input on Inquirer's keypress lifecycle. Mixing a raw
+    // `data` listener between Inquirer prompts breaks arrow/space keys on Windows.
+    const { createPrompt, isEnterKey, useKeypress } = await import('@inquirer/core');
+    const prompt = createPrompt((_config, done) => {
+        useKeypress((key) => {
+            if (key.ctrl && key.name === 'c') {
+                process.stdout.write('\n');
+                process.exit(0);
+            }
+            if (isEnterKey(key)) {
+                done(undefined);
+            }
+        });
+        return '';
+    });
+    await prompt({});
+}
+/**
+ * Shows the animated welcome screen.
+ * Returns when user presses Enter.
+ */
+export async function showWelcomeScreen(workflows, options = {}) {
+    const textLines = getWelcomeText(workflows);
+    if (options.animate === false || !canAnimate()) {
+        // Fallback: show static welcome. The "Press Enter" line is only honest
+        // when we actually wait; in a TTY, returning immediately would let the
+        // Enter it asks for fall through into the tool picker and submit the
+        // pre-selected tools sight-unseen. Without a TTY, drop the line instead.
+        const staticLines = process.stdin.isTTY
+            ? textLines
+            : textLines.filter((line) => !line.includes('Press Enter'));
+        const frame = WELCOME_ANIMATION.frames[3]; // Peak frame
+        process.stdout.write('\n' + renderFrame(frame, staticLines) + '\n\n');
+        await waitForEnter();
+        return;
+    }
+    let frameIndex = 0;
+    let running = true;
+    let isFirstRender = true;
+    // Content height for cursor movement between frames
+    const numContentLines = Math.max(WELCOME_ANIMATION.frames[0].length, textLines.length);
+    const frameHeight = numContentLines + 1; // internal newlines (11) + trailing newlines (2) = 13
+    // Total height including initial newline (for cleanup)
+    const totalHeight = frameHeight + 1; // 14
+    // Initial render
+    process.stdout.write('\n');
+    // Animation loop
+    const interval = setInterval(() => {
+        if (!running)
+            return;
+        const frame = WELCOME_ANIMATION.frames[frameIndex];
+        // Move cursor up to overwrite previous frame (always after first render)
+        if (!isFirstRender) {
+            process.stdout.write(`\x1b[${frameHeight}A`);
+        }
+        isFirstRender = false;
+        // Render current frame
+        process.stdout.write(renderFrame(frame, textLines) + '\n\n');
+        // Advance to next frame
+        frameIndex = (frameIndex + 1) % WELCOME_ANIMATION.frames.length;
+    }, WELCOME_ANIMATION.interval);
+    // Wait for Enter
+    await waitForEnter();
+    // Stop animation
+    running = false;
+    clearInterval(interval);
+    // Clear the welcome screen and move on
+    process.stdout.write(`\x1b[${totalHeight}A`);
+    for (let i = 0; i < totalHeight; i++) {
+        process.stdout.write('\x1b[2K\n'); // Clear line
+    }
+    process.stdout.write(`\x1b[${totalHeight}A`); // Move back up
+}
+//# sourceMappingURL=welcome-screen.js.map