autosnippet 3.3.5 → 3.3.7

package/dist/lib/service/cleanup/CleanupService.js

@@ -0,0 +1,571 @@
+/**
+ * CleanupService — 统一数据清理策略（垃圾桶模式）
+ *
+ * 提供两种清理模式:
+ *   - fullReset(): 全量清理 — 将旧数据打包到时间戳垃圾桶文件夹，DB 表清空
+ *   - rescanClean(): Rescan 清理 — 保留 Recipe，清除衍生缓存
+ *   - snapshotRecipes(): 快照当前活跃 Recipe 信息
+ *   - purgeExpiredTrash(): 清除超时限的垃圾桶文件夹
+ *
+ * 垃圾桶设计:
+ *   - 位于 .autosnippet/.trash/<ISO-timestamp>/ 下
+ *   - fullReset 时先将 candidates/ recipes/ skills/ wiki/ 移入垃圾桶，再清 DB
+ *   - DB 数据导出为 db-snapshot.jsonl 保存在垃圾桶内
+ *   - 超过保留天数(默认 7 天)的垃圾桶在下次 fullReset 或服务启动时自动清除
+ *   - 暂不提供恢复功能（需要 merge 处理过于复杂）
+ *
+ * 保留原则:
+ *   - 配置数据 (config.json, constitution.yaml, boxspec.json) 永不清理
+ *   - IDE 集成配置 (.vscode/, .cursor/, .github/) 永不清理
+ *   - 交付物 (.cursor/rules/autosnippet-*) 由 R4 重建，不在此清理
+ *
+ * @module service/cleanup/CleanupService
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CANDIDATES_DIR } from '#infra/config/Defaults.js';
+import { getContextIndexPath, getProjectKnowledgePath, getProjectRecipesPath, getProjectSkillsPath, } from '#infra/config/Paths.js';
+// ── 常量 ────────────────────────────────────────────────────
+/** 垃圾桶根目录（相对于 .autosnippet/） */
+const TRASH_DIR = '.trash';
+/** 垃圾桶保留天数，超过后自动 purge */
+const TRASH_RETENTION_DAYS = 7;
+/** DB 快照文件名 */
+const DB_SNAPSHOT_FILE = 'db-snapshot.jsonl';
+/**
+ * fullReset 时清除的所有 DB 表（不含 schema_migrations）
+ *
+ * ⚠️ 顺序重要：子表必须排在父表之前，否则 FK 约束会阻止 DELETE。
+ *   lifecycle_transition_events → knowledge_entries, evolution_proposals
+ *   evolution_proposals         → knowledge_entries
+ *   recipe_source_refs          → knowledge_entries (CASCADE)
+ *   bootstrap_dim_files         → bootstrap_snapshots (CASCADE)
+ */
+const ALL_DATA_TABLES = [
+    // ── FK 子表先删 ──
+    'lifecycle_transition_events',
+    'recipe_source_refs',
+    'evolution_proposals',
+    'knowledge_edges',
+    'bootstrap_dim_files',
+    // ── 父表后删 ──
+    'knowledge_entries',
+    'bootstrap_snapshots',
+    // ── 无 FK 依赖 ──
+    'guard_violations',
+    'audit_logs',
+    'sessions',
+    'semantic_memories',
+    'code_entities',
+    'remote_commands',
+    'remote_state',
+];
+/** rescanClean 时清除的 DB 表（保留知识/进化相关表） */
+const RESCAN_CLEAN_TABLES = [
+    'bootstrap_dim_files', // FK → bootstrap_snapshots, 先删
+    'recipe_source_refs', // FK → knowledge_entries, 先删
+    'bootstrap_snapshots',
+    'code_entities',
+    'guard_violations',
+    'semantic_memories',
+    'sessions',
+    'audit_logs',
+    'remote_commands',
+    'remote_state',
+];
+// ── CleanupService ──────────────────────────────────────────
+export class CleanupService {
+    #projectRoot;
+    #logger;
+    #db;
+    constructor(opts) {
+        this.#projectRoot = opts.projectRoot;
+        this.#logger = opts.logger || { info() { }, warn() { } };
+        this.#db = opts.db
+            ? typeof opts.db?.getDb === 'function'
+                ? opts.db.getDb()
+                : opts.db
+            : null;
+    }
+    /** 更新 DB 引用（fullReset 后重连时调用） */
+    setDb(db) {
+        this.#db = db
+            ? typeof db?.getDb === 'function'
+                ? db.getDb()
+                : db
+            : null;
+    }
+    // ─── 需求 A：全量清理（垃圾桶模式） ────────────────────
+    /**
+     * 全量清理 — 用于 bootstrap 冷启动（垃圾桶模式）
+     *
+     * 流程:
+     *   1. 先清除过期垃圾桶（超过 TRASH_RETENTION_DAYS）
+     *   2. 创建时间戳垃圾桶文件夹
+     *   3. 将 candidates/ recipes/ skills/ wiki/ 移入垃圾桶
+     *   4. 导出 DB 关键表数据到 db-snapshot.jsonl
+     *   5. 清空 DB 所有数据表
+     *   6. 清除向量索引、bootstrap-report、logs 等缓存
+     *
+     * 保留: config.json、constitution.yaml、boxspec.json、IDE 配置
+     */
+    async fullReset() {
+        const result = {
+            deletedFiles: 0,
+            clearedTables: [],
+            preservedRecipes: 0,
+            errors: [],
+        };
+        this.#logger.info('[CleanupService] Starting fullReset (trash-bin mode)...');
+        // 0. 清除过期垃圾桶
+        const purged = this.#purgeExpiredTrash();
+        if (purged.count > 0) {
+            result.purgedTrash = purged;
+            this.#logger.info(`[CleanupService] Purged ${purged.count} expired trash folders`);
+        }
+        // 1. 创建时间戳垃圾桶文件夹
+        const trashFolder = this.#createTrashFolder();
+        let movedItems = 0;
+        let dbSnapshotRows = 0;
+        // 2. 将知识目录移入垃圾桶（move 而非 copy，速度快）
+        const kbPath = getProjectKnowledgePath(this.#projectRoot);
+        const dirsToTrash = [
+            { src: path.join(this.#projectRoot, CANDIDATES_DIR), name: 'candidates' },
+            { src: getProjectRecipesPath(this.#projectRoot), name: 'recipes' },
+            { src: getProjectSkillsPath(this.#projectRoot), name: 'skills' },
+            { src: path.join(kbPath, 'wiki'), name: 'wiki' },
+        ];
+        for (const { src, name } of dirsToTrash) {
+            const moved = this.#moveToTrash(src, path.join(trashFolder, name));
+            movedItems += moved;
+        }
+        // 3. 导出 DB 数据到垃圾桶（JSONL 格式，每行一个 {table, row}）
+        if (this.#db) {
+            dbSnapshotRows = this.#exportDbToTrash(trashFolder);
+        }
+        // 4. 清空 DB 所有数据表
+        if (this.#db) {
+            for (const table of ALL_DATA_TABLES) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (!msg.includes('no such table')) {
+                        result.errors.push(`Failed to clear ${table}: ${msg}`);
+                        this.#logger.warn(`[CleanupService] DELETE FROM ${table} failed: ${msg}`);
+                    }
+                }
+            }
+            // tasks 相关表（来自 migration 002，需先删子表）
+            for (const table of ['task_events', 'task_dependencies', 'tasks']) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch {
+                    /* table may not exist */
+                }
+            }
+        }
+        else {
+            this.#logger.warn('[CleanupService] No database reference — DB tables NOT cleared!');
+            result.errors.push('DB reference is null, database tables were not cleared');
+        }
+        // 5. 重建被移走的空目录（bootstrap 后续步骤需要）
+        for (const { src } of dirsToTrash) {
+            if (!fs.existsSync(src)) {
+                fs.mkdirSync(src, { recursive: true });
+            }
+        }
+        // 6. 清除向量索引
+        result.deletedFiles += this.#clearDirectory(getContextIndexPath(this.#projectRoot));
+        // 7. 删除 bootstrap-report.json
+        result.deletedFiles += this.#deleteFile(path.join(kbPath, '.autosnippet', 'bootstrap-report.json'));
+        // 8. 清除 logs/signals/
+        result.deletedFiles += this.#clearDirectory(path.join(kbPath, '.autosnippet', 'logs', 'signals'));
+        result.deletedFiles += movedItems;
+        result.trash = { folder: trashFolder, movedItems, dbSnapshotRows };
+        this.#logger.info('[CleanupService] fullReset complete (trash-bin mode)', {
+            trashFolder: path.basename(trashFolder),
+            movedItems,
+            dbSnapshotRows,
+            tables: result.clearedTables.length,
+            purgedExpired: purged.count,
+            errors: result.errors.length,
+        });
+        return result;
+    }
+    // ─── 需求 B：Rescan 清理（保留 Recipe） ───────────────
+    /**
+     * Rescan 清理 — 保留 Recipe，清除衍生缓存
+     *
+     * 清除: 衍生 DB 表、pending/rejected/deprecated 知识条目、
+     *       candidates/、skills/、wiki/、向量索引、bootstrap-report
+     * 保留: recipes/、active/published/staging/evolving 知识条目、
+     *       knowledge_edges、evolution_proposals
+     */
+    async rescanClean() {
+        const result = {
+            deletedFiles: 0,
+            clearedTables: [],
+            preservedRecipes: 0,
+            errors: [],
+        };
+        this.#logger.info('[CleanupService] Starting rescanClean...');
+        // 1. 清除衍生 DB 表
+        if (this.#db) {
+            for (const table of RESCAN_CLEAN_TABLES) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (!msg.includes('no such table')) {
+                        result.errors.push(`Failed to clear ${table}: ${msg}`);
+                    }
+                }
+            }
+            // 清除旧候选/废弃条目，保留活跃知识
+            try {
+                this.#db.exec(`DELETE FROM knowledge_entries WHERE lifecycle IN ('pending', 'rejected', 'deprecated')`);
+                result.clearedTables.push('knowledge_entries (pending/rejected/deprecated)');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                result.errors.push(`Failed to clean old entries: ${msg}`);
+            }
+            // 也清除 tasks 相关表
+            for (const table of ['tasks', 'task_dependencies', 'task_events']) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch {
+                    /* table may not exist */
+                }
+            }
+        }
+        // 2. 清空 candidates/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(this.#projectRoot, CANDIDATES_DIR));
+        // 3. 清空 skills/ 目录
+        result.deletedFiles += this.#clearDirectory(getProjectSkillsPath(this.#projectRoot));
+        // 4. 清空 wiki/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(getProjectKnowledgePath(this.#projectRoot), 'wiki'));
+        // 5. 删除向量索引
+        result.deletedFiles += this.#clearDirectory(getContextIndexPath(this.#projectRoot));
+        // 6. 删除 bootstrap-report.json
+        result.deletedFiles += this.#deleteFile(path.join(getProjectKnowledgePath(this.#projectRoot), '.autosnippet', 'bootstrap-report.json'));
+        this.#logger.info('[CleanupService] rescanClean complete', {
+            tables: result.clearedTables.length,
+            files: result.deletedFiles,
+            errors: result.errors.length,
+        });
+        return result;
+    }
+    // ─── 快照当前 Recipe ──────────────────────────────────
+    /**
+     * 快照当前活跃 Recipe 信息
+     * 用于 rescan 前记录保留的知识条目
+     */
+    async snapshotRecipes() {
+        if (!this.#db) {
+            return { count: 0, entries: [], coverageByDimension: {} };
+        }
+        try {
+            const rows = this.#db
+                .prepare(`SELECT id, title, trigger, category, knowledgeType, doClause,
+                  sourceFile, lifecycle, content, json_extract(reasoning, '$.sources') AS sourceRefsJson
+           FROM knowledge_entries
+           WHERE lifecycle IN ('active', 'staging', 'evolving')`)
+                .all();
+            const entries = rows.map((r) => {
+                let parsedContent;
+                try {
+                    parsedContent = r.content
+                        ? JSON.parse(r.content)
+                        : undefined;
+                }
+                catch {
+                    parsedContent = undefined;
+                }
+                let parsedSourceRefs;
+                try {
+                    parsedSourceRefs = r.sourceRefsJson
+                        ? JSON.parse(r.sourceRefsJson)
+                        : undefined;
+                }
+                catch {
+                    parsedSourceRefs = undefined;
+                }
+                return {
+                    id: r.id,
+                    title: r.title || '',
+                    trigger: r.trigger || '',
+                    category: r.category || '',
+                    knowledgeType: r.knowledgeType || 'code-pattern',
+                    doClause: r.doClause || '',
+                    sourceFile: r.sourceFile || undefined,
+                    lifecycle: r.lifecycle,
+                    content: parsedContent,
+                    sourceRefs: parsedSourceRefs,
+                };
+            });
+            // 按维度统计覆盖度 (使用 knowledgeType = 维度 id)
+            const coverageByDimension = {};
+            for (const entry of entries) {
+                const dim = entry.knowledgeType || 'unknown';
+                coverageByDimension[dim] = (coverageByDimension[dim] || 0) + 1;
+            }
+            return {
+                count: entries.length,
+                entries,
+                coverageByDimension,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] snapshotRecipes failed: ${msg}`);
+            return { count: 0, entries: [], coverageByDimension: {} };
+        }
+    }
+    // ─── 垃圾桶管理 ───────────────────────────────────────
+    /**
+     * 清除超过保留期限的垃圾桶文件夹
+     * 可在服务启动时或 fullReset 前调用
+     */
+    purgeExpiredTrash() {
+        return this.#purgeExpiredTrash();
+    }
+    /**
+     * 列出当前所有垃圾桶（供 Dashboard 展示）
+     */
+    listTrashFolders() {
+        const trashRoot = this.#getTrashRoot();
+        if (!fs.existsSync(trashRoot)) {
+            return [];
+        }
+        const entries = fs.readdirSync(trashRoot).sort().reverse();
+        return entries
+            .filter((name) => /^\d{4}-\d{2}-\d{2}T/.test(name))
+            .map((name) => {
+            const fullPath = path.join(trashRoot, name);
+            const stat = fs.statSync(fullPath);
+            return {
+                name,
+                createdAt: stat.birthtime,
+                sizeMB: Math.round((this.#getDirSize(fullPath) / 1024 / 1024) * 100) / 100,
+            };
+        });
+    }
+    // ─── 内部工具方法 ─────────────────────────────────────
+    /** 获取垃圾桶根目录 (.autosnippet/.trash/) */
+    #getTrashRoot() {
+        return path.join(this.#projectRoot, '.autosnippet', TRASH_DIR);
+    }
+    /** 创建时间戳垃圾桶文件夹，返回绝对路径 */
+    #createTrashFolder() {
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const trashFolder = path.join(this.#getTrashRoot(), ts);
+        fs.mkdirSync(trashFolder, { recursive: true });
+        return trashFolder;
+    }
+    /**
+     * 将源目录内容移入垃圾桶对应子目录
+     * 使用 rename 实现（同文件系统内是原子操作，速度极快）
+     * @returns 移动的顶层条目数
+     */
+    #moveToTrash(srcDir, trashSubDir) {
+        if (!fs.existsSync(srcDir)) {
+            return 0;
+        }
+        const entries = fs.readdirSync(srcDir);
+        if (entries.length === 0) {
+            return 0;
+        }
+        fs.mkdirSync(trashSubDir, { recursive: true });
+        let count = 0;
+        for (const entry of entries) {
+            const src = path.join(srcDir, entry);
+            const dest = path.join(trashSubDir, entry);
+            try {
+                fs.renameSync(src, dest);
+                count++;
+            }
+            catch {
+                // rename 可能跨设备失败，fallback 到 copy+delete
+                try {
+                    fs.cpSync(src, dest, { recursive: true });
+                    fs.rmSync(src, { recursive: true, force: true });
+                    count++;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.#logger.warn(`[CleanupService] Failed to move ${entry} to trash: ${msg}`);
+                }
+            }
+        }
+        return count;
+    }
+    /**
+     * 导出 DB 关键表数据到垃圾桶（JSONL 格式）
+     * 只导出有实际业务数据的表，跳过纯缓存表
+     */
+    #exportDbToTrash(trashFolder) {
+        if (!this.#db) {
+            return 0;
+        }
+        const tablesToExport = [
+            'knowledge_entries',
+            'knowledge_edges',
+            'lifecycle_transition_events',
+            'evolution_proposals',
+            'recipe_source_refs',
+            'guard_violations',
+        ];
+        const snapshotPath = path.join(trashFolder, DB_SNAPSHOT_FILE);
+        let totalRows = 0;
+        const lines = [];
+        for (const table of tablesToExport) {
+            try {
+                const rows = this.#db.prepare(`SELECT * FROM ${table}`).all();
+                for (const row of rows) {
+                    lines.push(JSON.stringify({ _table: table, ...row }));
+                    totalRows++;
+                }
+            }
+            catch {
+                // 表可能不存在，跳过
+            }
+        }
+        if (lines.length > 0) {
+            fs.writeFileSync(snapshotPath, `${lines.join('\n')}\n`, 'utf-8');
+            this.#logger.info(`[CleanupService] DB snapshot: ${totalRows} rows → ${DB_SNAPSHOT_FILE}`);
+        }
+        return totalRows;
+    }
+    /** 清除过期垃圾桶文件夹 */
+    #purgeExpiredTrash() {
+        const trashRoot = this.#getTrashRoot();
+        if (!fs.existsSync(trashRoot)) {
+            return { count: 0, freedBytes: 0, folders: [] };
+        }
+        const now = Date.now();
+        const maxAge = TRASH_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+        const entries = fs.readdirSync(trashRoot);
+        let count = 0;
+        let freedBytes = 0;
+        const folders = [];
+        for (const entry of entries) {
+            const fullPath = path.join(trashRoot, entry);
+            try {
+                const stat = fs.statSync(fullPath);
+                if (!stat.isDirectory()) {
+                    continue;
+                }
+                // 从文件夹名解析时间戳（格式: 2026-04-09T14-30-00-000Z）
+                const ts = entry.replace(/-(\d{2})-(\d{2})-(\d{3}Z)$/, ':$1:$2.$3');
+                const created = new Date(ts).getTime();
+                const age = now - (Number.isNaN(created) ? stat.birthtimeMs : created);
+                if (age > maxAge) {
+                    const size = this.#getDirSize(fullPath);
+                    fs.rmSync(fullPath, { recursive: true, force: true });
+                    freedBytes += size;
+                    count++;
+                    folders.push(entry);
+                    this.#logger.info(`[CleanupService] Purged expired trash: ${entry} (${Math.round(size / 1024)}KB)`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.#logger.warn(`[CleanupService] Failed to purge trash ${entry}: ${msg}`);
+            }
+        }
+        // 如果垃圾桶根目录为空，也删掉
+        try {
+            const remaining = fs.readdirSync(trashRoot);
+            if (remaining.length === 0) {
+                fs.rmdirSync(trashRoot);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        return { count, freedBytes, folders };
+    }
+    /** 递归计算目录大小 (bytes) */
+    #getDirSize(dirPath) {
+        let size = 0;
+        try {
+            const entries = fs.readdirSync(dirPath);
+            for (const entry of entries) {
+                const fullPath = path.join(dirPath, entry);
+                const stat = fs.statSync(fullPath);
+                if (stat.isDirectory()) {
+                    size += this.#getDirSize(fullPath);
+                }
+                else {
+                    size += stat.size;
+                }
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        return size;
+    }
+    /**
+     * 清空目录内容（保留目录本身）
+     * @returns 删除的文件数
+     */
+    #clearDirectory(dirPath) {
+        let count = 0;
+        try {
+            if (!fs.existsSync(dirPath)) {
+                return 0;
+            }
+            const entries = fs.readdirSync(dirPath);
+            for (const entry of entries) {
+                const fullPath = path.join(dirPath, entry);
+                try {
+                    const stat = fs.statSync(fullPath);
+                    if (stat.isDirectory()) {
+                        fs.rmSync(fullPath, { recursive: true });
+                    }
+                    else {
+                        fs.unlinkSync(fullPath);
+                    }
+                    count++;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.#logger.warn(`[CleanupService] Failed to delete ${entry}: ${msg}`);
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] clearDirectory failed for ${dirPath}: ${msg}`);
+        }
+        return count;
+    }
+    /**
+     * 删除单个文件
+     * @returns 1 if deleted, 0 otherwise
+     */
+    #deleteFile(filePath) {
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                return 1;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] Failed to delete file ${filePath}: ${msg}`);
+        }
+        return 0;
+    }
+}