firevault 0.1.1-beta.1 → 0.1.1-beta.2

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 - 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
 

package/README.md

@@ -49,6 +49,20 @@ 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
@@ -330,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

@@ -31,41 +31,61 @@ function parseCollections(value) {
         .split(",")
         .map((collection) => collection.trim());
 }
-async function promptForConfig(options) {
+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;
     }
-    const rl = createInterface({ input, output });
-    try {
-        const projectId = (await rl.question("Firebase project ID: ")).trim();
-        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),
-        };
-    }
-    finally {
-        rl.close();
-    }
+    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) {
+async function promptForGitInit(options, rl) {
     if (options.yes) {
         return true;
     }
-    const rl = createInterface({ input, output });
-    try {
-        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";
-    }
-    finally {
-        rl.close();
+    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";
@@ -89,39 +109,49 @@ export async function runInit(options) {
     console.log("");
     const configPath = "firevault.config.json";
     const alreadyInGitRepository = isInsideGitRepository();
-    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);
-    const config = await promptForConfig(options);
-    config.collections = config.collections.map((collection) => collection.trim());
-    validateConfig(config);
-    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");
+    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")

package/docs/architecture.md

@@ -94,10 +94,12 @@ 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 commits, pushes, creates GitHub repositories, contacts Firebase, or writes secrets.
+- never creates service accounts, opens browsers, runs `gcloud`, commits, pushes, creates GitHub repositories, contacts Firebase, or writes secrets.
 
 ## Firebase Access
 
@@ -109,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
@@ -132,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,6 +24,7 @@ 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firevault",
-  "version": "0.1.1-beta.1",
+  "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"
   }