firevault 0.1.1-beta.3 → 0.2.0-beta.0

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## 0.1.1-beta.1 - Unreleased
+## 0.2.0-beta.0 - Unreleased
+
+Breaking prerelease change:
+
+- Firevault now uses `.firevault/config.json` and a dedicated `.firevault` recovery workspace.
+- Firevault backup history now lives in the `.firevault` Git repository instead of the parent app repo.
+- Config-relative paths now resolve from `.firevault/`.
+- `firevault init` no longer creates root `firevault.config.json`.
+- `firestore-backups/` is no longer ignored inside `.firevault/` by default.
+
+## 0.1.1-beta.1
 
 - Added guided `firevault init` setup with prompts for project ID, service account path, output directory, and collections.
 - Added init Git safety checks, `--force`, and `--yes`.

package/README.md

@@ -25,10 +25,12 @@ Current scope:
 Current export shape:
 
 ```txt
-firestore-backups/
-  users/
-    abc123.json
-    def456.json
+.firevault/
+  config.json
+  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.
@@ -36,10 +38,11 @@ The immediate priority is trustworthy document-level recovery: clear previews, e
 ## Quick Start
 
 ```bash
-npm install -g firevault
+npm install -g firevault@next
+cd my-app
 ```
 
-Create a Firebase service account key for your Firestore project, save it as `serviceAccountKey.json`, and keep it out of Git.
+Firevault 0.2 uses `.firevault/config.json` and a dedicated `.firevault` recovery workspace. The app repo stays focused on application source code; `.firevault/` contains Firevault config, backup JSON, credentials, and its own Git history.
 
 Run guided setup:
 
@@ -47,7 +50,7 @@ Run guided setup:
 firevault init
 ```
 
-`firevault init` asks for your Firebase project ID, service account path, output directory, and collections. It also checks Git state before writing files and appends safety entries to `.gitignore`.
+`firevault init` asks for your Firebase project ID, service account path, output directory, and collections. It creates `.firevault/`, writes `.firevault/config.json`, writes `.firevault/.gitignore`, can initialize Git inside `.firevault/`, and adds `.firevault/` to the parent app repo `.gitignore` when the parent is a Git repo.
 
 During setup, Firevault looks for likely Firebase project IDs in local files such as `.env.local`, `.env.development`, `firebase.json`, and common Firebase config files. Detection is best-effort and transparent: if Firevault finds candidates, it shows where they came from and lets you accept one or enter a value manually.
 
@@ -62,14 +65,14 @@ https://console.firebase.google.com/project/your-project-id/settings/serviceacco
 
 Download the JSON key and save it as:
 
-./serviceAccountKey.json
+.firevault/serviceAccountKey.json
 ```
 
 Firevault does not create service accounts, open a browser, run `gcloud`, or authenticate against Firebase during setup.
 
 If the selected service account file already exists, Firevault can optionally connect to Firestore and list top-level collections so you can choose which ones to back up. If the file is missing or Firebase access fails, init continues and you can enter collections manually.
 
-Generated `firevault.config.json`:
+Generated `.firevault/config.json`:
 
 ```json
 {
@@ -86,6 +89,8 @@ Take a snapshot:
 firevault snapshot
 ```
 
+Operational commands discover the nearest `.firevault/config.json`, so they work from the app root or from inside `.firevault/`.
+
 Example output:
 
 ```txt
@@ -179,6 +184,12 @@ firevault snapshot
 
 Firevault operates against an existing Firebase project using a service account.
 
+Expected config path:
+
+```txt
+.firevault/config.json
+```
+
 Expected config shape:
 
 ```json
@@ -192,19 +203,28 @@ Expected config shape:
 
 Notes:
 
-- `serviceAccountPath` points to a local Firebase service account JSON file.
-- `outputDir` is where Firestore documents are written.
+- paths are relative to `.firevault/`,
+- `serviceAccountPath` points to a local Firebase service account JSON file,
+- `outputDir` is where Firestore documents are written inside `.firevault/`,
 - `collections` controls which top-level Firestore collections are exported.
 - Service account files must not be committed.
 
-Recommended `.gitignore` entries for local development:
+Parent app repo `.gitignore`:
+
+```gitignore
+.firevault/
+```
+
+`.firevault/.gitignore`:
 
 ```gitignore
 serviceAccountKey.json
-firestore-backups/
+firestore-debug.log
+.env
+.env.*
 ```
 
-`firevault init` adds these safety entries automatically. `firestore-backups/` is ignored by default so exported Firestore data is not committed accidentally with normal Git commands. Firevault can still commit the configured backup directory explicitly through `firevault commit` or `firevault snapshot`, and it stages only that directory.
+`firevault init` adds these safety entries automatically. In the 0.2 workspace model, `firestore-backups/` is not ignored inside `.firevault/` because the `.firevault` Git repo exists to track backup history.
 
 ## Commands
 
@@ -262,7 +282,7 @@ JSON output is stable:
 
 `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.
+`firevault commit` commits inside the `.firevault` Git repository.
 
 Behavior:
 
@@ -270,6 +290,7 @@ Behavior:
 - exits successfully if no backup changes exist,
 - stages only the configured `outputDir`,
 - creates a local commit with message `backup: <ISO timestamp>`,
+- never stages app source files from the parent repo,
 - never pushes.
 
 Keep `serviceAccountKey.json` ignored so credentials cannot be committed by this workflow or by manual Git usage.

package/dist/commands/backup.js

@@ -4,7 +4,7 @@ import { exportCollection } from "../firestore/exportFirestore.js";
 export async function runBackup() {
     const config = loadConfig();
     for (const collection of config.collections) {
-        await exportCollection(config.outputDir, collection);
+        await exportCollection(config.outputDirPath, collection);
     }
     console.log("Backup complete.");
 }

package/dist/commands/changes.js

@@ -31,10 +31,10 @@ function normalizeLastWindow(last) {
 }
 export function runChanges(last) {
     const config = loadConfig();
-    assertInsideGitRepository();
+    assertInsideGitRepository(config.workspaceRoot);
     const changes = last
-        ? getHistoricalChanges(config.outputDir, normalizeLastWindow(last))
-        : getWorkingTreeChanges(config.outputDir);
+        ? getHistoricalChanges(config.outputDir, normalizeLastWindow(last), config.workspaceRoot)
+        : getWorkingTreeChanges(config.outputDir, config.workspaceRoot);
     printChanges(changes);
 }
 export const changesCommand = new Command("changes")

package/dist/commands/commit.js

@@ -3,14 +3,14 @@ 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)) {
+    assertInsideGitRepository(config.workspaceRoot);
+    if (!hasChangesUnder(config.outputDir, config.workspaceRoot)) {
         console.log(`No changes found under ${config.outputDir}.`);
         return;
     }
-    stagePath(config.outputDir);
+    stagePath(config.outputDir, config.workspaceRoot);
     const message = `backup: ${new Date().toISOString()}`;
-    commitPath(message, config.outputDir);
+    commitPath(message, config.outputDir, config.workspaceRoot);
     console.log(`Created commit: ${message}`);
 }
 export const commitCommand = new Command("commit")

package/dist/commands/history.js

@@ -15,8 +15,8 @@ function printHistory(entries) {
 export function runHistory(inputPath) {
     const config = loadConfig();
     const normalizedPath = normalizeHistoryPath(inputPath, config.outputDir);
-    assertInsideGitRepository();
-    const entries = getHistory(normalizedPath.path, normalizedPath.isCollection);
+    assertInsideGitRepository(config.workspaceRoot);
+    const entries = getHistory(normalizedPath.path, normalizedPath.isCollection, config.workspaceRoot);
     if (entries.length === 0) {
         console.log(`No history found for ${normalizedPath.path}.`);
         return;

package/dist/commands/init.js

@@ -1,7 +1,8 @@
 import { Command } from "commander";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { appendFileSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import path from "node:path";
 import { GitError, hasWorkingTreeChanges, initGitRepository, isInsideGitRepository, } from "../git/git.js";
 import { detectFirebaseProjectCandidates, uniqueProjectIds, } from "../init/detectFirebaseProject.js";
 import { detectServiceAccountPaths } from "../init/detectServiceAccount.js";
@@ -12,6 +13,8 @@ const defaultConfig = {
     outputDir: "firestore-backups",
     collections: ["users"],
 };
+const workspaceDirName = ".firevault";
+const configFileName = "config.json";
 function validateConfig(config) {
     if (config.projectId.trim() === "") {
         throw new Error("Firebase project ID is required.");
@@ -49,13 +52,13 @@ function printServiceAccountGuidance(projectId, serviceAccountPath) {
     console.log(serviceAccountPath);
     console.log("");
 }
-function printMissingServiceAccountInfo(serviceAccountPath) {
+function printMissingServiceAccountInfo(serviceAccountPath, serviceAccountDisplayPath) {
     if (existsSync(serviceAccountPath)) {
         return;
     }
-    console.log(`Service account file does not exist yet: ${serviceAccountPath}`);
+    console.log(`Service account file does not exist yet: ${serviceAccountDisplayPath}`);
     console.log("That is expected before downloading the Firebase Admin SDK key.");
-    console.log(`Save the downloaded JSON key at: ${serviceAccountPath}`);
+    console.log(`Save the downloaded JSON key at: ${serviceAccountDisplayPath}`);
     console.log("");
 }
 function gitignorePathFor(filePath) {
@@ -133,9 +136,9 @@ function parseSelectedCollections(inputValue, detectedCollections) {
     }
     return [...new Set(selectedCollections)];
 }
-async function promptForCollectionListing(rl, projectId, serviceAccountPath) {
+async function promptForCollectionListing(rl, projectId, serviceAccountPath, serviceAccountDisplayPath) {
     if (!existsSync(serviceAccountPath)) {
-        console.log(`Service account file is not present, so collection detection is skipped: ${serviceAccountPath}`);
+        console.log(`Service account file is not present, so collection detection is skipped: ${serviceAccountDisplayPath}`);
         console.log("");
         return undefined;
     }
@@ -175,9 +178,9 @@ async function promptForCollectionListing(rl, projectId, serviceAccountPath) {
     }
     return parseSelectedCollections(selected, detectedCollections);
 }
-async function promptForConfig(options, rl) {
+async function promptForConfig(options, workspaceRoot, rl) {
     const projectCandidates = detectFirebaseProjectCandidates();
-    const serviceAccountPaths = detectServiceAccountPaths();
+    const serviceAccountPaths = detectServiceAccountPaths(process.cwd(), workspaceRoot);
     if (options.yes) {
         return {
             ...defaultConfig,
@@ -189,11 +192,13 @@ async function promptForConfig(options, rl) {
     }
     const projectId = await promptForProjectId(rl, projectCandidates);
     if (projectId !== "") {
-        printServiceAccountGuidance(projectId, defaultConfig.serviceAccountPath);
+        printServiceAccountGuidance(projectId, path.join(workspaceDirName, defaultConfig.serviceAccountPath.replace(/^\.\//, "")));
     }
     const serviceAccountPath = await promptForServiceAccountPath(rl, serviceAccountPaths);
     const outputDir = (await rl.question(`Output directory (${defaultConfig.outputDir}): `)).trim() || defaultConfig.outputDir;
-    const detectedCollections = await promptForCollectionListing(rl, projectId, serviceAccountPath);
+    const serviceAccountAbsolutePath = path.resolve(workspaceRoot, serviceAccountPath);
+    const serviceAccountDisplayPath = path.relative(process.cwd(), serviceAccountAbsolutePath);
+    const detectedCollections = await promptForCollectionListing(rl, projectId, serviceAccountAbsolutePath, serviceAccountDisplayPath);
     const collectionsInput = detectedCollections
         ? detectedCollections.join(",")
         : (await rl.question("Collections, comma-separated: ")).trim();
@@ -211,13 +216,12 @@ async function promptForGitInit(options, rl) {
     if (!rl) {
         throw new Error("Prompt interface is required for interactive init.");
     }
-    const answer = (await rl.question("This directory is not a Git repository. Run git init? (Y/n): "))
+    const answer = (await rl.question("Initialize Git inside .firevault? (Y/n): "))
         .trim()
         .toLowerCase();
     return answer === "" || answer === "y" || answer === "yes";
 }
-function ensureGitignoreEntries(entries) {
-    const gitignorePath = ".gitignore";
+function ensureGitignoreEntries(gitignorePath, entries) {
     const existing = existsSync(gitignorePath)
         ? readFileSync(gitignorePath, "utf-8")
         : "";
@@ -236,45 +240,61 @@ export async function runInit(options) {
     console.log("Firevault");
     console.log("Undo button for Firestore.");
     console.log("");
-    const configPath = "firevault.config.json";
-    const alreadyInGitRepository = isInsideGitRepository();
+    const appRoot = process.cwd();
+    const workspaceRoot = path.join(appRoot, workspaceDirName);
+    const configPath = path.join(workspaceRoot, configFileName);
+    const parentIsGitRepository = isInsideGitRepository(appRoot);
+    const workspaceIsGitRepository = isInsideGitRepository(workspaceRoot);
     const rl = options.yes ? undefined : createInterface({ input, output });
     try {
-        if (alreadyInGitRepository && hasWorkingTreeChanges() && !options.force) {
+        if (parentIsGitRepository && hasWorkingTreeChanges(appRoot) && !options.force) {
             throw new Error("Git working tree has changes. Commit, stash, or rerun with --force before init writes files.");
         }
         if (existsSync(configPath) && !options.force) {
-            throw new Error("firevault.config.json already exists. Rerun with --force to overwrite it.");
+            throw new Error(".firevault/config.json already exists. Rerun with --force to overwrite it.");
         }
-        const shouldInitGit = alreadyInGitRepository
+        const shouldInitGit = workspaceIsGitRepository
             ? false
             : await promptForGitInit(options, rl);
-        const config = await promptForConfig(options, rl);
+        const config = await promptForConfig(options, workspaceRoot, rl);
         config.collections = config.collections.map((collection) => collection.trim());
         validateConfig(config);
+        const serviceAccountAbsolutePath = path.resolve(workspaceRoot, config.serviceAccountPath);
+        const serviceAccountDisplayPath = path.relative(appRoot, serviceAccountAbsolutePath);
         if (options.yes) {
-            printServiceAccountGuidance(config.projectId, config.serviceAccountPath);
+            printServiceAccountGuidance(config.projectId, serviceAccountDisplayPath);
         }
-        printMissingServiceAccountInfo(config.serviceAccountPath);
+        printMissingServiceAccountInfo(serviceAccountAbsolutePath, serviceAccountDisplayPath);
+        mkdirSync(workspaceRoot, { recursive: true });
         if (shouldInitGit) {
-            initGitRepository();
-            console.log("Initialized Git repository.");
+            initGitRepository(workspaceRoot);
+            console.log("Initialized Git repository in .firevault.");
         }
         if (existsSync(configPath) && options.force) {
-            console.log("Warning: overwriting existing firevault.config.json.");
+            console.log("Warning: overwriting existing .firevault/config.json.");
         }
         writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
-        ensureGitignoreEntries([
-            "serviceAccountKey.json",
+        ensureGitignoreEntries(path.join(workspaceRoot, ".gitignore"), [
             gitignorePathFor(config.serviceAccountPath),
-            "firestore-backups/",
             "firestore-debug.log",
+            ".env",
+            ".env.*",
         ]);
-        console.log("Created firevault.config.json.");
-        console.log("Updated .gitignore safety entries.");
+        if (parentIsGitRepository) {
+            const parentIgnoreEntries = [".firevault/"];
+            const serviceAccountInAppRepo = path.relative(appRoot, serviceAccountAbsolutePath);
+            if (!serviceAccountInAppRepo.startsWith("..") &&
+                !gitignorePathFor(serviceAccountInAppRepo).startsWith(".firevault/")) {
+                parentIgnoreEntries.push(gitignorePathFor(serviceAccountInAppRepo));
+            }
+            ensureGitignoreEntries(path.join(appRoot, ".gitignore"), parentIgnoreEntries);
+            console.log("Updated parent .gitignore safety entries.");
+        }
+        console.log("Created .firevault/config.json.");
+        console.log("Updated .firevault/.gitignore safety entries.");
         console.log("");
         console.log("Next steps:");
-        console.log(`1. Save your service account key at ${config.serviceAccountPath}`);
+        console.log(`1. Save your service account key at ${serviceAccountDisplayPath}`);
         console.log("2. Run `firevault snapshot`");
         console.log("3. Run `firevault changes`");
         console.log("4. Run `firevault restore-preview <path> --from <commit>` before a real restore");

package/dist/commands/restoreFirestore.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { ConfigError, loadConfig, resolveWorkspacePath } 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";
@@ -65,12 +65,13 @@ export async function runRestoreFirestore(inputPath, options) {
     }
     const config = loadConfig();
     const target = getFirestoreTarget(inputPath, config.outputDir);
-    assertInsideGitRepository();
-    const restoredContent = showFileAtCommit(options.from, target.backupPath);
+    assertInsideGitRepository(config.workspaceRoot);
+    const restoredContent = showFileAtCommit(options.from, target.backupPath, config.workspaceRoot);
     const restoredData = parseRestoreJson(restoredContent, target.backupPath);
-    const currentExists = existsSync(target.backupPath);
+    const targetFilePath = resolveWorkspacePath(config.workspaceRoot, target.backupPath);
+    const currentExists = existsSync(targetFilePath);
     const currentContent = currentExists
-        ? readFileSync(target.backupPath, "utf-8")
+        ? readFileSync(targetFilePath, "utf-8")
         : undefined;
     const diff = buildLineDiff(currentContent, restoredContent);
     printFirestorePreview(target, options.from, currentExists, diff);

package/dist/commands/restoreLocal.js

@@ -1,7 +1,7 @@
 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 { ConfigError, loadConfig, resolveWorkspacePath } from "../config/loadConfig.js";
 import { GitError, assertInsideGitRepository, showFileAtCommit, } from "../git/git.js";
 import { normalizeDocumentPath } from "../paths/backupPaths.js";
 import { buildLineDiff, printRestorePreview } from "./restorePreview.js";
@@ -14,14 +14,15 @@ export function runRestoreLocal(inputPath, options) {
     }
     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;
+    assertInsideGitRepository(config.workspaceRoot);
+    const restoredContent = showFileAtCommit(options.from, targetPath, config.workspaceRoot);
+    const targetFilePath = resolveWorkspacePath(config.workspaceRoot, targetPath);
+    const currentExists = existsSync(targetFilePath);
+    const currentContent = currentExists ? readFileSync(targetFilePath, "utf-8") : undefined;
     const diff = buildLineDiff(currentContent, restoredContent);
     printRestorePreview(targetPath, options.from, currentExists, diff);
-    mkdirSync(path.dirname(targetPath), { recursive: true });
-    writeFileSync(targetPath, restoredContent);
+    mkdirSync(path.dirname(targetFilePath), { recursive: true });
+    writeFileSync(targetFilePath, restoredContent);
     console.log("");
     console.log(`Restored local backup file: ${targetPath}`);
 }

package/dist/commands/restorePreview.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { Command } from "commander";
-import { ConfigError, loadConfig } from "../config/loadConfig.js";
+import { ConfigError, loadConfig, resolveWorkspacePath } from "../config/loadConfig.js";
 import { GitError, assertInsideGitRepository, showFileAtCommit, } from "../git/git.js";
 import { normalizeDocumentPath } from "../paths/backupPaths.js";
 function normalizeJson(content) {
@@ -76,10 +76,11 @@ export function runRestorePreview(inputPath, options) {
     }
     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;
+    assertInsideGitRepository(config.workspaceRoot);
+    const restoredContent = showFileAtCommit(options.from, targetPath, config.workspaceRoot);
+    const targetFilePath = resolveWorkspacePath(config.workspaceRoot, targetPath);
+    const currentExists = existsSync(targetFilePath);
+    const currentContent = currentExists ? readFileSync(targetFilePath, "utf-8") : undefined;
     const diff = buildLineDiff(currentContent, restoredContent);
     printRestorePreview(targetPath, options.from, currentExists, diff);
 }

package/dist/config/loadConfig.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
 export class ConfigError extends Error {
     constructor(message) {
         super(message);
@@ -11,7 +12,7 @@ function isRecord(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.`);
+        throw new ConfigError(`Invalid .firevault/config.json: "${field}" is required and must be a string.`);
     }
     return value;
 }
@@ -20,15 +21,36 @@ function requireStringArray(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.`);
+        throw new ConfigError(`Invalid .firevault/config.json: "${field}" is required and must include at least one collection name.`);
     }
     return value;
 }
+export function findWorkspaceRoot(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(currentDir, ".firevault", "config.json");
+        if (existsSync(candidate)) {
+            return path.join(currentDir, ".firevault");
+        }
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) {
+            return undefined;
+        }
+        currentDir = parent;
+    }
+}
+function normalizeConfigPath(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+export function resolveWorkspacePath(workspaceRoot, configPath) {
+    return path.resolve(workspaceRoot, configPath);
+}
 export function loadConfig() {
-    const configPath = "firevault.config.json";
-    if (!existsSync(configPath)) {
-        throw new ConfigError("Missing firevault.config.json. Run `firevault init` first.");
+    const workspaceRoot = findWorkspaceRoot();
+    if (!workspaceRoot) {
+        throw new ConfigError("Missing .firevault/config.json. Run `firevault init` first.");
     }
+    const configPath = path.join(workspaceRoot, "config.json");
     let parsed;
     try {
         const raw = readFileSync(configPath, "utf-8");
@@ -36,18 +58,24 @@ export function loadConfig() {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            throw new ConfigError("Invalid firevault.config.json: file is not valid JSON.");
+            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.");
+        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"),
+        serviceAccountPath: normalizeConfigPath(requireString(parsed, "serviceAccountPath")),
+        outputDir: normalizeConfigPath(requireString(parsed, "outputDir")),
         collections: requireStringArray(parsed, "collections"),
+        workspaceRoot,
+        configPath,
+        serviceAccountPathAbsolute: "",
+        outputDirPath: "",
     };
+    config.serviceAccountPathAbsolute = resolveWorkspacePath(workspaceRoot, config.serviceAccountPath);
+    config.outputDirPath = resolveWorkspacePath(workspaceRoot, config.outputDir);
     return config;
 }

package/dist/firestore/firebase.js

@@ -15,10 +15,10 @@ export function getFirestore() {
                 initialized = true;
                 return admin.firestore();
             }
-            if (!existsSync(config.serviceAccountPath)) {
+            if (!existsSync(config.serviceAccountPathAbsolute)) {
                 throw new ConfigError(`Service account file not found: ${config.serviceAccountPath}`);
             }
-            serviceAccount = JSON.parse(readFileSync(config.serviceAccountPath, "utf-8"));
+            serviceAccount = JSON.parse(readFileSync(config.serviceAccountPathAbsolute, "utf-8"));
             admin.initializeApp({
                 credential: admin.credential.cert(serviceAccount),
                 projectId: config.projectId,

package/dist/git/git.js

@@ -5,9 +5,10 @@ export class GitError extends Error {
         this.name = "GitError";
     }
 }
-function runGit(args) {
+function runGit(args, cwd = process.cwd()) {
     try {
         return execFileSync("git", args, {
+            cwd,
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -23,27 +24,27 @@ function runGit(args) {
         throw new GitError("Git command failed.");
     }
 }
-export function isInsideGitRepository() {
+export function isInsideGitRepository(cwd = process.cwd()) {
     try {
-        return runGit(["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+        return runGit(["rev-parse", "--is-inside-work-tree"], cwd).trim() === "true";
     }
     catch {
         return false;
     }
 }
-export function assertInsideGitRepository() {
-    if (!isInsideGitRepository()) {
+export function assertInsideGitRepository(cwd = process.cwd()) {
+    if (!isInsideGitRepository(cwd)) {
         throw new GitError("Current directory is not inside a Git repository.");
     }
 }
-export function initGitRepository() {
-    runGit(["init"]);
+export function initGitRepository(cwd = process.cwd()) {
+    runGit(["init"], cwd);
 }
-export function hasWorkingTreeChanges() {
-    return runGit(["status", "--porcelain"]).trim() !== "";
+export function hasWorkingTreeChanges(cwd = process.cwd()) {
+    return runGit(["status", "--porcelain"], cwd).trim() !== "";
 }
-export function hasChangesUnder(path) {
-    return runGit(["status", "--porcelain", "--ignored", "--", path]).trim() !== "";
+export function hasChangesUnder(path, cwd = process.cwd()) {
+    return runGit(["status", "--porcelain", "--ignored", "--", path], cwd).trim() !== "";
 }
 function emptyFileChanges() {
     return {
@@ -76,8 +77,8 @@ function normalizeFileChanges(changes) {
         deleted: dedupeSorted([...deleted]),
     };
 }
-export function getWorkingTreeChanges(path) {
-    const output = runGit(["status", "--porcelain", "--", path]);
+export function getWorkingTreeChanges(path, cwd = process.cwd()) {
+    const output = runGit(["status", "--porcelain", "--", path], cwd);
     const changes = emptyFileChanges();
     for (const line of output.split("\n")) {
         if (line.trim() === "") {
@@ -89,7 +90,7 @@ export function getWorkingTreeChanges(path) {
     }
     return normalizeFileChanges(changes);
 }
-export function getHistoricalChanges(path, since) {
+export function getHistoricalChanges(path, since, cwd = process.cwd()) {
     const output = runGit([
         "log",
         `--since=${since}`,
@@ -97,7 +98,7 @@ export function getHistoricalChanges(path, since) {
         "--format=",
         "--",
         path,
-    ]);
+    ], cwd);
     const changes = emptyFileChanges();
     for (const line of output.split("\n")) {
         if (line.trim() === "") {
@@ -111,9 +112,9 @@ export function getHistoricalChanges(path, since) {
     }
     return normalizeFileChanges(changes);
 }
-export function getHistory(path, includeChangedFileCount) {
+export function getHistory(path, includeChangedFileCount, cwd = process.cwd()) {
     const format = "%h%x09%cs%x09%s";
-    const output = runGit(["log", `--format=${format}`, "--name-only", "--", path]);
+    const output = runGit(["log", `--format=${format}`, "--name-only", "--", path], cwd);
     const entries = [];
     let current;
     let changedFiles = new Set();
@@ -146,17 +147,17 @@ export function getHistory(path, includeChangedFileCount) {
     finishCurrent();
     return entries;
 }
-export function showFileAtCommit(commit, path) {
+export function showFileAtCommit(commit, path, cwd = process.cwd()) {
     try {
-        return runGit(["show", `${commit}:${path}`]);
+        return runGit(["show", `${commit}:${path}`], cwd);
     }
     catch {
         throw new GitError(`File not found at ${commit}: ${path}`);
     }
 }
-export function stagePath(path) {
-    runGit(["add", "-f", "--", path]);
+export function stagePath(path, cwd = process.cwd()) {
+    runGit(["add", "-f", "--", path], cwd);
 }
-export function commitPath(message, path) {
-    runGit(["commit", "-m", message, "--", path]);
+export function commitPath(message, path, cwd = process.cwd()) {
+    runGit(["commit", "-m", message, "--", path], cwd);
 }

package/dist/index.js

@@ -13,7 +13,7 @@ const program = new Command();
 program
     .name("firevault")
     .description("Undo button for Firestore.")
-    .version("0.1.0");
+    .version("0.2.0-beta.0");
 program.addCommand(initCommand);
 program.addCommand(backupCommand);
 program.addCommand(commitCommand);

package/dist/init/detectServiceAccount.js

@@ -1,10 +1,29 @@
 import { existsSync } from "node:fs";
+import path from "node:path";
 const likelyServiceAccountPaths = [
     "./serviceAccountKey.json",
     "./service-account.json",
     "./firebase-service-account.json",
     "./credentials/firebase.json",
 ];
-export function detectServiceAccountPaths() {
-    return likelyServiceAccountPaths.filter((filePath) => existsSync(filePath));
+function normalizeConfigRelativePath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    if (normalized.startsWith("../")) {
+        return normalized;
+    }
+    return normalized.startsWith("./") ? normalized : `./${normalized}`;
+}
+export function detectServiceAccountPaths(appRoot = process.cwd(), workspaceRoot = path.join(appRoot, ".firevault")) {
+    const candidates = [];
+    for (const filePath of likelyServiceAccountPaths) {
+        const appPath = path.resolve(appRoot, filePath);
+        const workspacePath = path.resolve(workspaceRoot, filePath);
+        if (existsSync(workspacePath)) {
+            candidates.push(normalizeConfigRelativePath(filePath));
+        }
+        if (existsSync(appPath)) {
+            candidates.push(normalizeConfigRelativePath(path.relative(workspaceRoot, appPath)));
+        }
+    }
+    return [...new Set(candidates)];
 }

package/docs/architecture.md

@@ -27,21 +27,16 @@ The architecture should optimize for:
 ## Current Project Structure
 
 ```txt
-src/
-  commands/
-    init.ts
-    backup.ts
-  config/
-    loadConfig.ts
-  firestore/
-    exportFirestore.ts
-    firebase.ts
-    stableStringify.ts
-  git/
-  index.ts
-firevault.config.json
-package.json
-tsconfig.json
+my-app/
+  src/
+  firebase.ts
+  .env.local
+  .gitignore
+  .firevault/
+    config.json
+    firestore-backups/
+    .git/
+    .gitignore
 ```
 
 ## Command Layer
@@ -52,19 +47,25 @@ Current commands:
 
 - `firevault init`
 - `firevault backup`
+- `firevault commit`
+- `firevault snapshot`
+- `firevault changes`
+- `firevault history`
+- `firevault restore-preview`
+- `firevault restore-local`
+- `firevault restore-firestore`
 
 Expected future commands:
 
 ```bash
-firevault backup
-firevault changes --last 24h
 firevault diff users/abc123
-firevault restore users/abc123 --from HEAD~3
 ```
 
 ## Configuration
 
-Configuration is loaded from `firevault.config.json`.
+Configuration is loaded from `.firevault/config.json`.
+
+Firevault 0.2 uses `.firevault/config.json` and a dedicated `.firevault` recovery workspace. There is no backward compatibility with the old root-based `firevault.config.json` prerelease model.
 
 Intended shape:
 
@@ -79,9 +80,10 @@ Intended shape:
 
 Current implementation notes:
 
-- `loadConfig` reads and parses `firevault.config.json`.
-- Firebase initialization expects `serviceAccountPath`.
-- `firevault init` guides setup, validates required fields, checks Git state before writing, and updates `.gitignore` without overwriting existing entries.
+- `loadConfig` walks upward from the current directory, finds the nearest `.firevault/config.json`, and treats that `.firevault` directory as the workspace root.
+- Config-relative paths resolve from the workspace root.
+- Firebase initialization expects `serviceAccountPath` relative to `.firevault/`.
+- `firevault init` guides setup, validates required fields, checks Git state before writing, creates `.firevault/`, and updates `.gitignore` files without overwriting existing entries.
 - `firevault init` can suggest project IDs from local Firebase config files and likely service account paths from local filenames.
 - `firevault init --force` allows dirty Git state and config overwrite with a warning.
 - `firevault init --yes` provides a deterministic non-interactive path for tests and automation, using a detected project ID if one is available and skipping Firebase collection listing.
@@ -93,8 +95,8 @@ Current implementation notes:
 Behavior:
 
 - prints the Firevault identity before prompting,
-- detects whether the current directory is inside a Git repository,
-- offers `git init` when no repository exists,
+- detects whether the app directory is inside a Git repository,
+- offers to initialize Git inside `.firevault/`,
 - scans common local Firebase files for project ID candidates,
 - shows detected project ID candidates with their source files,
 - suggests likely service account paths without reading or printing private key contents,
@@ -102,8 +104,9 @@ Behavior:
 - explains where to save the manually downloaded service account key,
 - optionally lists top-level Firestore collections only after telling the user and only when the selected service account file exists,
 - refuses to run in a dirty Git working tree unless `--force` is provided,
-- refuses to overwrite `firevault.config.json` unless `--force` is provided,
-- appends `.gitignore` safety entries, including the selected service account path, without duplicating existing lines,
+- refuses to overwrite `.firevault/config.json` unless `--force` is provided,
+- adds `.firevault/` to the parent app repo `.gitignore` when the parent is a Git repo,
+- appends `.firevault/.gitignore` safety entries, including the selected service account path, without duplicating existing lines,
 - never creates service accounts, opens browsers, runs `gcloud`, commits, pushes, creates GitHub repositories, contacts Firebase, or writes secrets.
 
 ## Firebase Access
@@ -120,6 +123,17 @@ Design constraints:
 - do not introduce credential brokerage, hosted auth, or account systems,
 - avoid committing service account files.
 
+## Workspace Boundary
+
+The app repo and Firevault recovery repo are separate:
+
+- app repo: application source code and normal development history,
+- `.firevault` repo: Firestore recovery config, backup JSON, and recovery history.
+
+Operational commands work from the app root or from inside `.firevault/` by discovering the nearest `.firevault/config.json`. Git commands run with `.firevault/` as their working directory so `firevault commit`, `changes`, `history`, and restore previews cannot stage or inspect unrelated app source files.
+
+`firestore-backups/` is not ignored inside `.firevault/` by default. The `.firevault` repository exists to commit backup data.
+
 ## Emulator Tests
 
 Firestore emulator integration tests live under `test/integration/`.
@@ -153,7 +167,7 @@ Current backup flow:
 1. Load config.
 2. Iterate configured collections.
 3. Fetch each collection through Firebase Admin SDK.
-4. Write each document to `<outputDir>/<collection>/<documentId>.json`.
+4. Write each document to `.firevault/<outputDir>/<collection>/<documentId>.json`.
 5. Serialize document data using deterministic JSON.
 
 The current exporter handles configured top-level collections. Subcollections, deletes, metadata, timestamps, references, and special Firestore value types need explicit design before production use.
@@ -175,6 +189,8 @@ Serialization rules should remain boring and predictable:
 
 Git is the storage and history engine. Firevault should wrap Git workflows rather than reimplement versioning.
 
+For Firevault 0.2, Git operations are scoped to the `.firevault` workspace repository, not the parent app repository.
+
 Near-term Git integration should focus on:
 
 - detecting working tree changes after backup,

package/docs/roadmap.md

@@ -26,7 +26,8 @@ Status:
 - npm prerelease packaging is guarded by package file whitelisting and pack verification.
 - Local npm prerelease publishing is guarded by a `gitversionjs`-based publish script with clean-tree, build, emulator-test, pack, and forbidden-path checks.
 - Public GitHub release docs cover quick start, security, contributing, and issue triage.
-- Guided `firevault init` validates setup input, checks Git state, suggests local Firebase project settings, optionally lists Firestore collections, and applies `.gitignore` safety entries.
+- Firevault 0.2 uses `.firevault/config.json` and a dedicated `.firevault` recovery workspace as a breaking prerelease change.
+- Guided `firevault init` validates setup input, checks Git state, suggests local Firebase project settings, optionally lists Firestore collections, creates `.firevault/`, and applies workspace `.gitignore` safety entries.
 
 Next work:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firevault",
-  "version": "0.1.1-beta.3",
+  "version": "0.2.0-beta.0",
   "description": "Undo button for Firestore. Git-style history, rollback, and recovery for Firestore projects.",
   "keywords": [
     "firebase",