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

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## 0.1.1-beta.1 - Unreleased
+## 0.2.0-beta.1 - Unreleased
+
+- Added `firevault status` for compact local recovery health checks.
+- Added `firevault doctor` for actionable local setup validation.
+- Added `firevault setup-github-action` to generate a scheduled GitHub Actions workflow for offsite snapshots.
+- Added local workflow detection for generated GitHub Actions snapshot automation.
+
+## 0.2.0-beta.0
+
+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/`.
+- Operational commands discover the nearest `.firevault/config.json` from the app root or from inside `.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
 
@@ -213,6 +233,9 @@ firevault init
 firevault backup
 firevault commit
 firevault snapshot
+firevault status
+firevault doctor
+firevault setup-github-action
 firevault changes
 firevault changes --last 24h
 firevault history users/abc123
@@ -262,7 +285,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 +293,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.
@@ -282,6 +306,56 @@ Keep `serviceAccountKey.json` ignored so credentials cannot be committed by this
 - exits successfully when backup succeeds but no Git changes exist,
 - never pushes.
 
+`firevault status` shows a compact local recovery health overview. It does not contact Firebase, call GitHub APIs, fetch from remotes, write files, stage, commit, or push.
+
+Example output:
+
+```txt
+Firevault status
+
+Workspace:
+  Path: .firevault
+  Config: OK
+
+Firestore:
+  Project: my-project
+  Collections configured: 4
+
+Backups:
+  Output directory: firestore-backups
+  Output exists: yes
+  Last snapshot: 2026-05-17T14:22:10Z
+  Uncommitted backup changes: none
+
+Git:
+  Repository: OK
+  Branch: main
+  Working tree: clean
+  Remote origin: configured
+  Remote sync: unknown
+
+Automation:
+  GitHub Actions workflow: not configured
+```
+
+`firevault doctor` validates the local Firevault setup and prints actionable fixes. It checks workspace discovery, config validity, service account file presence, backup output state, `.firevault` Git setup, remote origin, GitHub Actions workflow contents, `.gitignore` safety, tracked secret-looking files, backup directory trackability, and working tree state.
+
+Doctor is local-only. It does not contact Firebase, call GitHub APIs, write files, stage, commit, push, or print secrets.
+
+Exit codes:
+
+- `0`: all checks OK,
+- `1`: warnings only,
+- `2`: one or more failures.
+
+`firevault setup-github-action` creates a local scheduled workflow at `.firevault/.github/workflows/firevault-snapshot.yml`.
+
+The workflow is intended for a private GitHub repository containing the `.firevault` recovery workspace. It runs daily by default, supports manual dispatch, installs `firevault@next`, writes the Firebase service account JSON from the GitHub secret `FIREVAULT_SERVICE_ACCOUNT_JSON`, runs `firevault snapshot`, and pushes only when a backup commit was created.
+
+This command only writes the workflow file. It does not create GitHub repositories, call GitHub APIs, create secrets, push, stage, commit, store credentials, or install GitHub CLI dependencies.
+
+After generation, push the `.firevault` repo to GitHub, create the `FIREVAULT_SERVICE_ACCOUNT_JSON` repository secret with the full service account JSON, review the workflow, and commit it yourself.
+
 `firevault changes` shows a file-level Git summary for the configured `outputDir` only:
 
 ```txt

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/doctor.js

@@ -0,0 +1,225 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { ConfigError, findWorkspaceRoot, loadConfig } from "../config/loadConfig.js";
+import { getRemoteUrl, getTrackedFiles, hasChangesUnder, hasWorkingTreeChanges, isInsideGitRepository, isPathIgnored, } from "../git/git.js";
+function findNearestWorkspaceDir(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(currentDir, ".firevault");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) {
+            return undefined;
+        }
+        currentDir = parent;
+    }
+}
+function addCheck(checks, severity, label, fix) {
+    checks.push({ severity, label, fix });
+}
+function displayPathFromApp(workspaceRoot, targetPath) {
+    return path.relative(path.dirname(workspaceRoot), targetPath).replaceAll("\\", "/");
+}
+function isInside(parent, child) {
+    const relativePath = path.relative(parent, child);
+    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+function gitignoreContains(workspaceRoot, value) {
+    const gitignorePath = path.join(workspaceRoot, ".gitignore");
+    if (!existsSync(gitignorePath)) {
+        return false;
+    }
+    const normalizedValue = value.replaceAll("\\", "/").replace(/^\.\//, "");
+    const basename = path.posix.basename(normalizedValue);
+    const lines = readFileSync(gitignorePath, "utf-8")
+        .split("\n")
+        .map((line) => line.trim().replace(/\/+$/, ""))
+        .filter((line) => line !== "" && !line.startsWith("#"));
+    return lines.includes(normalizedValue) || lines.includes(`./${normalizedValue}`) || lines.includes(basename);
+}
+function workflowChecks(checks, workspaceRoot) {
+    const workflowPath = path.join(workspaceRoot, ".github", "workflows", "firevault-snapshot.yml");
+    if (!existsSync(workflowPath)) {
+        addCheck(checks, "WARN", "GitHub Actions workflow missing", "Run `firevault setup-github-action`");
+        return;
+    }
+    const workflow = readFileSync(workflowPath, "utf-8");
+    const missing = [];
+    if (!workflow.includes("schedule:") || !workflow.includes("cron:")) {
+        missing.push("schedule trigger");
+    }
+    if (!workflow.includes("workflow_dispatch:")) {
+        missing.push("workflow_dispatch");
+    }
+    if (!workflow.includes("FIREVAULT_SERVICE_ACCOUNT_JSON")) {
+        missing.push("FIREVAULT_SERVICE_ACCOUNT_JSON");
+    }
+    if (!workflow.includes("firevault snapshot")) {
+        missing.push("firevault snapshot");
+    }
+    if (missing.length === 0) {
+        addCheck(checks, "OK", "GitHub Actions workflow configured");
+        return;
+    }
+    addCheck(checks, "WARN", `GitHub Actions workflow incomplete: missing ${missing.join(", ")}`, "Review .firevault/.github/workflows/firevault-snapshot.yml or rerun `firevault setup-github-action --force`");
+}
+function isObviousSecretPath(filePath, serviceAccountPath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const basename = path.posix.basename(normalized);
+    return (normalized === serviceAccountPath ||
+        basename === "serviceAccountKey.json" ||
+        basename === "service-account.json" ||
+        basename === "firebase-service-account.json" ||
+        normalized === "credentials/firebase.json" ||
+        basename === ".env" ||
+        basename.startsWith(".env.") ||
+        basename.endsWith(".pem") ||
+        basename.endsWith(".key"));
+}
+function printChecks(checks) {
+    console.log("Firevault doctor");
+    console.log("");
+    for (const check of checks) {
+        console.log(`${check.severity.padEnd(5)} ${check.label}`);
+    }
+    const fixes = checks
+        .map((check) => check.fix)
+        .filter((fix) => Boolean(fix));
+    const uniqueFixes = [...new Set(fixes)];
+    if (uniqueFixes.length > 0) {
+        console.log("");
+        console.log("Next fixes:");
+        uniqueFixes.forEach((fix, index) => {
+            const [firstLine, ...rest] = fix.split("\n");
+            console.log(`${index + 1}. ${firstLine}`);
+            for (const line of rest) {
+                console.log(`   ${line}`);
+            }
+        });
+    }
+}
+export function runDoctor() {
+    const checks = [];
+    const workspaceRoot = findWorkspaceRoot() ?? findNearestWorkspaceDir();
+    if (!workspaceRoot) {
+        addCheck(checks, "FAIL", "Workspace not found", "Run `firevault init`");
+        addCheck(checks, "FAIL", "Config missing", "Run `firevault init`");
+        printChecks(checks);
+        process.exitCode = 2;
+        return;
+    }
+    addCheck(checks, "OK", "Workspace found");
+    const configPath = path.join(workspaceRoot, "config.json");
+    if (!existsSync(configPath)) {
+        addCheck(checks, "FAIL", "Config missing", "Run `firevault init` or create .firevault/config.json");
+        printChecks(checks);
+        process.exitCode = 2;
+        return;
+    }
+    let config;
+    try {
+        config = loadConfig();
+        addCheck(checks, "OK", "Config valid");
+    }
+    catch (error) {
+        const message = error instanceof ConfigError ? error.message : "Config invalid";
+        addCheck(checks, "FAIL", message, "Edit .firevault/config.json or rerun `firevault init --force`");
+        printChecks(checks);
+        process.exitCode = 2;
+        return;
+    }
+    const serviceAccountDisplayPath = displayPathFromApp(config.workspaceRoot, config.serviceAccountPathAbsolute);
+    if (!isInside(config.workspaceRoot, config.serviceAccountPathAbsolute)) {
+        addCheck(checks, "FAIL", "Service account path is outside .firevault", "Set serviceAccountPath to a path inside .firevault, such as ./serviceAccountKey.json");
+    }
+    else if (existsSync(config.serviceAccountPathAbsolute)) {
+        addCheck(checks, "OK", "Service account file present");
+    }
+    else {
+        addCheck(checks, "FAIL", "Service account file missing", `Save your Firebase service account JSON to:\n${serviceAccountDisplayPath}`);
+    }
+    if (!isInside(config.workspaceRoot, config.outputDirPath)) {
+        addCheck(checks, "FAIL", "Backup output path is outside .firevault", "Set outputDir to a path inside .firevault, such as firestore-backups");
+    }
+    else if (existsSync(config.outputDirPath)) {
+        addCheck(checks, "OK", "Backup output directory exists");
+    }
+    else {
+        addCheck(checks, "WARN", "Backup output directory has not been created yet", "Run `firevault snapshot`");
+    }
+    const workspaceIsGitRepo = isInsideGitRepository(config.workspaceRoot);
+    if (workspaceIsGitRepo) {
+        addCheck(checks, "OK", ".firevault Git repository found");
+    }
+    else {
+        addCheck(checks, "FAIL", ".firevault is not a Git repository", "git -C .firevault init");
+    }
+    if (workspaceIsGitRepo && getRemoteUrl("origin", config.workspaceRoot)) {
+        addCheck(checks, "OK", "Git remote origin configured");
+    }
+    else {
+        addCheck(checks, "WARN", "No Git remote origin configured", "git -C .firevault remote add origin <private-repo-url>");
+    }
+    workflowChecks(checks, config.workspaceRoot);
+    const serviceAccountIgnored = workspaceIsGitRepo
+        ? isPathIgnored(config.serviceAccountPath, config.workspaceRoot)
+        : undefined;
+    if (serviceAccountIgnored === true || gitignoreContains(config.workspaceRoot, config.serviceAccountPath)) {
+        addCheck(checks, "OK", "Service account file ignored");
+    }
+    else {
+        addCheck(checks, "FAIL", "Service account file is not ignored", `Add ${config.serviceAccountPath} to .firevault/.gitignore`);
+    }
+    const appRoot = path.dirname(config.workspaceRoot);
+    if (!isInsideGitRepository(appRoot)) {
+        addCheck(checks, "WARN", "Parent app directory is not a Git repository");
+    }
+    else if (isPathIgnored(".firevault", appRoot)) {
+        addCheck(checks, "OK", "Parent app repo ignores .firevault/");
+    }
+    else {
+        addCheck(checks, "FAIL", "Parent app repo does not ignore .firevault/", "Add .firevault/ to .gitignore");
+    }
+    if (workspaceIsGitRepo) {
+        const trackedFiles = getTrackedFiles(config.workspaceRoot) ?? [];
+        const trackedSecretFiles = trackedFiles.filter((filePath) => isObviousSecretPath(filePath, config.serviceAccountPath));
+        if (trackedSecretFiles.length === 0) {
+            addCheck(checks, "OK", "No obvious secret files tracked");
+        }
+        else {
+            addCheck(checks, "FAIL", `Possible secret files tracked: ${trackedSecretFiles.join(", ")}`, "Remove tracked secret files from Git history and rotate exposed credentials.");
+        }
+        if (isPathIgnored(config.outputDir, config.workspaceRoot) ||
+            gitignoreContains(config.workspaceRoot, config.outputDir)) {
+            addCheck(checks, "FAIL", "Backup directory is ignored", `Remove ${config.outputDir}/ from .firevault/.gitignore`);
+        }
+        else {
+            addCheck(checks, "OK", "Backup directory is trackable");
+        }
+        if (hasWorkingTreeChanges(config.workspaceRoot)) {
+            addCheck(checks, "WARN", "Working tree has uncommitted changes", "Review changes, then run `firevault commit` when appropriate");
+        }
+        else {
+            addCheck(checks, "OK", "Working tree clean");
+        }
+        if (hasChangesUnder(config.outputDir, config.workspaceRoot)) {
+            addCheck(checks, "WARN", "Backup output has uncommitted changes", "Run `firevault commit` after reviewing changes");
+        }
+    }
+    printChecks(checks);
+    if (checks.some((check) => check.severity === "FAIL")) {
+        process.exitCode = 2;
+        return;
+    }
+    if (checks.some((check) => check.severity === "WARN")) {
+        process.exitCode = 1;
+    }
+}
+export const doctorCommand = new Command("doctor")
+    .description("Validate local Firevault recovery setup")
+    .action(() => {
+    runDoctor();
+});

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;