From 682720a6fef7c1af225f756c2989951b23120778 Mon Sep 17 00:00:00 2001 From: QQ Date: Thu, 12 Nov 2026 00:02:56 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20src/skill-update.ts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/skill-update.ts | 329 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 src/skill-update.ts diff --git a/src/skill-update.ts b/src/skill-update.ts new file mode 100644 index 0000000..23bdd21 --- /dev/null +++ b/src/skill-update.ts @@ -0,0 +1,329 @@ +/** + * Skill update & rollback (P3). + * + * Works only for skills that carry a `.skill-source.json` provenance record + * (written by the market / git install pipeline). Nothing here talks to the + * cloud center: it re-reads the pinned git source, shows a diff, keeps a local + * backup before touching the folder, and restores that backup on rollback. + * + * Safety rules baked in: + * - the source record is the only thing trusted for a repository URL; + * - a fresh clone happens in `$DSH_HOME/.dsh-brain-staging` and the copy is + * filtered (no `.git`, no symlinks); + * - a backup is always taken before an update so rollback is possible even + * when the update is interrupted; + * - a repository in-flight sync blocks any write. + */ +import { execFile } from 'node:child_process' +import { lstatSync } from 'node:fs' +import { createHash } from 'node:crypto' +import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises' +import { join, resolve } from 'node:path' +import { tmpdir } from 'node:os' +import type { SkillAdmin, SkillSourceRecord } from './skill-admin.ts' +import { readSkillSourceRecord, SkillAdminError } from './skill-admin.ts' +import { dshHome } from './store.ts' + +/** Where pre-update backups are kept (one folder per skill, one dir per run). */ +export function skillBackupsDir(): string { + return join(dshHome(), '.dsh-brain-backups') +} + +/** One file on disk with its hash, used for diffing two trees. */ +interface FileHash { + path: string + sha256: string + bytes: number +} + +/** Result of comparing the installed folder to the source's latest commit. */ +export interface UpdateCheck { + folder: string + updatable: boolean + reason?: string + provider?: string + repoUrl?: string + currentCommit?: string + remoteCommit?: string + available: boolean + added?: string[] + removed?: string[] + changed?: string[] + fetchedAt: number +} + +/** Result of applying an update or a rollback. */ +export interface UpdateResult { + folder: string + from: string + to: string + backup: string + added: string[] + removed: string[] + changed: string[] +} + +/** Run git and return stdout. */ +function git(args: string[], timeoutMs = 120_000): Promise { + return new Promise((resolvePromise, rejectPromise) => { + execFile( + 'git', + args, + { timeout: timeoutMs, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, maxBuffer: 8 * 1024 * 1024 }, + (error, stdout) => (error ? rejectPromise(error) : resolvePromise(String(stdout))), + ) + }) +} + +async function isSymlink(path: string): Promise { + return lstat(path).then((s) => s.isSymbolicLink()).catch(() => true) +} + +/** Hash every regular file under one directory (skips `.git` and symlinks). */ +async function hashTree(dir: string): Promise> { + const out = new Map() + const walk = async (sub: string): Promise => { + for (const entry of await readdir(join(dir, sub), { withFileTypes: true }).catch(() => [])) { + if (entry.name === '.git') continue + const rel = sub === '' ? entry.name : `${sub}/${entry.name}` + const abs = join(dir, rel) + if (entry.isSymbolicLink()) continue + if (entry.isDirectory()) { + await walk(rel) + continue + } + if (!entry.isFile()) continue + const buffer = await readFile(abs).catch(() => undefined) + if (buffer === undefined) continue + out.set(rel, { path: rel, sha256: createHash('sha256').update(buffer).digest('hex'), bytes: buffer.byteLength }) + } + } + await walk('') + return out +} + +/** A short human bucket for what changed. */ +function diffTrees(before: Map, after: Map): { added: string[]; removed: string[]; changed: string[] } { + const added: string[] = [] + const removed: string[] = [] + const changed: string[] = [] + for (const [path, file] of after) { + const old = before.get(path) + if (old === undefined) added.push(path) + else if (old.sha256 !== file.sha256) changed.push(path) + } + for (const path of before.keys()) if (!after.has(path)) removed.push(path) + added.sort(); removed.sort(); changed.sort() + return { added, removed, changed } +} + +/** Copy a skill tree, dropping `.git` and symlinks (same rule as install). */ +async function copySkillTree(source: string, target: string): Promise { + await cp(source, target, { + recursive: true, + filter: (path) => !path.split(/[\\/]/).includes('.git') && (() => { + try { + return !lstatSync(path).isSymbolicLink() + } catch { + return false + } + })(), + }) +} + +export interface SkillUpdaterDeps { + admin: SkillAdmin + skillsRoot: () => string + holdingDir: () => string + backupsDir?: () => string + syncRunning: () => boolean + log: (message: string) => void +} + +export class SkillUpdater { + private readonly deps: SkillUpdaterDeps + constructor(deps: SkillUpdaterDeps) { + this.deps = deps + } + + private backupsRoot(): string { + return this.deps.backupsDir?.() ?? skillBackupsDir() + } + + private guard(): void { + if (this.deps.syncRunning()) throw new SkillAdminError('sync_running', '技能同步正在进行,请稍候再试。') + } + + private async find(folder: string): Promise<{ dir: string; source: SkillSourceRecord }> { + const found = await this.deps.admin.locate(folder) + if (found === undefined) throw new SkillAdminError('not_found', `没有找到技能:${folder}`) + const source = await readSkillSourceRecord(found.dir) + if (source === undefined) { + throw new SkillAdminError('no_source', `该技能没有来源记录(不是从 Git 或市场安装的),无法更新或回退。`) + } + return { dir: found.dir, source } + } + + /** Clone the pinned source at its latest commit into a scratch directory. */ + private async cloneLatest(source: SkillSourceRecord): Promise<{ dir: string; commit: string; cleanup: () => Promise }> { + const root = join(dshHome(), '.dsh-brain-staging') + await mkdir(root, { recursive: true }) + const dir = join(root, `update_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`) + try { + await git(['clone', '--depth', '1', '--no-tags', '--', source.repoUrl, dir]) + // A commit SHA is a pin, not a moving ref: leave the default-branch head + // in place so an update check compares against the latest upstream. A + // branch/tag name is fetched and checked out instead. + const isSha = /^[0-9a-f]{7,40}$/i.test(source.ref) + if (!isSha && source.ref !== '') { + try { + await git(['-C', dir, 'fetch', '--depth', '1', 'origin', source.ref]) + await git(['-C', dir, 'checkout', '--detach', 'FETCH_HEAD']) + } catch { + // Fall back to the default branch head. + } + } + } catch (error) { + await rm(dir, { recursive: true, force: true }).catch(() => {}) + const code = (error as NodeJS.ErrnoException).code + throw new SkillAdminError('git_failed', code === 'ENOENT' + ? '本机没有 git 命令,无法检查更新。' + : '无法读取来源仓库(地址不可达、需要登录,或仓库已删除)。') + } + const commit = (await git(['-C', dir, 'rev-parse', 'HEAD'], 20_000)).trim() + return { dir, commit, cleanup: () => rm(dir, { recursive: true, force: true }).catch(() => {}) } + } + + /** Compare the installed folder against the source's latest commit. */ + async checkUpdate(folderInput: unknown): Promise { + const folder = typeof folderInput === 'string' ? folderInput : '' + if (folder === '') throw new SkillAdminError('invalid_name', '缺少技能目录名。') + const fetchedAt = Date.now() + const found = await this.deps.admin.locate(folder) + if (found === undefined) throw new SkillAdminError('not_found', `没有找到技能:${folder}`) + const source = await readSkillSourceRecord(found.dir) + if (source === undefined) { + return { folder, updatable: false, reason: 'no_source', available: false, fetchedAt } + } + const clone = await this.cloneLatest(source) + try { + if (clone.commit === source.commit) { + return { + folder, updatable: true, available: false, provider: source.provider, + repoUrl: source.repoUrl, currentCommit: source.commit, remoteCommit: clone.commit, fetchedAt, + } + } + const remoteDir = source.sourcePath === '' ? clone.dir : resolve(clone.dir, source.sourcePath) + const before = await hashTree(found.dir) + const after = await hashTree(remoteDir) + // The provenance file is ours, not the source's: never show it as removed. + before.delete('.skill-source.json') + const diff = diffTrees(before, after) + return { + folder, updatable: true, available: true, provider: source.provider, + repoUrl: source.repoUrl, currentCommit: source.commit, remoteCommit: clone.commit, + ...diff, fetchedAt, + } + } finally { + await clone.cleanup() + } + } + + /** Back up the current folder, then replace it with the source's latest. */ + async applyUpdate(folderInput: unknown, expectedCommit?: unknown): Promise { + this.guard() + const folder = typeof folderInput === 'string' ? folderInput : '' + if (folder === '') throw new SkillAdminError('invalid_name', '缺少技能目录名。') + const { dir, source } = await this.find(folder) + const check = await this.checkUpdate(folder) + if (!check.available) throw new SkillAdminError('up_to_date', '已经是最新版本,无需更新。') + if (typeof expectedCommit === 'string' && expectedCommit !== '' && check.remoteCommit !== expectedCommit) { + throw new SkillAdminError('stale_plan', '来源在上次检查后已更新,请重新检查差异再更新。') + } + return this.replaceWith(dir, source, { commit: check.remoteCommit ?? source.commit, ref: source.ref }) + } + + /** Restore the most recent pre-update backup. */ + async rollback(folderInput: unknown): Promise { + this.guard() + const folder = typeof folderInput === 'string' ? folderInput : '' + if (folder === '') throw new SkillAdminError('invalid_name', '缺少技能目录名。') + const { dir, source } = await this.find(folder) + const root = join(this.backupsRoot(), folder) + const entries = (await readdir(root, { withFileTypes: true }).catch(() => [])) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort() + const latest = entries[entries.length - 1] + if (latest === undefined) throw new SkillAdminError('no_backup', '没有可回退的备份。') + const backupDir = join(root, latest) + const restored = await readSkillSourceRecord(backupDir) + // Restore in place: move the current aside, copy the backup over, then drop + // the aside copy only after the backup has landed. + const aside = `${dir}.rollbacking-${Date.now().toString(36)}` + await mkdir(join(dir, '..'), { recursive: true }) + await rename(dir, aside) + try { + await copySkillTree(backupDir, dir) + } catch (error) { + await rm(dir, { recursive: true, force: true }).catch(() => {}) + await rename(aside, dir).catch(() => {}) + throw new SkillAdminError('rollback_failed', `回退失败,原目录已尽量还原:${error instanceof Error ? error.message : String(error)}`) + } + await rm(aside, { recursive: true, force: true }).catch(() => {}) + this.deps.log(`skill rolled back: ${folder} <- ${latest}`) + const beforeFiles = await hashTree(backupDir) + beforeFiles.delete('.skill-source.json') + const nowFiles = await hashTree(dir) + nowFiles.delete('.skill-source.json') + const diff = diffTrees(nowFiles, beforeFiles) + return { + folder, + from: source.commit, + to: restored?.commit ?? source.commit, + backup: backupDir, + ...diff, + } + } + + /** Shared write path: backup, copy new tree, rewrite provenance. */ + private async replaceWith(dir: string, source: SkillSourceRecord, next: { commit: string; ref: string }): Promise { + const clone = await this.cloneLatest({ ...source, ref: next.ref }) + let newDir = source.sourcePath === '' ? clone.dir : resolve(clone.dir, source.sourcePath) + try { + if (clone.commit !== next.commit) { + // A different head landed between check and apply: refuse, never guess. + throw new SkillAdminError('stale_plan', '来源在更新过程中已变化,请重新检查。') + } + const stamp = new Date().toISOString().replace(/[:.]/g, '-') + const backupDir = join(this.backupsRoot(), this.lastSegment(dir), stamp) + await mkdir(join(backupDir, '..'), { recursive: true }) + await copySkillTree(dir, backupDir) + const before = await hashTree(dir) + const after = await hashTree(newDir) + const diff = diffTrees(before, after) + const aside = `${dir}.updating-${Date.now().toString(36)}` + await rename(dir, aside) + try { + await copySkillTree(newDir, dir) + await writeFile(join(dir, '.skill-source.json'), `${JSON.stringify({ + ...source, commit: next.commit, ref: next.ref, installedAt: new Date().toISOString(), + } satisfies SkillSourceRecord, null, 2)}\n`, 'utf8') + } catch (error) { + await rm(dir, { recursive: true, force: true }).catch(() => {}) + await rename(aside, dir).catch(() => {}) + throw new SkillAdminError('update_failed', `更新失败,原目录已还原:${error instanceof Error ? error.message : String(error)}`) + } + await rm(aside, { recursive: true, force: true }).catch(() => {}) + this.deps.log(`skill updated: ${this.lastSegment(dir)} -> ${next.commit}`) + return { folder: this.lastSegment(dir), from: source.commit, to: next.commit, backup: backupDir, ...diff } + } finally { + await clone.cleanup() + } + } + + private lastSegment(path: string): string { + const parts = path.split(/[\\/]/).filter((part) => part !== '') + return parts[parts.length - 1] ?? path + } +}