firevault 0.2.0-beta.0 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Changelog
 
-## 0.2.0-beta.0 - 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.
 

package/README.md

@@ -233,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
@@ -303,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/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/setupGithubAction.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { ConfigError, loadConfig } from "../config/loadConfig.js";
+const workflowRelativePath = ".github/workflows/firevault-snapshot.yml";
+const secretName = "FIREVAULT_SERVICE_ACCOUNT_JSON";
+function normalizeWorkflowPath(configPath) {
+    const normalized = configPath.replaceAll("\\", "/").replace(/^\.\//, "");
+    if (normalized === "" ||
+        normalized.startsWith("/") ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../")) {
+        throw new ConfigError("Cannot generate GitHub Actions workflow: serviceAccountPath must stay inside .firevault.");
+    }
+    return normalized;
+}
+function workflowYaml(serviceAccountPath) {
+    const actionServiceAccountPath = `.firevault/${serviceAccountPath}`;
+    return `name: Firevault snapshot
+
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  snapshot:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out recovery repository
+        uses: actions/checkout@v4
+        with:
+          path: .firevault
+          fetch-depth: 0
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Firevault
+        run: npm install -g firevault@next
+
+      - name: Write Firebase service account
+        env:
+          ${secretName}: \${{ secrets.${secretName} }}
+        run: |
+          mkdir -p "$(dirname "${actionServiceAccountPath}")"
+          printf '%s' "$${secretName}" > "${actionServiceAccountPath}"
+
+      - name: Configure Git author
+        working-directory: .firevault
+        run: |
+          git config user.name "firevault"
+          git config user.email "firevault@users.noreply.github.com"
+
+      - name: Run snapshot
+        run: firevault snapshot
+
+      - name: Push backup commit
+        working-directory: .firevault
+        run: |
+          branch="$(git rev-parse --abbrev-ref HEAD)"
+
+          if git rev-parse --verify "origin/$branch" >/dev/null 2>&1; then
+            commits_to_push="$(git rev-list --count "origin/$branch..HEAD")"
+
+            if [ "$commits_to_push" = "0" ]; then
+              echo "No new backup commit to push."
+              exit 0
+            fi
+          fi
+
+          git push origin "HEAD:$branch"
+
+      - name: Remove service account file
+        if: always()
+        run: rm -f "${actionServiceAccountPath}"
+`;
+}
+export function runSetupGithubAction(options) {
+    const config = loadConfig();
+    const serviceAccountPath = normalizeWorkflowPath(config.serviceAccountPath);
+    const workflowPath = path.join(config.workspaceRoot, workflowRelativePath);
+    if (existsSync(workflowPath) && !options.force) {
+        throw new ConfigError(`${path.join(".firevault", workflowRelativePath)} already exists. Rerun with --force to overwrite it.`);
+    }
+    mkdirSync(path.dirname(workflowPath), { recursive: true });
+    writeFileSync(workflowPath, workflowYaml(serviceAccountPath));
+    console.log("Created:");
+    console.log(path.join(".firevault", workflowRelativePath));
+    console.log("");
+    console.log("Next steps:");
+    console.log("1. Push the .firevault repo to GitHub");
+    console.log("2. Create GitHub secret:");
+    console.log(`   ${secretName}`);
+    console.log("3. Add your Firebase service account JSON as the secret value");
+    console.log("4. Review and commit the workflow file yourself");
+    console.log("5. Run the workflow manually once before relying on the schedule");
+}
+export const setupGithubActionCommand = new Command("setup-github-action")
+    .description("Create a local GitHub Actions workflow for scheduled Firevault snapshots")
+    .option("--force", "Overwrite an existing Firevault snapshot workflow")
+    .action((options) => {
+    try {
+        runSetupGithubAction(options);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});

package/dist/commands/status.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { ConfigError, findWorkspaceRoot, loadConfig } from "../config/loadConfig.js";
+import { getAheadBehind, getCurrentBranch, getLatestCommitDate, getRemoteUrl, hasChangesUnder, hasWorkingTreeChanges, isInsideGitRepository, } from "../git/git.js";
+function relativeDisplayPath(targetPath) {
+    const relativePath = path.relative(process.cwd(), targetPath);
+    if (relativePath === "") {
+        return ".";
+    }
+    return relativePath.startsWith("..") ? targetPath : relativePath || ".";
+}
+function workflowStatus(workspaceRoot) {
+    const workflowPath = path.join(workspaceRoot, ".github", "workflows", "firevault-snapshot.yml");
+    if (!existsSync(workflowPath)) {
+        return "not configured";
+    }
+    try {
+        const workflow = readFileSync(workflowPath, "utf-8");
+        if (workflow.includes("schedule:") && workflow.includes("cron:")) {
+            return "configured";
+        }
+        return "present, schedule missing";
+    }
+    catch {
+        return "present, unreadable";
+    }
+}
+function printMissingWorkspace() {
+    console.log("Firevault status");
+    console.log("");
+    console.log("Workspace:");
+    console.log("  Path: not found");
+    console.log("  Config: missing");
+    console.log("");
+    console.log("Next step:");
+    console.log("  Run `firevault init`");
+    process.exitCode = 1;
+}
+function formatRemoteSync(sync) {
+    if (!sync) {
+        return "unknown";
+    }
+    return `ahead ${sync.ahead}, behind ${sync.behind}`;
+}
+export function runStatus() {
+    const workspaceRoot = findWorkspaceRoot();
+    if (!workspaceRoot) {
+        printMissingWorkspace();
+        return;
+    }
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.log("Firevault status");
+            console.log("");
+            console.log("Workspace:");
+            console.log(`  Path: ${relativeDisplayPath(workspaceRoot)}`);
+            console.log("  Config: invalid");
+            console.log("");
+            console.log(`Error: ${error.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+    const gitRepositoryExists = isInsideGitRepository(config.workspaceRoot);
+    const outputDirExists = existsSync(config.outputDirPath);
+    const workingTreeDirty = gitRepositoryExists
+        ? hasWorkingTreeChanges(config.workspaceRoot)
+        : undefined;
+    const backupChanges = gitRepositoryExists
+        ? hasChangesUnder(config.outputDir, config.workspaceRoot)
+        : undefined;
+    const latestSnapshot = gitRepositoryExists
+        ? getLatestCommitDate(config.outputDir, config.workspaceRoot)
+        : undefined;
+    const branch = gitRepositoryExists
+        ? getCurrentBranch(config.workspaceRoot)
+        : undefined;
+    const remoteOrigin = gitRepositoryExists
+        ? getRemoteUrl("origin", config.workspaceRoot)
+        : undefined;
+    const remoteSync = gitRepositoryExists && remoteOrigin
+        ? getAheadBehind(config.workspaceRoot)
+        : undefined;
+    console.log("Firevault status");
+    console.log("");
+    console.log("Workspace:");
+    console.log(`  Path: ${relativeDisplayPath(config.workspaceRoot)}`);
+    console.log("  Config: OK");
+    console.log("");
+    console.log("Firestore:");
+    console.log(`  Project: ${config.projectId}`);
+    console.log(`  Collections configured: ${config.collections.length}`);
+    console.log("");
+    console.log("Backups:");
+    console.log(`  Output directory: ${config.outputDir}`);
+    console.log(`  Output exists: ${outputDirExists ? "yes" : "no"}`);
+    console.log(`  Last snapshot: ${latestSnapshot ?? "none"}`);
+    console.log(`  Uncommitted backup changes: ${backupChanges === undefined ? "unknown" : backupChanges ? "yes" : "none"}`);
+    console.log("");
+    console.log("Git:");
+    console.log(`  Repository: ${gitRepositoryExists ? "OK" : "missing"}`);
+    if (gitRepositoryExists) {
+        console.log(`  Branch: ${branch ?? "unknown"}`);
+        console.log(`  Working tree: ${workingTreeDirty ? "dirty" : "clean"}`);
+        console.log(`  Remote origin: ${remoteOrigin ? "configured" : "not configured"}`);
+        if (remoteOrigin) {
+            console.log(`  Remote sync: ${formatRemoteSync(remoteSync)}`);
+        }
+    }
+    console.log("");
+    console.log("Automation:");
+    console.log(`  GitHub Actions workflow: ${workflowStatus(config.workspaceRoot)}`);
+}
+export const statusCommand = new Command("status")
+    .description("Show local Firevault recovery health")
+    .action(() => {
+    runStatus();
+});

package/dist/git/git.js

@@ -24,6 +24,14 @@ function runGit(args, cwd = process.cwd()) {
         throw new GitError("Git command failed.");
     }
 }
+function tryRunGit(args, cwd = process.cwd()) {
+    try {
+        return runGit(args, cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function isInsideGitRepository(cwd = process.cwd()) {
     try {
         return runGit(["rev-parse", "--is-inside-work-tree"], cwd).trim() === "true";
@@ -46,6 +54,63 @@ export function hasWorkingTreeChanges(cwd = process.cwd()) {
 export function hasChangesUnder(path, cwd = process.cwd()) {
     return runGit(["status", "--porcelain", "--ignored", "--", path], cwd).trim() !== "";
 }
+export function getCurrentBranch(cwd = process.cwd()) {
+    const branch = tryRunGit(["branch", "--show-current"], cwd)?.trim();
+    if (branch) {
+        return branch;
+    }
+    const shortSha = tryRunGit(["rev-parse", "--short", "HEAD"], cwd)?.trim();
+    return shortSha ? `detached at ${shortSha}` : undefined;
+}
+export function getRemoteUrl(name, cwd = process.cwd()) {
+    return tryRunGit(["config", "--get", `remote.${name}.url`], cwd)?.trim() || undefined;
+}
+export function isPathIgnored(path, cwd = process.cwd()) {
+    const output = tryRunGit(["check-ignore", "--quiet", "--", path], cwd);
+    if (output !== undefined) {
+        return true;
+    }
+    try {
+        runGit(["check-ignore", "--quiet", "--", path], cwd);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof GitError) {
+            return false;
+        }
+        return undefined;
+    }
+}
+export function getTrackedFiles(cwd = process.cwd()) {
+    const output = tryRunGit(["ls-files"], cwd);
+    if (output === undefined) {
+        return undefined;
+    }
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+}
+export function getLatestCommitDate(path, cwd = process.cwd()) {
+    return tryRunGit(["log", "-1", "--format=%cI", "--", path], cwd)?.trim() || undefined;
+}
+export function getAheadBehind(cwd = process.cwd()) {
+    const upstream = tryRunGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], cwd)
+        ?.trim();
+    if (!upstream) {
+        return undefined;
+    }
+    const output = tryRunGit(["rev-list", "--left-right", "--count", "HEAD...@{u}"], cwd)
+        ?.trim();
+    if (!output) {
+        return undefined;
+    }
+    const [ahead, behind] = output.split(/\s+/).map((value) => Number(value));
+    if (!Number.isFinite(ahead) || !Number.isFinite(behind)) {
+        return undefined;
+    }
+    return { ahead, behind };
+}
 function emptyFileChanges() {
     return {
         added: [],

package/dist/index.js

@@ -6,6 +6,9 @@ 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 { statusCommand } from "./commands/status.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { setupGithubActionCommand } from "./commands/setupGithubAction.js";
 import { restorePreviewCommand } from "./commands/restorePreview.js";
 import { restoreLocalCommand } from "./commands/restoreLocal.js";
 import { restoreFirestoreCommand } from "./commands/restoreFirestore.js";
@@ -20,6 +23,9 @@ program.addCommand(commitCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(changesCommand);
 program.addCommand(historyCommand);
+program.addCommand(statusCommand);
+program.addCommand(doctorCommand);
+program.addCommand(setupGithubActionCommand);
 program.addCommand(restorePreviewCommand);
 program.addCommand(restoreLocalCommand);
 program.addCommand(restoreFirestoreCommand);

package/docs/architecture.md

@@ -134,6 +134,14 @@ Operational commands work from the app root or from inside `.firevault/` by disc
 
 `firestore-backups/` is not ignored inside `.firevault/` by default. The `.firevault` repository exists to commit backup data.
 
+## GitHub Actions Automation
+
+`firevault setup-github-action` is a local workflow-file generator for scheduled offsite snapshots. It writes `.firevault/.github/workflows/firevault-snapshot.yml` and stops there.
+
+The command does not create GitHub repositories, call GitHub APIs, create secrets, push, stage, commit, store credentials, or depend on the GitHub CLI. Users push the `.firevault` repository and create the `FIREVAULT_SERVICE_ACCOUNT_JSON` secret themselves.
+
+The generated workflow checks out the recovery repository into a `.firevault` directory, installs `firevault@next`, writes the service account JSON from the GitHub secret to `.firevault/serviceAccountKey.json`, runs `firevault snapshot` from the parent workspace, and pushes only if a backup commit was created.
+
 ## Emulator Tests
 
 Firestore emulator integration tests live under `test/integration/`.