Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
#!/usr/bin/env node
/* global console, process */
/**
* validate-migrations.mjs — drizzle migration 完整性校验(release 前置护栏)。
*
* 检查 6 件事,任何一条失败都会 exit(1):
* 1. `drizzle/` 下所有 `NNNN_*.sql` 文件的序号严格从 0 开始、连续、无跳号、无重复
* 2. `drizzle/meta/_journal.json` 的 entries 数量 / tag / idx 与 sql 文件一一对齐;
* 每个 entry 对应的 snapshot 文件存在;snapshot 链 prevId/id 首尾相接(防"手写
* sql 但漏跑 db:generate"导致 prevId 跳过中间 idx)
* 3. 跑 `drizzle-kit check`(schema drift 检查)返回码必须为 0
* 4. `meta/` 下 snapshot 文件数量与 journal entries 一致(防孤儿 snapshot)
* 5. `drizzle/scripts/NNNN_*.ts` 配套迁移脚本必须是 CommonJS(`module.exports = { run }`
* + 依赖只用 `import type`),禁止顶层 ESM `export` / value `import`——这些脚本以 raw
* 形式随包发出(forge extraResource),生产 Electron 用 `require()` 当 CJS 加载,ESM
* 语法会在用户端炸 `Unexpected token 'export'`(dev/vitest 走 import 不复现,静默生产坑)
* 6. 从旧仓迁入的固定 SHA256 基线,以及已进入新仓 main/PR base 的 migration SQL +
* companion TS runtime identity 不可增删或修改,只允许追加新 migration
*
* 通过 → stdout 输出 `✅ migration validation passed: 0000..<max> ... + historical runtime identities frozen`
*
* 使用:
* pnpm db:validate
*
* Windows/macOS/Linux 通用;在 apps/desktop/ 下运行(cwd 自动定位)。
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { spawnSync } from 'node:child_process';
import { validateMigrationFreeze } from './lib/migration-freeze.mjs';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const DESKTOP_ROOT = path.resolve(__dirname, '..');
const REPO_ROOT = path.resolve(DESKTOP_ROOT, '..', '..');
const DRIZZLE_DIR = path.join(DESKTOP_ROOT, 'drizzle');
const META_DIR = path.join(DRIZZLE_DIR, 'meta');
const JOURNAL_PATH = path.join(META_DIR, '_journal.json');
/**
* 失败时统一打印格式 + exit 1。
* @param {string} msg
*/
function fail(msg) {
console.error(`[db:validate] FAIL: ${msg}`);
process.exit(1);
}
function info(msg) {
console.log(`[db:validate] ${msg}`);
}
// ── 1. 扫描 sql 文件、校验序号 ────────────────────────────────────────────
if (!fs.existsSync(DRIZZLE_DIR)) {
fail(`drizzle 目录不存在:${DRIZZLE_DIR}`);
}
/** @type {{ seq: number, file: string, tag: string }[]} */
const sqlFiles = [];
for (const entry of fs.readdirSync(DRIZZLE_DIR, { withFileTypes: true })) {
// 忽略 meta/ 和 scripts/ 子目录 —— 它们不是 migration sql
if (entry.isDirectory()) continue;
if (!entry.isFile()) continue;
const match = entry.name.match(/^(\d{4})_(.+)\.sql$/);
if (!match) continue; // 不符合命名的忽略(比如 .DS_Store 之类)
const seq = parseInt(match[1], 10);
const tag = `${match[1]}_${match[2]}`; // 例: '0000_init'
sqlFiles.push({ seq, file: entry.name, tag });
}
if (sqlFiles.length === 0) {
fail(`drizzle/ 下没有任何 NNNN_*.sql migration 文件`);
}
sqlFiles.sort((a, b) => a.seq - b.seq);
// 检查序号严格从 0 开始、连续、无跳号、无重复
const seenSeqs = new Set();
for (let i = 0; i < sqlFiles.length; i++) {
const { seq, file } = sqlFiles[i];
if (seenSeqs.has(seq)) {
fail(`序号 ${String(seq).padStart(4, '0')} 重复(${file})`);
}
seenSeqs.add(seq);
if (seq !== i) {
// 例如 sqlFiles[0].seq 不是 0 → 缺 0000;sqlFiles[2].seq 是 3 → 缺 0002
if (i === 0) {
fail(`序号必须从 0000 开始,但首个文件是 ${file}(seq=${seq})`);
} else {
const missing = String(i).padStart(4, '0');
fail(`序号 ${missing} 缺失(${file} 跳到 ${String(seq).padStart(4, '0')})`);
}
}
}
const maxSeq = sqlFiles[sqlFiles.length - 1].seq;
info(`step 1/6 ok — ${sqlFiles.length} sql file(s), seq 0000..${String(maxSeq).padStart(4, '0')}`);
// ── 2. _journal.json ↔ sql 文件对齐 ────────────────────────────────────────
if (!fs.existsSync(JOURNAL_PATH)) {
fail(`drizzle/meta/_journal.json 不存在(请跑 pnpm db:generate 重新生成)`);
}
let journal;
try {
journal = JSON.parse(fs.readFileSync(JOURNAL_PATH, 'utf-8'));
} catch (err) {
fail(`_journal.json 解析失败:${err instanceof Error ? err.message : String(err)}`);
}
if (!Array.isArray(journal.entries)) {
fail(`_journal.json 缺少 entries 数组`);
}
/** @type {{ idx: number, tag: string }[]} */
const entries = journal.entries;
if (entries.length !== sqlFiles.length) {
fail(
`_journal.json.entries 数量 ${entries.length} ≠ sql 文件数量 ${sqlFiles.length};` +
`很可能有 sql 文件手工新增或删除后忘了重新 drizzle-kit generate。`,
);
}
for (let i = 0; i < entries.length; i++) {
const entry = entries[i];
if (typeof entry.idx !== 'number') {
fail(`_journal.json entries[${i}] 缺少 idx 字段`);
}
if (entry.idx !== i) {
fail(`_journal.json entries[${i}].idx = ${entry.idx}(应为 ${i})`);
}
if (typeof entry.tag !== 'string') {
fail(`_journal.json entries[${i}] 缺少 tag 字段`);
}
const expectedTag = sqlFiles[i].tag;
if (entry.tag !== expectedTag) {
fail(
`_journal.json entries[${i}].tag = "${entry.tag}",但对应的 sql 文件 tag 是 "${expectedTag}"(${sqlFiles[i].file})`,
);
}
// drizzle-kit 的命名惯例:每个 tag 都有对应的 <tag>_snapshot.json
// (实测当前 0000_init 对应 meta/0000_snapshot.json —— snapshot 用 idx 前缀而非完整 tag)
const snapshotByIdx = path.join(META_DIR, `${String(i).padStart(4, '0')}_snapshot.json`);
if (!fs.existsSync(snapshotByIdx)) {
fail(
`snapshot 文件缺失:${path.relative(DESKTOP_ROOT, snapshotByIdx)}(entries[${i}].tag="${entry.tag}")`,
);
}
}
// snapshot 链 id/prevId 首尾相接检查 —— 防御"手写 sql migration 忘了 drizzle-kit
// generate"导致 prevId 跳过中间 idx 的情况(drizzle-kit check 也会报,但这里给出
// 更清晰的中文错误,且不依赖子进程返回码语义)。
// 约定:0000 的 prevId 是全零 uuid;后续每个 prevId 必须等于上一份的 id。
const ZERO_UUID = '00000000-0000-0000-0000-000000000000';
let prevSnapshotId = ZERO_UUID;
for (let i = 0; i < entries.length; i++) {
const snapshotPath = path.join(META_DIR, `${String(i).padStart(4, '0')}_snapshot.json`);
let snap;
try {
snap = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
} catch (err) {
fail(
`snapshot 解析失败:${path.relative(DESKTOP_ROOT, snapshotPath)} — ${err instanceof Error ? err.message : String(err)}`,
);
}
if (typeof snap.id !== 'string' || typeof snap.prevId !== 'string') {
fail(`snapshot 缺少 id/prevId 字段:${path.relative(DESKTOP_ROOT, snapshotPath)}`);
}
if (snap.prevId !== prevSnapshotId) {
fail(
`snapshot 链断裂:${path.relative(DESKTOP_ROOT, snapshotPath)} 的 prevId="${snap.prevId}"` +
`,应等于上一份(${i === 0 ? '全零 uuid' : `${String(i - 1).padStart(4, '0')}_snapshot.json`})` +
`的 id="${prevSnapshotId}"。常见原因:手写了 NNNN_xxx.sql 但忘了跑 pnpm db:generate 补 snapshot。`,
);
}
prevSnapshotId = snap.id;
}
info(`step 2/6 ok — _journal.json entries 与 sql 文件、snapshot 全部对齐,snapshot 链 id/prevId 连续`);
// ── 3. drizzle-kit check(schema drift 检查)──────────────────────────────
info(`step 3/6 running — drizzle-kit check ...`);
// Windows: spawn pnpm 时必须 shell:true 才能找到 .cmd 外壳(pnpm.cmd / pnpm.exe)
const isWin = process.platform === 'win32';
const checkResult = spawnSync(
isWin ? 'pnpm.cmd' : 'pnpm',
['exec', 'drizzle-kit', 'check'],
{
cwd: DESKTOP_ROOT,
stdio: ['ignore', 'pipe', 'pipe'],
encoding: 'utf-8',
shell: isWin,
},
);
if (checkResult.status !== 0) {
const stderrOut = (checkResult.stderr || '').toString().trim();
const stdoutOut = (checkResult.stdout || '').toString().trim();
console.error('[db:validate] drizzle-kit check failed. stdout:');
console.error(stdoutOut || '(empty)');
console.error('[db:validate] drizzle-kit check failed. stderr:');
console.error(stderrOut || '(empty)');
fail(
`drizzle-kit check 返回 ${checkResult.status};通常意味着 schema.ts 改动后忘了跑 pnpm db:generate`,
);
}
info(`step 3/6 ok — drizzle-kit check 通过(无 schema drift)`);
// ── 4. 冗余的 sql↔snapshot 对齐检查(step 2 已覆盖主要逻辑,这里简单复核)─
// 检查 meta/ 目录中是否存在不属于任何 entries 的 snapshot(孤儿 snapshot)
const metaFiles = fs.readdirSync(META_DIR);
const snapshotFiles = metaFiles.filter((f) => /^\d{4}_snapshot\.json$/.test(f));
if (snapshotFiles.length !== entries.length) {
fail(
`meta/ 下的 snapshot 文件数 ${snapshotFiles.length} ≠ journal entries 数 ${entries.length}` +
`(可能有孤儿 snapshot 或丢失 snapshot,请跑 pnpm db:generate 重新生成)`,
);
}
info(`step 4/6 ok — ${snapshotFiles.length} snapshot file(s) 与 journal entries 数量一致`);
// ── 5. 配套迁移脚本 drizzle/scripts/*.ts 必须是 CommonJS ─────────────────────
//
// 这些 .ts 不经编译、以 raw 形式随包发出(forge.config.ts extraResource: 'drizzle'),
// 生产 Electron 用 require() 加载:type-stripping 擦掉 `import type` 与类型注解后,按最近
// 的 package.json(无 "type":"module")当 CommonJS 解析。顶层 ESM `export` / value `import`
// 会让用户端报 `Unexpected token 'export'` / ERR_REQUIRE_ESM——而 dev/vitest 走 import
// 不复现,是只在生产暴露的静默坑(2026-06 由 0040 触发)。约定与 0038 等历史脚本一致:
// `function run(db) {...}` + 末尾 `module.exports = { run }`,依赖一律 `import type`。
const SCRIPTS_DIR = path.join(DRIZZLE_DIR, 'scripts');
const ESM_EXPORT_RE = /^[ \t]*export\b/m; // 顶层 export(含 export function/const/default/{)
const ESM_VALUE_IMPORT_RE = /^[ \t]*import\b(?![ \t]+type\b)/m; // 顶层 import 但非 import type
if (fs.existsSync(SCRIPTS_DIR)) {
const scriptFiles = fs
.readdirSync(SCRIPTS_DIR)
.filter((f) => /^\d{4}_.+\.ts$/.test(f))
.sort();
for (const file of scriptFiles) {
const src = fs.readFileSync(path.join(SCRIPTS_DIR, file), 'utf-8');
if (ESM_EXPORT_RE.test(src)) {
fail(
`drizzle/scripts/${file} 含顶层 ESM \`export\`,但该脚本以 CommonJS require() 加载,` +
`生产 Electron 会报 Unexpected token 'export'。请改用 \`function run(db){...}\` + ` +
`\`module.exports = { run }\`(参考 0038_add_session_remote_host_id.ts)。`,
);
}
if (ESM_VALUE_IMPORT_RE.test(src)) {
fail(
`drizzle/scripts/${file} 含顶层 value \`import\`(ESM),同样会在生产 require() 时炸。` +
`依赖请用 \`import type ...\`(type-only,会被擦除)或在 run() 内 \`require()\`。`,
);
}
}
info(`step 5/6 ok — ${scriptFiles.length} 个配套迁移脚本均为 CommonJS(无顶层 ESM export/import)`);
} else {
info(`step 5/6 ok — 无 drizzle/scripts/ 目录,跳过`);
}
// ── 6. 旧仓固定基线 / 新仓 main 的 migration runtime identity 冻结 ────────
let freezeResult;
try {
freezeResult = validateMigrationFreeze(REPO_ROOT);
} catch (err) {
fail(`migration 冻结校验无法执行:${err instanceof Error ? err.message : String(err)}`);
}
const freezeChecks = [
{
label: `migrated baseline (${freezeResult.fixedCheck.sourceCommit.slice(0, 10)})`,
result: freezeResult.fixedCheck,
},
];
if (freezeResult.baseline && freezeResult.mainCheck) {
freezeChecks.push({
label: `main baseline ${freezeResult.baseline.ref} (${freezeResult.baseline.commit.slice(0, 10)})`,
result: freezeResult.mainCheck,
});
}
for (const check of freezeChecks) {
if (check.result.violations.length === 0) continue;
const detail = check.result.violations
.map((violation) => `${violation.path} (${violation.kind})`)
.join(', ');
fail(
`${check.label} 中已有的 migration SQL / companion TS identity 被改写:${detail}。` +
`已进入 main/发版的 migration runtime 不可增删或修改,请新增 migration 修正。`,
);
}
const mainSummary = freezeResult.mainCheck
? `,main 基线冻结 ${freezeResult.mainCheck.migrationCount} 条 SQL + ` +
`${freezeResult.mainCheck.runtimeScriptCount} 条 runtime script`
: ';新仓尚无 main commit,跳过增量 Git 基线';
info(
`step 6/6 ok — 固定 SHA256 基线冻结 ${freezeResult.fixedCheck.migrationCount} 条 migration SQL + ` +
`${freezeResult.fixedCheck.runtimeScriptCount} 条 runtime script${mainSummary}`,
);
// ── Done ───────────────────────────────────────────────────────────────────
const maxSeqTag = String(maxSeq).padStart(4, '0');
console.log(
`✅ migration validation passed: 0000..${maxSeqTag} sql files + journal aligned + no schema drift + scripts CJS-only + historical runtime identities frozen`,
);
process.exit(0);