@bobby_z/openspec 0.0.1

package/dist/core/completions/command-registry.js

@@ -0,0 +1,454 @@
+/**
+ * Common flags used across multiple commands
+ */
+const COMMON_FLAGS = {
+    json: {
+        name: "json",
+        description: "以 JSON 输出",
+    },
+    jsonValidation: {
+        name: "json",
+        description: "以 JSON 输出校验结果",
+    },
+    strict: {
+        name: "strict",
+        description: "启用严格校验模式",
+    },
+    noInteractive: {
+        name: "no-interactive",
+        description: "关闭交互提示",
+    },
+    type: {
+        name: "type",
+        description: "名称歧义时指定项类型",
+        takesValue: true,
+        values: ["change", "spec"],
+    },
+};
+/**
+ * Registry of all OpenSpec CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export const COMMAND_REGISTRY = [
+    {
+        name: "init",
+        description: "在项目中初始化 OpenSpec",
+        acceptsPositional: true,
+        positionalType: "path",
+        flags: [
+            {
+                name: "tools",
+                description: '非交互配置 AI 工具（如 "all"、"none" 或逗号分隔的工具 ID）',
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: "update",
+        description: "更新 OpenSpec 指令文件",
+        acceptsPositional: true,
+        positionalType: "path",
+        flags: [],
+    },
+    {
+        name: "list",
+        description: "列出项（默认变更，加 --specs 为规范）",
+        flags: [
+            {
+                name: "specs",
+                description: "列出规范而非变更",
+            },
+            {
+                name: "changes",
+                description: "明确列出变更（默认）",
+            },
+        ],
+    },
+    {
+        name: "view",
+        description: "显示规范与变更的交互式总览",
+        flags: [],
+    },
+    {
+        name: "validate",
+        description: "校验变更与规范",
+        acceptsPositional: true,
+        positionalType: "change-or-spec-id",
+        flags: [
+            {
+                name: "all",
+                description: "校验所有变更与规范",
+            },
+            {
+                name: "changes",
+                description: "校验所有变更",
+            },
+            {
+                name: "specs",
+                description: "校验所有规范",
+            },
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.strict,
+            COMMON_FLAGS.jsonValidation,
+            {
+                name: "concurrency",
+                description: "最大并发校验数（默认取 OPENSPEC_CONCURRENCY 或 6）",
+                takesValue: true,
+            },
+            COMMON_FLAGS.noInteractive,
+        ],
+    },
+    {
+        name: "show",
+        description: "显示变更或规范",
+        acceptsPositional: true,
+        positionalType: "change-or-spec-id",
+        flags: [
+            COMMON_FLAGS.json,
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.noInteractive,
+            {
+                name: "deltas-only",
+                description: "仅显示增量（仅 JSON，变更）",
+            },
+            {
+                name: "requirements-only",
+                description: "同 --deltas-only（已弃用，变更）",
+            },
+            {
+                name: "requirements",
+                description: "仅显示需求，不含场景（仅 JSON，规范）",
+            },
+            {
+                name: "no-scenarios",
+                description: "不含场景内容（仅 JSON，规范）",
+            },
+            {
+                name: "requirement",
+                short: "r",
+                description: "按 ID 显示指定需求（仅 JSON，规范）",
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: "archive",
+        description: "归档已完成的变更并更新主规范",
+        acceptsPositional: true,
+        positionalType: "change-id",
+        flags: [
+            {
+                name: "yes",
+                short: "y",
+                description: "跳过确认提示",
+            },
+            {
+                name: "skip-specs",
+                description: "跳过规范更新",
+            },
+            {
+                name: "no-validate",
+                description: "跳过校验（不推荐）",
+            },
+        ],
+    },
+    {
+        name: "feedback",
+        description: "提交 OpenSpec 相关反馈",
+        acceptsPositional: true,
+        flags: [
+            {
+                name: "body",
+                description: "反馈的详细说明",
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: "change",
+        description: "管理 OpenSpec 变更提案（已弃用）",
+        flags: [],
+        subcommands: [
+            {
+                name: "show",
+                description: "显示变更提案",
+                acceptsPositional: true,
+                positionalType: "change-id",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "deltas-only",
+                        description: "仅显示增量（仅 JSON）",
+                    },
+                    {
+                        name: "requirements-only",
+                        description: "同 --deltas-only（已弃用）",
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: "list",
+                description: "列出所有进行中变更（已弃用）",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "long",
+                        description: "显示 id 与标题及数量",
+                    },
+                ],
+            },
+            {
+                name: "validate",
+                description: "校验变更提案",
+                acceptsPositional: true,
+                positionalType: "change-id",
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: "spec",
+        description: "管理 OpenSpec 规范",
+        flags: [],
+        subcommands: [
+            {
+                name: "show",
+                description: "显示规范",
+                acceptsPositional: true,
+                positionalType: "spec-id",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "requirements",
+                        description: "仅显示需求，不含场景（仅 JSON）",
+                    },
+                    {
+                        name: "no-scenarios",
+                        description: "不含场景内容（仅 JSON）",
+                    },
+                    {
+                        name: "requirement",
+                        short: "r",
+                        description: "按 ID 显示指定需求（仅 JSON）",
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: "list",
+                description: "列出所有规范",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "long",
+                        description: "显示 id 与标题及数量",
+                    },
+                ],
+            },
+            {
+                name: "validate",
+                description: "校验规范",
+                acceptsPositional: true,
+                positionalType: "spec-id",
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: "completion",
+        description: "管理 OpenSpec CLI 的 Shell 补全",
+        flags: [],
+        subcommands: [
+            {
+                name: "generate",
+                description: "生成某 Shell 的补全脚本（输出到 stdout）",
+                acceptsPositional: true,
+                positionalType: "shell",
+                flags: [],
+            },
+            {
+                name: "install",
+                description: "为某 Shell 安装补全脚本",
+                acceptsPositional: true,
+                positionalType: "shell",
+                flags: [
+                    {
+                        name: "verbose",
+                        description: "显示详细安装输出",
+                    },
+                ],
+            },
+            {
+                name: "uninstall",
+                description: "卸载某 Shell 的补全脚本",
+                acceptsPositional: true,
+                positionalType: "shell",
+                flags: [
+                    {
+                        name: "yes",
+                        short: "y",
+                        description: "跳过确认提示",
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        name: "config",
+        description: "查看与修改全局 OpenSpec 配置",
+        flags: [
+            {
+                name: "scope",
+                description: '配置范围（当前仅支持 "global"）',
+                takesValue: true,
+                values: ["global"],
+            },
+        ],
+        subcommands: [
+            {
+                name: "path",
+                description: "显示配置文件路径",
+                flags: [],
+            },
+            {
+                name: "list",
+                description: "显示当前所有设置",
+                flags: [COMMON_FLAGS.json],
+            },
+            {
+                name: "get",
+                description: "获取某值（原始、可脚本）",
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: "set",
+                description: "设置某值（自动类型转换）",
+                acceptsPositional: true,
+                flags: [
+                    {
+                        name: "string",
+                        description: "强制按字符串存储",
+                    },
+                    {
+                        name: "allow-unknown",
+                        description: "允许设置未知键",
+                    },
+                ],
+            },
+            {
+                name: "unset",
+                description: "删除某键（恢复默认）",
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: "reset",
+                description: "将配置恢复为默认",
+                flags: [
+                    {
+                        name: "all",
+                        description: "重置全部配置（必填）",
+                    },
+                    {
+                        name: "yes",
+                        short: "y",
+                        description: "跳过确认提示",
+                    },
+                ],
+            },
+            {
+                name: "edit",
+                description: "用 $EDITOR 打开配置",
+                flags: [],
+            },
+        ],
+    },
+    {
+        name: "schema",
+        description: "管理工作流模式",
+        flags: [],
+        subcommands: [
+            {
+                name: "which",
+                description: "显示某模式解析自何处",
+                acceptsPositional: true,
+                positionalType: "schema-name",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "all",
+                        description: "列出所有模式及其解析来源",
+                    },
+                ],
+            },
+            {
+                name: "validate",
+                description: "校验工作流模式结构与模板",
+                acceptsPositional: true,
+                positionalType: "schema-name",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "verbose",
+                        description: "显示详细校验步骤",
+                    },
+                ],
+            },
+            {
+                name: "fork",
+                description: "将已有模式复制到项目以便自定义",
+                acceptsPositional: true,
+                positionalType: "schema-name",
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "force",
+                        description: "覆盖已有目标",
+                    },
+                ],
+            },
+            {
+                name: "init",
+                description: "创建新的项目本地工作流模式",
+                acceptsPositional: true,
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: "description",
+                        description: "模式说明",
+                        takesValue: true,
+                    },
+                    {
+                        name: "artifacts",
+                        description: "逗号分隔的制品 ID",
+                        takesValue: true,
+                    },
+                    {
+                        name: "default",
+                        description: "设为项目默认模式",
+                    },
+                    {
+                        name: "no-default",
+                        description: "不提示设为默认",
+                    },
+                    {
+                        name: "force",
+                        description: "覆盖已有模式",
+                    },
+                ],
+            },
+        ],
+    },
+];
+//# sourceMappingURL=command-registry.js.map

package/dist/core/completions/completion-provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export declare class CompletionProvider {
+    private readonly cacheTTLMs;
+    private readonly projectRoot;
+    private readonly cacheTTL;
+    private changeCache;
+    private specCache;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs?: number, projectRoot?: string);
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    getChangeIds(): Promise<string[]>;
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    getSpecIds(): Promise<string[]>;
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    getAllIds(): Promise<{
+        changeIds: string[];
+        specIds: string[];
+    }>;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats(): {
+        changeCache: {
+            valid: boolean;
+            age?: number;
+        };
+        specCache: {
+            valid: boolean;
+            age?: number;
+        };
+    };
+}
+//# sourceMappingURL=completion-provider.d.ts.map

package/dist/core/completions/completion-provider.js

@@ -0,0 +1,102 @@
+import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
+/**
+ * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export class CompletionProvider {
+    cacheTTLMs;
+    projectRoot;
+    cacheTTL;
+    changeCache = null;
+    specCache = null;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs = 2000, projectRoot = process.cwd()) {
+        this.cacheTTLMs = cacheTTLMs;
+        this.projectRoot = projectRoot;
+        this.cacheTTL = cacheTTLMs;
+    }
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    async getChangeIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.changeCache && now - this.changeCache.timestamp < this.cacheTTL) {
+            return this.changeCache.data;
+        }
+        // Fetch fresh data
+        const changeIds = await getActiveChangeIds(this.projectRoot);
+        // Update cache
+        this.changeCache = {
+            data: changeIds,
+            timestamp: now,
+        };
+        return changeIds;
+    }
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    async getSpecIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.specCache && now - this.specCache.timestamp < this.cacheTTL) {
+            return this.specCache.data;
+        }
+        // Fetch fresh data
+        const specIds = await getSpecIds(this.projectRoot);
+        // Update cache
+        this.specCache = {
+            data: specIds,
+            timestamp: now,
+        };
+        return specIds;
+    }
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    async getAllIds() {
+        const [changeIds, specIds] = await Promise.all([
+            this.getChangeIds(),
+            this.getSpecIds(),
+        ]);
+        return { changeIds, specIds };
+    }
+    /**
+     * Clear all cached data
+     */
+    clearCache() {
+        this.changeCache = null;
+        this.specCache = null;
+    }
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats() {
+        const now = Date.now();
+        return {
+            changeCache: {
+                valid: this.changeCache !== null && now - this.changeCache.timestamp < this.cacheTTL,
+                age: this.changeCache ? now - this.changeCache.timestamp : undefined,
+            },
+            specCache: {
+                valid: this.specCache !== null && now - this.specCache.timestamp < this.cacheTTL,
+                age: this.specCache ? now - this.specCache.timestamp : undefined,
+            },
+        };
+    }
+}
+//# sourceMappingURL=completion-provider.js.map

package/dist/core/completions/factory.d.ts

@@ -0,0 +1,64 @@
+import { CompletionGenerator } from './types.js';
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Common installation result interface
+ */
+export interface InstallationResult {
+    success: boolean;
+    installedPath?: string;
+    backupPath?: string;
+    message: string;
+    instructions?: string[];
+    warnings?: string[];
+    isOhMyZsh?: boolean;
+    zshrcConfigured?: boolean;
+    bashrcConfigured?: boolean;
+    profileConfigured?: boolean;
+}
+/**
+ * Interface for completion installers
+ */
+export interface CompletionInstaller {
+    install(script: string): Promise<InstallationResult>;
+    uninstall(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export declare class CompletionFactory {
+    private static readonly SUPPORTED_SHELLS;
+    /**
+     * Create a completion generator for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionGenerator instance
+     * @throws Error if shell is not supported
+     */
+    static createGenerator(shell: SupportedShell): CompletionGenerator;
+    /**
+     * Create a completion installer for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionInstaller instance
+     * @throws Error if shell is not supported
+     */
+    static createInstaller(shell: SupportedShell): CompletionInstaller;
+    /**
+     * Check if a shell is supported
+     *
+     * @param shell - The shell to check
+     * @returns true if the shell is supported
+     */
+    static isSupported(shell: string): shell is SupportedShell;
+    /**
+     * Get list of all supported shells
+     *
+     * @returns Array of supported shell names
+     */
+    static getSupportedShells(): SupportedShell[];
+}
+//# sourceMappingURL=factory.d.ts.map