@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/zod-issues.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'zod';
+/** One rendering for zod issues across every state/config parser. */
+export declare function formatZodIssues(error: z.ZodError, fallbackLocation?: string): string;
+//# sourceMappingURL=zod-issues.d.ts.map

package/dist/core/zod-issues.js

@@ -0,0 +1,10 @@
+/** One rendering for zod issues across every state/config parser. */
+export function formatZodIssues(error, fallbackLocation = 'root') {
+    return error.issues
+        .map((issue) => {
+        const location = issue.path.length > 0 ? issue.path.join('.') : fallbackLocation;
+        return `${location}: ${issue.message}`;
+    })
+        .join('; ');
+}
+//# sourceMappingURL=zod-issues.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cli/index.js';
+export * from './core/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './cli/index.js';
+export * from './core/index.js';
+//# sourceMappingURL=index.js.map

package/dist/prompts/searchable-multi-select.d.ts

@@ -0,0 +1,35 @@
+interface Choice {
+    name: string;
+    value: string;
+    /**
+     * Extra terms the search box matches, for choices users look for by a word
+     * the name does not spell (see #653). Never rendered.
+     */
+    searchAliases?: string[];
+    description?: string;
+    configured?: boolean;
+    detected?: boolean;
+    configuredLabel?: string;
+    preSelected?: boolean;
+}
+interface Config {
+    message: string;
+    choices: Choice[];
+    pageSize?: number;
+    validate?: (selected: string[]) => boolean | string;
+    /** Shown when a search matches nothing, so the list is not a dead end. */
+    emptyHint?: string;
+}
+/**
+ * A searchable multi-select prompt with visible search box,
+ * selected items display, and intuitive keyboard navigation.
+ *
+ * - Type to filter choices
+ * - ↑↓ to navigate
+ * - Space to toggle highlighted item selection
+ * - Backspace to remove last selected item (or delete search char)
+ * - Enter to confirm selections
+ */
+export declare function searchableMultiSelect(config: Config): Promise<string[]>;
+export default searchableMultiSelect;
+//# sourceMappingURL=searchable-multi-select.d.ts.map

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

@@ -0,0 +1,188 @@
+import chalk from 'chalk';
+/**
+ * True when every character is printable, so the text can go in the search box.
+ * `\u007f` is DEL, which sorts above the printable range.
+ */
+function isPrintable(text) {
+    return text.length > 0 && [...text].every((char) => char >= ' ' && char !== '\u007f');
+}
+/**
+ * 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, emptyHint } = 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.trim().toLowerCase();
+            return choices.filter((c) => c.name.toLowerCase().includes(term) ||
+                c.value.toLowerCase().includes(term) ||
+                (c.searchAliases ?? []).some((alias) => alias.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;
+            // Enter to confirm/submit
+            if (isEnterKey(key)) {
+                if (validate) {
+                    const result = validate(selectedValues);
+                    if (result !== true) {
+                        setError(typeof result === 'string' ? result : 'Invalid');
+                        return;
+                    }
+                }
+                setStatus('done');
+                done(selectedValues);
+                return;
+            }
+            // Space to toggle selection
+            if (key.name === 'space') {
+                const choice = filteredChoices[cursor];
+                if (choice) {
+                    if (selectedSet.has(choice.value)) {
+                        setSelectedValues(selectedValues.filter(v => v !== choice.value));
+                    }
+                    else {
+                        setSelectedValues([...selectedValues, choice.value]);
+                    }
+                }
+                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.
+            // readline reports punctuation (`.`, `-`, `/`) only in `sequence`, leaving
+            // `name` undefined, so keying off `name` alone silently dropped every
+            // non-alphanumeric character the user typed.
+            // `@inquirer/core` types only `name` and `ctrl`; readline emits more.
+            const event = key;
+            if (event.ctrl || event.meta)
+                return;
+            // Requiring every character to be printable drops escape sequences
+            // (arrows, function keys), tab, escape and delete. readline splits a
+            // paste into one key per character, so a pasted space still toggles.
+            const typed = typeof event.sequence === 'string' && isPrintable(event.sequence)
+                ? event.sequence
+                : // Only the sequence may be multi-character: readline `name`s such as
+                    // 'tab' and 'escape' are printable strings but not typed input.
+                    typeof event.name === 'string' &&
+                        event.name.length === 1 &&
+                        isPrintable(event.name)
+                        ? event.name
+                        : undefined;
+            if (typed) {
+                setSearchText(searchText + typed);
+                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('Space')} toggle • ${chalk.cyan('Backspace')} remove • ${chalk.cyan('Enter')} confirm`);
+        // List
+        if (filteredChoices.length === 0) {
+            lines.push(chalk.yellow('  No matches'));
+            if (emptyHint)
+                lines.push(chalk.dim(`  ${emptyHint}`));
+        }
+        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('[x]') : chalk.dim('[ ]');
+                const arrow = isActive ? chalk.cyan('›') : ' ';
+                const name = isActive ? chalk.cyan(item.name) : item.name;
+                const isRefresh = selected && item.configured;
+                const statusLabel = !selected
+                    ? item.configured
+                        ? ' (configured)'
+                        : item.detected
+                            ? ' (detected)'
+                            : ''
+                    : '';
+                const suffix = selected
+                    ? chalk.dim(isRefresh ? ' (refresh)' : ' (selected)')
+                    : chalk.dim(statusLabel);
+                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
+ * - Space to toggle highlighted item selection
+ * - Backspace to remove last selected item (or delete search char)
+ * - Enter 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,37 @@
+import { type TelemetryConfig } from '../core/global-config.js';
+export declare const CONFIG_DIR_NAME = "freespec";
+export declare const CONFIG_FILE_NAME = "config.json";
+/** Re-export shared telemetry section type (single source of truth in global-config). */
+export type { TelemetryConfig };
+export interface GlobalConfig {
+    telemetry?: TelemetryConfig;
+    [key: string]: unknown;
+}
+/**
+ * Get the path to the global config file.
+ * Follows XDG Base Directory Specification and platform conventions.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/freespec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/freespec/
+ * - Windows fallback: %APPDATA%/freespec/
+ */
+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,148 @@
+/**
+ * Global configuration for telemetry state.
+ * Stores anonymous ID and notice-seen flag in the platform-appropriate config directory.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, getGlobalConfigDir, isConfigRootObject, unreadableGlobalConfigMessage, } from '../core/global-config.js';
+// Constants
+export const CONFIG_DIR_NAME = GLOBAL_CONFIG_DIR_NAME;
+export const CONFIG_FILE_NAME = GLOBAL_CONFIG_FILE_NAME;
+function getConfigDir() {
+    return getGlobalConfigDir();
+}
+function getLegacyConfigPath() {
+    return path.join(os.homedir(), '.config', CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+}
+async function readConfigFile(configPath) {
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Valid JSON that is not an object carries no settings to merge into, and
+        // spreading it would replace the file (a string even spreads to numeric
+        // character keys). Same predicate the rest of the CLI refuses to save over.
+        if (!isConfigRootObject(parsed)) {
+            return { status: 'invalid', config: {} };
+        }
+        return { status: 'ok', config: parsed };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { status: 'missing' };
+        }
+        // If parse fails or another read error occurs, ignore the file.
+        return { status: 'invalid', config: {} };
+    }
+}
+async function writeConfigFile(configPath, config) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+function hasMissingTelemetryFields(config) {
+    const telemetry = config.telemetry;
+    return (!telemetry ||
+        telemetry.anonymousId === undefined ||
+        telemetry.noticeSeen === undefined);
+}
+function mergeLegacyTelemetry(config, legacyConfig) {
+    const legacyTelemetry = legacyConfig.telemetry;
+    if (!legacyTelemetry) {
+        return undefined;
+    }
+    const currentTelemetry = config.telemetry ?? {};
+    const shouldMigrate = (currentTelemetry.anonymousId === undefined && legacyTelemetry.anonymousId !== undefined) ||
+        (currentTelemetry.noticeSeen === undefined && legacyTelemetry.noticeSeen !== undefined);
+    if (!shouldMigrate) {
+        return undefined;
+    }
+    return {
+        ...config,
+        telemetry: {
+            ...legacyTelemetry,
+            ...currentTelemetry,
+        },
+    };
+}
+async function migrateLegacyTelemetryConfig(configPath, config, persist) {
+    const legacyConfigPath = getLegacyConfigPath();
+    if (path.resolve(configPath) === path.resolve(legacyConfigPath) || !hasMissingTelemetryFields(config)) {
+        return config;
+    }
+    const legacyRead = await readConfigFile(legacyConfigPath);
+    if (legacyRead.status !== 'ok') {
+        return config;
+    }
+    const migrated = mergeLegacyTelemetry(config, legacyRead.config);
+    if (!migrated) {
+        return config;
+    }
+    if (persist) {
+        try {
+            await writeConfigFile(configPath, migrated);
+        }
+        catch {
+            // Preserve telemetry for this run even if the one-time migration cannot be persisted.
+        }
+    }
+    return migrated;
+}
+/**
+ * Get the path to the global config file.
+ * Follows XDG Base Directory Specification and platform conventions.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/freespec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/freespec/
+ * - Windows fallback: %APPDATA%/freespec/
+ */
+export function getConfigPath() {
+    const configDir = getConfigDir();
+    return path.join(configDir, CONFIG_FILE_NAME);
+}
+/**
+ * Read the global config file.
+ * Returns an empty object if the file doesn't exist.
+ */
+export async function readConfig() {
+    const configPath = getConfigPath();
+    const read = await readConfigFile(configPath);
+    const config = read.status === 'ok' ? read.config : {};
+    return migrateLegacyTelemetryConfig(configPath, config, read.status !== 'invalid');
+}
+/**
+ * Write to the global config file.
+ * Preserves existing fields and merges in new values.
+ */
+export async function writeConfig(updates) {
+    const configPath = getConfigPath();
+    // Never write over a file that did not parse: the merge below would start
+    // from an empty object and replace every setting in it with these updates.
+    if ((await readConfigFile(configPath)).status === 'invalid') {
+        throw new Error(unreadableGlobalConfigMessage(configPath));
+    }
+    // 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 writeConfigFile(configPath, merged);
+}
+/**
+ * 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,39 @@
+/**
+ * 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 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 FreeSpec version
+ */
+export declare function trackCommand(commandName: string, version: string): Promise<void>;
+/**
+ * Show first-run telemetry notice if not already seen.
+ */
+export declare function maybeShowTelemetryNotice(options?: {
+    silent?: boolean;
+}): Promise<void>;
+/**
+ * Flush pending telemetry events.
+ * Call this before CLI exit.
+ */
+export declare function shutdown(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map