firevault 0.1.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+Initial prerelease candidate for Firevault, an undo button for Firestore.
+
+- Firestore backup to deterministic JSON files.
+- Git-scoped local snapshot workflow.
+- File-level change inspection.
+- Document and collection history inspection.
+- Restore preview from Git.
+- Local backup-file restore with explicit confirmation.
+- Single-document Firestore restore with explicit confirmation.
+- Firestore emulator integration tests for backup and restore safety paths.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 henskjold73
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,363 @@
+# Firevault
+
+Undo button for Firestore.
+
+Firevault gives Firestore projects Git-style history, change inspection, and document-level rollback so teams can recover from accidental writes, bad migrations, and destructive scripts.
+
+Supporting line: Git-style history, rollback, and recovery for Firestore projects.
+
+Firevault is focused operational recovery tooling for existing Firestore projects. It is not a hosted database platform, Firebase replacement, generic backup vendor, SaaS product, or dashboard.
+
+## Current Status
+
+Firevault is in Foundation / Phase 0.
+
+This is an experimental prerelease CLI. Use it against test or non-critical Firestore projects until recovery behavior has been reviewed for your project.
+
+Current scope:
+
+- snapshot Firestore into Git-friendly JSON,
+- inspect changes,
+- view document history,
+- preview rollback,
+- restore one document back to Firestore.
+
+Current export shape:
+
+```txt
+firestore-backups/
+  users/
+    abc123.json
+    def456.json
+```
+
+The immediate priority is trustworthy document-level recovery: clear previews, explicit confirmation, and no broad destructive restore flows.
+
+## Quick Start
+
+```bash
+npm install -g firevault
+```
+
+Create a Firebase service account key for your Firestore project, save it as `serviceAccountKey.json`, and keep it out of Git.
+
+Create `firevault.config.json`:
+
+```json
+{
+  "projectId": "your-project-id",
+  "serviceAccountPath": "./serviceAccountKey.json",
+  "outputDir": "firestore-backups",
+  "collections": ["users"]
+}
+```
+
+Take a snapshot:
+
+```bash
+firevault snapshot
+```
+
+Example output:
+
+```txt
+Exported 2 docs from users
+Backup complete.
+Created commit: backup: 2026-05-16T17:00:00.000Z
+```
+
+Inspect what changed:
+
+```bash
+firevault changes
+```
+
+Example output:
+
+```txt
+Added:
+
+* firestore-backups/users/abc123.json
+
+Modified:
+
+Deleted:
+```
+
+Preview a document rollback:
+
+```bash
+firevault restore-preview users/abc123 --from HEAD~1
+```
+
+Example output:
+
+```txt
+Target: firestore-backups/users/abc123.json
+Source commit: HEAD~1
+Current file exists: yes
+
+Diff:
+
+  {
+-   "name": "Ada Lovelace"
++   "name": "Ada"
+  }
+```
+
+Restore one document to Firestore after reviewing the preview:
+
+```bash
+firevault restore-firestore users/abc123 --from HEAD~1 --confirm
+```
+
+`restore-firestore` overwrites one Firestore document with the JSON from Git. It does not support collection restore, merge, or patch restore yet.
+
+## Recovery Workflow
+
+Scenario: a script accidentally overwrites `users/abc123`.
+
+1. Inspect recent snapshot changes:
+
+```bash
+firevault changes --last 24h
+```
+
+2. Find the document history:
+
+```bash
+firevault history users/abc123
+```
+
+3. Preview the rollback:
+
+```bash
+firevault restore-preview users/abc123 --from HEAD~3
+```
+
+4. Restore only that document:
+
+```bash
+firevault restore-firestore users/abc123 --from HEAD~3 --confirm
+```
+
+5. Take a new snapshot after recovery:
+
+```bash
+firevault snapshot
+```
+
+## Configuration
+
+Firevault operates against an existing Firebase project using a service account.
+
+Expected config shape:
+
+```json
+{
+  "projectId": "your-project-id",
+  "serviceAccountPath": "./serviceAccountKey.json",
+  "outputDir": "firestore-backups",
+  "collections": ["users"]
+}
+```
+
+Notes:
+
+- `serviceAccountPath` points to a local Firebase service account JSON file.
+- `outputDir` is where Firestore documents are written.
+- `collections` controls which top-level Firestore collections are exported.
+- Service account files must not be committed.
+
+Recommended `.gitignore` entries for local development:
+
+```gitignore
+serviceAccountKey.json
+firestore-backups/
+```
+
+## Commands
+
+```bash
+firevault init
+firevault backup
+firevault commit
+firevault snapshot
+firevault changes
+firevault changes --last 24h
+firevault history users/abc123
+firevault restore-preview users/abc123 --from HEAD~3
+firevault restore-local users/abc123 --from HEAD~3 --confirm
+firevault restore-firestore users/abc123 --from HEAD~3 --confirm
+```
+
+## Local Development
+
+Install dependencies and run commands through the TypeScript entrypoint:
+
+```bash
+npm install
+npm run dev -- --help
+npm run dev -- backup
+npm run dev -- changes
+```
+
+Build and link the compiled CLI:
+
+```bash
+npm run build
+npm link
+firevault --help
+```
+
+The installed `firevault` binary runs from `dist/index.js`.
+
+## Backup Model
+
+Firevault writes one document per file:
+
+```txt
+<outputDir>/<collection>/<documentId>.json
+```
+
+JSON output is stable:
+
+- object keys are sorted recursively,
+- formatting is deterministic,
+- files are intended to produce readable Git diffs.
+
+## Git Commit Flow
+
+`firevault backup` exports configured Firestore collections to deterministic local JSON files. It does not stage or commit anything.
+
+`firevault commit` expects to run inside a Git repository.
+
+Behavior:
+
+- checks for changes under the configured `outputDir`,
+- exits successfully if no backup changes exist,
+- stages only the configured `outputDir`,
+- creates a local commit with message `backup: <ISO timestamp>`,
+- never pushes.
+
+Keep `serviceAccountKey.json` ignored so credentials cannot be committed by this workflow or by manual Git usage.
+
+`firevault snapshot` is the safe local recovery snapshot workflow:
+
+- runs backup,
+- stops immediately if backup fails,
+- commits backup changes when files changed,
+- exits successfully when backup succeeds but no Git changes exist,
+- never pushes.
+
+`firevault changes` shows a file-level Git summary for the configured `outputDir` only:
+
+```txt
+Added:
+
+* firestore-backups/users/abc123.json
+
+Modified:
+
+* firestore-backups/users/def456.json
+
+Deleted:
+
+* firestore-backups/users/old-user.json
+```
+
+Without options it inspects working tree changes. With `--last 24h`, it uses Git history and lists files changed under `outputDir` in commits since that time window. It does not contact Firebase.
+
+`firevault history <path>` shows commit history for one backed-up document or collection. It accepts logical paths like `users/abc123`, full backup file paths like `firestore-backups/users/abc123.json`, and collection paths like `users`.
+
+Output includes commit short SHA, commit date, and commit message. For collection paths, it also includes the number of files changed by each commit under that collection. It uses Git history only and does not contact Firebase.
+
+`firevault restore-preview <path> --from <commit>` shows what would be restored for one backed-up document without writing anything. It accepts logical document paths and full backup file paths, reads the source JSON from Git, compares it to the current local backup file if present, and prints a readable line diff.
+
+Restore preview is intentionally dry-run only. It does not write to Firestore, does not overwrite local files, does not push, and does not contact Firebase.
+
+`firevault restore-local <path> --from <commit> --confirm` restores one backed-up document from Git into the local backup directory. It prints the same preview information before writing, creates parent directories if needed, and requires `--confirm`.
+
+Restore local does not write to Firestore, does not stage, does not commit, does not push, and does not contact Firebase.
+
+`firevault restore-firestore <path> --from <commit> --confirm` restores one backed-up document from Git directly into Firestore. It prints target backup path, Firestore collection, document ID, source commit, and a local JSON diff before writing.
+
+Firestore restore overwrites the target document with the parsed JSON from Git. It does not support collection restore, merge, or patch restore yet. It does not modify local backup files, stage, commit, push, or contact GitHub.
+
+Manual Firestore restore verification:
+
+1. Point `serviceAccountPath` at a valid service account for a test Firebase project.
+2. Run `npm run restore-preview -- users/abc123 --from <commit>` and inspect the diff.
+3. Run `npm run restore-firestore -- users/abc123 --from <commit> --confirm`.
+4. Verify the document in Firestore was overwritten with the JSON from Git.
+5. Run `git status` to confirm no local files were changed by `restore-firestore`.
+
+## Testing
+
+Run the TypeScript build:
+
+```bash
+npm run build
+```
+
+Run Firestore emulator integration tests:
+
+```bash
+npm run test:emulator
+```
+
+The emulator tests require dependencies installed through `npm install`, including the `firebase-tools` dev dependency. The test runner starts the local Firestore emulator with demo project `demo-firevault-test`; it does not require `serviceAccountKey.json` and does not contact a real Firebase project.
+
+Covered emulator flows:
+
+- `backup` exports a known Firestore document,
+- `backup` writes deterministic JSON,
+- `restore-firestore` overwrites one emulator document from a Git commit,
+- `restore-firestore` rejects collection paths,
+- `restore-firestore` requires `--confirm`.
+
+## Publishing
+
+Before publishing:
+
+- run `npm run build`,
+- run `npm run test:emulator`,
+- run `npm pack --dry-run` and review the file list,
+- verify `dist/index.js` exists and starts with `#!/usr/bin/env node`,
+- do not publish `serviceAccountKey.json`,
+- do not publish local `firestore-backups/` output,
+- verify logs such as `firestore-debug.log` are not included.
+
+The package `bin` points to `./dist/index.js`, so a published or linked package must include compiled output. `prepublishOnly` currently runs clean, build, and emulator tests.
+
+## Product Principles
+
+Firevault should stay:
+
+- small,
+- operational,
+- trustworthy,
+- CLI-first,
+- Git-backed.
+
+Avoid adding SaaS features, hosted infrastructure, auth systems, collaboration features, dashboards, billing, or broad multi-cloud abstractions before the core Firestore to stable JSON to Git workflow is robust.
+
+## Safety
+
+Firestore restore is document-only and overwrite-only for now. Future restore flows should:
+
+- default to dry-run,
+- require explicit confirmation for writes,
+- start with document-level recovery,
+- avoid early whole-database destructive workflows.
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Roadmap](docs/roadmap.md)
+- [GitHub labels](docs/github-labels.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [AI review ledger](AI_REVIEW.md)
+
+AI agents must never create git commits automatically. Human review and commits are required.

package/dist/commands/backup.js

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { exportCollection } from "../firestore/exportFirestore.js";
+export async function runBackup() {
+    const config = loadConfig();
+    for (const collection of config.collections) {
+        await exportCollection(config.outputDir, collection);
+    }
+    console.log("Backup complete.");
+}
+export const backupCommand = new Command("backup")
+    .description("Back up configured Firestore collections")
+    .action(async () => {
+    try {
+        await runBackup();
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/changes.js

@@ -0,0 +1,55 @@
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { GitError, assertInsideGitRepository, getHistoricalChanges, getWorkingTreeChanges, } from "../git/git.js";
+function printSection(title, paths) {
+    console.log(`${title}:`);
+    console.log("");
+    for (const path of paths) {
+        console.log(`* ${path}`);
+    }
+    console.log("");
+}
+function printChanges(changes) {
+    printSection("Added", changes.added);
+    printSection("Modified", changes.modified);
+    printSection("Deleted", changes.deleted);
+}
+function normalizeLastWindow(last) {
+    const match = last.match(/^(\d+)([hdw])$/);
+    if (!match) {
+        return last;
+    }
+    const amount = match[1];
+    const unit = match[2];
+    if (unit === "h") {
+        return `${amount} hours ago`;
+    }
+    if (unit === "d") {
+        return `${amount} days ago`;
+    }
+    return `${amount} weeks ago`;
+}
+export function runChanges(last) {
+    const config = loadConfig();
+    assertInsideGitRepository();
+    const changes = last
+        ? getHistoricalChanges(config.outputDir, normalizeLastWindow(last))
+        : getWorkingTreeChanges(config.outputDir);
+    printChanges(changes);
+}
+export const changesCommand = new Command("changes")
+    .description("Show file-level Git changes under the configured backup directory")
+    .option("--last <window>", "Show committed changes since a time window, such as 24h")
+    .action((options) => {
+    try {
+        runChanges(options.last);
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/commit.js

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { GitError, assertInsideGitRepository, commitPath, hasChangesUnder, stagePath, } from "../git/git.js";
+export function runCommit() {
+    const config = loadConfig();
+    assertInsideGitRepository();
+    if (!hasChangesUnder(config.outputDir)) {
+        console.log(`No changes found under ${config.outputDir}.`);
+        return;
+    }
+    stagePath(config.outputDir);
+    const message = `backup: ${new Date().toISOString()}`;
+    commitPath(message, config.outputDir);
+    console.log(`Created commit: ${message}`);
+}
+export const commitCommand = new Command("commit")
+    .description("Commit changes under the configured Firestore backup directory")
+    .action(() => {
+    try {
+        runCommit();
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/history.js

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { GitError, assertInsideGitRepository, getHistory, } from "../git/git.js";
+import { normalizeHistoryPath } from "../paths/backupPaths.js";
+function printHistory(entries) {
+    for (const entry of entries) {
+        const parts = [entry.shortSha, entry.date, entry.message];
+        if (entry.changedFileCount !== undefined) {
+            const label = entry.changedFileCount === 1 ? "file" : "files";
+            parts.push(`${entry.changedFileCount} ${label}`);
+        }
+        console.log(parts.join("  "));
+    }
+}
+export function runHistory(inputPath) {
+    const config = loadConfig();
+    const normalizedPath = normalizeHistoryPath(inputPath, config.outputDir);
+    assertInsideGitRepository();
+    const entries = getHistory(normalizedPath.path, normalizedPath.isCollection);
+    if (entries.length === 0) {
+        console.log(`No history found for ${normalizedPath.path}.`);
+        return;
+    }
+    printHistory(entries);
+}
+export const historyCommand = new Command("history")
+    .description("Show Git history for a backed-up document or collection")
+    .argument("<path>", "Logical path or backup file path")
+    .action((inputPath) => {
+    try {
+        runHistory(inputPath);
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/init.js

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { writeFileSync, existsSync } from "node:fs";
+const defaultConfig = {
+    projectId: "your-firebase-project-id",
+    serviceAccountPath: "./serviceAccountKey.json",
+    outputDir: "firestore-backups",
+    collections: [],
+};
+export const initCommand = new Command("init")
+    .description("Create a firevault.config.json file")
+    .action(() => {
+    const configPath = "firevault.config.json";
+    if (existsSync(configPath)) {
+        console.log("firevault.config.json already exists.");
+        return;
+    }
+    writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+    console.log("Created firevault.config.json");
+});

package/dist/commands/restoreFirestore.js

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { FirestoreError, writeDocument } from "../firestore/writeDocument.js";
+import { GitError, assertInsideGitRepository, showFileAtCommit, } from "../git/git.js";
+import { normalizeDocumentPath, normalizeSlashes, } from "../paths/backupPaths.js";
+import { buildLineDiff } from "./restorePreview.js";
+function getFirestoreTarget(inputPath, outputDir) {
+    const normalizedInput = normalizeSlashes(inputPath);
+    const normalizedOutputDir = normalizeSlashes(outputDir);
+    if (normalizedInput === normalizedOutputDir ||
+        normalizedInput === normalizedOutputDir.split("/")[0] ||
+        (!normalizedInput.includes("/") && !normalizedInput.endsWith(".json"))) {
+        throw new ConfigError("Collection restore is not supported yet. Provide a document path such as users/abc123.");
+    }
+    const backupPath = normalizeDocumentPath(inputPath, outputDir);
+    const relativePath = path.posix.relative(normalizedOutputDir, backupPath);
+    const parts = relativePath.split("/");
+    if (parts.length !== 2 || !parts[1].endsWith(".json")) {
+        throw new ConfigError("Only top-level document restore is supported. Provide a path such as users/abc123.");
+    }
+    return {
+        backupPath,
+        collection: parts[0],
+        documentId: parts[1].slice(0, -".json".length),
+    };
+}
+function parseRestoreJson(content, backupPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new ConfigError(`Malformed JSON at source commit for ${backupPath}.`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ConfigError(`Malformed JSON at source commit for ${backupPath}: expected a JSON object.`);
+    }
+    return parsed;
+}
+function printFirestorePreview(target, sourceCommit, currentExists, diff) {
+    console.log(`Target backup path: ${target.backupPath}`);
+    console.log(`Firestore collection: ${target.collection}`);
+    console.log(`Firestore document ID: ${target.documentId}`);
+    console.log(`Source commit: ${sourceCommit}`);
+    console.log(`Current local backup file exists: ${currentExists ? "yes" : "no"}`);
+    console.log("");
+    console.log("Diff:");
+    console.log("");
+    if (diff.length === 0) {
+        console.log("No changes.");
+        return;
+    }
+    for (const line of diff) {
+        console.log(line);
+    }
+}
+export async function runRestoreFirestore(inputPath, options) {
+    if (!options.from) {
+        throw new ConfigError("Missing required option: --from <commit>");
+    }
+    if (!options.confirm) {
+        throw new ConfigError("Missing required option: --confirm. Run restore-preview first, then rerun with --confirm to overwrite the Firestore document.");
+    }
+    const config = loadConfig();
+    const target = getFirestoreTarget(inputPath, config.outputDir);
+    assertInsideGitRepository();
+    const restoredContent = showFileAtCommit(options.from, target.backupPath);
+    const restoredData = parseRestoreJson(restoredContent, target.backupPath);
+    const currentExists = existsSync(target.backupPath);
+    const currentContent = currentExists
+        ? readFileSync(target.backupPath, "utf-8")
+        : undefined;
+    const diff = buildLineDiff(currentContent, restoredContent);
+    printFirestorePreview(target, options.from, currentExists, diff);
+    await writeDocument(target.collection, target.documentId, restoredData);
+    console.log("");
+    console.log(`Restored Firestore document: ${target.collection}/${target.documentId}`);
+}
+export const restoreFirestoreCommand = new Command("restore-firestore")
+    .description("Restore a backed-up document from Git directly into Firestore")
+    .argument("<path>", "Logical document path or backup file path")
+    .option("--from <commit>", "Git commit to restore from")
+    .option("--confirm", "Confirm overwriting the Firestore document")
+    .action(async (inputPath, options) => {
+    try {
+        await runRestoreFirestore(inputPath, options);
+    }
+    catch (error) {
+        if (error instanceof ConfigError ||
+            error instanceof GitError ||
+            error instanceof FirestoreError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});