firevault 0.1.1-beta.0 → 0.1.1-beta.2

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## 0.1.0 - Unreleased
+## 0.1.1-beta.1 - Unreleased
+
+- 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`.
+- Added safe `.gitignore` updates for service account keys, backup output, and emulator logs.
+- Ensured Firevault can still explicitly commit the configured backup directory even when it is ignored by default.
+- Added a guarded local npm prerelease publish workflow using `gitversionjs`, pack verification, and forbidden-path checks.
+
+## 0.1.0
 
 Initial prerelease candidate for Firevault, an undo button for Firestore.
 

package/README.md

@@ -41,7 +41,29 @@ npm install -g firevault
 
 Create a Firebase service account key for your Firestore project, save it as `serviceAccountKey.json`, and keep it out of Git.
 
-Create `firevault.config.json`:
+Run guided setup:
+
+```bash
+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`.
+
+After you enter a project ID, Firevault prints the direct Firebase Console URL for that project's Admin SDK service account page:
+
+```txt
+Create a Firebase service account key here:
+
+https://console.firebase.google.com/project/your-project-id/settings/serviceaccounts/adminsdk
+
+Download the JSON key and save it as:
+
+./serviceAccountKey.json
+```
+
+Firevault does not create service accounts, open a browser, run `gcloud`, or authenticate against Firebase during setup.
+
+Generated `firevault.config.json`:
 
 ```json
 {
@@ -176,6 +198,8 @@ serviceAccountKey.json
 firestore-backups/
 ```
 
+`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.
+
 ## Commands
 
 ```bash
@@ -191,6 +215,8 @@ firevault restore-local users/abc123 --from HEAD~3 --confirm
 firevault restore-firestore users/abc123 --from HEAD~3 --confirm
 ```
 
+`firevault init --yes` uses default values for non-interactive setup. `firevault init --force` allows setup with a dirty Git working tree and overwrites an existing config after warning.
+
 ## Local Development
 
 Install dependencies and run commands through the TypeScript entrypoint:
@@ -318,15 +344,36 @@ Covered emulator flows:
 
 ## Publishing
 
-Before publishing:
+Firevault uses a local publish script for early prereleases. npm auth must already be configured before publishing; `npm whoami` should succeed for the intended npm account.
+
+Calculate the Git-derived prerelease version:
+
+```bash
+npm run version:calculate
+```
+
+Verify the package without publishing:
+
+```bash
+npm run publish:dry-run
+```
+
+Publish the prerelease with the `next` dist-tag:
+
+```bash
+npm run publish:next
+```
+
+Use `npm run publish:next -- --yes` only when you intentionally want to skip the final confirmation prompt.
+
+The publish script:
 
-- run `npm run build`,
-- run `npm run test:emulator`,
-- run `npm pack --dry-run` and review the file list,
-- verify `dist/index.js` exists and starts with `#!/usr/bin/env node`,
-- do not publish `serviceAccountKey.json`,
-- do not publish local `firestore-backups/` output,
-- verify logs such as `firestore-debug.log` are not included.
+- requires a clean Git working tree before real publishing,
+- calculates the npm prerelease version with `gitversionjs`,
+- runs clean, build, and emulator tests,
+- runs `npm pack --dry-run --cache /private/tmp/firevault-npm-cache`,
+- rejects forbidden package contents such as `serviceAccountKey.json`, `firestore-backups/`, `firestore-debug.log`, `src/`, `test/`, `firebase.json`, `firestore.rules`, and `.env` files,
+- publishes with `npm publish --access public --tag next --cache /private/tmp/firevault-npm-cache`.
 
 The package `bin` points to `./dist/index.js`, so a published or linked package must include compiled output. `prepublishOnly` currently runs clean, build, and emulator tests.
 

package/dist/commands/init.js

@@ -1,19 +1,172 @@
 import { Command } from "commander";
-import { writeFileSync, existsSync } from "node:fs";
+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 { GitError, hasWorkingTreeChanges, initGitRepository, isInsideGitRepository, } from "../git/git.js";
 const defaultConfig = {
     projectId: "your-firebase-project-id",
     serviceAccountPath: "./serviceAccountKey.json",
     outputDir: "firestore-backups",
-    collections: [],
+    collections: ["users"],
 };
-export const initCommand = new Command("init")
-    .description("Create a firevault.config.json file")
-    .action(() => {
-    const configPath = "firevault.config.json";
-    if (existsSync(configPath)) {
-        console.log("firevault.config.json already exists.");
+function validateConfig(config) {
+    if (config.projectId.trim() === "") {
+        throw new Error("Firebase project ID is required.");
+    }
+    if (config.serviceAccountPath.trim() === "") {
+        throw new Error("Service account path is required.");
+    }
+    if (config.outputDir.trim() === "") {
+        throw new Error("Output directory is required.");
+    }
+    if (config.collections.length === 0) {
+        throw new Error("At least one collection is required.");
+    }
+    if (config.collections.some((collection) => collection.trim() === "")) {
+        throw new Error("Collection names must not be empty.");
+    }
+}
+function parseCollections(value) {
+    return value
+        .split(",")
+        .map((collection) => collection.trim());
+}
+function getServiceAccountUrl(projectId) {
+    return `https://console.firebase.google.com/project/${encodeURIComponent(projectId)}/settings/serviceaccounts/adminsdk`;
+}
+function printServiceAccountGuidance(projectId, serviceAccountPath) {
+    console.log("");
+    console.log("Create a Firebase service account key here:");
+    console.log("");
+    console.log(getServiceAccountUrl(projectId));
+    console.log("");
+    console.log("Download the JSON key and save it as:");
+    console.log("");
+    console.log(serviceAccountPath);
+    console.log("");
+}
+function printMissingServiceAccountInfo(serviceAccountPath) {
+    if (existsSync(serviceAccountPath)) {
+        return;
+    }
+    console.log(`Service account file does not exist yet: ${serviceAccountPath}`);
+    console.log("That is expected before downloading the Firebase Admin SDK key.");
+    console.log(`Save the downloaded JSON key at: ${serviceAccountPath}`);
+    console.log("");
+}
+async function promptForConfig(options, rl) {
+    if (options.yes) {
+        return defaultConfig;
+    }
+    if (!rl) {
+        throw new Error("Prompt interface is required for interactive init.");
+    }
+    const projectId = (await rl.question("Firebase project ID: ")).trim();
+    if (projectId !== "") {
+        printServiceAccountGuidance(projectId, defaultConfig.serviceAccountPath);
+    }
+    const serviceAccountPath = (await rl.question(`Service account path (${defaultConfig.serviceAccountPath}): `)).trim() || defaultConfig.serviceAccountPath;
+    const outputDir = (await rl.question(`Output directory (${defaultConfig.outputDir}): `)).trim() || defaultConfig.outputDir;
+    const collectionsInput = (await rl.question("Collections, comma-separated: ")).trim();
+    return {
+        projectId,
+        serviceAccountPath,
+        outputDir,
+        collections: parseCollections(collectionsInput),
+    };
+}
+async function promptForGitInit(options, rl) {
+    if (options.yes) {
+        return true;
+    }
+    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): "))
+        .trim()
+        .toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+}
+function ensureGitignoreEntries(entries) {
+    const gitignorePath = ".gitignore";
+    const existing = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, "utf-8")
+        : "";
+    const existingLines = new Set(existing
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== ""));
+    const missingEntries = entries.filter((entry) => !existingLines.has(entry));
+    if (missingEntries.length === 0) {
         return;
     }
-    writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
-    console.log("Created firevault.config.json");
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync(gitignorePath, `${prefix}${missingEntries.join("\n")}\n`);
+}
+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 rl = options.yes ? undefined : createInterface({ input, output });
+    try {
+        if (alreadyInGitRepository && hasWorkingTreeChanges() && !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.");
+        }
+        const shouldInitGit = alreadyInGitRepository
+            ? false
+            : await promptForGitInit(options, rl);
+        const config = await promptForConfig(options, rl);
+        config.collections = config.collections.map((collection) => collection.trim());
+        validateConfig(config);
+        if (options.yes) {
+            printServiceAccountGuidance(config.projectId, config.serviceAccountPath);
+        }
+        printMissingServiceAccountInfo(config.serviceAccountPath);
+        if (shouldInitGit) {
+            initGitRepository();
+            console.log("Initialized Git repository.");
+        }
+        if (existsSync(configPath) && options.force) {
+            console.log("Warning: overwriting existing firevault.config.json.");
+        }
+        writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        ensureGitignoreEntries([
+            "serviceAccountKey.json",
+            "firestore-backups/",
+            "firestore-debug.log",
+        ]);
+        console.log("Created firevault.config.json.");
+        console.log("Updated .gitignore safety entries.");
+        console.log("");
+        console.log("Next steps:");
+        console.log(`1. Save your service account key at ${config.serviceAccountPath}`);
+        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");
+    }
+    finally {
+        rl?.close();
+    }
+}
+export const initCommand = new Command("init")
+    .description("Create a guided Firevault configuration")
+    .option("--force", "Allow init with a dirty Git tree and overwrite existing config")
+    .option("--yes", "Use defaults and skip prompts")
+    .action(async (options) => {
+    try {
+        await runInit(options);
+    }
+    catch (error) {
+        if (error instanceof GitError || error instanceof Error) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
 });

package/dist/git/git.js

@@ -23,20 +23,27 @@ function runGit(args) {
         throw new GitError("Git command failed.");
     }
 }
-export function assertInsideGitRepository() {
-    let result;
+export function isInsideGitRepository() {
     try {
-        result = runGit(["rev-parse", "--is-inside-work-tree"]).trim();
+        return runGit(["rev-parse", "--is-inside-work-tree"]).trim() === "true";
     }
     catch {
-        throw new GitError("Current directory is not inside a Git repository.");
+        return false;
     }
-    if (result !== "true") {
+}
+export function assertInsideGitRepository() {
+    if (!isInsideGitRepository()) {
         throw new GitError("Current directory is not inside a Git repository.");
     }
 }
+export function initGitRepository() {
+    runGit(["init"]);
+}
+export function hasWorkingTreeChanges() {
+    return runGit(["status", "--porcelain"]).trim() !== "";
+}
 export function hasChangesUnder(path) {
-    return runGit(["status", "--porcelain", "--", path]).trim() !== "";
+    return runGit(["status", "--porcelain", "--ignored", "--", path]).trim() !== "";
 }
 function emptyFileChanges() {
     return {
@@ -148,7 +155,7 @@ export function showFileAtCommit(commit, path) {
     }
 }
 export function stagePath(path) {
-    runGit(["add", "--", path]);
+    runGit(["add", "-f", "--", path]);
 }
 export function commitPath(message, path) {
     runGit(["commit", "-m", message, "--", path]);

package/dist/index.js

@@ -12,7 +12,7 @@ import { restoreFirestoreCommand } from "./commands/restoreFirestore.js";
 const program = new Command();
 program
     .name("firevault")
-    .description("Git-native backup, diff, and recovery tooling for Firestore.")
+    .description("Undo button for Firestore.")
     .version("0.1.0");
 program.addCommand(initCommand);
 program.addCommand(backupCommand);

package/docs/architecture.md

@@ -81,7 +81,25 @@ Current implementation notes:
 
 - `loadConfig` reads and parses `firevault.config.json`.
 - Firebase initialization expects `serviceAccountPath`.
-- The current `init` template should be kept aligned with the expected config shape.
+- `firevault init` guides setup, validates required fields, checks Git state before writing, and updates `.gitignore` without overwriting existing entries.
+- `firevault init --force` allows dirty Git state and config overwrite with a warning.
+- `firevault init --yes` provides a non-interactive path for tests and automation.
+
+## Init Safety
+
+`firevault init` is intentionally conservative because setup writes local project files.
+
+Behavior:
+
+- prints the Firevault identity before prompting,
+- detects whether the current directory is inside a Git repository,
+- offers `git init` when no repository exists,
+- prints the Firebase Console Admin SDK service account URL for the entered project ID,
+- explains where to save the manually downloaded service account key,
+- 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 without duplicating existing lines,
+- never creates service accounts, opens browsers, runs `gcloud`, commits, pushes, creates GitHub repositories, contacts Firebase, or writes secrets.
 
 ## Firebase Access
 
@@ -93,7 +111,8 @@ Design constraints:
 
 - operate only on existing Firestore projects,
 - keep credentials local,
-- do not introduce hosted auth or account systems,
+- use manually managed service account credentials,
+- do not introduce credential brokerage, hosted auth, or account systems,
 - avoid committing service account files.
 
 ## Emulator Tests
@@ -116,6 +135,12 @@ Current emulator coverage:
 - collection path rejection,
 - `--confirm` enforcement.
 
+## Publishing
+
+Prerelease publishing is intentionally local-script based for now. `scripts/publish.ts` calculates an npm-safe prerelease version from Git state with `gitversionjs`, verifies a clean working tree for real publishes, runs clean/build/emulator tests, inspects `npm pack --dry-run` contents, rejects known unsafe paths, and publishes with the `next` npm dist-tag only after explicit confirmation.
+
+There is no GitHub Actions publishing, trusted publishing, or release automation beyond this local guard script yet.
+
 ## Export Pipeline
 
 Current backup flow:

package/docs/roadmap.md

@@ -24,7 +24,9 @@ Status:
 - Firestore emulator integration tests cover backup and document restore safety paths.
 - CLI packaging runs from compiled `dist/index.js`.
 - 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, and applies `.gitignore` safety entries.
 
 Next work:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firevault",
-  "version": "0.1.1-beta.0",
+  "version": "0.1.1-beta.2",
   "description": "Undo button for Firestore. Git-style history, rollback, and recovery for Firestore projects.",
   "keywords": [
     "firebase",
@@ -33,6 +33,9 @@
     "clean": "rm -rf dist",
     "build": "tsc && chmod +x dist/index.js",
     "prepublishOnly": "npm run clean && npm run build && npm run test:emulator",
+    "version:calculate": "tsx scripts/publish.ts --version-only",
+    "publish:dry-run": "tsx scripts/publish.ts --dry-run --allow-dirty",
+    "publish:next": "tsx scripts/publish.ts",
     "test:emulator": "tsx test/integration/run-firestore-emulator.ts",
     "backup": "tsx src/index.ts backup",
     "commit": "tsx src/index.ts commit",
@@ -51,6 +54,7 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "firebase-tools": "^15.18.0",
+    "gitversionjs": "^1.0.15",
     "tsx": "^4.20.0",
     "typescript": "^5.8.0"
   }