local-kanban 1.6.3

package/src/db.js

@@ -0,0 +1,321 @@
+import Database from 'better-sqlite3';
+import { readFileSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR, ROOT, langOverride, ghOwnerEnv, ghRepoEnv } from './config.js';
+
+export { DATA_DIR };
+
+mkdirSync(DATA_DIR, { recursive: true });
+
+const MIGRATIONS = [
+  { v: 1, name: 'legacy-consolidation-2026-07', up: legacyMigrate, ownTx: true },
+  { v: 2, name: 'app-errors-resolved', up: () => {
+    const cols = db.prepare('PRAGMA table_info(app_errors)').all();
+    if (!cols.length) return;
+    const has = (col) => cols.some((c) => c.name === col);
+    if (!has('op_id')) db.exec('ALTER TABLE app_errors ADD COLUMN op_id INTEGER');
+    if (!has('resolved_at')) db.exec('ALTER TABLE app_errors ADD COLUMN resolved_at TEXT');
+  } },
+  { v: 3, name: 'locked-categories-en', up: () => {
+    const cols = db.prepare('PRAGMA table_info(projects)').all();
+    if (!cols.some((c) => c.name === 'category')) return;
+    db.prepare("UPDATE projects SET category = 'Local' WHERE category = 'Локальные'").run();
+    db.prepare("UPDATE projects SET category = 'Other' WHERE category = 'Прочее'").run();
+  } },
+  { v: 4, name: 'work-truncated-counter', up: () => {
+    const cols = db.prepare('PRAGMA table_info(tasks)').all();
+    if (!cols.length || cols.some((c) => c.name === 'work_truncated')) return;
+    db.exec('ALTER TABLE tasks ADD COLUMN work_truncated INTEGER NOT NULL DEFAULT 0');
+  } },
+  { v: 5, name: 'app-errors-repeats', up: () => {
+    const cols = db.prepare('PRAGMA table_info(app_errors)').all();
+    if (!cols.length || cols.some((c) => c.name === 'repeats')) return;
+    db.exec('ALTER TABLE app_errors ADD COLUMN repeats INTEGER NOT NULL DEFAULT 0');
+  } },
+  { v: 6, name: 'sync-queue-started-at', up: () => {
+    const cols = db.prepare('PRAGMA table_info(sync_queue)').all();
+    if (!cols.length || cols.some((c) => c.name === 'started_at')) return;
+    db.exec('ALTER TABLE sync_queue ADD COLUMN started_at TEXT');
+  } },
+];
+export const SCHEMA_VERSION = MIGRATIONS.at(-1).v;
+
+function dieOnBrokenDatabase(e) {
+  const dir = join(DATA_DIR, 'backups');
+  console.error(`\n  The board could not open its database: ${e.message}\n`);
+  console.error(`  The file is ${join(DATA_DIR, 'kanban.db')}`);
+  console.error('  What to do:');
+  console.error(`    · restore the newest snapshot over it — they are in ${dir}`);
+  console.error(`    · a snapshot taken before the last schema change is in ${join(dir, 'pre-migrate')}`);
+  console.error('    · stop the board first, then copy the file back and start it again\n');
+  process.exit(1);
+}
+
+let db;
+try {
+  db = new Database(join(DATA_DIR, 'kanban.db'));
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+} catch (e) { dieOnBrokenDatabase(e); }
+export { db };
+db.function('kb_lower', { deterministic: true }, (s) => (s === null || s === undefined ? null : String(s).toLowerCase()));
+
+try {
+  migrate();
+  db.exec(readFileSync(join(ROOT, 'src', 'schema.sql'), 'utf8'));
+  backfill();
+} catch (e) { dieOnBrokenDatabase(e); }
+
+export const SYNC_MAX_ATTEMPTS = 15;
+
+export const WORK_SEGMENT_MAX_S = 2 * 3600;
+
+export const STATUSES = ['backlog', 'todo', 'prep', 'doing', 'deploy', 'review', 'done', 'cancelled'];
+
+function migrate() {
+  const from = db.pragma('user_version', { simple: true });
+  if (from >= SCHEMA_VERSION) return;
+  preMigrateBackup(from);
+  for (const m of MIGRATIONS) {
+    if (m.v <= from) continue;
+    if (m.ownTx) {
+      m.up();
+      db.pragma(`user_version = ${m.v}`);
+    } else {
+      db.transaction(() => {
+        m.up();
+        db.pragma(`user_version = ${m.v}`);
+      })();
+    }
+  }
+}
+
+function preMigrateBackup(fromVersion) {
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' LIMIT 1").get()) return;
+  const dir = join(DATA_DIR, 'backups', 'pre-migrate');
+  mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-');
+  const target = join(dir, `kanban-v${fromVersion}-${stamp}.db`);
+  const tmp = `${target}.part`;
+  rmSync(tmp, { force: true });
+  try {
+    db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
+    renameSync(tmp, target);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  const files = readdirSync(dir).filter((f) => f.endsWith('.db')).sort();
+  for (const f of files.slice(0, -5)) rmSync(join(dir, f), { force: true });
+}
+
+function legacyMigrate() {
+  const tasksSql = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='tasks'").get()?.sql;
+  if (tasksSql && !tasksSql.includes('backlog')) {
+    db.pragma('foreign_keys = OFF');
+    db.exec(`
+      BEGIN;
+      CREATE TABLE new_tasks (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_id       INTEGER NOT NULL REFERENCES projects(id),
+        task_no          INTEGER,
+        title            TEXT NOT NULL,
+        description      TEXT NOT NULL DEFAULT '',
+        status           TEXT NOT NULL DEFAULT 'backlog'
+                           CHECK (status IN ('backlog','todo','doing','deploy','review','done','cancelled')),
+        priority         INTEGER NOT NULL DEFAULT 0 CHECK (priority BETWEEN 0 AND 3),
+        labels           TEXT NOT NULL DEFAULT '[]',
+        blocked          INTEGER NOT NULL DEFAULT 0,
+        blocked_reason   TEXT,
+        position         REAL NOT NULL DEFAULT 0,
+        gh_issue_number  INTEGER,
+        gh_issue_url     TEXT,
+        gh_item_id       TEXT,
+        created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        done_at          TEXT
+      );
+      INSERT INTO new_tasks (id, project_id, title, description, status, priority, blocked, blocked_reason,
+                             position, gh_issue_number, gh_issue_url, gh_item_id, created_at, updated_at, done_at)
+        SELECT id, project_id, title, description, status, priority, blocked, blocked_reason,
+               position, gh_issue_number, gh_issue_url, gh_item_id, created_at, updated_at, done_at
+        FROM tasks;
+      DROP TABLE tasks;
+      ALTER TABLE new_tasks RENAME TO tasks;
+      DROP INDEX IF EXISTS idx_tasks_proj_status;
+      COMMIT;
+    `);
+    db.pragma('foreign_keys = ON');
+  }
+  const projCols = db.prepare("SELECT name FROM pragma_table_info('projects')").all().map((c) => c.name);
+  if (projCols.length && !projCols.includes('prefix')) db.exec('ALTER TABLE projects ADD COLUMN prefix TEXT');
+
+  const taskCols = db.prepare("SELECT name FROM pragma_table_info('tasks')").all().map((c) => c.name);
+  if (taskCols.length && !taskCols.includes('work_seconds')) {
+    db.exec('ALTER TABLE tasks ADD COLUMN work_seconds INTEGER NOT NULL DEFAULT 0');
+    db.exec('ALTER TABLE tasks ADD COLUMN work_started_at TEXT');
+  }
+  if (projCols.length && !projCols.includes('next_task_no')) db.exec('ALTER TABLE projects ADD COLUMN next_task_no INTEGER');
+  if (projCols.length && !projCols.includes('description')) db.exec('ALTER TABLE projects ADD COLUMN description TEXT');
+  if (projCols.length && !projCols.includes('pinned')) db.exec('ALTER TABLE projects ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0');
+  if (projCols.length && !projCols.includes('position')) db.exec('ALTER TABLE projects ADD COLUMN position REAL NOT NULL DEFAULT 0');
+
+  const curTasksSql = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='tasks'").get()?.sql;
+  if (curTasksSql && !curTasksSql.includes("'prep'")) {
+    db.pragma('foreign_keys = OFF');
+    db.exec(`
+      BEGIN;
+      CREATE TABLE new_tasks (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_id       INTEGER NOT NULL REFERENCES projects(id),
+        task_no          INTEGER,
+        title            TEXT NOT NULL,
+        description      TEXT NOT NULL DEFAULT '',
+        status           TEXT NOT NULL DEFAULT 'backlog'
+                           CHECK (status IN ('backlog','todo','prep','doing','deploy','review','done','cancelled')),
+        priority         INTEGER NOT NULL DEFAULT 0 CHECK (priority BETWEEN 0 AND 3),
+        labels           TEXT NOT NULL DEFAULT '[]',
+        blocked          INTEGER NOT NULL DEFAULT 0,
+        blocked_reason   TEXT,
+        position         REAL NOT NULL DEFAULT 0,
+        work_seconds     INTEGER NOT NULL DEFAULT 0,
+        work_started_at  TEXT,
+        gh_issue_number  INTEGER,
+        gh_issue_url     TEXT,
+        gh_item_id       TEXT,
+        created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        done_at          TEXT
+      );
+      INSERT INTO new_tasks (id, project_id, task_no, title, description, status, priority, labels,
+                             blocked, blocked_reason, position, work_seconds, work_started_at,
+                             gh_issue_number, gh_issue_url, gh_item_id, created_at, updated_at, done_at)
+        SELECT id, project_id, task_no, title, description, status, priority, labels,
+               blocked, blocked_reason, position, work_seconds, work_started_at,
+               gh_issue_number, gh_issue_url, gh_item_id, created_at, updated_at, done_at
+        FROM tasks;
+      DROP TABLE tasks;
+      ALTER TABLE new_tasks RENAME TO tasks;
+      COMMIT;
+    `);
+    db.pragma('foreign_keys = ON');
+  }
+
+  const tCols = db.prepare("SELECT name FROM pragma_table_info('tasks')").all().map((c) => c.name);
+  if (tCols.length && !tCols.includes('pinned')) db.exec('ALTER TABLE tasks ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0');
+  const lCols = db.prepare("SELECT name FROM pragma_table_info('task_links')").all().map((c) => c.name);
+  if (lCols.length && !lCols.includes('kind')) db.exec("ALTER TABLE task_links ADD COLUMN kind TEXT NOT NULL DEFAULT 'related'");
+  const cCols = db.prepare("SELECT name FROM pragma_table_info('task_comments')").all().map((c) => c.name);
+  if (cCols.length && !cCols.includes('image')) db.exec('ALTER TABLE task_comments ADD COLUMN image TEXT');
+}
+
+export function kvGet(key) {
+  return db.prepare('SELECT value FROM kv WHERE key = ?').get(key)?.value ?? null;
+}
+export function kvSet(key, value) {
+  db.prepare('INSERT INTO kv(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, String(value));
+}
+
+const ERRORS_KEEP = 300;
+
+const DEDUP_MS = 10000;
+const lastLogged = new Map();
+export function logError(source, scope, message, detail, opId = null) {
+  try {
+    const scopeStr = scope ? String(scope).slice(0, 200) : null;
+    const msgStr = String(message).slice(0, 500);
+    const key = `${source}
${scopeStr}
${msgStr}`;
+    const now = Date.now();
+    const seen = lastLogged.get(key);
+    if (seen && now - seen.at < DEDUP_MS) {
+      db.prepare('UPDATE app_errors SET repeats = repeats + 1 WHERE id = ?').run(seen.id);
+      return;
+    }
+    for (const [k, v] of lastLogged) { if (now - v.at >= DEDUP_MS) lastLogged.delete(k); }
+    const info = db.prepare('INSERT INTO app_errors(source, scope, message, detail, op_id) VALUES(?, ?, ?, ?, ?)')
+      .run(String(source), scopeStr, msgStr, detail ? String(detail).slice(0, 2000) : null, opId ?? null);
+    lastLogged.set(key, { at: now, id: info.lastInsertRowid });
+    db.prepare('DELETE FROM app_errors WHERE id NOT IN (SELECT id FROM app_errors ORDER BY id DESC LIMIT ?)').run(ERRORS_KEEP);
+  } catch (e) {
+    console.error('logError failed:', e?.message || e, '|', source, scope, message);
+  }
+}
+
+export function resolveErrors(opId) {
+  if (!opId) return;
+  try {
+    db.prepare("UPDATE app_errors SET resolved_at = datetime('now') WHERE op_id = ? AND resolved_at IS NULL").run(opId);
+  } catch {  }
+}
+
+export function uiLang() {
+  const v = langOverride() || kvGet('ui.lang') || 'ru';
+  return v === 'en' ? 'en' : 'ru';
+}
+
+export function ghOwner() { return ghOwnerEnv() || kvGet('gh.owner') || ''; }
+export function ghRepo() { return ghRepoEnv() || kvGet('gh.repo') || ''; }
+export function syncConfigured() { return Boolean(ghOwner() && ghRepo()); }
+
+function backfill() {
+  const used = usedPrefixes();
+  for (const p of db.prepare('SELECT id, slug FROM projects WHERE prefix IS NULL').all()) {
+    const prefix = genPrefix(p.slug, used);
+    used.add(prefix);
+    db.prepare('UPDATE projects SET prefix = ? WHERE id = ?').run(prefix, p.id);
+  }
+  db.exec(`
+    UPDATE tasks SET task_no = (
+      SELECT COUNT(*) FROM tasks t2 WHERE t2.project_id = tasks.project_id AND t2.id <= tasks.id
+    ) WHERE task_no IS NULL;
+  `);
+  db.exec(`
+    INSERT INTO task_events (task_id, status, created_at)
+    SELECT id, status, done_at FROM tasks
+    WHERE done_at IS NOT NULL AND status IN ('done','cancelled')
+      AND NOT EXISTS (SELECT 1 FROM task_events e WHERE e.task_id = tasks.id);
+  `);
+}
+
+export function genPrefix(slug, used = new Set()) {
+  const words = slug.replace(/[^a-z0-9-]/gi, '').split('-').filter(Boolean);
+  let base = words.length >= 2
+    ? words.map((w) => w[0]).join('').slice(0, 3).toUpperCase()
+    : slug.slice(0, 3).toUpperCase();
+  if (base.length < 2) base = (base + 'XX').slice(0, 2);
+  let prefix = base;
+  let n = 2;
+  while (used.has(prefix)) prefix = base + n++;
+  return prefix;
+}
+
+export function nextPosition(projectId, status) {
+  return db.prepare('SELECT COALESCE(MAX(position),0) AS mx FROM tasks WHERE project_id=? AND status=?')
+    .get(projectId, status).mx + 1;
+}
+
+export function usedPrefixes() {
+  return new Set(db.prepare('SELECT upper(prefix) AS p FROM projects WHERE prefix IS NOT NULL').all().map((r) => r.p));
+}
+export const makePrefix = (slug) => genPrefix(slug, usedPrefixes());
+
+export function nextTaskNo(projectId) {
+  db.prepare(`
+    UPDATE projects SET next_task_no = COALESCE(
+      next_task_no,
+      (SELECT COALESCE(MAX(task_no), 0) FROM tasks WHERE project_id = ?) + 1
+    ) WHERE id = ?
+  `).run(projectId, projectId);
+  const { n } = db.prepare('SELECT next_task_no AS n FROM projects WHERE id = ?').get(projectId);
+  db.prepare('UPDATE projects SET next_task_no = next_task_no + 1 WHERE id = ?').run(projectId);
+  return n;
+}
+
+export function enqueue(op, taskId, payload) {
+  if (!syncConfigured()) return;
+  if (taskId && ['set_status', 'set_priority', 'set_blocked', 'set_labels', 'update_issue'].includes(op)) {
+    db.prepare('DELETE FROM sync_queue WHERE task_id = ? AND op = ?').run(taskId, op);
+  }
+  db.prepare('INSERT INTO sync_queue (task_id, op, payload) VALUES (?, ?, ?)')
+    .run(taskId, op, JSON.stringify(payload));
+}

package/src/error-handler.js

@@ -0,0 +1,11 @@
+import { logError } from './db.js';
+
+export function errorHandler(err, req, reply) {
+  const code = err.statusCode || 500;
+  if (code >= 500) {
+    req.log.error(err);
+    logError('server', `${req.method} ${req.url.split('?')[0]}`, err.message, err.stack);
+    return reply.code(500).send({ error: 'internal error — details under Settings → Errors' });
+  }
+  return reply.send(err);
+}

package/src/file-snapshot.js

@@ -0,0 +1,22 @@
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './config.js';
+
+const KEEP = 10;
+
+export const snapshotDir = (kind) => join(DATA_DIR, 'backups', kind);
+
+export function snapshotFile(kind, label, path) {
+  if (!existsSync(path)) return null;
+  const dir = snapshotDir(kind);
+  mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const dest = join(dir, `${label}-${stamp}.md`);
+  copyFileSync(path, dest);
+  const mine = readdirSync(dir).filter((f) => f.startsWith(`${label}-`) && f.endsWith('.md')).sort();
+  for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) {
+    try { rmSync(join(dir, old), { force: true }); } catch {  }
+  }
+  return dest;
+}

package/src/origin-guard.js

@@ -0,0 +1,32 @@
+import { allowedHosts } from './config.js';
+
+const envHosts = () => allowedHosts().map((h) => h.toLowerCase());
+
+export function selfHosts(port) {
+  return new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`, ...envHosts()]);
+}
+
+export function selfOrigins(port) {
+  const out = new Set();
+  for (const h of selfHosts(port)) { out.add(`http://${h}`); out.add(`https://${h}`); }
+  return out;
+}
+
+export function makeOriginGuard(port) {
+  const hosts = selfHosts(port);
+  const origins = selfOrigins(port);
+  return function originGuard(req, reply, done) {
+    if (!hosts.has(String(req.headers.host || '').toLowerCase())) {
+      return reply.code(421).send({ error: 'request addressed to an unexpected host' });
+    }
+    const origin = req.headers.origin;
+    if (origin && !origins.has(String(origin).toLowerCase())) {
+      return reply.code(403).send({ error: 'cross-origin request rejected' });
+    }
+    const site = req.headers['sec-fetch-site'];
+    if (site && site !== 'same-origin' && site !== 'none') {
+      return reply.code(403).send({ error: 'cross-site request rejected' });
+    }
+    done();
+  };
+}

package/src/pm2-services.js

@@ -0,0 +1,31 @@
+// pm2_services: one tolerant parser for every reader.
+// The column stores a JSON array of process names, but both the "add project" wizard and
+// PATCH /api/projects document the field as "a comma-separated string <-> JSON", so a plain
+// string is a legal value that really occurs in existing databases. Every reader used to call
+// JSON.parse unconditionally, so such a row crashed `kb info` (exit 3, SyntaxError) and made
+// GET /api/projects/:slug/status answer 500.
+
+// Accepts a JSON array, a comma-separated string or an array; always returns string names.
+export function parsePm2Services(raw) {
+  if (!raw) return [];
+  const list = Array.isArray(raw) ? raw : parseRaw(String(raw));
+  return list.map((s) => String(s).trim()).filter(Boolean);
+}
+
+function parseRaw(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return parsed;
+    } catch { /* not JSON after all — fall through to the comma-separated form */ }
+  }
+  return trimmed.split(',');
+}
+
+// Canonical storage form. Returns null for an empty list so the column is cleared, not set to "[]".
+export function serializePm2Services(raw) {
+  const list = parsePm2Services(raw);
+  return list.length ? JSON.stringify(list) : null;
+}

package/src/query-params.js

@@ -0,0 +1,17 @@
+
+export function scalarParam(value, name) {
+  if (value === undefined || value === null) return { value: undefined };
+  if (Array.isArray(value)) return { error: `${name}: given more than once` };
+  if (typeof value === 'object') return { error: `${name}: expected a single value` };
+  return { value: String(value) };
+}
+
+export function scalarQuery(query, names) {
+  const out = {};
+  for (const name of names) {
+    const r = scalarParam(query?.[name], name);
+    if (r.error) return { error: r.error };
+    out[name] = r.value;
+  }
+  return { values: out };
+}

package/src/repo-base.js

@@ -0,0 +1,23 @@
+import { execFile } from 'node:child_process';
+
+const cache = new Map();
+const TTL = 5 * 60 * 1000;
+
+const gitOut = (args) => new Promise((resolve) =>
+  execFile('git', args, { timeout: 3000 }, (err, out) => resolve(err ? null : String(out).trim())));
+
+export function forgetRepoBase(path) {
+  if (path) cache.delete(path);
+}
+
+export async function repoHttpsBase(path) {
+  if (!path) return null;
+  const hit = cache.get(path);
+  if (hit && Date.now() - hit.at < TTL) return hit.base;
+  const url = await gitOut(['-C', path, 'remote', 'get-url', 'origin']);
+  // git@github.com:owner/repo.git | https://github.com/owner/repo
+  const m = url?.match(/github\.com[:/](.+?)(?:\.git)?$/);
+  const base = m ? `https://github.com/${m[1]}` : null;
+  cache.set(path, { base, at: Date.now() });
+  return base;
+}

package/src/restore.js

@@ -0,0 +1,153 @@
+import { spawn } from 'node:child_process';
+import { closeSync, cpSync, mkdtempSync, openSync, readSync, readdirSync, statSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:net';
+import Database from 'better-sqlite3';
+import { logError } from './db.js';
+import { ATTACH_MIRROR } from './backup.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const LIFETIME_MS = 30 * 60 * 1000;
+let current = null; // { port, proc, dir, startedAt, timer, stats }
+
+function readHead(path) {
+  const buf = Buffer.alloc(15);
+  let fd;
+  try { fd = openSync(path, 'r'); readSync(fd, buf, 0, 15, 0); } catch { return Buffer.alloc(0); } finally { if (fd !== undefined) closeSync(fd); }
+  return buf;
+}
+
+const freePort = () => new Promise((resolve, reject) => {
+  const s = createServer();
+  s.on('error', reject);
+  s.listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => resolve(port)); });
+});
+
+export function inspectBackup(input) {
+  const fromPath = typeof input === 'string';
+  const head = fromPath ? readHead(input) : input.subarray(0, 15);
+  const size = fromPath ? (statSync(input, { throwIfNoEntry: false })?.size ?? 0) : input.length;
+  if (size < 100 || head.toString('latin1') !== 'SQLite format 3') {
+    return { ok: false, error: 'not an SQLite database file' };
+  }
+  const dir = mkdtempSync(join(tmpdir(), 'kb-restore-'));
+  const file = join(dir, 'kanban.db');
+  if (fromPath) cpSync(input, file); else writeFileSync(file, input);
+  try {
+    const db = new Database(file, { readonly: true });
+    const integrity = db.pragma('integrity_check', { simple: true });
+    if (integrity !== 'ok') { db.close(); rmSync(dir, { recursive: true, force: true }); return { ok: false, error: `database is corrupted: ${integrity}` }; }
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((r) => r.name));
+    for (const need of ['tasks', 'projects']) {
+      if (!tables.has(need)) { db.close(); rmSync(dir, { recursive: true, force: true }); return { ok: false, error: `an SQLite database, but not a board: no ${need} table` }; }
+    }
+    const stats = {
+      tasks: db.prepare('SELECT COUNT(*) n FROM tasks').get().n,
+      projects: db.prepare('SELECT COUNT(*) n FROM projects').get().n,
+      version: db.pragma('user_version', { simple: true }),
+    };
+    db.close();
+    disarmSync(file);
+    return { ok: true, dir, stats };
+  } catch (e) {
+    rmSync(dir, { recursive: true, force: true });
+    return { ok: false, error: `could not read the database: ${e.message}` };
+  }
+}
+
+function disarmSync(file) {
+  const db = new Database(file);
+  try {
+    const has = (t) => Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(t));
+    if (has('kv')) {
+      db.prepare("DELETE FROM kv WHERE key IN ('gh.owner','gh.repo')").run();
+      db.prepare("INSERT INTO kv(key, value) VALUES('sync.paused','1') ON CONFLICT(key) DO UPDATE SET value='1'").run();
+    }
+    if (has('sync_queue')) db.prepare('DELETE FROM sync_queue').run();
+  } catch (e) {
+    logError('server', 'restore-preview', `could not disable the sync in the copy: ${e.message}`);
+    throw e;
+  } finally { db.close(); }
+}
+
+export function sweepStalePreviews() {
+  const base = tmpdir();
+  let left = 0;
+  try {
+    for (const name of readdirSync(base)) {
+      if (!name.startsWith('kb-restore-')) continue;
+      const dir = join(base, name);
+      try {
+        if (Date.now() - statSync(dir).mtimeMs < 3600 * 1000) continue;
+        rmSync(dir, { recursive: true, force: true });
+        left++;
+      } catch {  }
+    }
+  } catch {  }
+  return left;
+}
+
+export function previewProcessForTests() { return current; }
+
+export function currentPreview() {
+  if (!current) return null;
+  const { port, startedAt, stats } = current;
+  return { port, url: `http://127.0.0.1:${port}`, started_at: startedAt, stats, expires_in: Math.max(0, LIFETIME_MS - (Date.now() - startedAt)) };
+}
+
+const onExit = () => { if (current) stopPreview(); };
+const SIGNAL_HANDLERS = { SIGINT: () => { stopPreview(); process.exit(130); },
+  SIGTERM: () => { stopPreview(); process.exit(143); } };
+
+function armCleanup() {
+  process.on('exit', onExit);
+  for (const [sig, fn] of Object.entries(SIGNAL_HANDLERS)) process.on(sig, fn);
+}
+function disarmCleanup() {
+  process.off('exit', onExit);
+  for (const [sig, fn] of Object.entries(SIGNAL_HANDLERS)) process.off(sig, fn);
+}
+
+export function stopPreview() {
+  if (!current) return false;
+  const { proc, dir, timer } = current;
+  clearTimeout(timer);
+  disarmCleanup();
+  try { proc.kill('SIGTERM'); } catch {  }
+  try { setTimeout(() => { try { proc.kill('SIGKILL'); } catch {  } }, 2000).unref(); } catch {  }
+  try { rmSync(dir, { recursive: true, force: true }); } catch {  }
+  current = null;
+  return true;
+}
+
+export async function startPreview(dir, stats) {
+  stopPreview();
+  try { if (existsSync(ATTACH_MIRROR)) cpSync(ATTACH_MIRROR, join(dir, 'attachments'), { recursive: true }); } catch (e) {
+    logError('server', 'restore-preview', `could not copy the attachments into the copy: ${e.message}`);
+  }
+  const port = await freePort();
+  const proc = spawn(process.execPath, [join(ROOT, 'src', 'server.js')], {
+    cwd: ROOT,
+    env: { ...process.env, PORT: String(port), KB_DATA_DIR: dir, KB_GH_OWNER: '', KB_GH_REPO: '', KB_PREVIEW_TTL_MS: String(LIFETIME_MS) },
+    stdio: ['pipe', 'ignore', 'ignore'],
+    detached: false,
+  });
+  proc.on('exit', (code) => { if (current && current.proc === proc && code) logError('server', 'restore-preview', `the preview board crashed, code ${code}`); });
+  const timer = setTimeout(() => stopPreview(), LIFETIME_MS);
+  current = { port, proc, dir, startedAt: Date.now(), timer, stats };
+  armCleanup();
+  const deadline = Date.now() + 15000;
+  let up = false;
+  while (Date.now() < deadline) {
+    if (proc.exitCode !== null) break;
+    try { const r = await fetch(`http://127.0.0.1:${port}/api/projects`); if (r.ok) { up = true; break; } } catch {  }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  if (!up) {
+    stopPreview();
+    throw new Error('the preview board did not answer within 15 seconds');
+  }
+  return currentPreview();
+}