/** * Types for `ops.mjs`, which is plain JavaScript because it runs without the app. * Everything importing it from `src/` is type-checked, so its shapes live here. */ import type { DbState } from './db-state.d.mts'; export type BackupManifest = { /** A later format keeps an older manifest readable. */ readonly format: number; readonly createdAt: string; readonly madeBy: string; readonly source: string; readonly database: { readonly file: string; readonly bytes: number; readonly sha256: string }; readonly secret: boolean; readonly uploads: { readonly files: number; readonly bytes: number } | null; readonly schema: { readonly applied: number; readonly newest: string | null; readonly lastVersion: string | null; readonly lastOpenedAt: string | null; }; readonly integrity: string; readonly contents: BackupContents; }; export type BackupContents = { readonly feedback?: number | null; readonly shares?: number | null; readonly invitations?: number | null; readonly projects: number | null; readonly scenes: number | null; readonly notes: number | null; /** * Optional: a manifest from an older build holds none of these, so a reader * that compares them skips them. */ readonly accounts?: number | null; readonly passkeys?: number | null; readonly sceneVersions?: number | null; readonly itemVersions?: number | null; readonly checkpoints?: number | null; readonly images?: number | null; readonly noteTypes?: number | null; readonly storylines?: number | null; readonly plotCards?: number | null; readonly writingDays?: number | null; readonly writingGoals?: number | null; readonly importReports?: number | null; }; export type BackupResult = { readonly dir: string; readonly manifest: BackupManifest; /** Backups removed to stay within `keep`. */ readonly pruned: string[]; }; export type VerifyReport = { /** True only when `problems` is empty. */ readonly ok: boolean; readonly problems: string[]; readonly manifest: BackupManifest | null; readonly database?: { path: string; bytes: number; sha256: string } | null; readonly schema?: DbState | null; readonly contents?: BackupContents | null; readonly integrity?: string; readonly foreignKeyProblems?: number; readonly secret?: boolean; readonly uploads?: { files: number; bytes: number } | null; }; export type RestoreResult = { readonly databasePath: string; /** Where the replaced database was moved, or null when there was none. */ readonly previous: string | null; readonly secret: boolean; readonly uploads: { files: number; bytes: number } | null; }; export type DrillCheck = { readonly id: string; readonly label: string; readonly ok: boolean; /** What the check found, in one sentence a reader can act on. */ readonly detail: string; }; export type DrillBackup = { readonly dir: string; readonly createdAt: string | null; readonly madeBy: string | null; readonly sha256: string | null; readonly applied: number | null; readonly newest: string | null; readonly lastVersion: string | null; }; /** One line of `restore-drills.ndjson`, beside the database. */ export type DrillRecord = { readonly format: number; /** When the drill ran, as an ISO string. */ readonly at: string; readonly ok: boolean; /** The build that ran the drill, not the build that made the backup. */ readonly madeBy: string; /** The instance the backup was taken from, when this drill took one. */ readonly source: string | null; readonly backup: DrillBackup | null; readonly restored: { readonly bytes: number; readonly uploads: { files: number; bytes: number } | null; } | null; readonly checks: readonly DrillCheck[]; /** Every failed check, in the words the check reported. */ readonly problems: readonly string[]; readonly durationMs: number; }; export type DrillResult = DrillRecord & { /** Where the record was appended, or null when it could not be written. */ readonly recordPath: string | null; readonly recordError: string | null; }; export function takeBackup(options: { databasePath: string; dataDir?: string; outDir?: string; keep?: number; /** The database alone, for a deployment that copies the rest of the data itself. */ databaseOnly?: boolean; now?: Date; }): BackupResult; export function verifyBackup(dir: string | undefined): VerifyReport; export function restoreBackup(options: { dir: string; databasePath: string; dataDir?: string; now?: Date; }): RestoreResult; /** The file the drill appends its records to, inside the data directory. */ export const DRILLS_FILE: string; /** * Restores a backup into an empty directory and checks what came back. Reads * the copy, never the instance, so it runs while the app is serving. */ export function drillRestore(options: { /** The instance to back up when no `backupDir` names a backup. */ databasePath?: string | null; dataDir: string; outDir?: string; /** The backup to exercise. Without it the drill takes one first. */ backupDir?: string; /** Where the restored copy goes. Defaults to the system temporary directory. */ scratchDir?: string; keep?: number; now?: Date; }): DrillResult; export type PruneUploadsResult = { readonly totalFiles: number; readonly totalBytes: number; readonly referencedFiles: number; readonly unreferencedFiles: number; readonly unreferencedBytes: number; /** Unreferenced files left alone because they are inside the grace window. */ readonly recentFiles: number; readonly recentBytes: number; readonly removedFiles: number; readonly removedBytes: number; /** One line per file the filesystem refused to delete, as `path: reason`. */ readonly failedFiles: readonly string[]; }; export type DropOriginalsResult = { readonly totalOriginals: number; readonly totalBytes: number; /** Originals a sweep may drop: the display copy is there and old enough. */ readonly droppableOriginals: number; readonly droppableBytes: number; readonly droppedOriginals: number; readonly droppedBytes: number; /** Originals kept because the display copy is missing, so they are the only copy. */ readonly keptOriginals: number; readonly recentOriginals: number; /** Rows that claim an original the disk no longer holds. */ readonly missingOriginals: number; readonly failedFiles: readonly string[]; }; /** Re-exported from `history-retention.mjs` for CLI callers and parity specs. */ export const DEFAULT_RETENTION_DAYS: number; export const KEEP_SCENE_VERSIONS: number; export const KEEP_ITEM_VERSIONS: number; export const KEEP_PROJECT_VERSIONS: number; export type HistoryPruneResult = { readonly days: number; /** The oldest moment that survives, or null when the window is off. */ readonly cutoff: string | null; /** Rows removed, or that a dry run would remove. */ readonly sceneVersions: number; readonly itemVersions: number; readonly projectVersions: number; /** Rows the instance holds, for a report of what is at stake. */ readonly held: { readonly sceneVersions: number; readonly itemVersions: number; readonly projectVersions: number; }; readonly removed: boolean; readonly bytesBefore: number; readonly bytesAfter: number; /** Space the vacuum gave back, or null when no vacuum ran. */ readonly reclaimedBytes: number | null; }; export function pruneHistory(options: { databasePath: string; /** A day count, or the flag as typed. Omitted reads the instance setting. */ days?: number | string; includeKept?: boolean; apply?: boolean; vacuum?: boolean; now?: Date; }): HistoryPruneResult; export function pruneUploads(options: { databasePath: string; dataDir?: string; apply?: boolean; graceMs?: number; }): PruneUploadsResult; export function dropOriginals(options: { databasePath: string; dataDir?: string; apply?: boolean; graceMs?: number; }): DropOriginalsResult; /** * How long a file must have sat on disk before a sweep may delete it. It covers * the gap between the app publishing a file and committing the row that names it. */ export const SWEEP_GRACE_MS: number; export function main(argv?: string[]): number; export type ResetPasswordResult = { /** The address as it is stored, which may differ in case from the argument. */ readonly email: string; readonly sessions: number; }; /** The hash better-auth stores: salt in hex, then the scrypt key in hex. */ export function hashPassword(password: string): string; /** A password an operator can read out and type. */ export function generatePassword(length?: number): string; export function resetPassword(options: { databasePath: string; email: string; password: string; }): ResetPasswordResult; export type DeleteAccountResult = { /** The address as it is stored, which may differ in case from the argument. */ readonly email: string; /** Projects removed with the account. */ readonly projects: number; /** How many of those had other people in them. */ readonly shared: number; }; export function deleteAccount(options: { databasePath: string; email: string; deleteSharedProjects?: boolean; }): DeleteAccountResult;