synabun 1.3.0 → 2.0.0-beta

package/scripts/recover-user-config.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+/**
+ * Build a validated recovery staging tree from a SynaBun backup.
+ *
+ * The current .env, memory database, blobs, whiteboard, images, and transient
+ * runtime state are preserved. Only allow-listed user configuration is merged
+ * from the backup, with backup values winning conflicts and current-only object
+ * keys retained.
+ */
+
+import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(SCRIPT_DIR, '..');
+const requireFromNeuralInterface = createRequire(resolve(PACKAGE_ROOT, 'neural-interface', 'package.json'));
+const AdmZip = requireFromNeuralInterface('adm-zip');
+
+export const RECOVERABLE_CONFIG_FILES = new Set([
+  'ui-state.json',
+  'greeting-config.json',
+  'codex-greeting-config.json',
+  'opencode-greeting-config.json',
+  'hook-features.json',
+  'claude-code-projects.json',
+  'keybinds.json',
+  'cli-config.json',
+  'loop-folders.json',
+  'auto-backup-config.json',
+  'cost-tracking.json',
+  'image-favorites.json',
+  'browser-config.json',
+  'browser-storage.json',
+  'stored-plans.json',
+  'synabun-plugins.json',
+  'mcp-registry.json',
+  'active-profile.json',
+]);
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Backup values win conflicts; current-only nested object keys survive. */
+export function mergeBackupBaseline(backup, current) {
+  if (!isPlainObject(backup) || !isPlainObject(current)) return structuredClone(backup);
+  const result = structuredClone(backup);
+  for (const [key, currentValue] of Object.entries(current)) {
+    if (!(key in backup)) {
+      result[key] = structuredClone(currentValue);
+      continue;
+    }
+    if (isPlainObject(backup[key]) && isPlainObject(currentValue)) {
+      result[key] = mergeBackupBaseline(backup[key], currentValue);
+    }
+  }
+  return result;
+}
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function parseJsonBuffer(buffer, label) {
+  try {
+    return JSON.parse(buffer.toString('utf-8'));
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${label}: ${error.message}`);
+  }
+}
+
+function scheduleArray(value) {
+  if (Array.isArray(value)) return value;
+  return Array.isArray(value?.schedules) ? value.schedules : [];
+}
+
+function templateArray(value) {
+  if (Array.isArray(value)) return value;
+  return Array.isArray(value?.templates) ? value.templates : [];
+}
+
+function validateAutomationData(dataDir) {
+  const schedules = [];
+  const templates = [];
+  const groups = [];
+  const files = [];
+
+  for (const file of readdirSync(dataDir).sort()) {
+    if (!/^loop-(schedules|templates).*\.json$/.test(file)) continue;
+    const parsed = JSON.parse(readFileSync(resolve(dataDir, file), 'utf-8'));
+    files.push(file);
+    if (file.startsWith('loop-schedules')) {
+      schedules.push(...scheduleArray(parsed));
+      if (file === 'loop-schedules.json' && Array.isArray(parsed?.groups)) groups.push(...parsed.groups);
+    } else {
+      templates.push(...templateArray(parsed));
+    }
+  }
+
+  const duplicateIds = (items) => {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const item of items) {
+      if (!item?.id) continue;
+      if (seen.has(String(item.id))) duplicates.add(String(item.id));
+      seen.add(String(item.id));
+    }
+    return [...duplicates];
+  };
+
+  const duplicateSchedules = duplicateIds(schedules);
+  const duplicateTemplates = duplicateIds(templates);
+  const duplicateGroups = duplicateIds(groups);
+  if (duplicateSchedules.length || duplicateTemplates.length || duplicateGroups.length) {
+    throw new Error(`Duplicate automation IDs: schedules=${duplicateSchedules.join(',') || 'none'}, templates=${duplicateTemplates.join(',') || 'none'}, groups=${duplicateGroups.join(',') || 'none'}`);
+  }
+
+  const templateIds = new Set(templates.map(item => String(item.id)));
+  const groupIds = new Set(groups.map(item => String(item.id)));
+  const missingTemplates = schedules.filter(item => item.templateId && !templateIds.has(String(item.templateId)));
+  const missingGroups = schedules.filter(item => item.groupId && !groupIds.has(String(item.groupId)));
+  if (missingTemplates.length || missingGroups.length) {
+    throw new Error(
+      `Broken automation references: templates=${missingTemplates.map(item => item.name || item.id).join(',') || 'none'}, ` +
+      `groups=${missingGroups.map(item => item.name || item.id).join(',') || 'none'}`
+    );
+  }
+
+  return {
+    scheduleCount: schedules.length,
+    templateCount: templates.length,
+    groupCount: groups.length,
+    automationFiles: files,
+  };
+}
+
+function backupEntryName(prefix, file) {
+  return `${prefix}/data/${file}`;
+}
+
+function recoverableBackupFiles(zip, prefix) {
+  return zip.getEntries()
+    .map(entry => entry.entryName)
+    .filter(name => name.startsWith(`${prefix}/data/`))
+    .map(name => name.slice(`${prefix}/data/`.length))
+    .filter(file => !file.includes('/'))
+    .filter(file => RECOVERABLE_CONFIG_FILES.has(file) || /^loop-(schedules|templates).*\.json$/.test(file))
+    .sort();
+}
+
+export function buildRecovery({ backupPath, currentRoot, outputRoot, now = () => new Date() }) {
+  if (!backupPath || !currentRoot || !outputRoot) throw new Error('backupPath, currentRoot, and outputRoot are required');
+  const current = resolve(currentRoot);
+  const output = resolve(outputRoot);
+  if (!existsSync(backupPath)) throw new Error(`Backup not found: ${backupPath}`);
+  if (!existsSync(resolve(current, 'mcp-data', 'memory.db'))) throw new Error(`Current memory database not found in ${current}`);
+
+  const zip = new AdmZip(backupPath);
+  const manifestEntry = zip.getEntries().find(entry => entry.entryName.endsWith('/manifest.json'));
+  if (!manifestEntry) throw new Error('Backup manifest.json not found');
+  const prefix = manifestEntry.entryName.slice(0, -'/manifest.json'.length);
+  const manifest = parseJsonBuffer(manifestEntry.getData(), manifestEntry.entryName);
+  if (manifest.version !== 2) throw new Error(`Unsupported backup version: ${manifest.version}`);
+
+  const files = recoverableBackupFiles(zip, prefix);
+  if (!files.some(file => file.startsWith('loop-schedules'))) throw new Error('Backup contains no schedule files');
+
+  rmSync(output, { recursive: true, force: true });
+  mkdirSync(output, { recursive: true });
+  for (const item of ['.env', 'data', 'mcp-data']) {
+    const source = resolve(current, item);
+    if (existsSync(source)) cpSync(source, resolve(output, item), { recursive: true, force: true, dereference: false });
+  }
+  mkdirSync(resolve(output, 'data'), { recursive: true });
+
+  const restored = [];
+  const merged = [];
+  for (const file of files) {
+    const entryName = backupEntryName(prefix, file);
+    const entry = zip.getEntry(entryName);
+    if (!entry) throw new Error(`Backup entry disappeared: ${entryName}`);
+    const buffer = entry.getData();
+    const expected = manifest.checksums?.[`data/${file}`]?.replace(/^sha256:/, '');
+    if (expected && sha256(buffer) !== expected) throw new Error(`Checksum mismatch for data/${file}`);
+
+    const backupValue = parseJsonBuffer(buffer, entryName);
+    const currentPath = resolve(current, 'data', file);
+    let outputValue = backupValue;
+    if (existsSync(currentPath)) {
+      const currentValue = JSON.parse(readFileSync(currentPath, 'utf-8'));
+      outputValue = mergeBackupBaseline(backupValue, currentValue);
+      merged.push(file);
+    } else {
+      restored.push(file);
+    }
+
+    if (file === 'ui-state.json' && isPlainObject(outputValue)) {
+      const currentValue = existsSync(currentPath) ? JSON.parse(readFileSync(currentPath, 'utf-8')) : {};
+      if (currentValue._version !== undefined) outputValue._version = currentValue._version;
+      outputValue._updated = now().toISOString();
+    }
+    writeFileSync(resolve(output, 'data', file), JSON.stringify(outputValue, null, 2) + '\n', 'utf-8');
+  }
+
+  const automation = validateAutomationData(resolve(output, 'data'));
+  const report = {
+    version: 1,
+    builtAt: now().toISOString(),
+    backupPath: resolve(backupPath),
+    backupCreatedAt: manifest.created,
+    currentRoot: current,
+    outputRoot: output,
+    restored,
+    merged,
+    excluded: ['env.bak', 'database/memory.db', 'mcp-data/', 'global-skills/', 'global-agents/', 'skins/', 'transient runtime files'],
+    ...automation,
+  };
+  writeFileSync(resolve(output, '.recovery-report.json'), JSON.stringify(report, null, 2) + '\n', 'utf-8');
+  return report;
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const backupPath = option('--backup');
+    const currentRoot = option('--current') || PACKAGE_ROOT;
+    const outputRoot = option('--output');
+    if (!backupPath || !outputRoot) {
+      console.error('Usage: node scripts/recover-user-config.mjs --backup <zip> --output <staging-root> [--current <data-root>]');
+      process.exit(1);
+    }
+    const report = buildRecovery({ backupPath, currentRoot, outputRoot });
+    console.log(JSON.stringify(report, null, 2));
+  } catch (error) {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  }
+}

package/scripts/restore-data-home-from-backup.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * Restore durable SynaBun state from a verified v2/v3 backup.
+ *
+ * The archive is fully checksum-verified before extraction. Restore happens in
+ * a sibling staging directory; the existing target is renamed (never deleted)
+ * immediately before the staged tree is atomically activated.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Streaming reader: AdmZip buffered the whole archive, which Node refuses past
+// 2 GiB, so large data homes could be backed up but never restored.
+import {
+  extractZipEntry,
+  openZipArchive,
+  readBackupManifest,
+  verifyBackupChecksums,
+} from '../neural-interface/lib/backup-zip-reader.js';
+
+function pathIsInside(candidate, parent) {
+  const rel = relative(resolve(parent), resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function timestamp(date) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/** Open the archive and stream-verify every checksum before anything is extracted. */
+async function parseArchive(backupPath) {
+  const zip = await openZipArchive(backupPath);
+  try {
+    const found = await readBackupManifest(zip);
+    if (!found || !found.prefix) throw new Error('Invalid backup: manifest.json is missing');
+    const { manifest, prefix } = found;
+    if (![2, 3].includes(manifest.version)) {
+      throw new Error(`Unsupported backup version: ${manifest.version}. Expected v2 or v3.`);
+    }
+    await verifyBackupChecksums(zip, { prefix, manifest, label: 'Invalid backup' });
+    return { zip, entries: zip.entries, manifest, prefix };
+  } catch (error) {
+    await zip.close().catch(() => {});
+    throw error;
+  }
+}
+
+function restoredRelativePath(entryName, prefix) {
+  const rel = entryName.slice(`${prefix}/`.length);
+  if (rel === 'env.bak') return '.env';
+  if (rel === 'database/memory.db') return 'mcp-data/memory.db';
+  if (rel.startsWith('data/') || rel.startsWith('mcp-data/')) return rel;
+  return null;
+}
+
+async function writeSelectedEntries({ zip, entries, prefix, stageRoot }) {
+  const selected = [];
+  for (const entry of entries) {
+    if (entry.isDirectory || !entry.name.startsWith(`${prefix}/`)) continue;
+    const rel = restoredRelativePath(entry.name, prefix);
+    if (!rel) continue;
+    const target = resolve(stageRoot, rel);
+    if (!pathIsInside(target, stageRoot) || target === resolve(stageRoot)) throw new Error(`Unsafe backup path: ${entry.name}`);
+    selected.push({ entry, rel, target });
+  }
+  for (const { entry, target } of selected) await extractZipEntry(zip, entry, target);
+  return [...new Set(selected.map(item => item.rel))].sort();
+}
+
+function normalizeEnv(stageRoot, targetRoot) {
+  const envPath = resolve(stageRoot, '.env');
+  const values = new Map([
+    ['SYNABUN_DATA_HOME', resolve(targetRoot)],
+    ['MEMORY_DATA_DIR', resolve(targetRoot, 'mcp-data')],
+    ['SQLITE_DB_PATH', resolve(targetRoot, 'mcp-data', 'memory.db')],
+    ['DOTENV_PATH', resolve(targetRoot, '.env')],
+  ]);
+  const original = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+  const seen = new Set();
+  const lines = original.split(/\r?\n/).map(line => {
+    const match = line.match(/^(\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*)(.*)$/);
+    if (!match || !values.has(match[2])) return line;
+    seen.add(match[2]);
+    return `${match[1]}${values.get(match[2])}`;
+  });
+  for (const [key, value] of values) {
+    if (!seen.has(key)) lines.push(`${key}=${value}`);
+  }
+  writeFileSync(envPath, `${lines.join('\n').replace(/^\n+|\n+$/g, '')}\n`, 'utf-8');
+}
+
+function walkJson(root, current = root, result = []) {
+  if (!existsSync(current)) return result;
+  const stat = statSync(current);
+  if (stat.isFile()) {
+    if (current.endsWith('.json')) result.push(current);
+    return result;
+  }
+  for (const name of readdirSync(current)) walkJson(root, resolve(current, name), result);
+  return result;
+}
+
+/**
+ * JSON that does not parse is restored exactly as it was backed up and
+ * reported. The checksums already proved these bytes match the archive, so a
+ * bad file here was bad in the source. One torn hook-state write
+ * (data/pending-remember/*.json) used to refuse the restore of a whole data home.
+ */
+function findInvalidJson(stageRoot) {
+  const invalid = [];
+  for (const path of walkJson(stageRoot)) {
+    try { JSON.parse(readFileSync(path, 'utf-8')); }
+    catch (error) { invalid.push({ path: relative(stageRoot, path), error: error.message }); }
+  }
+  return invalid;
+}
+
+function validateStage(stageRoot) {
+  const dbPath = resolve(stageRoot, 'mcp-data', 'memory.db');
+  if (!existsSync(dbPath)) throw new Error('Backup does not contain database/memory.db');
+  let database;
+  try {
+    database = new DatabaseSync(dbPath, { readOnly: true });
+    const integrityRow = database.prepare('PRAGMA integrity_check').get();
+    const integrity = integrityRow?.integrity_check || integrityRow?.integrity || 'unknown';
+    if (integrity !== 'ok') throw new Error(`SQLite integrity check returned: ${integrity}`);
+    const memories = Number(database.prepare('SELECT COUNT(*) AS count FROM memories').get()?.count || 0);
+    let categories = null;
+    try { categories = Number(database.prepare('SELECT COUNT(*) AS count FROM categories').get()?.count || 0); } catch {}
+    return { integrity, memories, categories, sizeBytes: statSync(dbPath).size };
+  } finally {
+    try { database?.close(); } catch {}
+  }
+}
+
+export async function restoreDataHomeFromBackup({
+  backupPath,
+  targetRoot,
+  legacyRoot = null,
+  apply = false,
+  now = () => new Date(),
+} = {}) {
+  if (!backupPath || !targetRoot) throw new Error('backupPath and targetRoot are required');
+  const backup = resolve(backupPath);
+  const target = resolve(targetRoot);
+  if (!existsSync(backup)) throw new Error(`Backup not found: ${backup}`);
+
+  const parsed = await parseArchive(backup);
+  const createdAt = now();
+  const targetName = basename(target).replace(/^\.+/, '') || 'synabun';
+  const parent = dirname(target);
+  const stage = resolve(parent, `.${targetName}.restore-stage-${process.pid}-${Date.now()}`);
+  const displacedTarget = resolve(parent, `.${targetName}.pre-restore-${timestamp(createdAt)}`);
+  let activated = false;
+  let targetMoved = false;
+  try {
+    mkdirSync(parent, { recursive: true });
+    mkdirSync(stage, { recursive: true });
+    const restoredFiles = await writeSelectedEntries({ ...parsed, stageRoot: stage });
+    normalizeEnv(stage, target);
+    const database = validateStage(stage);
+    const invalidJson = findInvalidJson(stage);
+    const existingManifest = existsSync(resolve(target, '.synabun-data-home.json'))
+      ? JSON.parse(readFileSync(resolve(target, '.synabun-data-home.json'), 'utf-8'))
+      : {};
+    const acknowledgedLegacyRoots = legacyRoot ? [resolve(legacyRoot)] : [];
+    const manifest = {
+      version: 1,
+      installationId: existingManifest.installationId || createHash('sha256').update(`${process.pid}:${Date.now()}:${Math.random()}`).digest('hex').slice(0, 32),
+      dataSchemaVersion: 1,
+      activatedAt: createdAt.toISOString(),
+      activationReason: 'verified-backup-restore',
+      restoredFrom: backup,
+      restoredBackupVersion: parsed.manifest.version,
+      restoredBackupCreatedAt: parsed.manifest.created || parsed.manifest.createdAt || null,
+      acknowledgedLegacyRoots,
+    };
+    writeFileSync(resolve(stage, '.synabun-data-home.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    const result = {
+      applied: false,
+      backupPath: backup,
+      targetRoot: target,
+      displacedTarget: existsSync(target) ? displacedTarget : null,
+      manifest: parsed.manifest,
+      database,
+      invalidJson,
+      restoredFiles,
+    };
+    if (!apply) return result;
+
+    if (existsSync(target)) {
+      renameSync(target, displacedTarget);
+      targetMoved = true;
+    }
+    renameSync(stage, target);
+    activated = true;
+    return { ...result, applied: true };
+  } catch (error) {
+    if (targetMoved && !existsSync(target) && existsSync(displacedTarget)) renameSync(displacedTarget, target);
+    throw error;
+  } finally {
+    await parsed.zip.close().catch(() => {});
+    if (!activated) rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = await restoreDataHomeFromBackup({
+      backupPath: option('--backup') || option('--from'),
+      targetRoot: option('--target'),
+      legacyRoot: option('--legacy-root'),
+      apply: process.argv.includes('--apply'),
+    });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}