firevault 0.1.1-beta.0

package/dist/commands/restoreLocal.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { GitError, assertInsideGitRepository, showFileAtCommit, } from "../git/git.js";
+import { normalizeDocumentPath } from "../paths/backupPaths.js";
+import { buildLineDiff, printRestorePreview } from "./restorePreview.js";
+export function runRestoreLocal(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 write the local backup file.");
+    }
+    const config = loadConfig();
+    const targetPath = normalizeDocumentPath(inputPath, config.outputDir);
+    assertInsideGitRepository();
+    const restoredContent = showFileAtCommit(options.from, targetPath);
+    const currentExists = existsSync(targetPath);
+    const currentContent = currentExists ? readFileSync(targetPath, "utf-8") : undefined;
+    const diff = buildLineDiff(currentContent, restoredContent);
+    printRestorePreview(targetPath, options.from, currentExists, diff);
+    mkdirSync(path.dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, restoredContent);
+    console.log("");
+    console.log(`Restored local backup file: ${targetPath}`);
+}
+export const restoreLocalCommand = new Command("restore-local")
+    .description("Restore a backed-up document from Git into the local backup directory")
+    .argument("<path>", "Logical document path or backup file path")
+    .option("--from <commit>", "Git commit to restore from")
+    .option("--confirm", "Confirm writing the local backup file")
+    .action((inputPath, options) => {
+    try {
+        runRestoreLocal(inputPath, options);
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/restorePreview.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "node:fs";
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { GitError, assertInsideGitRepository, showFileAtCommit, } from "../git/git.js";
+import { normalizeDocumentPath } from "../paths/backupPaths.js";
+function normalizeJson(content) {
+    try {
+        return JSON.stringify(JSON.parse(content), null, 2).split("\n");
+    }
+    catch {
+        return content.split("\n");
+    }
+}
+export function buildLineDiff(currentContent, restoredContent) {
+    const currentLines = currentContent ? normalizeJson(currentContent) : [];
+    const restoredLines = normalizeJson(restoredContent);
+    const lengths = Array.from({ length: currentLines.length + 1 }, () => Array(restoredLines.length + 1).fill(0));
+    const lines = [];
+    for (let currentIndex = currentLines.length - 1; currentIndex >= 0; currentIndex -= 1) {
+        for (let restoredIndex = restoredLines.length - 1; restoredIndex >= 0; restoredIndex -= 1) {
+            if (currentLines[currentIndex] === restoredLines[restoredIndex]) {
+                lengths[currentIndex][restoredIndex] =
+                    lengths[currentIndex + 1][restoredIndex + 1] + 1;
+            }
+            else {
+                lengths[currentIndex][restoredIndex] = Math.max(lengths[currentIndex + 1][restoredIndex], lengths[currentIndex][restoredIndex + 1]);
+            }
+        }
+    }
+    let currentIndex = 0;
+    let restoredIndex = 0;
+    while (currentIndex < currentLines.length && restoredIndex < restoredLines.length) {
+        if (currentLines[currentIndex] === restoredLines[restoredIndex]) {
+            lines.push(`  ${currentLines[currentIndex]}`);
+            currentIndex += 1;
+            restoredIndex += 1;
+            continue;
+        }
+        if (lengths[currentIndex + 1][restoredIndex] >= lengths[currentIndex][restoredIndex + 1]) {
+            lines.push(`- ${currentLines[currentIndex]}`);
+            currentIndex += 1;
+        }
+        else {
+            lines.push(`+ ${restoredLines[restoredIndex]}`);
+            restoredIndex += 1;
+        }
+    }
+    while (currentIndex < currentLines.length) {
+        lines.push(`- ${currentLines[currentIndex]}`);
+        currentIndex += 1;
+    }
+    while (restoredIndex < restoredLines.length) {
+        lines.push(`+ ${restoredLines[restoredIndex]}`);
+        restoredIndex += 1;
+    }
+    return lines;
+}
+export function printRestorePreview(targetPath, sourceCommit, currentExists, diff) {
+    console.log(`Target: ${targetPath}`);
+    console.log(`Source commit: ${sourceCommit}`);
+    console.log(`Current 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 function runRestorePreview(inputPath, options) {
+    if (!options.from) {
+        throw new ConfigError("Missing required option: --from <commit>");
+    }
+    const config = loadConfig();
+    const targetPath = normalizeDocumentPath(inputPath, config.outputDir);
+    assertInsideGitRepository();
+    const restoredContent = showFileAtCommit(options.from, targetPath);
+    const currentExists = existsSync(targetPath);
+    const currentContent = currentExists ? readFileSync(targetPath, "utf-8") : undefined;
+    const diff = buildLineDiff(currentContent, restoredContent);
+    printRestorePreview(targetPath, options.from, currentExists, diff);
+}
+export const restorePreviewCommand = new Command("restore-preview")
+    .description("Preview restoring a backed-up document from Git")
+    .argument("<path>", "Logical document path or backup file path")
+    .requiredOption("--from <commit>", "Git commit to restore from")
+    .action((inputPath, options) => {
+    try {
+        runRestorePreview(inputPath, options);
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/snapshot.js

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { ConfigError } from "../config/loadConfig.js";
+import { GitError } from "../git/git.js";
+import { runBackup } from "./backup.js";
+import { runCommit } from "./commit.js";
+export async function runSnapshot(backup = runBackup, commit = runCommit) {
+    await backup();
+    commit();
+}
+export const snapshotCommand = new Command("snapshot")
+    .description("Back up Firestore and commit backup changes locally")
+    .action(async () => {
+    try {
+        await runSnapshot();
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof GitError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/config/loadConfig.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(config, field) {
+    const value = config[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ConfigError(`Invalid firevault.config.json: "${field}" is required and must be a string.`);
+    }
+    return value;
+}
+function requireStringArray(config, field) {
+    const value = config[field];
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.some((item) => typeof item !== "string" || item.trim() === "")) {
+        throw new ConfigError(`Invalid firevault.config.json: "${field}" is required and must include at least one collection name.`);
+    }
+    return value;
+}
+export function loadConfig() {
+    const configPath = "firevault.config.json";
+    if (!existsSync(configPath)) {
+        throw new ConfigError("Missing firevault.config.json. Run `firevault init` first.");
+    }
+    let parsed;
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new ConfigError("Invalid firevault.config.json: file is not valid JSON.");
+        }
+        throw error;
+    }
+    if (!isRecord(parsed)) {
+        throw new ConfigError("Invalid firevault.config.json: expected a JSON object.");
+    }
+    const config = {
+        projectId: requireString(parsed, "projectId"),
+        serviceAccountPath: requireString(parsed, "serviceAccountPath"),
+        outputDir: requireString(parsed, "outputDir"),
+        collections: requireStringArray(parsed, "collections"),
+    };
+    return config;
+}

package/dist/firestore/exportFirestore.js

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { getFirestore } from "./firebase.js";
+import { stableStringify } from "./stableStringify.js";
+export async function exportCollection(outputDir, collectionName) {
+    const db = getFirestore();
+    const snapshot = await db.collection(collectionName).get();
+    const collectionDir = path.join(outputDir, collectionName);
+    mkdirSync(collectionDir, { recursive: true });
+    for (const doc of snapshot.docs) {
+        const filePath = path.join(collectionDir, `${doc.id}.json`);
+        writeFileSync(filePath, stableStringify(doc.data()));
+    }
+    console.log(`Exported ${snapshot.docs.length} docs from ${collectionName}`);
+}

package/dist/firestore/firebase.js

@@ -0,0 +1,39 @@
+import admin from "firebase-admin";
+import { existsSync, readFileSync } from "node:fs";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+let initialized = false;
+export function getFirestore() {
+    if (!initialized) {
+        const config = loadConfig();
+        let serviceAccount;
+        const emulatorHost = process.env.FIRESTORE_EMULATOR_HOST;
+        try {
+            if (emulatorHost) {
+                admin.initializeApp({
+                    projectId: config.projectId,
+                });
+                initialized = true;
+                return admin.firestore();
+            }
+            if (!existsSync(config.serviceAccountPath)) {
+                throw new ConfigError(`Service account file not found: ${config.serviceAccountPath}`);
+            }
+            serviceAccount = JSON.parse(readFileSync(config.serviceAccountPath, "utf-8"));
+            admin.initializeApp({
+                credential: admin.credential.cert(serviceAccount),
+                projectId: config.projectId,
+            });
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new ConfigError(`Invalid service account file: ${config.serviceAccountPath}`);
+            }
+            if (error instanceof Error && error.message.includes("Failed to parse")) {
+                throw new ConfigError(`Invalid service account file: ${config.serviceAccountPath}`);
+            }
+            throw error;
+        }
+        initialized = true;
+    }
+    return admin.firestore();
+}

package/dist/firestore/stableStringify.js

@@ -0,0 +1,17 @@
+function sortObject(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortObject);
+    }
+    if (value && typeof value === "object") {
+        return Object.keys(value)
+            .sort()
+            .reduce((result, key) => {
+            result[key] = sortObject(value[key]);
+            return result;
+        }, {});
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortObject(value), null, 2);
+}

package/dist/firestore/writeDocument.js

@@ -0,0 +1,22 @@
+import { getFirestore } from "./firebase.js";
+export class FirestoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FirestoreError";
+    }
+}
+export async function writeDocument(collection, documentId, data) {
+    try {
+        const db = getFirestore();
+        await db.collection(collection).doc(documentId).set(data);
+    }
+    catch (error) {
+        if (error instanceof FirestoreError) {
+            throw error;
+        }
+        if (error instanceof Error) {
+            throw new FirestoreError(`Failed to write Firestore document ${collection}/${documentId}: ${error.message}`);
+        }
+        throw new FirestoreError(`Failed to write Firestore document ${collection}/${documentId}.`);
+    }
+}

package/dist/git/git.js

@@ -0,0 +1,155 @@
+import { execFileSync } from "node:child_process";
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitError";
+    }
+}
+function runGit(args) {
+    try {
+        return execFileSync("git", args, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "stderr" in error &&
+            typeof error.stderr === "string" &&
+            error.stderr.trim() !== "") {
+            throw new GitError(error.stderr.trim());
+        }
+        throw new GitError("Git command failed.");
+    }
+}
+export function assertInsideGitRepository() {
+    let result;
+    try {
+        result = runGit(["rev-parse", "--is-inside-work-tree"]).trim();
+    }
+    catch {
+        throw new GitError("Current directory is not inside a Git repository.");
+    }
+    if (result !== "true") {
+        throw new GitError("Current directory is not inside a Git repository.");
+    }
+}
+export function hasChangesUnder(path) {
+    return runGit(["status", "--porcelain", "--", path]).trim() !== "";
+}
+function emptyFileChanges() {
+    return {
+        added: [],
+        modified: [],
+        deleted: [],
+    };
+}
+function addFileChange(changes, status, filePath) {
+    if (status.includes("D")) {
+        changes.deleted.push(filePath);
+        return;
+    }
+    if (status.includes("A") || status === "??") {
+        changes.added.push(filePath);
+        return;
+    }
+    changes.modified.push(filePath);
+}
+function dedupeSorted(paths) {
+    return [...new Set(paths)].sort();
+}
+function normalizeFileChanges(changes) {
+    const deleted = new Set(changes.deleted);
+    const added = new Set(changes.added.filter((path) => !deleted.has(path)));
+    const modified = new Set(changes.modified.filter((path) => !deleted.has(path) && !added.has(path)));
+    return {
+        added: dedupeSorted([...added]),
+        modified: dedupeSorted([...modified]),
+        deleted: dedupeSorted([...deleted]),
+    };
+}
+export function getWorkingTreeChanges(path) {
+    const output = runGit(["status", "--porcelain", "--", path]);
+    const changes = emptyFileChanges();
+    for (const line of output.split("\n")) {
+        if (line.trim() === "") {
+            continue;
+        }
+        const status = line.slice(0, 2);
+        const filePath = line.slice(3).trim();
+        addFileChange(changes, status, filePath);
+    }
+    return normalizeFileChanges(changes);
+}
+export function getHistoricalChanges(path, since) {
+    const output = runGit([
+        "log",
+        `--since=${since}`,
+        "--name-status",
+        "--format=",
+        "--",
+        path,
+    ]);
+    const changes = emptyFileChanges();
+    for (const line of output.split("\n")) {
+        if (line.trim() === "") {
+            continue;
+        }
+        const [status, filePath] = line.split("\t");
+        if (!status || !filePath) {
+            continue;
+        }
+        addFileChange(changes, status, filePath);
+    }
+    return normalizeFileChanges(changes);
+}
+export function getHistory(path, includeChangedFileCount) {
+    const format = "%h%x09%cs%x09%s";
+    const output = runGit(["log", `--format=${format}`, "--name-only", "--", path]);
+    const entries = [];
+    let current;
+    let changedFiles = new Set();
+    function finishCurrent() {
+        if (!current) {
+            return;
+        }
+        if (includeChangedFileCount) {
+            current.changedFileCount = changedFiles.size;
+        }
+        entries.push(current);
+    }
+    for (const line of output.split("\n")) {
+        if (line.trim() === "") {
+            continue;
+        }
+        const parts = line.split("\t");
+        if (parts.length >= 3) {
+            finishCurrent();
+            current = {
+                shortSha: parts[0],
+                date: parts[1],
+                message: parts.slice(2).join("\t"),
+            };
+            changedFiles = new Set();
+            continue;
+        }
+        changedFiles.add(line.trim());
+    }
+    finishCurrent();
+    return entries;
+}
+export function showFileAtCommit(commit, path) {
+    try {
+        return runGit(["show", `${commit}:${path}`]);
+    }
+    catch {
+        throw new GitError(`File not found at ${commit}: ${path}`);
+    }
+}
+export function stagePath(path) {
+    runGit(["add", "--", path]);
+}
+export function commitPath(message, path) {
+    runGit(["commit", "-m", message, "--", path]);
+}

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { backupCommand } from "./commands/backup.js";
+import { commitCommand } from "./commands/commit.js";
+import { snapshotCommand } from "./commands/snapshot.js";
+import { changesCommand } from "./commands/changes.js";
+import { historyCommand } from "./commands/history.js";
+import { restorePreviewCommand } from "./commands/restorePreview.js";
+import { restoreLocalCommand } from "./commands/restoreLocal.js";
+import { restoreFirestoreCommand } from "./commands/restoreFirestore.js";
+const program = new Command();
+program
+    .name("firevault")
+    .description("Git-native backup, diff, and recovery tooling for Firestore.")
+    .version("0.1.0");
+program.addCommand(initCommand);
+program.addCommand(backupCommand);
+program.addCommand(commitCommand);
+program.addCommand(snapshotCommand);
+program.addCommand(changesCommand);
+program.addCommand(historyCommand);
+program.addCommand(restorePreviewCommand);
+program.addCommand(restoreLocalCommand);
+program.addCommand(restoreFirestoreCommand);
+program.parse();

package/dist/paths/backupPaths.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+export function normalizeSlashes(value) {
+    return value.replaceAll("\\", "/").replace(/^\.?\//, "").replace(/\/+$/, "");
+}
+export function normalizeHistoryPath(input, outputDir) {
+    const normalizedInput = normalizeSlashes(input);
+    const normalizedOutputDir = normalizeSlashes(outputDir);
+    if (normalizedInput === normalizedOutputDir ||
+        normalizedInput.startsWith(`${normalizedOutputDir}/`)) {
+        return {
+            path: normalizedInput,
+            isCollection: !normalizedInput.endsWith(".json"),
+        };
+    }
+    const parts = normalizedInput.split("/");
+    if (parts.length === 1) {
+        return {
+            path: path.posix.join(normalizedOutputDir, parts[0]),
+            isCollection: true,
+        };
+    }
+    return {
+        path: path.posix.join(normalizedOutputDir, parts[0], `${parts.slice(1).join("/")}.json`),
+        isCollection: false,
+    };
+}
+export function normalizeDocumentPath(input, outputDir) {
+    const normalizedInput = normalizeSlashes(input);
+    const normalizedOutputDir = normalizeSlashes(outputDir);
+    if (normalizedInput.startsWith(`${normalizedOutputDir}/`)) {
+        return normalizedInput;
+    }
+    const parts = normalizedInput.split("/");
+    return path.posix.join(normalizedOutputDir, parts[0], `${parts.slice(1).join("/")}.json`);
+}