refactor(8.0): delete DataAPI — superseded by Db persist/restore + import API + stats

The legacy backup/import/export/stats facade (src/api/DataAPI.ts) drifted
from the modern entity shape and every job it did now has a first-class
surface. Delete it and brain.data(), and rewire the CLI:

- data-stats → brain.stats() (full BrainyStats report: per-type breakdowns,
  indexed fields, index health, storage backend, writer lock, version)
- clean → brain.clear()
- export → alias of snapshot; a db.persist() snapshot is the full-fidelity
  export format (open with Brainy.load, load wholesale with brainy restore);
  external data ingestion remains brainy import (UniversalImportAPI)

Rewiring clean onto brain.clear() exposed two real bugs, both fixed:

- clear() left this.graphIndex undefined forever — any graph-touching call
  afterwards (relate, getNeighbors, stats) crashed. clear() now re-resolves
  the graph index exactly as init() does and re-wires the shared UUID↔int
  resolver, and re-resolves the metadata index with the same provider
  fallback as init().
- storage.clear() reset the legacy totals but not the per-type/subtype
  count rollups or id→type caches, so stats() reported phantom counts for
  deleted entities. Both adapters now delegate derived-state reset to
  reloadDerivedState(), the same path restore-from-snapshot uses.

One-shot CLI commands (data-stats, clean, snapshot/export, restore,
history, generation) now close the brain and exit explicitly — global
cache timers otherwise keep the process alive holding the writer lock.

Verified: build clean, 1383/1383 unit tests, 24/24 db-mvcc integration,
plus an end-to-end CLI smoke (add → data-stats → export → clean →
data-stats).
This commit is contained in:
David Snelling 2026-06-11 09:05:12 -07:00
parent cc8037db10
commit 478fa176f2
12 changed files with 262 additions and 639 deletions

View file

@ -1,13 +1,14 @@
/**
* Core CLI Commands - TypeScript Implementation
*
* Essential database operations: add, search, get, relate, import, export
* @module cli/commands/core
* @description Essential database CLI commands: add, search, get, update,
* delete, relate, unrelate, and diagnostics. Database export lives under
* `brainy snapshot` (aliased as `brainy export`) a `db.persist()` snapshot
* is the full-fidelity export format.
*/
import chalk from 'chalk'
import ora from 'ora'
import inquirer from 'inquirer'
import { readFileSync, writeFileSync } from 'node:fs'
import { Brainy } from '../../brainy.js'
import { BrainyTypes, NounType, VerbType } from '../../index.js'
@ -66,10 +67,6 @@ interface RelateOptions extends CoreOptions {
subtype?: string
}
interface ExportOptions extends CoreOptions {
format?: 'json' | 'csv' | 'jsonl'
}
let brainyInstance: Brainy | null = null
const getBrainy = (): Brainy => {
@ -866,82 +863,6 @@ export const coreCommands = {
}
},
/**
* Export database
*/
async export(file: string | undefined, options: ExportOptions) {
const spinner = ora('Exporting database...').start()
try {
const brain = getBrainy()
const format = options.format || 'json'
// Export all data
const dataApi = await brain.data()
const data = await dataApi.export({ format: 'json' })
let output = ''
switch (format) {
case 'json':
output = options.pretty
? JSON.stringify(data, null, 2)
: JSON.stringify(data)
break
case 'jsonl':
if (Array.isArray(data)) {
output = data.map(item => JSON.stringify(item)).join('\n')
} else {
output = JSON.stringify(data)
}
break
case 'csv':
if (Array.isArray(data) && data.length > 0) {
// Get all unique keys for headers
const headers = new Set<string>()
data.forEach(item => {
Object.keys(item).forEach(key => headers.add(key))
})
const headerArray = Array.from(headers)
// Create CSV
output = headerArray.join(',') + '\n'
output += data.map(item => {
return headerArray.map(h => {
const value = item[h]
if (typeof value === 'object') {
return JSON.stringify(value)
}
return value || ''
}).join(',')
}).join('\n')
}
break
}
if (file) {
writeFileSync(file, output)
spinner.succeed(`Exported to ${file}`)
if (!options.json) {
console.log(chalk.green(`✓ Successfully exported database to ${file}`))
console.log(chalk.dim(` Format: ${format}`))
console.log(chalk.dim(` Items: ${Array.isArray(data) ? data.length : 1}`))
} else {
formatOutput({ file, format, count: Array.isArray(data) ? data.length : 1 }, options)
}
} else {
spinner.succeed('Export complete')
console.log(output)
}
} catch (error: any) {
spinner.fail('Export failed')
console.error(chalk.red(error.message))
process.exit(1)
}
},
/**
* Show plugin and provider diagnostics
*/