firevault 0.1.1-beta.0

package/docs/architecture.md

@@ -0,0 +1,182 @@
+# Architecture
+
+Firevault is an undo button for Firestore: operational recovery tooling that gives Firestore projects Git-style history, change inspection, and document-level rollback.
+
+## Positioning
+
+Firevault wraps existing Firestore projects. It does not replace Firebase and does not host data.
+
+The architecture should optimize for:
+
+- safe restores,
+- readable recovery previews,
+- document-level rollback,
+- deterministic exports,
+- Git-backed history,
+- disaster recovery workflows,
+- simple local operation.
+
+## Current Stack
+
+- TypeScript
+- Node.js
+- Firebase Admin SDK
+- Commander
+- tsx for development execution
+
+## 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
+```
+
+## Command Layer
+
+`src/index.ts` creates the Commander program and registers commands.
+
+Current commands:
+
+- `firevault init`
+- `firevault backup`
+
+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`.
+
+Intended shape:
+
+```json
+{
+  "projectId": "your-project-id",
+  "serviceAccountPath": "./serviceAccountKey.json",
+  "outputDir": "firestore-backups",
+  "collections": ["users"]
+}
+```
+
+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.
+
+## Firebase Access
+
+`src/firestore/firebase.ts` initializes Firebase Admin SDK from the configured service account path and returns a Firestore client.
+
+When `FIRESTORE_EMULATOR_HOST` is set, Firebase Admin initializes with only the configured `projectId`. This lets integration tests run against the local Firestore emulator without a service account file and without contacting real Firebase.
+
+Design constraints:
+
+- operate only on existing Firestore projects,
+- keep credentials local,
+- do not introduce hosted auth or account systems,
+- avoid committing service account files.
+
+## Emulator Tests
+
+Firestore emulator integration tests live under `test/integration/`.
+
+The test command:
+
+```bash
+npm run test:emulator
+```
+
+starts the Firestore emulator through `firebase-tools`, runs Node's built-in test runner through `tsx`, and uses temporary Git repositories and backup directories for each test. The tests seed emulator Firestore directly, drive the Firevault CLI, and clean up temporary directories where practical.
+
+Current emulator coverage:
+
+- backup export from emulator Firestore,
+- deterministic JSON output,
+- single-document `restore-firestore` overwrite into emulator Firestore,
+- collection path rejection,
+- `--confirm` enforcement.
+
+## Export Pipeline
+
+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`.
+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.
+
+## Deterministic Serialization
+
+`src/firestore/stableStringify.ts` recursively sorts object keys and writes pretty JSON.
+
+This is foundational because Git is the history engine. Output should be stable when Firestore data has not changed.
+
+Serialization rules should remain boring and predictable:
+
+- sort object keys,
+- preserve array order,
+- write one document per file,
+- avoid transient metadata unless explicitly modeled.
+
+## Git Boundary
+
+Git is the storage and history engine. Firevault should wrap Git workflows rather than reimplement versioning.
+
+Near-term Git integration should focus on:
+
+- detecting working tree changes after backup,
+- showing changed documents,
+- helping users inspect diffs,
+- optionally guiding commit workflows without committing automatically.
+
+AI agents and Firevault itself must not create commits automatically unless a human explicitly performs that step outside the agent workflow.
+
+## Restore Boundary
+
+Restore is safety-critical and should be introduced incrementally.
+
+Initial restore scope:
+
+- document-level only,
+- dry-run by default,
+- explicit confirmation required for writes,
+- clear source revision and target document path,
+- readable diff before applying changes.
+
+Avoid early whole-database restore commands.
+
+## Non-Goals
+
+Do not introduce these before the core workflow is stable:
+
+- SaaS platform,
+- hosted infrastructure,
+- web dashboard,
+- billing,
+- auth system,
+- collaboration features,
+- Firebase Extensions,
+- generic multi-cloud backup abstractions.

package/docs/github-labels.md

@@ -0,0 +1,18 @@
+# GitHub Labels
+
+Recommended labels for the public repository:
+
+| Label | Purpose |
+| --- | --- |
+| `bug` | Incorrect behavior or regression |
+| `enhancement` | Focused workflow improvement |
+| `documentation` | README, docs, examples, or release notes |
+| `safety` | Restore safety, confirmation, or destructive-action concerns |
+| `firestore` | Firestore Admin SDK, emulator, or data model behavior |
+| `git` | Git history, commit, status, or path behavior |
+| `testing` | Unit, emulator, or verification work |
+| `packaging` | npm, build, release, and install behavior |
+| `question` | Usage questions that are not bugs |
+| `good first issue` | Small, well-scoped starter tasks |
+
+Keep labels operational and workflow-focused. Avoid broad platform labels until the project scope expands.

package/docs/roadmap.md

@@ -0,0 +1,138 @@
+# Roadmap
+
+Firevault is currently in Foundation / Phase 0. The roadmap is intentionally incremental: make the undo button for Firestore trustworthy before adding broader recovery workflows.
+
+## Foundation
+
+Goal: provide a safe document-level recovery loop backed by deterministic local snapshots and Git history.
+
+Status:
+
+- TypeScript CLI scaffold exists.
+- Commander command wiring exists.
+- Config loading exists.
+- Firebase Admin initialization exists.
+- Stable JSON serializer exists.
+- Backup command exports configured collections.
+- Documents are written one file per document.
+- Local Git snapshot workflow exists through separate `backup`, `commit`, and `snapshot` commands.
+- File-level change inspection exists through `changes` and `changes --last <window>`.
+- Document and collection history inspection exists through `history <path>`.
+- Dry-run recovery inspection exists through `restore-preview <path> --from <commit>`.
+- Local backup-file recovery exists through `restore-local <path> --from <commit> --confirm`.
+- Single-document Firestore overwrite restore exists through `restore-firestore <path> --from <commit> --confirm`.
+- 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.
+- Public GitHub release docs cover quick start, security, contributing, and issue triage.
+
+Next work:
+
+- Decide how to represent Firestore special value types.
+- Decide how to handle subcollections.
+- Add broader error handling around Firestore export failures.
+- Add non-emulator unit tests for pure path and Git parsing helpers.
+- Review first npm prerelease feedback before widening restore scope.
+- Dogfood against real non-critical Firestore projects before expanding restore behavior.
+
+## MVP
+
+Goal: make Git-style history, inspection, and rollback useful for real Firestore recovery work.
+
+Expected capabilities:
+
+- `firevault backup` reliably exports configured collections.
+- Clear output summary after backup.
+- Local Git snapshot command for backup plus scoped commit.
+- Git status integration showing changed, added, and deleted backup files.
+- History helpers for document and collection paths.
+- Restore preview helpers for document paths.
+- Local document restore into backup files only.
+- Firestore document restore with explicit confirmation.
+- Diff helpers for document paths.
+- Document path addressing such as `users/abc123`.
+- Basic change inspection workflows.
+- Documentation for a safe backup cadence.
+
+Example commands:
+
+```bash
+firevault backup
+firevault commit
+firevault snapshot
+firevault history users/abc123
+firevault restore-preview users/abc123 --from HEAD~3
+firevault restore-local users/abc123 --from HEAD~3 --confirm
+firevault restore-firestore users/abc123 --from HEAD~3 --confirm
+firevault diff users/abc123
+firevault changes
+```
+
+## Semi-Production
+
+Goal: introduce safe document-level recovery without broad destructive operations.
+
+Expected capabilities:
+
+- Safer document-level restore from a Git revision.
+- Dry-run preview before destructive restore.
+- Required confirmation for writes.
+- Diff preview before restore.
+- Better Firestore type handling.
+- Clear failure modes and exit codes.
+- Tests for restore safety behavior.
+- Guidance for CI or scheduled backup jobs.
+
+Example command:
+
+```bash
+firevault restore users/abc123 --from HEAD~3
+```
+
+## Production
+
+Goal: make Firevault dependable for teams that need disaster recovery workflows.
+
+Expected capabilities:
+
+- Robust recursive export design if subcollections are supported.
+- Delete detection and explicit delete handling.
+- Restore audit output.
+- Backup validation command.
+- Safer configuration validation.
+- Larger collection handling with pagination and progress.
+- Better handling of rate limits and transient Firebase failures.
+- Release packaging and installation story.
+- Security guidance for credentials and least-privilege service accounts.
+
+## Polished
+
+Goal: refine the CLI experience after the core workflows are proven.
+
+Possible capabilities:
+
+- Better command UX and help text.
+- Human-readable change summaries.
+- Time-window helpers such as `firevault changes --last 24h`.
+- Guided Git workflow prompts that still leave commits to humans.
+- Optional machine-readable output for automation.
+- Richer docs and recovery playbooks.
+- AI-assisted development recovery positioning once the operational core is stable.
+
+## Guardrails
+
+Do not build these during early phases:
+
+- SaaS,
+- web UI,
+- hosted infrastructure,
+- billing,
+- auth systems,
+- collaboration features,
+- generalized multi-cloud backup platform.
+
+The core workflow must remain:
+
+```txt
+Firestore -> stable JSON files -> Git history -> safe diff/restore workflows
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "firevault",
+  "version": "0.1.1-beta.0",
+  "description": "Undo button for Firestore. Git-style history, rollback, and recovery for Firestore projects.",
+  "keywords": [
+    "firebase",
+    "firestore",
+    "backup",
+    "restore",
+    "git",
+    "cli",
+    "disaster-recovery"
+  ],
+  "author": "henskjold73",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/henskjold73/firevault.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "firevault": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist",
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run clean && npm run build && npm run test:emulator",
+    "test:emulator": "tsx test/integration/run-firestore-emulator.ts",
+    "backup": "tsx src/index.ts backup",
+    "commit": "tsx src/index.ts commit",
+    "changes": "tsx src/index.ts changes",
+    "history": "tsx src/index.ts history",
+    "restore-preview": "tsx src/index.ts restore-preview",
+    "restore-local": "tsx src/index.ts restore-local",
+    "restore-firestore": "tsx src/index.ts restore-firestore",
+    "snapshot": "tsx src/index.ts snapshot",
+    "init": "tsx src/index.ts init"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "firebase-admin": "^13.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "firebase-tools": "^15.18.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0"
+  }
+}