@bobby_z/openspec 0.0.1

package/dist/cli/index.js

@@ -0,0 +1,482 @@
+import { Command } from "commander";
+import { createRequire } from "module";
+import ora from "ora";
+import path from "path";
+import { promises as fs } from "fs";
+import { AI_TOOLS } from "../core/config.js";
+import { UpdateCommand } from "../core/update.js";
+import { ListCommand } from "../core/list.js";
+import { ArchiveCommand } from "../core/archive.js";
+import { ViewCommand } from "../core/view.js";
+import { registerSpecCommand } from "../commands/spec.js";
+import { ChangeCommand } from "../commands/change.js";
+import { ValidateCommand } from "../commands/validate.js";
+import { ShowCommand } from "../commands/show.js";
+import { CompletionCommand } from "../commands/completion.js";
+import { FeedbackCommand } from "../commands/feedback.js";
+import { registerConfigCommand } from "../commands/config.js";
+import { registerSchemaCommand } from "../commands/schema.js";
+import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from "../commands/workflow/index.js";
+import { maybeShowTelemetryNotice, trackCommand, shutdown, } from "../telemetry/index.js";
+const program = new Command();
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+/**
+ * Get the full command path for nested commands.
+ * For example: 'change show' -> 'change:show'
+ */
+function getCommandPath(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        // Skip the root 'openspec' command
+        if (name && name !== "openspec") {
+            names.unshift(name);
+        }
+        current = current.parent;
+    }
+    return names.join(":") || "openspec";
+}
+program
+    .name("openspec")
+    .description("面向规范驱动的 AI 原生开发系统")
+    .version(version);
+// Global options
+program.option("--no-color", "关闭彩色输出");
+// Apply global flags and telemetry before any command runs
+// Note: preAction receives (thisCommand, actionCommand) where:
+// - thisCommand: the command where hook was added (root program)
+// - actionCommand: the command actually being executed (subcommand)
+program.hook("preAction", async (thisCommand, actionCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.color === false) {
+        process.env.NO_COLOR = "1";
+    }
+    // Show first-run telemetry notice (if not seen)
+    await maybeShowTelemetryNotice();
+    // Track command execution (use actionCommand to get the actual subcommand)
+    const commandPath = getCommandPath(actionCommand);
+    await trackCommand(commandPath, version);
+});
+// Shutdown telemetry after command completes
+program.hook("postAction", async () => {
+    await shutdown();
+});
+const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
+const toolsOptionDescription = `非交互配置 AI 工具。可选 "all"、"none" 或逗号分隔列表：${availableToolIds.join(", ")}`;
+program
+    .command("init [path]")
+    .description("在项目中初始化 OpenSpec")
+    .option("--tools <tools>", toolsOptionDescription)
+    .option("--force", "自动清理旧版文件且不提示")
+    .action(async (targetPath = ".", options) => {
+    try {
+        // Validate that the path is a valid directory
+        const resolvedPath = path.resolve(targetPath);
+        try {
+            const stats = await fs.stat(resolvedPath);
+            if (!stats.isDirectory()) {
+                throw new Error(`路径 "${targetPath}" 不是目录`);
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                // Directory doesn't exist, but we can create it
+                console.log(`目录 "${targetPath}" 不存在，将自动创建。`);
+            }
+            else if (error.message &&
+                (error.message.includes("不是目录") ||
+                    error.message.includes("not a directory"))) {
+                throw error;
+            }
+            else {
+                throw new Error(`无法访问路径 "${targetPath}": ${error.message}`);
+            }
+        }
+        const { InitCommand } = await import("../core/init.js");
+        const initCommand = new InitCommand({
+            tools: options?.tools,
+            force: options?.force,
+        });
+        await initCommand.execute(targetPath);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Hidden alias: 'experimental' -> 'init' for backwards compatibility
+program
+    .command("experimental", { hidden: true })
+    .description("init 的别名（已弃用）")
+    .option("--tool <tool-id>", "目标 AI 工具（等同于 --tools）")
+    .option("--no-interactive", "关闭交互提示")
+    .action(async (options) => {
+    try {
+        console.log('提示："openspec experimental" 已弃用，请改用 "openspec init"。');
+        const { InitCommand } = await import("../core/init.js");
+        const initCommand = new InitCommand({
+            tools: options?.tool,
+            interactive: options?.noInteractive === true ? false : undefined,
+        });
+        await initCommand.execute(".");
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command("update [path]")
+    .description("更新 OpenSpec 指令文件")
+    .option("--force", "即使工具已是最新也强制更新")
+    .action(async (targetPath = ".", options) => {
+    try {
+        const resolvedPath = path.resolve(targetPath);
+        const updateCommand = new UpdateCommand({ force: options?.force });
+        await updateCommand.execute(resolvedPath);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command("list")
+    .description("列出项（默认为变更）。使用 --specs 列出规范。")
+    .option("--specs", "列出规范而非变更")
+    .option("--changes", "明确列出变更（默认）")
+    .option("--sort <order>", "排序：recent（默认）或 name", "recent")
+    .option("--json", "以 JSON 输出（供程序使用）")
+    .action(async (options) => {
+    try {
+        const listCommand = new ListCommand();
+        const mode = options?.specs ? "specs" : "changes";
+        const sort = options?.sort === "name" ? "name" : "recent";
+        await listCommand.execute(".", mode, { sort, json: options?.json });
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command("view")
+    .description("显示规范与变更的交互式总览")
+    .action(async () => {
+    try {
+        const viewCommand = new ViewCommand();
+        await viewCommand.execute(".");
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Change command with subcommands
+const changeCmd = program
+    .command("change")
+    .description("管理 OpenSpec 变更提案");
+// Deprecation notice for noun-based commands
+changeCmd.hook("preAction", () => {
+    console.error('警告："openspec change ..." 命令已弃用，请使用动词优先命令（如 "openspec list"、"openspec validate --changes"）。');
+});
+changeCmd
+    .command("show [change-name]")
+    .description("以 JSON 或 Markdown 显示变更提案")
+    .option("--json", "输出 JSON")
+    .option("--deltas-only", "仅显示增量（仅 JSON）")
+    .option("--requirements-only", "同 --deltas-only（已弃用）")
+    .option("--no-interactive", "关闭交互提示")
+    .action(async (changeName, options) => {
+    try {
+        const changeCommand = new ChangeCommand();
+        await changeCommand.show(changeName, options);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+changeCmd
+    .command("list")
+    .description('列出所有进行中变更（已弃用：请用 "openspec list"）')
+    .option("--json", "输出 JSON")
+    .option("--long", "显示 id 与标题及数量")
+    .action(async (options) => {
+    try {
+        console.error('警告："openspec change list" 已弃用，请使用 "openspec list"。');
+        const changeCommand = new ChangeCommand();
+        await changeCommand.list(options);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+changeCmd
+    .command("validate [change-name]")
+    .description("校验变更提案")
+    .option("--strict", "启用严格校验模式")
+    .option("--json", "以 JSON 输出校验报告")
+    .option("--no-interactive", "关闭交互提示")
+    .action(async (changeName, options) => {
+    try {
+        const changeCommand = new ChangeCommand();
+        await changeCommand.validate(changeName, options);
+        if (typeof process.exitCode === "number" && process.exitCode !== 0) {
+            process.exit(process.exitCode);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("archive [change-name]")
+    .description("归档已完成的变更并更新主规范")
+    .option("-y, --yes", "跳过确认提示")
+    .option("--skip-specs", "跳过规范更新（适用于基础设施、工具或仅文档类变更）")
+    .option("--no-validate", "跳过校验（不推荐，需确认）")
+    .action(async (changeName, options) => {
+    try {
+        const archiveCommand = new ArchiveCommand();
+        await archiveCommand.execute(changeName, options);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+registerSpecCommand(program);
+registerConfigCommand(program);
+registerSchemaCommand(program);
+// Top-level validate command
+program
+    .command("validate [item-name]")
+    .description("校验变更与规范")
+    .option("--all", "校验所有变更与规范")
+    .option("--changes", "校验所有变更")
+    .option("--specs", "校验所有规范")
+    .option("--type <type>", "名称歧义时指定类型：change|spec")
+    .option("--strict", "启用严格校验模式")
+    .option("--json", "以 JSON 输出校验结果")
+    .option("--concurrency <n>", "最大并发校验数（默认取 OPENSPEC_CONCURRENCY 或 6）")
+    .option("--no-interactive", "关闭交互提示")
+    .action(async (itemName, options) => {
+    try {
+        const validateCommand = new ValidateCommand();
+        await validateCommand.execute(itemName, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Top-level show command
+program
+    .command("show [item-name]")
+    .description("显示变更或规范")
+    .option("--json", "输出 JSON")
+    .option("--type <type>", "名称歧义时指定类型：change|spec")
+    .option("--no-interactive", "关闭交互提示")
+    // change-only flags
+    .option("--deltas-only", "仅显示增量（仅 JSON，变更）")
+    .option("--requirements-only", "同 --deltas-only（已弃用，变更）")
+    // spec-only flags
+    .option("--requirements", "仅 JSON：仅显示需求（不含场景）")
+    .option("--no-scenarios", "仅 JSON：不含场景内容")
+    .option("-r, --requirement <id>", "仅 JSON：按 ID 显示指定需求（从 1 起）")
+    // allow unknown options to pass-through to underlying command implementation
+    .allowUnknownOption(true)
+    .action(async (itemName, options) => {
+    try {
+        const showCommand = new ShowCommand();
+        await showCommand.execute(itemName, options ?? {});
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Feedback command
+program
+    .command("feedback <message>")
+    .description("提交 OpenSpec 相关反馈")
+    .option("--body <text>", "反馈的详细说明")
+    .action(async (message, options) => {
+    try {
+        const feedbackCommand = new FeedbackCommand();
+        await feedbackCommand.execute(message, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Completion command with subcommands
+const completionCmd = program
+    .command("completion")
+    .description("管理 OpenSpec CLI 的 Shell 补全");
+completionCmd
+    .command("generate [shell]")
+    .description("生成某 Shell 的补全脚本（输出到 stdout）")
+    .action(async (shell) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.generate({ shell });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command("install [shell]")
+    .description("为某 Shell 安装补全脚本")
+    .option("--verbose", "显示详细安装输出")
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.install({ shell, verbose: options?.verbose });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command("uninstall [shell]")
+    .description("卸载某 Shell 的补全脚本")
+    .option("-y, --yes", "跳过确认提示")
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.uninstall({ shell, yes: options?.yes });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Hidden command for machine-readable completion data
+program
+    .command("__complete <type>", { hidden: true })
+    .description("以机器可读格式输出补全数据（内部使用）")
+    .action(async (type) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.complete({ type });
+    }
+    catch (error) {
+        // Silently fail for graceful shell completion experience
+        process.exitCode = 1;
+    }
+});
+// ═══════════════════════════════════════════════════════════
+// Workflow Commands (formerly experimental)
+// ═══════════════════════════════════════════════════════════
+// Status command
+program
+    .command("status")
+    .description("显示某变更的制品完成状态")
+    .option("--change <id>", "要查看状态的变更名")
+    .option("--schema <name>", "工作流模式覆盖（默认从 config.yaml 检测）")
+    .option("--json", "输出 JSON")
+    .action(async (options) => {
+    try {
+        await statusCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Instructions command
+program
+    .command("instructions [artifact]")
+    .description("输出创建制品或实施任务的增强指引")
+    .option("--change <id>", "变更名")
+    .option("--schema <name>", "工作流模式覆盖（默认从 config.yaml 检测）")
+    .option("--json", "输出 JSON")
+    .action(async (artifactId, options) => {
+    try {
+        // Special case: "apply" is not an artifact, but a command to get apply instructions
+        if (artifactId === "apply") {
+            await applyInstructionsCommand(options);
+        }
+        else {
+            await instructionsCommand(artifactId, options);
+        }
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Templates command
+program
+    .command("templates")
+    .description("显示某工作流模式中所有制品的解析后模板路径")
+    .option("--schema <name>", `使用的工作流模式（默认：${DEFAULT_SCHEMA}）`)
+    .option("--json", "以 JSON 输出制品 ID 到模板路径的映射")
+    .action(async (options) => {
+    try {
+        await templatesCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Schemas command
+program
+    .command("schemas")
+    .description("列出可用工作流模式及说明")
+    .option("--json", "输出 JSON（供 Agent 使用）")
+    .action(async (options) => {
+    try {
+        await schemasCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// New command group with change subcommand
+const newCmd = program.command("new").description("创建新项");
+newCmd
+    .command("change <name>")
+    .description("创建新的变更目录")
+    .option("--description <text>", "写入 README.md 的说明")
+    .option("--schema <name>", `使用的工作流模式（默认：${DEFAULT_SCHEMA}）`)
+    .action(async (name, options) => {
+    try {
+        await newChangeCommand(name, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/commands/change.d.ts

@@ -0,0 +1,35 @@
+export declare class ChangeCommand {
+    private converter;
+    constructor();
+    /**
+     * Show a change proposal.
+     * - Text mode: raw markdown passthrough (no filters)
+     * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+     *   Note: --requirements-only is deprecated alias for --deltas-only
+     */
+    show(changeName?: string, options?: {
+        json?: boolean;
+        requirementsOnly?: boolean;
+        deltasOnly?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    /**
+     * List active changes.
+     * - Text default: IDs only; --long prints minimal details (title, counts)
+     * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+     */
+    list(options?: {
+        json?: boolean;
+        long?: boolean;
+    }): Promise<void>;
+    validate(changeName?: string, options?: {
+        strict?: boolean;
+        json?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    private getActiveChanges;
+    private extractTitle;
+    private countTasks;
+    private printNextSteps;
+}
+//# sourceMappingURL=change.d.ts.map