@adminiumjs/adminium 0.1.0-rc.1

package/dist/backup/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/backup/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAC1C,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,QAA+B,CAAC;AAEhE,eAAO,MAAM,gBAAgB,aAE3B,CAAC;AAEH,wEAAwE;AACxE,eAAO,MAAM,YAAY,aAEvB,CAAC;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;kBAWpC,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;;kBAMvC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;4BAGpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,gEAAgE;AAChE,eAAO,MAAM,qBAAqB;;;;kBAIhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;kBAgB/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5D,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAGpB;AAID,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AACrD,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAuC,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEpD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAO3E"}

package/dist/backup/format.js

@@ -0,0 +1,304 @@
+/**
+ * THE DESKTOP BACKUP FORMAT (11-electron.md §9), frozen at `formatVersion: 1`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THIS FILE IS A WIRE CONTRACT, NOT AN IMPLEMENTATION DETAIL. A zip written by
+ * any build must be readable by any other, so the layout, the manifest shape and
+ * the slug grammar live in ONE module, imported by the writer
+ * (`backup-service.ts`), the reader (`apps/desktop/src/main/backup-archive.ts`,
+ * via a mirrored schema pinned to these types) and the tests. Changing anything
+ * here is a `formatVersion` bump, not an edit.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ─── THE M10 CLI DOES NOT READ THIS FORMAT. §9's INTEROP CLAIM IS UNBUILT ────
+ *
+ * §9 says the backup zip "doubles as the migration path to self-host/Cloud:
+ * `npx adminium` import accepts the same format". IT DOES NOT, and this header
+ * used to assert that it did. The truth, so nobody plans around the fiction:
+ *
+ * There are TWO unrelated archive formats that both independently call
+ * themselves `formatVersion: 1`.
+ *
+ *  - THIS one (§9 backup): `manifest.json` at the archive ROOT, carrying
+ *    `{ formatVersion, appVersion, serverVersion, metaMigrationVersion,
+ *    createdAt, meta, databases }`, plus `meta.db` and `databases/*.sqlite` —
+ *    a byte-level snapshot of a whole desktop install.
+ *  - The M10 CONFIG BUNDLE (`export/bundle.ts`): `adminium-export/manifest.json`
+ *    with a required, DISJOINT shape (`{ appVersion, configVersion, metaVersion,
+ *    exportedAt, connectionId, secrets, counts }`), describing rows to upsert.
+ *
+ * `cli/commands/import-zip.ts` → `export/import-service.ts` reads only the
+ * second: `parseBundle` demands `adminium-export/manifest.json` and throws
+ * "it is not an Adminium configuration bundle" for anything else. A desktop user
+ * who follows §9's stated migration path is told their backup is not an Adminium
+ * file. Nothing outside the desktop reader and a parity test has ever imported
+ * {@link BACKUP_FORMAT_VERSION}.
+ *
+ * WHY IT IS NOT MERELY A MISSING `if`. The two formats are not dialects, they
+ * are different operations. The bundle import replays CONFIG ROWS into whatever
+ * meta store the target runs; this archive's `meta.db` is a SQLite FILE, and a
+ * self-host target's meta store is routinely Postgres or MySQL. Making the CLI
+ * "accept the same archive" therefore means reading a SQLite meta store and
+ * translating every table into another dialect — a cross-dialect meta migration,
+ * not a branch. That is a real feature with a real design, and no task in
+ * 11-T12 or M10 covers it.
+ *
+ * WHOEVER PICKS THIS UP: sniffing a root `manifest.json` in `parseBundle` is the
+ * entry point, and the version gate below is ready for it. Until then, the
+ * desktop restore (`main/backup.ts`) is the only reader of this format, and
+ * anything telling a user otherwise — docs, dialog copy, this comment — is
+ * making a promise the code does not keep.
+ *
+ * The archive (§9, verbatim):
+ *
+ * ```
+ * adminium-backup-20260712-1430.zip
+ *   manifest.json              { formatVersion, appVersion, serverVersion,
+ *                                metaMigrationVersion, createdAt, databases: [...] }
+ *   meta.db                    meta-store snapshot
+ *   config.json                desktop config, secrets REDACTED
+ *   databases/<slug>.sqlite    every LOCAL source DB
+ * ```
+ *
+ * ─── Two places this completes §9 rather than quoting it ─────────────────────
+ *
+ * 1. **`databases[]` is a discriminated union.** §9's example row is
+ *    `{ slug, file, bytes, sha256 }`, and its prose says remote PG/MySQL "are
+ *    listed in manifest.json as 'external', never dumped". A row that is not
+ *    dumped has no `file`, no `bytes` and no `sha256` to carry, so the two cases
+ *    cannot be one shape. {@link BackupDatabaseEntry} is therefore
+ *    `kind: 'local' | 'external'`; the local arm is §9's four fields exactly,
+ *    plus the provenance (`connectionId`, `sourcePath`) a restore needs to
+ *    explain itself. Reading the union back as §9's example means: take the
+ *    local arm.
+ * 2. **`meta` carries its own checksum.** §9 lists `meta.db` as an archive
+ *    member and puts checksums only on `databases[]`. That asymmetry cannot be
+ *    right: a restore validates checksums *before* it moves the live data aside
+ *    (§9's flow), and meta.db is the file whose corruption is unrecoverable —
+ *    it holds every connection, page and user. A backup whose source DBs verify
+ *    and whose meta.db is truncated would pass validation and then destroy the
+ *    install. Since `formatVersion: 1` is being frozen by this task rather than
+ *    inherited, the hole is closed now instead of being shipped and versioned
+ *    around.
+ *
+ * NOTHING ELSE IS ADDED. In particular there is no `secrets` block: `config.json`
+ * travels redacted, unconditionally, and a manifest field describing a policy
+ * with one possible value would only invite a second value later.
+ */
+import { createHash } from 'node:crypto';
+import { basename, extname } from 'node:path';
+import { z } from 'zod';
+/**
+ * FROZEN (§9: "format frozen here as `formatVersion: 1`").
+ *
+ * READ BY: the desktop restore's `validateArchive`, which refuses a higher
+ * number rather than parsing leniently — the same rule `config.ts`'s version
+ * gate and the M10 bundle's already obey.
+ *
+ * NOT read by the M10 CLI, whatever §9 says — see the module header. This
+ * doc-comment used to claim it was; the claim was never true and the number is
+ * the same either way, which is exactly why nobody noticed.
+ */
+export const BACKUP_FORMAT_VERSION = 1;
+/** Archive member paths. The reader allow-lists against these — see below. */
+export const BACKUP_MANIFEST_PATH = 'manifest.json';
+export const BACKUP_META_PATH = 'meta.db';
+export const BACKUP_CONFIG_PATH = 'config.json';
+export const BACKUP_DATABASES_DIR = 'databases';
+/** `databases/<slug>.sqlite` — the ONLY shape a source-DB member may have. */
+export function backupDatabasePath(slug) {
+    return `${BACKUP_DATABASES_DIR}/${slug}.sqlite`;
+}
+/**
+ * The slug grammar, and the reason it is this narrow.
+ *
+ * A slug is interpolated into an archive member path and then, on restore, into
+ * a filesystem path under `<dataDir>/databases/`. That makes it the one value in
+ * this format that can escape its directory: `../../config.json` is a perfectly
+ * good zip entry name, and an unpacker that trusted it would overwrite the
+ * desktop config — with the master secret in it — from inside an archive a user
+ * double-clicked. Lowercase alnum + `-` + `_` cannot express a separator, a
+ * drive letter, a dot segment, or a NUL, so the traversal is not defended
+ * against, it is unrepresentable.
+ *
+ * The reader re-validates every slug it reads (it must: the archive is untrusted
+ * input, and the writer's guarantees are the writer's), which is why this regex
+ * is exported rather than inlined at the point of use.
+ */
+export const BACKUP_SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const backupSlugSchema = z.string().regex(BACKUP_SLUG_PATTERN, {
+    message: 'must be 1-64 chars of lowercase a-z, 0-9, "-" or "_", starting alphanumeric',
+});
+/** SHA-256, lowercase hex — the digest every checksum field carries. */
+export const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/, {
+    message: 'must be a lowercase hex SHA-256 digest',
+});
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * A LOCAL source database: dumped, checksummed, restorable.
+ *
+ * `sourcePath` is provenance, not an instruction. It records where the file was
+ * when the backup ran; the restore does NOT write to it. See
+ * `apps/desktop/src/main/backup-archive.ts` for why an unpacker that honoured an
+ * absolute path out of an archive would be a remote-file-write primitive.
+ *
+ * It is READ, though — by `assertRestorablePaths`, which refuses any archive
+ * whose `sourcePath` is not already `<dataDir>/databases/<slug>.sqlite` on the
+ * target. That check is the whole reason this field is load-bearing rather than
+ * decorative: the unpack writes to the slug-derived path and `meta.db` is
+ * restored byte-for-byte, so a `sourcePath` that disagrees means the restored
+ * DSN would point somewhere the bytes are not — and the slug might belong to a
+ * different connection entirely. Provenance is exactly what is needed to notice
+ * that, and refusing is exactly what may be done with it.
+ */
+export const backupLocalDatabaseSchema = z.strictObject({
+    kind: z.literal('local'),
+    slug: backupSlugSchema,
+    /** §9's `file` — the archive member, i.e. `databases/<slug>.sqlite`. */
+    file: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+    sha256: sha256Schema,
+    /** `adminium_connections.id` this snapshot came from. */
+    connectionId: z.string().min(1),
+    /** Absolute path of the live file at backup time. Provenance only. */
+    sourcePath: z.string().min(1),
+});
+/**
+ * A REMOTE source database (§9: "remote PG/MySQL are listed in manifest.json as
+ * 'external', never dumped").
+ *
+ * Listed rather than omitted, because the difference between "this instance had
+ * no Postgres" and "this instance had a Postgres we did not dump" is the whole
+ * question a person asks when a restore comes up short. No DSN, not even
+ * encrypted: the DSN is in meta.db, and a manifest is the one file in the
+ * archive that is read before anything is trusted.
+ */
+export const backupExternalDatabaseSchema = z.strictObject({
+    kind: z.literal('external'),
+    slug: backupSlugSchema,
+    connectionId: z.string().min(1),
+    /** `postgres` | `mysql` | … — whatever `adminium_connections.engine` said. */
+    engine: z.string().min(1),
+});
+export const backupDatabaseEntrySchema = z.discriminatedUnion('kind', [
+    backupLocalDatabaseSchema,
+    backupExternalDatabaseSchema,
+]);
+/** `meta.db`'s own entry — see point 2 in the module header. */
+export const backupMetaEntrySchema = z.strictObject({
+    file: z.literal(BACKUP_META_PATH),
+    bytes: z.number().int().nonnegative(),
+    sha256: sha256Schema,
+});
+/**
+ * `manifest.json` (§9).
+ *
+ * `strictObject`, like `config.json`'s schema and for the same reason: an
+ * unknown key is a hand-edit or a typo, and a genuinely newer archive is caught
+ * one field earlier by {@link BACKUP_FORMAT_VERSION}, with a message the user
+ * can act on.
+ */
+export const backupManifestSchema = z.strictObject({
+    formatVersion: z.number().int().positive(),
+    /** The Electron shell's `app.getVersion()`, or `null` outside it. */
+    appVersion: z.string().min(1).nullable(),
+    /** `@adminium/server`'s `APP_VERSION`. */
+    serverVersion: z.string().min(1),
+    /**
+     * The meta-store's migration high-water mark — the ledger's last applied
+     * name (`0009_views_kind`), NOT the count and NOT the build's own latest.
+     * What replay needs to know is what the SOURCE actually ran.
+     */
+    metaMigrationVersion: z.string().min(1),
+    /** Epoch ms. */
+    createdAt: z.number().int().nonnegative(),
+    meta: backupMetaEntrySchema,
+    databases: z.array(backupDatabaseEntrySchema),
+});
+export function compareMetaMigrationVersion(backupVersion, appVersion) {
+    if (backupVersion === appVersion)
+        return 'same';
+    return backupVersion > appVersion ? 'newer' : 'older';
+}
+// ─── Naming ─────────────────────────────────────────────────────────────────
+/** §9's `adminium-backup-20260712-1430.zip`. */
+export const BACKUP_FILE_PREFIX = 'adminium-backup-';
+export const BACKUP_FILE_EXTENSION = '.zip';
+/**
+ * Matches {@link backupFileName}'s output. The rotation sweep uses it as an
+ * allow-list rather than deleting whatever is in `<dataDir>/backups/`: that
+ * directory is `showItemInFolder`-revealed (§9) and users put things in folders
+ * they can see. Rotation deletes files THIS code wrote and nothing else.
+ */
+export const BACKUP_FILE_PATTERN = /^adminium-backup-\d{8}-\d{6}\.zip$/;
+/**
+ * `adminium-backup-YYYYMMDD-HHMMSS.zip`, in UTC.
+ *
+ * §9's example shows minutes (`…-1430.zip`); seconds are here because rotation
+ * sorts by NAME (the only ordering that survives a file copy, an rsync, or a
+ * restored-from-Time-Machine backups folder — mtime does not), and two backups
+ * in one minute would then be indistinguishable and unorderable. UTC for the
+ * same reason: a local-time name goes backwards for an hour every autumn, and a
+ * rotation that sorts names would delete the wrong one.
+ */
+export function backupFileName(createdAt) {
+    const iso = new Date(createdAt).toISOString();
+    const date = iso.slice(0, 10).replace(/-/g, '');
+    const time = iso.slice(11, 19).replace(/:/g, '');
+    return `${BACKUP_FILE_PREFIX}${date}-${time}${BACKUP_FILE_EXTENSION}`;
+}
+/** `<dataDir>/pre-restore-<ts>` (§9). The folder a restore never deletes. */
+export const PRE_RESTORE_PREFIX = 'pre-restore-';
+export function preRestoreDirName(at) {
+    return `${PRE_RESTORE_PREFIX}${new Date(at).toISOString().replace(/[:.]/g, '-')}`;
+}
+// ─── Slugs ──────────────────────────────────────────────────────────────────
+/**
+ * A slug for a local database file, derived from its BASENAME.
+ *
+ * The basename, not the connection name, because on desktop they are the same
+ * thing by construction: §6 step 2 creates `<dataDir>/databases/<slug>.sqlite`
+ * from the name the user typed, so the file already carries the slug the user
+ * chose and round-tripping through it keeps `databases/orders.sqlite` in the
+ * archive named `orders`. Deriving from `connection.name` instead would rename
+ * everything the moment somebody edited a label, and "Open an existing SQLite
+ * file" (§6 step 2, opened in place) has a real filename and a name the user
+ * never picked.
+ *
+ * Falls back to the connection id for a basename that survives none of the
+ * grammar — a file called `数据.sqlite` is legitimate and must not fail a backup.
+ */
+export function deriveDatabaseSlug(filePath, connectionId) {
+    const base = basename(filePath, extname(filePath));
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+/, '')
+        .replace(/-+$/, '')
+        .slice(0, 64);
+    if (BACKUP_SLUG_PATTERN.test(slug))
+        return slug;
+    return `db-${connectionId.toLowerCase().replace(/[^a-z0-9]+/g, '')}`.slice(0, 64);
+}
+/**
+ * Make `slug` unique against `taken`, appending `-2`, `-3`, …
+ *
+ * Needed because slugs come from basenames and basenames are only unique within
+ * a directory: "Open an existing SQLite file" can register
+ * `~/work/app.sqlite` and `~/archive/app.sqlite` as two connections, and two
+ * archive members called `databases/app.sqlite` means the second silently
+ * replaces the first — a backup that looks complete and has lost a database.
+ */
+export function uniqueSlug(slug, taken) {
+    if (!taken.has(slug))
+        return slug;
+    for (let n = 2;; n += 1) {
+        const suffix = `-${String(n)}`;
+        const candidate = `${slug.slice(0, 64 - suffix.length)}${suffix}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/backup/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/backup/format.ts"],"names":[],"mappings":"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"}

package/dist/backup/notify.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The completion notification (11-electron.md §9: "Completion raises an
+ * `adminium_notifications` entry with 'Show in folder'").
+ *
+ * Originally a hand-rolled insert — the first producer in the product, which
+ * predated any notifications repo and said so. The repo now exists
+ * (`notificationsRepo`, M7 reports/notifications track) and this module rides
+ * the shared writer in `../notifications/notify.ts`, exactly the refactor the
+ * original comment invited.
+ *
+ * ─── "Show in folder" is not an `action_url` ─────────────────────────────────
+ *
+ * Every other affordance in that table is a link the SPA can follow. Revealing a
+ * file in Finder/Explorer is not: it is `shell.showItemInFolder`, which lives in
+ * the main process behind §4's bridge. So the row carries the PATH in `entity`
+ * and leaves `action_url` null, and the notification centre renders the button
+ * only when `window.adminiumDesktop` exists (§4's detection contract). On
+ * self-host the same row, if it ever appeared, would render as a plain "backup
+ * finished" line — which is the correct degradation rather than a dead button.
+ *
+ * ─── Language ────────────────────────────────────────────────────────────────
+ *
+ * The strings are en-US and are NOT routed through `@adminium/i18n`, because a
+ * notification row is written once and read later, possibly by a user who has
+ * since changed locale — translating at write time bakes in the wrong answer.
+ * `kind` is the stable, translatable key (`desktop.backup.completed`) and
+ * `entity` carries the substitutions, so the notification centre can localize at
+ * RENDER time; `title`/`body` are the fallback for a client that does not know
+ * this kind. Same shape the audit log uses for the same reason.
+ */
+import type { MetaDb } from '@adminium/meta';
+import { type NotificationPublisher } from '../notifications/notify.js';
+/** The stable key the notification centre localizes on. */
+export declare const BACKUP_NOTIFICATION_KIND = "desktop.backup.completed";
+export interface BackupNotificationInput {
+    meta: MetaDb;
+    /** Who gets the row. `adminium_notifications.user_id` is NOT NULL. */
+    userId: string;
+    /** Absolute path of the archive — the "Show in folder" target. */
+    path: string;
+    bytes: number;
+    /** How many local source DBs went in, for the body line. */
+    databases: number;
+    /** Optional realtime fan-out (`notifications:<userId>`) when the caller has the hub. */
+    hub?: NotificationPublisher | undefined;
+    at?: number | undefined;
+}
+/**
+ * Insert the row through the shared writer. Best-effort at the CALL SITE, not
+ * here: a failure to write a notification must never fail the backup that
+ * succeeded (see the route), but it must also not be silently swallowed inside
+ * the writer, where nobody would ever learn about it.
+ */
+export declare function notifyBackupCompleted(input: BackupNotificationInput): Promise<void>;
+//# sourceMappingURL=notify.d.ts.map

package/dist/backup/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/backup/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAU,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEhF,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,GAAG,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACxC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAcD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAczF"}

package/dist/backup/notify.js

@@ -0,0 +1,60 @@
+/**
+ * The completion notification (11-electron.md §9: "Completion raises an
+ * `adminium_notifications` entry with 'Show in folder'").
+ *
+ * Originally a hand-rolled insert — the first producer in the product, which
+ * predated any notifications repo and said so. The repo now exists
+ * (`notificationsRepo`, M7 reports/notifications track) and this module rides
+ * the shared writer in `../notifications/notify.ts`, exactly the refactor the
+ * original comment invited.
+ *
+ * ─── "Show in folder" is not an `action_url` ─────────────────────────────────
+ *
+ * Every other affordance in that table is a link the SPA can follow. Revealing a
+ * file in Finder/Explorer is not: it is `shell.showItemInFolder`, which lives in
+ * the main process behind §4's bridge. So the row carries the PATH in `entity`
+ * and leaves `action_url` null, and the notification centre renders the button
+ * only when `window.adminiumDesktop` exists (§4's detection contract). On
+ * self-host the same row, if it ever appeared, would render as a plain "backup
+ * finished" line — which is the correct degradation rather than a dead button.
+ *
+ * ─── Language ────────────────────────────────────────────────────────────────
+ *
+ * The strings are en-US and are NOT routed through `@adminium/i18n`, because a
+ * notification row is written once and read later, possibly by a user who has
+ * since changed locale — translating at write time bakes in the wrong answer.
+ * `kind` is the stable, translatable key (`desktop.backup.completed`) and
+ * `entity` carries the substitutions, so the notification centre can localize at
+ * RENDER time; `title`/`body` are the fallback for a client that does not know
+ * this kind. Same shape the audit log uses for the same reason.
+ */
+import { notify } from '../notifications/notify.js';
+/** The stable key the notification centre localizes on. */
+export const BACKUP_NOTIFICATION_KIND = 'desktop.backup.completed';
+/** Bytes → `12.4 MB`, for the body line only. */
+function humanBytes(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? String(value) : value.toFixed(1)} ${units[unit] ?? 'B'}`;
+}
+/**
+ * Insert the row through the shared writer. Best-effort at the CALL SITE, not
+ * here: a failure to write a notification must never fail the backup that
+ * succeeded (see the route), but it must also not be silently swallowed inside
+ * the writer, where nobody would ever learn about it.
+ */
+export async function notifyBackupCompleted(input) {
+    await notify(input.meta, {
+        userId: input.userId,
+        kind: BACKUP_NOTIFICATION_KIND,
+        title: 'Backup complete',
+        body: `${String(input.databases)} database${input.databases === 1 ? '' : 's'} · ${humanBytes(input.bytes)}`,
+        entity: { kind: 'backup', path: input.path, bytes: input.bytes },
+    }, { hub: input.hub, at: input.at });
+}
+//# sourceMappingURL=notify.js.map

package/dist/backup/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/backup/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAAE,MAAM,EAA8B,MAAM,4BAA4B,CAAC;AAEhF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AAgBnE,iDAAiD;AACjD,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;IAC/C,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,KAAK,IAAI,IAAI,IAAI,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,KAAK,IAAI,IAAI,CAAC;QACd,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAA8B;IACxE,MAAM,MAAM,CACV,KAAK,CAAC,IAAI,EACV;QACE,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,KAAK,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,UAAU,CAC1F,KAAK,CAAC,KAAK,CACZ,EAAE;QACH,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;KACjE,EACD,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CACjC,CAAC;AACJ,CAAC"}

package/dist/backup/snapshot.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SQLite snapshotting for the §9 backup (11-electron.md §9), and the discovery
+ * of what there is to snapshot.
+ *
+ * ─── Why `backup()` and not `copyFile()` ─────────────────────────────────────
+ *
+ * §9 is specific — "the server snapshots each SQLite file with the
+ * `better-sqlite3` online `backup()` API (WAL-safe, no locking of live writers)"
+ * — and the alternative it rules out is not merely inferior, it is silently
+ * wrong. Every local database runs `journal_mode = WAL` (§9's pragma block), so
+ * a committed row lives in `<db>-wal` until a checkpoint folds it back. Copying
+ * the `.sqlite` file therefore copies a database that is missing its most recent
+ * commits; copying all three files copies them at three different instants, so
+ * the WAL can describe pages the main file does not have yet. Both produce an
+ * archive that unzips, opens, passes `PRAGMA integrity_check`, and has lost
+ * data — the worst failure a backup can have, because it is invisible until the
+ * restore.
+ *
+ * `backup()` runs SQLite's own online backup: it reads through the same page
+ * cache and WAL a reader would, restarts itself if a writer changes the source
+ * mid-copy, and lands a self-contained, checkpointed file. The destination is
+ * complete at whatever instant the copy finished, and live writers are never
+ * blocked.
+ *
+ * ─── Why a second connection ─────────────────────────────────────────────────
+ *
+ * The obvious move is to reach through `ConnectionManager` for the handle the
+ * server already holds. It is the wrong move: those handles are role-branded
+ * (01 §3's privilege model), pooled, and owned by request-scoped code, and a
+ * backup that borrowed one would serialize itself behind whatever CRUD is in
+ * flight — the exact locking §9 says not to do. A second connection to a WAL
+ * database is the normal, supported thing (WAL exists so readers and a writer
+ * coexist), so this module opens its own, READONLY, and closes it. `readonly`
+ * is belt and braces: a backup is the one operation in the product with no
+ * reason whatsoever to be able to write to a source database, and
+ * `fileMustExist` keeps a stale DSN from CREATING an empty database and
+ * cheerfully backing it up.
+ */
+import { type DsnCrypto, type MetaDb } from '@adminium/meta';
+/** A local SQLite source DB found in `adminium_connections`, ready to snapshot. */
+export interface LocalDatabaseSource {
+    connectionId: string;
+    slug: string;
+    /** Absolute path of the live file. */
+    path: string;
+}
+/** A source DB the backup lists but never dumps (§9's "external"). */
+export interface ExternalDatabaseSource {
+    connectionId: string;
+    slug: string;
+    engine: string;
+}
+export interface DiscoveredSources {
+    local: LocalDatabaseSource[];
+    external: ExternalDatabaseSource[];
+}
+/**
+ * Split every configured connection into "we dump this" and "we list this".
+ *
+ * §9's rule is about the ENGINE, not about reachability: a Postgres on
+ * `localhost` is still external (we do not have a byte-level snapshot mechanism
+ * for it, and `pg_dump` is not a thing this process may assume exists), and a
+ * SQLite file on a network share is still local. Anything that is neither — a
+ * `sqlite:` connection whose DSN is `:memory:` or relative — is listed as
+ * external too, which is the honest answer: the manifest says the connection
+ * existed and says its bytes are not in this archive.
+ */
+export declare function discoverSources(meta: MetaDb, crypto: DsnCrypto): Promise<DiscoveredSources>;
+/**
+ * Snapshot `sourcePath` to `destPath` with SQLite's online backup.
+ *
+ * Awaited rather than fire-and-forget: better-sqlite3's `backup()` returns a
+ * promise that resolves when `remainingPages` hits 0, and a caller that hashed
+ * the destination without waiting would hash a partial file and write a checksum
+ * for a database that does not exist yet.
+ */
+export declare function snapshotSqliteFile(sourcePath: string, destPath: string): Promise<void>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/backup/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/backup/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAMH,OAAO,EAAoC,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAK/F,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,iBAAiB,CAAC,CAkC5B;AAwBD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5F"}