openspec-cn 0.23.0

package/dist/prompts/searchable-multi-select.js

@@ -0,0 +1,149 @@
+import chalk from 'chalk';
+/**
+ * Create the searchable multi-select prompt.
+ * Uses dynamic import to prevent pre-commit hook hangs (see #367).
+ */
+async function createSearchableMultiSelect() {
+    const { createPrompt, useState, useKeypress, useMemo, usePrefix, isEnterKey, isBackspaceKey, isUpKey, isDownKey, } = await import('@inquirer/core');
+    return createPrompt((config, done) => {
+        const { message, choices, pageSize = 15, validate } = config;
+        const [searchText, setSearchText] = useState('');
+        const [selectedValues, setSelectedValues] = useState(() => choices.filter(c => c.preSelected).map(c => c.value));
+        const [cursor, setCursor] = useState(0);
+        const [status, setStatus] = useState('idle');
+        const [error, setError] = useState(null);
+        const prefix = usePrefix({ status });
+        // Filter choices by search
+        const filteredChoices = useMemo(() => {
+            if (!searchText.trim())
+                return choices;
+            const term = searchText.toLowerCase();
+            return choices.filter((c) => c.name.toLowerCase().includes(term) ||
+                c.value.toLowerCase().includes(term));
+        }, [searchText, choices]);
+        const selectedSet = useMemo(() => new Set(selectedValues), [selectedValues]);
+        const choiceMap = useMemo(() => new Map(choices.map((c) => [c.value, c])), [choices]);
+        useKeypress((key) => {
+            if (status === 'done')
+                return;
+            // Tab to confirm
+            if (key.name === 'tab') {
+                if (validate) {
+                    const result = validate(selectedValues);
+                    if (result !== true) {
+                        setError(typeof result === 'string' ? result : 'Invalid');
+                        return;
+                    }
+                }
+                setStatus('done');
+                done(selectedValues);
+                return;
+            }
+            // Enter to add item
+            if (isEnterKey(key)) {
+                const choice = filteredChoices[cursor];
+                if (choice && !selectedSet.has(choice.value)) {
+                    setSelectedValues([...selectedValues, choice.value]);
+                    setSearchText('');
+                    setCursor(0);
+                }
+                return;
+            }
+            // Backspace to remove or delete search char
+            if (isBackspaceKey(key)) {
+                if (searchText === '' && selectedValues.length > 0) {
+                    setSelectedValues(selectedValues.slice(0, -1));
+                }
+                else {
+                    setSearchText(searchText.slice(0, -1));
+                    setCursor(0);
+                }
+                return;
+            }
+            // Navigation
+            if (isUpKey(key)) {
+                setCursor(Math.max(0, cursor - 1));
+                return;
+            }
+            if (isDownKey(key)) {
+                setCursor(Math.min(filteredChoices.length - 1, cursor + 1));
+                return;
+            }
+            // Character input - handle printable characters
+            if (key.name && key.name.length === 1 && !key.ctrl) {
+                setSearchText(searchText + key.name);
+                setCursor(0);
+            }
+        });
+        // Render done state
+        if (status === 'done') {
+            const names = selectedValues
+                .map((v) => choiceMap.get(v)?.name ?? v)
+                .join(', ');
+            return `${prefix} ${chalk.bold(message)} ${chalk.cyan(names || '(none)')}`;
+        }
+        // Render active state
+        const lines = [];
+        lines.push(`${prefix} ${chalk.bold(message)}`);
+        // Selected chips
+        const chips = selectedValues.length > 0
+            ? selectedValues
+                .map((v) => chalk.bgCyan.black(` ${choiceMap.get(v)?.name} `))
+                .join(' ')
+            : chalk.dim('(none selected)');
+        lines.push(`  Selected: ${chips}`);
+        // Search box
+        lines.push(`  Search: ${chalk.yellow('[')}${searchText || chalk.dim('type to filter')}${chalk.yellow(']')}`);
+        // Instructions
+        lines.push(`  ${chalk.cyan('↑↓')} navigate • ${chalk.cyan('Enter')} add • ${chalk.cyan('Backspace')} remove • ${chalk.cyan('Tab')} confirm`);
+        // List
+        if (filteredChoices.length === 0) {
+            lines.push(chalk.yellow('  No matches'));
+        }
+        else {
+            // Calculate pagination
+            const startIndex = Math.max(0, Math.min(cursor - Math.floor(pageSize / 2), filteredChoices.length - pageSize));
+            const endIndex = Math.min(startIndex + pageSize, filteredChoices.length);
+            const visibleChoices = filteredChoices.slice(startIndex, endIndex);
+            for (let i = 0; i < visibleChoices.length; i++) {
+                const item = visibleChoices[i];
+                const actualIndex = startIndex + i;
+                const isActive = actualIndex === cursor;
+                const selected = selectedSet.has(item.value);
+                const icon = selected ? chalk.green('◉') : chalk.dim('○');
+                const arrow = isActive ? chalk.cyan('›') : ' ';
+                const name = isActive ? chalk.cyan(item.name) : item.name;
+                const isRefresh = selected && item.configured;
+                const suffix = selected
+                    ? chalk.dim(isRefresh ? ' (refresh)' : ' (selected)')
+                    : '';
+                lines.push(`  ${arrow} ${icon} ${name}${suffix}`);
+            }
+            // Show pagination indicator if needed
+            if (filteredChoices.length > pageSize) {
+                const currentPage = Math.floor(cursor / pageSize) + 1;
+                const totalPages = Math.ceil(filteredChoices.length / pageSize);
+                lines.push(chalk.dim(`  (${currentPage}/${totalPages})`));
+            }
+        }
+        if (error)
+            lines.push(chalk.red(`  ${error}`));
+        return lines.join('\n');
+    });
+}
+/**
+ * A searchable multi-select prompt with visible search box,
+ * selected items display, and intuitive keyboard navigation.
+ *
+ * - Type to filter choices
+ * - ↑↓ to navigate
+ * - Enter to add highlighted item
+ * - Backspace to remove last selected item (or delete search char)
+ * - Tab to confirm selections
+ */
+export async function searchableMultiSelect(config) {
+    const prompt = await createSearchableMultiSelect();
+    return prompt(config);
+}
+export default searchableMultiSelect;
+//# sourceMappingURL=searchable-multi-select.js.map

package/dist/telemetry/config.d.ts

@@ -0,0 +1,32 @@
+export interface TelemetryConfig {
+    anonymousId?: string;
+    noticeSeen?: boolean;
+}
+export interface GlobalConfig {
+    telemetry?: TelemetryConfig;
+    [key: string]: unknown;
+}
+/**
+ * Get the path to the global config file.
+ * Uses ~/.config/openspec/config.json on all platforms.
+ */
+export declare function getConfigPath(): string;
+/**
+ * Read the global config file.
+ * Returns an empty object if the file doesn't exist.
+ */
+export declare function readConfig(): Promise<GlobalConfig>;
+/**
+ * Write to the global config file.
+ * Preserves existing fields and merges in new values.
+ */
+export declare function writeConfig(updates: Partial<GlobalConfig>): Promise<void>;
+/**
+ * Get the telemetry config section.
+ */
+export declare function getTelemetryConfig(): Promise<TelemetryConfig>;
+/**
+ * Update the telemetry config section.
+ */
+export declare function updateTelemetryConfig(updates: Partial<TelemetryConfig>): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.js

@@ -0,0 +1,68 @@
+/**
+ * Global configuration for telemetry state.
+ * Stores anonymous ID and notice-seen flag in ~/.config/openspec/config.json
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+/**
+ * Get the path to the global config file.
+ * Uses ~/.config/openspec/config.json on all platforms.
+ */
+export function getConfigPath() {
+    const configDir = path.join(os.homedir(), '.config', 'openspec');
+    return path.join(configDir, 'config.json');
+}
+/**
+ * Read the global config file.
+ * Returns an empty object if the file doesn't exist.
+ */
+export async function readConfig() {
+    const configPath = getConfigPath();
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        // If parse fails or other error, return empty config
+        return {};
+    }
+}
+/**
+ * Write to the global config file.
+ * Preserves existing fields and merges in new values.
+ */
+export async function writeConfig(updates) {
+    const configPath = getConfigPath();
+    const configDir = path.dirname(configPath);
+    // Ensure directory exists
+    await fs.mkdir(configDir, { recursive: true });
+    // Read existing config and merge
+    const existing = await readConfig();
+    const merged = { ...existing, ...updates };
+    // Deep merge for telemetry object
+    if (updates.telemetry && existing.telemetry) {
+        merged.telemetry = { ...existing.telemetry, ...updates.telemetry };
+    }
+    await fs.writeFile(configPath, JSON.stringify(merged, null, 2) + '\n');
+}
+/**
+ * Get the telemetry config section.
+ */
+export async function getTelemetryConfig() {
+    const config = await readConfig();
+    return config.telemetry ?? {};
+}
+/**
+ * Update the telemetry config section.
+ */
+export async function updateTelemetryConfig(updates) {
+    const existing = await getTelemetryConfig();
+    await writeConfig({
+        telemetry: { ...existing, ...updates },
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Check if telemetry is enabled.
+ *
+ * Disabled when:
+ * - OPENSPEC_TELEMETRY=0
+ * - DO_NOT_TRACK=1
+ * - CI=true (any CI environment)
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Get or create the anonymous user ID.
+ * Lazily generates a UUID on first call and persists it.
+ */
+export declare function getOrCreateAnonymousId(): Promise<string>;
+/**
+ * Track a command execution.
+ *
+ * @param commandName - The command name (e.g., 'init', 'change:apply')
+ * @param version - The OpenSpec version
+ */
+export declare function trackCommand(commandName: string, version: string): Promise<void>;
+/**
+ * Show first-run telemetry notice if not already seen.
+ */
+export declare function maybeShowTelemetryNotice(): Promise<void>;
+/**
+ * Shutdown the PostHog client and flush pending events.
+ * Call this before CLI exit.
+ */
+export declare function shutdown(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -0,0 +1,145 @@
+/**
+ * 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 or DO_NOT_TRACK=1
+ * - Auto-disabled in CI environments
+ * - Anonymous ID is a random UUID with no relation to the user
+ */
+import { PostHog } from 'posthog-node';
+import { randomUUID } from 'crypto';
+import { getTelemetryConfig, updateTelemetryConfig } from './config.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';
+let posthogClient = null;
+let anonymousId = null;
+/**
+ * Check if telemetry is enabled.
+ *
+ * Disabled when:
+ * - OPENSPEC_TELEMETRY=0
+ * - DO_NOT_TRACK=1
+ * - CI=true (any CI environment)
+ */
+export function isTelemetryEnabled() {
+    // Check explicit opt-out
+    if (process.env.OPENSPEC_TELEMETRY === '0') {
+        return false;
+    }
+    // Respect DO_NOT_TRACK standard
+    if (process.env.DO_NOT_TRACK === '1') {
+        return false;
+    }
+    // Auto-disable in CI environments
+    if (process.env.CI === 'true') {
+        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;
+}
+/**
+ * Get the PostHog client instance.
+ * Creates it on first call with CLI-optimized settings.
+ */
+function getClient() {
+    if (!posthogClient) {
+        posthogClient = new PostHog(POSTHOG_API_KEY, {
+            host: POSTHOG_HOST,
+            flushAt: 1, // Send immediately, don't batch
+            flushInterval: 0, // No timer-based flushing
+        });
+    }
+    return posthogClient;
+}
+/**
+ * Track a command execution.
+ *
+ * @param commandName - The command name (e.g., 'init', 'change:apply')
+ * @param version - The OpenSpec version
+ */
+export async function trackCommand(commandName, version) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const userId = await getOrCreateAnonymousId();
+        const client = getClient();
+        client.capture({
+            distinctId: userId,
+            event: 'command_executed',
+            properties: {
+                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() {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const config = await getTelemetryConfig();
+        if (config.noticeSeen) {
+            return;
+        }
+        // Display notice
+        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0');
+        // Mark as seen
+        await updateTelemetryConfig({ noticeSeen: true });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Shutdown the PostHog client and flush pending events.
+ * Call this before CLI exit.
+ */
+export async function shutdown() {
+    if (!posthogClient) {
+        return;
+    }
+    try {
+        await posthogClient.shutdown();
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI exit
+    }
+    finally {
+        posthogClient = null;
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * ASCII art animation patterns for the welcome screen.
+ * OpenSpec logo animation - diamond/rhombus shape with hollow center "O".
+ */
+/**
+ * Welcome animation frames - OpenSpec 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.
+ * OpenSpec 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 - OpenSpec 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,10 @@
+/**
+ * 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.
+ */
+/**
+ * Shows the animated welcome screen.
+ * Returns when user presses Enter.
+ */
+export declare function showWelcomeScreen(): Promise<void>;
+//# sourceMappingURL=welcome-screen.d.ts.map