dsh-hams 0.1.2 → 0.1.4

package/src/store/bootstrap.ts

@@ -1,225 +0,0 @@
-/**
- * 存储启动编排：严格按 dsh-compat §7 的顺序
- *
- *   拿锁 → 开可写库 → （库非空则）备份 → 迁移 → 种子元数据 → runtime_epoch +1 → 交付
- *
- * 细节取舍：
- * - 空库（user_version=0）不备份：没有业务数据可保，备份只会制造噪音；
- * - 非空库升级前必先备份，备份校验不过就**不迁移**，宁可起不来也不带着坏备份往前走；
- * - 任何一步失败都要回滚并释放锁，绝不半启动接流量（错误原样上抛，由插件置诊断态）；
- * - `recover()` 冷启动对账属于 M4，这里不做，但 runtime_epoch 已经就位供它使用。
- */
-import type { DatabaseSync } from 'node:sqlite'
-import {
-  closeDatabase,
-  databasePath,
-  openDatabase,
-  resolveDataDir,
-  userVersion,
-  StoreError,
-} from './db.ts'
-import { acquireLock, lockPath, type LockHandle } from './lock.ts'
-import { backupDir, createBackup, type BackupReport } from './backup.ts'
-import {
-  MIGRATIONS,
-  P1_SCHEMA_META,
-  SchemaTooNewError,
-  TARGET_VERSION,
-  migrate,
-  type Migration,
-} from './migrations.ts'
-import {
-  assertBaselineSeed,
-  bumpRuntimeEpoch,
-  ensureMetaDefaults,
-  readMeta,
-  type SeedSummary,
-} from './seed.ts'
-
-export interface BootstrapOptions {
-  /** 数据目录；缺省 = $DSH_HOME/hams。 */
-  dataDir?: string
-  migrations?: readonly Migration[]
-  now?: () => number
-  backupKeep?: number
-  staleMs?: number
-  /** 默认 true；关掉只用于测试「不备份直接迁移」的失败路径。 */
-  backupBeforeMigrate?: boolean
-}
-
-export interface BootstrapReport {
-  dataDir: string
-  dbPath: string
-  lockPath: string
-  fromVersion: number
-  toVersion: number
-  runtimeEpoch: number
-  backup: { name: string; path: string; bytes: number; tables: number } | null
-  migration: { migrated: boolean; applied: { version: number; name: string }[]; checkedBaseline: boolean }
-  seed: SeedSummary
-  meta: Record<string, string>
-  steps: string[]
-}
-
-export interface StoreRuntime {
-  dataDir: string
-  dbPath: string
-  db: DatabaseSync
-  lock: LockHandle
-  report: BootstrapReport
-  readonly closed: boolean
-  close(): void
-}
-
-function toBackupSummary(report: BackupReport | null): BootstrapReport['backup'] {
-  if (!report) return null
-  return { name: report.name, path: report.path, bytes: report.bytes, tables: report.tables }
-}
-
-export function bootstrapStore(options: BootstrapOptions = {}): StoreRuntime {
-  const now = options.now ?? Date.now
-  const migrations = options.migrations ?? MIGRATIONS
-  const targetVersion = migrations[migrations.length - 1].version
-  const dataDir = resolveDataDir(options.dataDir)
-  const dbPath = databasePath(dataDir)
-
-  const steps: string[] = []
-  const lock = acquireLock(dataDir, { staleMs: options.staleMs, now: now() })
-  steps.push('acquire-lock')
-
-  let db: DatabaseSync | null = null
-  try {
-    db = openDatabase({ path: dbPath })
-    steps.push('open-db')
-
-    const fromVersion = userVersion(db)
-    let backupReport: BackupReport | null = null
-
-    if (fromVersion > 0 && fromVersion < targetVersion && options.backupBeforeMigrate !== false) {
-      backupReport = createBackup(db, {
-        dir: backupDir(dataDir),
-        keep: options.backupKeep,
-        now: new Date(now()),
-      })
-      steps.push(`backup-before-migrate:${backupReport.name}`)
-    } else if (fromVersion === 0) {
-      steps.push('skip-backup-fresh-db')
-    } else {
-      steps.push('skip-backup-no-upgrade')
-    }
-
-    const migrationReport = migrate(db, {
-      migrations,
-      verifyBaseline: options.verifyBaseline ?? migrations === MIGRATIONS,
-    })
-    steps.push(
-      migrationReport.migrated
-        ? `migrate:${migrationReport.applied.map((item) => item.version).join(',')}`
-        : 'migrate:noop',
-    )
-
-    ensureMetaDefaults(db, { now: now() })
-    steps.push('seed-meta')
-
-    const seed = assertBaselineSeed(db)
-    steps.push('assert-baseline-seed')
-
-    const runtimeEpoch = bumpRuntimeEpoch(db)
-    steps.push(`bump-runtime-epoch:${runtimeEpoch}`)
-
-    // 报告里的 meta 必须是加了启动代次之后的快照（否则界面显示 epoch 0）。
-    const finalMeta = readMeta(db)
-
-    const report: BootstrapReport = {
-      dataDir,
-      dbPath,
-      lockPath: lockPath(dataDir),
-      fromVersion,
-      toVersion: migrationReport.toVersion,
-      runtimeEpoch,
-      backup: toBackupSummary(backupReport),
-      migration: {
-        migrated: migrationReport.migrated,
-        applied: migrationReport.applied,
-        checkedBaseline: migrationReport.checkedBaseline,
-      },
-      seed,
-      meta: finalMeta,
-      steps,
-    }
-
-    let closed = false
-    const runtime: StoreRuntime = {
-      dataDir,
-      dbPath,
-      db,
-      lock,
-      report,
-      get closed() {
-        return closed
-      },
-      close(): void {
-        if (closed) return
-        closed = true
-        try {
-          closeDatabase(db as DatabaseSync)
-        } finally {
-          lock.release()
-        }
-      },
-    }
-    return runtime
-  } catch (error) {
-    if (db) {
-      try {
-        closeDatabase(db)
-      } catch {
-        // 关闭失败不能盖住原始错误。
-      }
-    }
-    lock.release()
-    throw error
-  }
-}
-
-export interface ReadOnlyStore {
-  dataDir: string
-  db: DatabaseSync
-  userVersion: number
-  close(): void
-}
-
-/**
- * 第二实例 / 运维查看：只读打开，不迁移、不写 runtime_epoch、不拿写锁。
- * 版本必须与代码完全一致，否则拒绝（旧代码不许读新库，新代码也不假装能处理旧库）。
- */
-export function openReadOnlyStore(dataDir?: string, expectedVersion: number = TARGET_VERSION): ReadOnlyStore {
-  const resolved = resolveDataDir(dataDir)
-  const db = openDatabase({ path: databasePath(resolved), readOnly: true })
-  const version = userVersion(db)
-  if (version > expectedVersion) {
-    closeDatabase(db)
-    throw new SchemaTooNewError(version, expectedVersion)
-  }
-  if (version < expectedVersion) {
-    closeDatabase(db)
-    throw new StoreError(
-      'SCHEMA_OUTDATED',
-      `只读实例遇到旧版本库 ${version} < ${expectedVersion}；请先用可写实例完成迁移`,
-    )
-  }
-  let closed = false
-  return {
-    dataDir: resolved,
-    db,
-    userVersion: version,
-    close(): void {
-      if (closed) return
-      closed = true
-      closeDatabase(db)
-    },
-  }
-}
-
-/** 基线表数量，供诊断页显示「41 张 P1 表是否齐」。 */
-export const P1_TABLE_COUNT = P1_SCHEMA_META.tables

package/src/store/db.ts

@@ -1,179 +0,0 @@
-/**
- * node:sqlite 的唯一封装点。
- *
- * 约定（来自实测）：
- * - 连接参数固定 WAL + foreign_keys=ON + busy_timeout，由本文件统一设置，别处不再重复；
- * - 写事务一律 BEGIN IMMEDIATE，禁止嵌套；
- * - 本版运行时的 DatabaseSync 没有 backup()，备份走 VACUUM INTO（见 backup.ts）。
- *
- * 这一层只碰数据库，不解析宿主对象、不读 $DSH_HOME/sessions/。
- */
-import { DatabaseSync } from 'node:sqlite'
-import { mkdirSync } from 'node:fs'
-import { homedir } from 'node:os'
-import path from 'node:path'
-import { createHash } from 'node:crypto'
-
-export const DB_FILENAME = 'hams.db'
-export const DEFAULT_BUSY_TIMEOUT_MS = 5000
-
-export interface OpenDatabaseOptions {
-  /** 数据库文件的绝对路径。 */
-  path: string
-  /** 只读打开：第二实例与运维查看用；不建目录、不设 WAL。 */
-  readOnly?: boolean
-  busyTimeoutMs?: number
-}
-
-export class StoreError extends Error {
-  code: string
-
-  constructor(code: string, message: string, options?: { cause?: unknown }) {
-    super(message, options)
-    this.code = code
-    this.name = 'StoreError'
-  }
-}
-
-/**
- * 数据目录解析：显式传入 > $DSH_HOME/hams > ~/.dsh/hams。
- * 只做路径计算，不创建目录——创建发生在 openDatabase 的可写分支。
- */
-export function resolveDataDir(
-  explicit?: string,
-  env: Record<string, string | undefined> = process.env,
-): string {
-  if (explicit && explicit.trim()) return path.resolve(explicit)
-  const dshHome = env.DSH_HOME && env.DSH_HOME.trim() ? env.DSH_HOME : path.join(homedir(), '.dsh')
-  return path.join(path.resolve(dshHome), 'hams')
-}
-
-export function databasePath(dataDir: string): string {
-  return path.join(path.resolve(dataDir), DB_FILENAME)
-}
-
-export function openDatabase(options: OpenDatabaseOptions): DatabaseSync {
-  const readOnly = options.readOnly === true
-  if (!readOnly) mkdirSync(path.dirname(options.path), { recursive: true })
-
-  const db = new DatabaseSync(options.path, { readOnly })
-  db.exec('PRAGMA foreign_keys = ON')
-  db.exec(`PRAGMA busy_timeout = ${options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS}`)
-
-  if (!readOnly) {
-    const mode = db.prepare('PRAGMA journal_mode = WAL').get() as { journal_mode?: string }
-    if (String(mode?.journal_mode ?? '').toLowerCase() !== 'wal') {
-      db.close()
-      throw new StoreError('WAL_UNAVAILABLE', `无法把 journal_mode 切到 WAL（当前 ${mode?.journal_mode}）`)
-    }
-    // 业务库按会计口径保守设置：崩溃后最后一次 tick 可以重跑，但不能丢已提交事务。
-    db.exec('PRAGMA synchronous = FULL')
-  }
-  return db
-}
-
-/** 当前事务状态以 node:sqlite 的 isTransaction 为准，不自己记账。 */
-export function isInTransaction(db: DatabaseSync): boolean {
-  return db.isTransaction === true
-}
-
-export function beginImmediate(db: DatabaseSync): void {
-  if (isInTransaction(db)) {
-    throw new StoreError('NESTED_TRANSACTION', 'BEGIN IMMEDIATE 不允许嵌套')
-  }
-  db.exec('BEGIN IMMEDIATE')
-}
-
-export function commit(db: DatabaseSync): void {
-  db.exec('COMMIT')
-}
-
-export function rollbackQuietly(db: DatabaseSync): void {
-  try {
-    db.exec('ROLLBACK')
-  } catch {
-    // 事务已经被 SQLite 自己回滚（例如语句级错误）时，这里无事可做。
-  }
-}
-
-/** 同步事务包装：回调抛错即回滚，返回值原样带回。 */
-export function transaction<T>(db: DatabaseSync, fn: () => T): T {
-  beginImmediate(db)
-  try {
-    const result = fn()
-    commit(db)
-    return result
-  } catch (error) {
-    rollbackQuietly(db)
-    throw error
-  }
-}
-
-export function userVersion(db: DatabaseSync): number {
-  const row = db.prepare('PRAGMA user_version').get() as { user_version?: number }
-  return Number(row?.user_version ?? 0)
-}
-
-export function setUserVersion(db: DatabaseSync, version: number): void {
-  if (!Number.isInteger(version) || version < 0) {
-    throw new StoreError('BAD_VERSION', `user_version 必须是非负整数，收到 ${version}`)
-  }
-  db.exec(`PRAGMA user_version = ${version}`)
-}
-
-export interface DbObject {
-  type: 'table' | 'index' | 'trigger' | 'view'
-  name: string
-  table: string
-  sql: string
-}
-
-/** 用户对象清单（排除 sqlite_ 内部表，例如 AUTOINCREMENT 生成的 sqlite_sequence）。 */
-export function listObjects(db: DatabaseSync): DbObject[] {
-  const rows = db
-    .prepare(
-      `SELECT type, name, tbl_name AS "table", COALESCE(sql, '') AS sql
-         FROM sqlite_master
-        WHERE type IN ('table','index','trigger','view')
-          AND name NOT LIKE 'sqlite_%'
-        ORDER BY type, name`,
-    )
-    .all() as DbObject[]
-  return rows.map((row) => ({ ...row }))
-}
-
-export function tableNames(db: DatabaseSync): string[] {
-  return listObjects(db)
-    .filter((object) => object.type === 'table')
-    .map((object) => object.name)
-}
-
-/** 每张用户表的行数；备份校验与冒烟检查共用。 */
-export function tableRowCounts(db: DatabaseSync): Record<string, number> {
-  const counts: Record<string, number> = {}
-  for (const name of tableNames(db)) {
-    const row = db.prepare(`SELECT COUNT(*) AS c FROM "${name.replaceAll('"', '""')}"`).get() as { c: number }
-    counts[name] = Number(row.c)
-  }
-  return counts
-}
-
-/** 结构指纹：对象类型 + 名字 + 规范化 SQL 的哈希，用于「备份与源库结构一致」的判断。 */
-export function schemaFingerprint(db: DatabaseSync): string {
-  const parts = listObjects(db).map((object) => `${object.type}|${object.name}|${normalizeSql(object.sql)}`)
-  return createHash('sha256').update(parts.join('\n')).digest('hex')
-}
-
-/** 只折叠空白，不改写 SQL 文本——注释也是结构的一部分（保存了分期标记）。 */
-export function normalizeSql(sql: string): string {
-  return sql.replace(/\s+/g, ' ').trim()
-}
-
-export function objectByTypeAndName(db: DatabaseSync, type: string, name: string): DbObject | undefined {
-  return listObjects(db).find((object) => object.type === type && object.name === name)
-}
-
-export function closeDatabase(db: DatabaseSync): void {
-  if (isInTransaction(db)) rollbackQuietly(db)
-  db.close()
-}

package/src/store/lock.ts

@@ -1,194 +0,0 @@
-/**
- * 单写者锁：$DSH_HOME/hams/hams.lock（JSON：pid / started_at / heartbeat_at / hostname / token）。
- *
- * 语义（dsh-compat §7）：
- * - 拿到锁的进程才允许迁移、tick 与写命令；拿不到的实例只读打开并在界面说明；
- * - 持有进程已不存在，或心跳超过 staleMs（默认 30 秒），视为陈旧锁，可接管；
- * - 接管与续期都用「写临时文件 + rename」的原子替换，rename 覆盖是原子的，
- *   写完再读回校验 token，避免两个进程同时接管后都以为自己是写者；
- * - 释放只删自己 token 的锁，绝不删别人的。
- */
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs'
-import { hostname as osHostname } from 'node:os'
-import { randomUUID } from 'node:crypto'
-import path from 'node:path'
-import { StoreError } from './db.ts'
-
-export const LOCK_FILENAME = 'hams.lock'
-export const DEFAULT_STALE_MS = 30_000
-
-export interface LockInfo {
-  token: string
-  pid: number
-  hostname: string
-  startedAt: number
-  heartbeatAt: number
-  runtimeEpoch: number
-}
-
-export class LockHeldError extends StoreError {
-  holder: LockInfo | null
-
-  constructor(holder: LockInfo | null, lockPath: string) {
-    super(
-      'LOCK_HELD',
-      holder
-        ? `数据目录已被 pid=${holder.pid}（${holder.hostname}，心跳 ${holder.heartbeatAt}）持有：${lockPath}`
-        : `数据目录锁存在但内容不可解析，已按陈旧锁处理失败：${lockPath}`,
-    )
-    this.holder = holder
-  }
-}
-
-export interface AcquireLockOptions {
-  staleMs?: number
-  now?: number
-  pid?: number
-  hostname?: string
-  runtimeEpoch?: number
-}
-
-export interface LockHandle {
-  path: string
-  info: LockInfo
-  /** 刷新心跳；返回写入后的快照。 */
-  heartbeat(now?: number): LockInfo
-  /** 只删自己 token 的锁；返回是否真的删掉了。 */
-  release(): boolean
-  ageMs(now?: number): number
-}
-
-export function lockPath(dataDir: string): string {
-  return path.join(path.resolve(dataDir), LOCK_FILENAME)
-}
-
-export function readLock(dataDir: string): LockInfo | null {
-  const file = lockPath(dataDir)
-  if (!existsSync(file)) return null
-  try {
-    const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<LockInfo>
-    if (
-      typeof parsed.token !== 'string' ||
-      typeof parsed.pid !== 'number' ||
-      typeof parsed.heartbeatAt !== 'number'
-    ) {
-      return null
-    }
-    return {
-      token: parsed.token,
-      pid: parsed.pid,
-      hostname: typeof parsed.hostname === 'string' ? parsed.hostname : '',
-      startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
-      heartbeatAt: parsed.heartbeatAt,
-      runtimeEpoch: typeof parsed.runtimeEpoch === 'number' ? parsed.runtimeEpoch : 0,
-    }
-  } catch {
-    return null
-  }
-}
-
-export function isProcessAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch (error) {
-    // EPERM 说明进程存在但无权发信号，仍算活着。
-    return (error as NodeJS.ErrnoException).code === 'EPERM'
-  }
-}
-
-function writeAtomic(target: string, info: LockInfo): void {
-  const tmp = `${target}.${info.token}.${process.pid}.tmp`
-  writeFileSync(tmp, `${JSON.stringify(info)}\n`, { mode: 0o600 })
-  renameSync(tmp, target)
-}
-
-export function acquireLock(dataDir: string, options: AcquireLockOptions = {}): LockHandle {
-  const dir = path.resolve(dataDir)
-  const file = lockPath(dir)
-  const now = options.now ?? Date.now()
-  const staleMs = options.staleMs ?? DEFAULT_STALE_MS
-  const pid = options.pid ?? process.pid
-  const hostname = options.hostname ?? osHostname()
-
-  mkdirSync(dir, { recursive: true })
-
-  const candidate: LockInfo = {
-    token: randomUUID(),
-    pid,
-    hostname,
-    startedAt: now,
-    heartbeatAt: now,
-    runtimeEpoch: options.runtimeEpoch ?? 0,
-  }
-
-  const current = readLock(dir)
-  if (current) {
-    const sameHost = current.hostname === hostname
-    const heartbeatAge = now - current.heartbeatAt
-    const dead = sameHost && !isProcessAlive(current.pid)
-    const stale = dead || heartbeatAge > staleMs
-    if (!stale) {
-      if (sameHost && current.pid === pid) {
-        throw new StoreError(
-          'LOCK_HELD_SELF',
-          `本进程（pid=${pid}）已经持有该数据目录的锁：${file}；不要重复获取`,
-        )
-      }
-      throw new LockHeldError(current, file)
-    }
-  }
-
-  writeAtomic(file, candidate)
-  const confirmed = readLock(dir)
-  if (!confirmed || confirmed.token !== candidate.token) {
-    throw new LockHeldError(confirmed, file)
-  }
-
-  let released = false
-
-  const handle: LockHandle = {
-    path: file,
-    info: confirmed,
-    heartbeat(at?: number): LockInfo {
-      if (released) throw new StoreError('LOCK_RELEASED', '锁已释放，不能再续期')
-      const currentInfo = readLock(dir)
-      if (!currentInfo || currentInfo.token !== candidate.token) {
-        throw new StoreError('LOCK_LOST', '锁已被其它进程接管，续期失败')
-      }
-      const next: LockInfo = {
-        ...currentInfo,
-        heartbeatAt: at ?? Date.now(),
-        runtimeEpoch: currentInfo.runtimeEpoch,
-      }
-      writeAtomic(file, next)
-      handle.info = next
-      return next
-    },
-    release(): boolean {
-      if (released) return false
-      const currentInfo = readLock(dir)
-      if (!currentInfo || currentInfo.token !== candidate.token) {
-        released = true
-        return false
-      }
-      unlinkSync(file)
-      released = true
-      return true
-    },
-    ageMs(at?: number): number {
-      return (at ?? Date.now()) - handle.info.heartbeatAt
-    },
-  }
-
-  handle.info = confirmed
-  return handle
-}