spectra-cli 4.1.1

package/dist/utils/file-scanner.d.ts

@@ -0,0 +1,38 @@
+export interface ScanOptions {
+    /** 项目根目录（用于查找 .gitignore） */
+    projectRoot?: string;
+    /** 额外的忽略模式 */
+    extraIgnorePatterns?: string[];
+    /** 显式指定支持的扩展名，覆盖 Registry 默认值 */
+    extensions?: Set<string>;
+}
+/** 单种语言在项目中的文件分布统计 */
+export interface LanguageFileStat {
+    /** 适配器 ID（如 'ts-js', 'python', 'go', 'java'） */
+    adapterId: string;
+    /** 该语言的文件数量 */
+    fileCount: number;
+    /** 该语言涉及的文件扩展名列表（如 ['.ts', '.tsx']） */
+    extensions: string[];
+}
+export interface ScanResult {
+    /** 发现的文件路径列表（相对于扫描目录，排序后） */
+    files: string[];
+    /** 扫描的总文件数（含被忽略的） */
+    totalScanned: number;
+    /** 被忽略的文件数 */
+    ignored: number;
+    /** 不支持的文件扩展名统计 */
+    unsupportedExtensions?: Map<string, number>;
+    /** 各已支持语言的文件统计（key 为 adapter.id） */
+    languageStats?: Map<string, LanguageFileStat>;
+}
+/**
+ * 扫描目录中支持的源文件
+ *
+ * @param targetDir - 扫描的目标目录
+ * @param options - 扫描选项
+ * @returns 排序后的文件路径列表和统计信息
+ */
+export declare function scanFiles(targetDir: string, options?: ScanOptions): ScanResult;
+//# sourceMappingURL=file-scanner.d.ts.map

package/dist/utils/file-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-scanner.d.ts","sourceRoot":"","sources":["../../src/utils/file-scanner.ts"],"names":[],"mappings":"AAwGA,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,iCAAiC;IACjC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,sBAAsB;AACtB,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,qBAAqB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,oCAAoC;IACpC,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAiLD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,UAAU,CAyE9E"}

package/dist/utils/file-scanner.js

@@ -0,0 +1,323 @@
+/**
+ * 文件发现与 .gitignore 过滤
+ * 扫描目录中支持的源文件，遵循 .gitignore 规则（FR-026）
+ * 支持的扩展名从 LanguageAdapterRegistry 动态获取
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { LanguageAdapterRegistry } from '../adapters/language-adapter-registry.js';
+/** 通用忽略目录（与语言无关，始终忽略） */
+const UNIVERSAL_IGNORE_DIRS = new Set([
+    // VCS
+    '.git',
+    // 测试产物和覆盖率
+    'coverage',
+    // 本工具的输出目录
+    'specs',
+    // 构建产物
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    // 第三方打包产物和依赖
+    'vendor',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'env',
+    // 示例/文档代码（通常不是核心源码）
+    'examples',
+    'example',
+    'worked',
+    'fixtures',
+    '__fixtures__',
+    'testdata',
+    'test-fixtures',
+    // CI/CD 和工具配置
+    '.cache',
+    '.parcel-cache',
+    '.turbo',
+]);
+/**
+ * 已知扩展名到语言名称的映射表
+ * 用于不支持语言的友好警告（输出人类可读的语言名称）
+ */
+const KNOWN_LANGUAGE_NAMES = {
+    '.rs': 'Rust',
+    '.cpp': 'C++',
+    '.cc': 'C++',
+    '.cxx': 'C++',
+    '.hpp': 'C++',
+    '.hxx': 'C++',
+    '.c': 'C',
+    '.h': 'C/C++',
+    '.cs': 'C#',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.swift': 'Swift',
+    '.kt': 'Kotlin',
+    '.kts': 'Kotlin',
+    '.scala': 'Scala',
+    '.r': 'R',
+    '.R': 'R',
+    '.pl': 'Perl',
+    '.pm': 'Perl',
+    '.lua': 'Lua',
+    '.hs': 'Haskell',
+    '.erl': 'Erlang',
+    '.ex': 'Elixir',
+    '.exs': 'Elixir',
+    '.clj': 'Clojure',
+    '.dart': 'Dart',
+    '.m': 'Objective-C',
+    '.mm': 'Objective-C++',
+    '.zig': 'Zig',
+    '.nim': 'Nim',
+    '.v': 'V',
+    '.ml': 'OCaml',
+    '.fs': 'F#',
+    '.fsx': 'F#',
+    '.groovy': 'Groovy',
+    '.jl': 'Julia',
+};
+/**
+ * 获取当前有效的忽略目录集合
+ * 合并通用忽略目录与 Registry 聚合的适配器忽略目录
+ */
+function getIgnoreDirs() {
+    const registryDirs = LanguageAdapterRegistry.getInstance().getDefaultIgnoreDirs();
+    return new Set([...UNIVERSAL_IGNORE_DIRS, ...registryDirs]);
+}
+/**
+ * 获取当前有效的支持扩展名集合
+ * 优先使用调用方显式传入的扩展名，否则从 Registry 动态获取
+ */
+function getSupportedExtensions(options) {
+    if (options?.extensions)
+        return options.extensions;
+    return LanguageAdapterRegistry.getInstance().getSupportedExtensions();
+}
+/**
+ * 解析 .gitignore 文件，返回匹配函数
+ * 支持基本的 gitignore 模式：目录、通配符、否定
+ */
+function parseGitignore(gitignorePath) {
+    if (!fs.existsSync(gitignorePath)) {
+        return () => false;
+    }
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    const patterns = [];
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        // 跳过空行和注释
+        if (!line || line.startsWith('#'))
+            continue;
+        let negate = false;
+        let pattern = line;
+        // 否定模式
+        if (pattern.startsWith('!')) {
+            negate = true;
+            pattern = pattern.slice(1);
+        }
+        // 去除尾部斜杠（目录标记），但记住它是目录模式
+        const isDirPattern = pattern.endsWith('/');
+        if (isDirPattern) {
+            pattern = pattern.slice(0, -1);
+        }
+        // 转换 glob 模式为正则
+        const regexStr = globToRegex(pattern, isDirPattern);
+        patterns.push({ pattern: new RegExp(regexStr), negate });
+    }
+    return (relativePath) => {
+        let ignored = false;
+        for (const { pattern, negate } of patterns) {
+            if (pattern.test(relativePath)) {
+                ignored = !negate;
+            }
+        }
+        return ignored;
+    };
+}
+/**
+ * 将简单 glob 模式转换为正则表达式
+ */
+function globToRegex(pattern, isDirPattern) {
+    let regex = '';
+    // 如果模式不包含 /，则匹配任何路径层级中的文件名
+    const matchAnywhere = !pattern.includes('/');
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === '*') {
+            if (pattern[i + 1] === '*') {
+                // ** 匹配任意路径
+                regex += '.*';
+                i++; // 跳过第二个 *
+                if (pattern[i + 1] === '/') {
+                    i++; // 跳过 /
+                }
+            }
+            else {
+                // * 匹配非 / 的字符
+                regex += '[^/]*';
+            }
+        }
+        else if (char === '?') {
+            regex += '[^/]';
+        }
+        else if (char === '.') {
+            regex += '\\.';
+        }
+        else {
+            regex += char;
+        }
+    }
+    if (matchAnywhere) {
+        // 匹配路径任意位置：作为完整路径段或文件名
+        if (isDirPattern) {
+            return `(^|/)${regex}(/|$)`;
+        }
+        return `(^|/)${regex}$`;
+    }
+    // 以 / 开头的模式只匹配根路径
+    if (isDirPattern) {
+        return `^${regex}(/|$)`;
+    }
+    return `^${regex}$`;
+}
+/**
+ * 递归扫描目录，收集符合条件的文件
+ */
+function walkDir(dir, baseDir, isIgnored, supportedExtensions, ignoreDirs, results, stats, unsupported, languageStats) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        // 无法读取的目录静默跳过
+        return;
+    }
+    const registry = LanguageAdapterRegistry.getInstance();
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(baseDir, fullPath);
+        // 跳过忽略目录（通用 + Registry 聚合）
+        if (entry.isDirectory() && ignoreDirs.has(entry.name)) {
+            continue;
+        }
+        // 跳过符号链接
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        // 检查 .gitignore 规则
+        if (isIgnored(relativePath)) {
+            stats.ignored++;
+            continue;
+        }
+        if (entry.isDirectory()) {
+            walkDir(fullPath, baseDir, isIgnored, supportedExtensions, ignoreDirs, results, stats, unsupported, languageStats);
+        }
+        else if (entry.isFile()) {
+            stats.totalScanned++;
+            const ext = path.extname(entry.name).toLowerCase();
+            if (supportedExtensions.has(ext)) {
+                results.push(relativePath);
+                // 累加 languageStats（按 adapter.id 分组）
+                const adapter = registry.getAdapter(entry.name);
+                if (adapter) {
+                    const existing = languageStats.get(adapter.id);
+                    if (existing) {
+                        existing.fileCount++;
+                        if (!existing.extensions.includes(ext)) {
+                            existing.extensions.push(ext);
+                        }
+                    }
+                    else {
+                        languageStats.set(adapter.id, {
+                            adapterId: adapter.id,
+                            fileCount: 1,
+                            extensions: [ext],
+                        });
+                    }
+                }
+            }
+            else {
+                stats.ignored++;
+                // 收集不支持的扩展名统计（仅统计有扩展名的文件）
+                if (ext) {
+                    unsupported.set(ext, (unsupported.get(ext) ?? 0) + 1);
+                }
+            }
+        }
+    }
+}
+/**
+ * 扫描目录中支持的源文件
+ *
+ * @param targetDir - 扫描的目标目录
+ * @param options - 扫描选项
+ * @returns 排序后的文件路径列表和统计信息
+ */
+export function scanFiles(targetDir, options) {
+    const resolvedDir = path.resolve(targetDir);
+    if (!fs.existsSync(resolvedDir)) {
+        throw new Error(`目录不存在: ${resolvedDir}`);
+    }
+    if (!fs.statSync(resolvedDir).isDirectory()) {
+        throw new Error(`路径不是目录: ${resolvedDir}`);
+    }
+    // FR-034: Registry 未初始化时给出明确提示
+    const registry = LanguageAdapterRegistry.getInstance();
+    if (registry.isEmpty() && !options?.extensions) {
+        throw new Error('LanguageAdapterRegistry 未注册任何适配器。' +
+            '请在使用前调用 bootstrapAdapters() 完成初始化。');
+    }
+    // 获取当前有效的支持扩展名和忽略目录
+    const supportedExtensions = getSupportedExtensions(options);
+    const ignoreDirs = getIgnoreDirs();
+    // 解析 .gitignore
+    const projectRoot = options?.projectRoot ?? resolvedDir;
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const gitignoreCheck = parseGitignore(gitignorePath);
+    // 合并额外忽略模式
+    const extraPatterns = (options?.extraIgnorePatterns ?? []).map((p) => {
+        const regex = globToRegex(p, false);
+        return new RegExp(regex);
+    });
+    const isIgnored = (relativePath) => {
+        if (gitignoreCheck(relativePath))
+            return true;
+        return extraPatterns.some((r) => r.test(relativePath));
+    };
+    const files = [];
+    const stats = { totalScanned: 0, ignored: 0 };
+    const unsupportedExtensions = new Map();
+    const languageStats = new Map();
+    walkDir(resolvedDir, resolvedDir, isIgnored, supportedExtensions, ignoreDirs, files, stats, unsupportedExtensions, languageStats);
+    // 按字母排序
+    files.sort();
+    // 输出不支持文件的 warn 级聚合提示到 stderr（含语言名称）
+    if (unsupportedExtensions.size > 0) {
+        // 按文件数降序排列
+        const sorted = [...unsupportedExtensions.entries()].sort((a, b) => b[1] - a[1]);
+        const parts = [];
+        for (const [ext, count] of sorted) {
+            const langName = KNOWN_LANGUAGE_NAMES[ext];
+            if (langName) {
+                parts.push(`${count} 个 ${ext} 文件（${langName}，不支持）`);
+            }
+            else {
+                parts.push(`${count} 个 ${ext} 文件（不支持）`);
+            }
+        }
+        console.warn(`\u26A0 跳过 ${parts.join('、')}`);
+    }
+    return {
+        files,
+        totalScanned: stats.totalScanned,
+        ignored: stats.ignored,
+        unsupportedExtensions: unsupportedExtensions.size > 0 ? unsupportedExtensions : undefined,
+        languageStats: languageStats.size > 0 ? languageStats : undefined,
+    };
+}
+//# sourceMappingURL=file-scanner.js.map

package/dist/utils/file-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-scanner.js","sourceRoot":"","sources":["../../src/utils/file-scanner.ts"],"names":[],"mappings":"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"}

package/dist/utils/git-blame.d.ts

@@ -0,0 +1,32 @@
+export interface BlameInfo {
+    /** commit 作者；uncommitted 或任何错误场景为 "uncommitted" */
+    author: string;
+    /** commit UTC 时间；uncommitted 或错误场景为 null */
+    commitDate: Date | null;
+    /** commit 距今天数；uncommitted 或错误场景为 0 */
+    ageDays: number;
+}
+/** 单文件的行号 → BlameInfo 映射 */
+type FileBlameMap = Map<number, BlameInfo>;
+/**
+ * 重置所有缓存（仅给测试使用）
+ */
+export declare function resetBlameCache(): void;
+/**
+ * 查询指定文件 指定行的 blame。
+ * 任何失败都返回 uncommitted 占位。
+ *
+ * @param filePath 绝对路径推荐；相对路径会按 process.cwd() 解析
+ * @param line 1-indexed 行号
+ */
+export declare function getLineBlame(filePath: string, line: number): Promise<BlameInfo>;
+/**
+ * 解析 git blame --porcelain 输出。
+ * Porcelain 格式每个 chunk：
+ *   <sha> <origLine> <finalLine> [numLines]
+ *   header key value 行（author / author-time / author-tz / summary / previous / filename）
+ *   \t<source line>
+ */
+export declare function parsePorcelain(raw: string, out: FileBlameMap): void;
+export {};
+//# sourceMappingURL=git-blame.d.ts.map

package/dist/utils/git-blame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-blame.d.ts","sourceRoot":"","sources":["../../src/utils/git-blame.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,4BAA4B;AAC5B,KAAK,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAK3C;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAWrF;AAsBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAkDnE"}

package/dist/utils/git-blame.js

@@ -0,0 +1,151 @@
+/**
+ * Git blame 轻量 wrapper
+ *
+ * 用于 debt-scanner 为每条 TODO/FIXME 条目解析 author 与 age。
+ * 任何失败（非 git 仓库、文件未追踪、git 不存在等）都返回
+ * `{ author: 'uncommitted', commitDate: null, ageDays: 0 }`，绝不抛出异常。
+ *
+ * 性能：按 filePath 缓存一次 `git blame --porcelain <file>` 的完整解析结果，
+ * 多次 getLineBlame 调用只做内存 map 查找。
+ */
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+const UNCOMMITTED = Object.freeze({
+    author: 'uncommitted',
+    commitDate: null,
+    ageDays: 0,
+});
+/** 全局缓存：绝对路径 → 该文件所有行的 blame */
+const fileCache = new Map();
+/**
+ * 重置所有缓存（仅给测试使用）
+ */
+export function resetBlameCache() {
+    fileCache.clear();
+}
+/**
+ * 查询指定文件 指定行的 blame。
+ * 任何失败都返回 uncommitted 占位。
+ *
+ * @param filePath 绝对路径推荐；相对路径会按 process.cwd() 解析
+ * @param line 1-indexed 行号
+ */
+export async function getLineBlame(filePath, line) {
+    const absPath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(process.cwd(), filePath);
+    let cached = fileCache.get(absPath);
+    if (!cached) {
+        cached = await loadFileBlame(absPath);
+        fileCache.set(absPath, cached);
+    }
+    return cached.get(line) ?? { ...UNCOMMITTED };
+}
+/**
+ * 执行 git blame --porcelain 并把结果解析为 line → BlameInfo。
+ * 任何错误返回空 Map（调用方会回退到 uncommitted）。
+ */
+async function loadFileBlame(absFilePath) {
+    const dir = path.dirname(absFilePath);
+    const out = new Map();
+    let raw;
+    try {
+        raw = await runGit(['blame', '--porcelain', absFilePath], dir);
+    }
+    catch {
+        // 非 git 仓库、git 未安装、文件未 committed 等
+        return out;
+    }
+    parsePorcelain(raw, out);
+    return out;
+}
+/**
+ * 解析 git blame --porcelain 输出。
+ * Porcelain 格式每个 chunk：
+ *   <sha> <origLine> <finalLine> [numLines]
+ *   header key value 行（author / author-time / author-tz / summary / previous / filename）
+ *   \t<source line>
+ */
+export function parsePorcelain(raw, out) {
+    const lines = raw.split('\n');
+    // headers-by-sha 缓存；porcelain 对同一 sha 的后续 chunk 只给 header 子集
+    const headersBySha = new Map();
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // chunk 开头行形如 "<sha> <orig> <final> [count]"
+        const headerMatch = /^([0-9a-f]{7,40}) (\d+) (\d+)(?: (\d+))?$/.exec(line);
+        if (!headerMatch) {
+            i++;
+            continue;
+        }
+        const sha = headerMatch[1];
+        const finalLine = parseInt(headerMatch[3], 10);
+        const count = headerMatch[4] ? parseInt(headerMatch[4], 10) : 1;
+        let author = headersBySha.get(sha)?.author ?? '';
+        let authorTime = headersBySha.get(sha)?.authorTime ?? null;
+        // 读取 header 行，直到遇到 \t<source> 行
+        i++;
+        while (i < lines.length && !lines[i].startsWith('\t')) {
+            const h = lines[i];
+            if (h.startsWith('author '))
+                author = h.slice('author '.length).trim();
+            else if (h.startsWith('author-time ')) {
+                const ts = parseInt(h.slice('author-time '.length).trim(), 10);
+                if (Number.isFinite(ts))
+                    authorTime = ts;
+            }
+            i++;
+        }
+        // 跳过 \t<source>
+        if (i < lines.length && lines[i].startsWith('\t')) {
+            i++;
+        }
+        headersBySha.set(sha, { author, authorTime });
+        // 生成 BlameInfo
+        // 对 uncommitted（所有 0 的 sha，git 通常是 40 个 0）
+        const isUncommitted = /^0+$/.test(sha);
+        const info = isUncommitted
+            ? { ...UNCOMMITTED }
+            : buildBlameInfo(author, authorTime);
+        for (let n = 0; n < count; n++) {
+            out.set(finalLine + n, info);
+        }
+    }
+}
+function buildBlameInfo(author, authorTime) {
+    const commitDate = authorTime != null ? new Date(authorTime * 1000) : null;
+    const ageDays = commitDate
+        ? Math.max(0, Math.floor((Date.now() - commitDate.getTime()) / 86_400_000))
+        : 0;
+    return {
+        author: author || 'uncommitted',
+        commitDate,
+        ageDays,
+    };
+}
+/**
+ * 启动 git 子进程，返回 stdout。非零退出或错误抛出异常。
+ * 调用方应 try/catch 并回退到 uncommitted。
+ */
+function runGit(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => reject(err));
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`git exited with ${code}: ${stderr.trim()}`));
+        });
+    });
+}
+//# sourceMappingURL=git-blame.js.map

package/dist/utils/git-blame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-blame.js","sourceRoot":"","sources":["../../src/utils/git-blame.ts"],"names":[],"mappings":"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"}

package/dist/utils/specify-template-sync.d.ts

@@ -0,0 +1,16 @@
+export interface EnsureSpecifyTemplatesResult {
+    copied: string[];
+    missing: string[];
+}
+export interface EnsureSpecifyTemplatesOptions {
+    /**
+     * 模板源目录列表（按优先级）。
+     * 默认自动探测 package 内置路径和开发态路径。
+     */
+    sourceDirs?: string[];
+}
+/**
+ * 确保项目 .specify/templates 基础模板存在（幂等）。
+ */
+export declare function ensureSpecifyTemplates(projectRoot: string, options?: EnsureSpecifyTemplatesOptions): EnsureSpecifyTemplatesResult;
+//# sourceMappingURL=specify-template-sync.d.ts.map

package/dist/utils/specify-template-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specify-template-sync.d.ts","sourceRoot":"","sources":["../../src/utils/specify-template-sync.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AA2BD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CAyB9B"}

package/dist/utils/specify-template-sync.js

@@ -0,0 +1,66 @@
+/**
+ * .specify/templates 基础模板同步器
+ * 用于首次运行时自动补齐 Spec Driver 依赖的模板文件。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const REQUIRED_TEMPLATES = [
+    'plan-template.md',
+    'spec-template.md',
+    'tasks-template.md',
+    'checklist-template.md',
+    'constitution-template.md',
+    'agent-file-template.md',
+    // 调研模板（FR-001: 纳入同步体系）
+    'product-research-template.md',
+    'tech-research-template.md',
+    'research-synthesis-template.md',
+    'verification-report-template.md',
+];
+function getDefaultSourceDirs() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    return [
+        // 运行态（dist/ -> package root）
+        path.resolve(__dirname, '../../plugins/spec-driver/templates/specify-base'),
+        // 开发态兜底（仓库根 .specify/templates）
+        path.resolve(__dirname, '../../.specify/templates'),
+        // 当前项目内置（若项目自身 vendored 了 spec-driver）
+        path.resolve(process.cwd(), 'plugins/spec-driver/templates/specify-base'),
+    ];
+}
+function resolveTemplateSource(templateName, sourceDirs) {
+    for (const dir of sourceDirs) {
+        const candidate = path.join(dir, templateName);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * 确保项目 .specify/templates 基础模板存在（幂等）。
+ */
+export function ensureSpecifyTemplates(projectRoot, options = {}) {
+    const sourceDirs = options.sourceDirs ?? getDefaultSourceDirs();
+    const targetDir = path.join(projectRoot, '.specify', 'templates');
+    fs.mkdirSync(targetDir, { recursive: true });
+    const copied = [];
+    const missing = [];
+    for (const templateName of REQUIRED_TEMPLATES) {
+        const targetPath = path.join(targetDir, templateName);
+        if (fs.existsSync(targetPath)) {
+            continue;
+        }
+        const sourcePath = resolveTemplateSource(templateName, sourceDirs);
+        if (!sourcePath) {
+            missing.push(templateName);
+            continue;
+        }
+        fs.copyFileSync(sourcePath, targetPath);
+        copied.push(templateName);
+    }
+    return { copied, missing };
+}
+//# sourceMappingURL=specify-template-sync.js.map