// 项目状态存储:单个 JSON 文件,原子写,读取时严格校验。 // 读取时按版本分流:当前格式直接校验;旧格式先迁移再原子写回;其它情况一律报明确错误, // 不静默回退成“健康空状态”,也绝不覆盖原始文件。 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises' import { dirname } from 'node:path' import { STATE_VERSION, emptyState, emptyProject, validateState } from '../shared/schema.js' import { isLegacyState, migrateLegacyState } from '../shared/migrate.js' import { seatBySessionId } from '../shared/roles.js' export class StoreError extends Error { constructor(code, message, { retryable = true } = {}) { super(message) this.name = 'StoreError' this.code = code this.retryable = retryable } } function isObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v) } // 旧版本状态没有任务/成果字段:读入时就地补空数组,不需要改文件版本。 function normalizeProjects(state) { for (const project of Object.values(state.projects ?? {})) { if (!Array.isArray(project.tasks)) project.tasks = [] if (!Array.isArray(project.artifacts)) project.artifacts = [] if (!Number.isFinite(project.taskSeq)) project.taskSeq = 0 if (!Number.isFinite(project.artifactSeq)) project.artifactSeq = 0 } return state } export class SanshengStore { constructor(file) { this.file = file this.state = emptyState() this._queue = Promise.resolve() this._loaded = false this._loadPromise = null } // 惰性加载:插件 apply 必须同步返回,真实 HTTP 请求到达时再确保状态已读入。 ensureLoaded() { if (this._loaded) return Promise.resolve() if (!this._loadPromise) { this._loadPromise = this.load().catch(error => { this._loadPromise = null; throw error }) } return this._loadPromise } async load() { let raw try { raw = await readFile(this.file, 'utf8') } catch (error) { if (error?.code === 'ENOENT') { this.state = emptyState(); this._loaded = true; return } throw new StoreError('sansheng/state-unreadable', `无法读取状态文件:${error?.message ?? error}`) } let parsed try { parsed = JSON.parse(raw) } catch (error) { throw new StoreError( 'sansheng/state-json', `状态文件不是合法 JSON:${error.message}。文件未被改动;请修复该文件或从版本库恢复。`, { retryable: false }, ) } if (!isObject(parsed)) { throw new StoreError('sansheng/state-corrupt', '状态文件顶层不是对象。文件未被改动。', { retryable: false }) } // 1) 已经是当前格式:严格校验。 if (parsed.version === STATE_VERSION) { const valid = validateState(parsed) if (!valid.ok) { throw new StoreError('sansheng/state-corrupt', `状态文件损坏:${valid.error}。文件未被改动。`, { retryable: false }) } this.state = normalizeProjects(valid.state) this._loaded = true return } // 2) 已知旧格式:转换成当前格式,校验通过后原子写回。 if (isLegacyState(parsed)) { const migrated = migrateLegacyState(parsed) if (!migrated.ok) { throw new StoreError(migrated.code, `${migrated.message}。原文件未被改动。`, { retryable: false }) } this.state = migrated.state if (migrated.warnings.length > 0) { console.warn('[sansheng] 旧数据迁移提示:', migrated.warnings.join(';')) } // 只有转换结果已经过 validateState,才会走到这里写盘;写失败(磁盘错误等)不覆盖原文件。 await this.save() this._loaded = true return } // 3) 未知版本:明确说“不支持”,不再谎报“损坏”。 throw new StoreError( 'sansheng/state-unsupported', `状态文件格式不受支持:检测到版本 ${String(parsed.version)},本插件当前格式为 ${STATE_VERSION}(可自动升级的旧格式为 2/3)。文件未被改动。`, { retryable: false }, ) } snapshot() { return structuredClone(this.state) } get(projectId) { return this.state.projects[projectId] } list() { return Object.values(this.state.projects) } seatBySession(sessionId) { return seatBySessionId(this.state.projects, sessionId) } // 所有写操作经此串行化:同一时刻只有一个 mutate 在跑,失败回滚内存状态。 async mutate(fn) { const run = async () => { await this.ensureLoaded() const before = structuredClone(this.state) try { const result = await fn(this.state) this.state.seq = (this.state.seq ?? 0) + 1 await this.save() return result } catch (error) { this.state = before throw error } } this._queue = this._queue.then(run, run) return this._queue } async save() { await mkdir(dirname(this.file), { recursive: true }) const tmp = `${this.file}.${process.pid}.${Date.now()}.tmp` await writeFile(tmp, JSON.stringify(this.state, null, 2), 'utf8') await rename(tmp, this.file) } // 确保项目记录存在;已存在则只补空字段,不覆盖既有会话/配置。 ensureProjectRecord({ id, name, workspaceId = null, path = null, now = Date.now() }) { let project = this.state.projects[id] if (!project) { project = emptyProject({ id, name: name ?? id, workspaceId, path, now }) this.state.projects[id] = project return project } if (name && !project.name) project.name = name if (workspaceId && !project.workspaceId) project.workspaceId = workspaceId if (path && !project.path) project.path = path project.updatedAt = now project.revision = (project.revision ?? 0) + 1 return project } }