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

package/docs/doctor-design.md

@@ -0,0 +1,418 @@
+# firevault doctor Design
+
+`firevault doctor` should answer:
+
+> Is my Firevault setup correctly configured?
+
+This is different from `firevault status`.
+
+- `status` is the current operational state: compact, confidence-oriented, and useful for quick checks.
+- `doctor` is validation: more detailed, actionable, and focused on fixes.
+
+## Scope
+
+First version: local validation only.
+
+Doctor must not:
+
+- contact Firebase,
+- call GitHub APIs,
+- use the network,
+- write files,
+- stage,
+- commit,
+- push,
+- print secrets.
+
+## Output Shape
+
+Output should be grouped but still compact:
+
+```txt
+Firevault doctor
+
+OK    Workspace found
+OK    Config valid
+WARN  No Git remote origin configured
+FAIL  Service account file missing
+
+Next fixes:
+1. Save your Firebase service account JSON to .firevault/serviceAccountKey.json
+2. Add Git remote:
+   git -C .firevault remote add origin <private-repo-url>
+```
+
+Use clear severity:
+
+- `OK`: check passed.
+- `WARN`: setup can work locally but recovery posture is weaker.
+- `FAIL`: setup is incomplete or unsafe enough that normal recovery workflows may fail.
+
+Exit codes:
+
+- `0` if all checks are `OK`.
+- `1` if warnings are present and no checks fail.
+- `2` if any `FAIL`.
+
+## Checks
+
+### Workspace
+
+Checks:
+
+- `.firevault/config.json` can be discovered from the current directory.
+
+Result:
+
+- `OK Workspace found`
+- `FAIL Workspace not found`
+
+Fix:
+
+```txt
+Run `firevault init`
+```
+
+### Config
+
+Checks:
+
+- config file exists,
+- JSON parses,
+- required fields are present:
+  - `projectId`,
+  - `serviceAccountPath`,
+  - `outputDir`,
+  - `collections`,
+- `collections` is a non-empty string array.
+
+Reuse `loadConfig()` for validation.
+
+Result:
+
+- `OK Config valid`
+- `FAIL Config invalid`
+
+Fix:
+
+```txt
+Edit .firevault/config.json or rerun `firevault init --force`
+```
+
+### Service Account File
+
+Checks:
+
+- configured `serviceAccountPath` resolves inside `.firevault`,
+- file exists.
+
+Do not parse the service account JSON in the first version. Parsing is local, but it starts pulling doctor toward credential validation. Save that for a later `--verify` mode.
+
+Result:
+
+- `OK Service account file present`
+- `FAIL Service account file missing`
+
+Fix:
+
+```txt
+Save your Firebase service account JSON to .firevault/serviceAccountKey.json
+```
+
+Use the actual configured relative path in output. Never print file contents.
+
+### Backup Output Directory
+
+Checks:
+
+- configured output directory exists, or
+- parent workspace exists and the path could be created by normal backup flow.
+
+Because doctor is read-only, it should not create the directory.
+
+Result:
+
+- `OK Backup output directory exists`
+- `WARN Backup output directory has not been created yet`
+- `FAIL Backup output path is unsafe or outside .firevault`
+
+Fix:
+
+```txt
+Run `firevault snapshot`
+```
+
+### Workspace Git Repository
+
+Checks:
+
+- `.firevault` is a Git repository.
+
+Result:
+
+- `OK .firevault Git repository found`
+- `FAIL .firevault is not a Git repository`
+
+Fix:
+
+```txt
+git -C .firevault init
+```
+
+### Remote Origin
+
+Checks:
+
+- `.firevault` has `origin` configured.
+
+Do not call `git fetch`.
+
+Result:
+
+- `OK Git remote origin configured`
+- `WARN No Git remote origin configured`
+
+Fix:
+
+```txt
+git -C .firevault remote add origin <private-repo-url>
+```
+
+### GitHub Actions Workflow
+
+Checks:
+
+- `.firevault/.github/workflows/firevault-snapshot.yml` exists,
+- contains `schedule:`,
+- contains `workflow_dispatch:`,
+- contains `FIREVAULT_SERVICE_ACCOUNT_JSON`,
+- contains `firevault snapshot`.
+
+This should remain text-based in the first version. A YAML parser is not required yet unless false positives become a problem.
+
+Result:
+
+- `OK GitHub Actions workflow configured`
+- `WARN GitHub Actions workflow missing`
+- `WARN GitHub Actions workflow missing schedule trigger`
+- `WARN GitHub Actions workflow missing manual dispatch`
+- `WARN GitHub Actions workflow missing FIREVAULT_SERVICE_ACCOUNT_JSON`
+- `WARN GitHub Actions workflow missing firevault snapshot`
+
+Fix:
+
+```txt
+Run `firevault setup-github-action`
+```
+
+If the file exists but is incomplete:
+
+```txt
+Review .firevault/.github/workflows/firevault-snapshot.yml or rerun `firevault setup-github-action --force`
+```
+
+### Service Account Ignored
+
+Checks:
+
+- `.firevault/.gitignore` exists,
+- configured service account path is ignored by Git.
+
+Best check:
+
+```bash
+git -C .firevault check-ignore <serviceAccountPath>
+```
+
+Fallback:
+
+- read `.firevault/.gitignore`,
+- look for exact configured service account path or basename.
+
+Result:
+
+- `OK Service account file ignored`
+- `FAIL Service account file is not ignored`
+
+Fix:
+
+```txt
+Add serviceAccountKey.json to .firevault/.gitignore
+```
+
+Use configured path in output.
+
+### Parent App Repo Ignores .firevault
+
+Checks:
+
+- parent app repo exists,
+- parent app repo ignores `.firevault/`.
+
+Best check:
+
+```bash
+git -C <app-root> check-ignore .firevault
+```
+
+If parent app is not a Git repo, this can be a warning rather than failure.
+
+Result:
+
+- `OK Parent app repo ignores .firevault/`
+- `WARN Parent app directory is not a Git repository`
+- `FAIL Parent app repo does not ignore .firevault/`
+
+Fix:
+
+```txt
+Add .firevault/ to .gitignore
+```
+
+### Secret Files Tracked By Git
+
+Checks:
+
+- no obvious credential or environment files are tracked in `.firevault` Git.
+
+Candidate tracked paths:
+
+- configured `serviceAccountPath`,
+- `serviceAccountKey.json`,
+- `service-account.json`,
+- `firebase-service-account.json`,
+- `credentials/firebase.json`,
+- `.env`,
+- `.env.*`,
+- `*.pem`,
+- `*.key`.
+
+Use local Git only:
+
+```bash
+git -C .firevault ls-files
+```
+
+Result:
+
+- `OK No obvious secret files tracked`
+- `FAIL Possible secret files tracked`
+
+Fix:
+
+```txt
+Remove tracked secret files from Git history and rotate exposed credentials.
+```
+
+Be careful not to print secret contents. Printing suspicious file paths is acceptable.
+
+### Backup Directory Not Ignored
+
+Checks:
+
+- configured backup output directory is not ignored inside `.firevault`.
+
+Use:
+
+```bash
+git -C .firevault check-ignore <outputDir>
+```
+
+Result:
+
+- `OK Backup directory is trackable`
+- `FAIL Backup directory is ignored`
+
+Fix:
+
+```txt
+Remove firestore-backups/ from .firevault/.gitignore
+```
+
+Use configured path in output.
+
+### Working Tree State
+
+Checks:
+
+- `.firevault` working tree clean or dirty,
+- uncommitted backup changes under `outputDir`.
+
+Result:
+
+- `OK Working tree clean`
+- `WARN Working tree has uncommitted changes`
+- `WARN Backup output has uncommitted changes`
+
+Fix:
+
+```txt
+Run `firevault commit` after reviewing changes
+```
+
+Doctor should report dirty state clearly but not treat it as a failure.
+
+## Suggested Implementation Shape
+
+Likely files:
+
+- `src/commands/doctor.ts`
+- `src/index.ts`
+- `src/git/git.ts`
+- `package.json`
+- `README.md`
+- `docs/roadmap.md`
+- `docs/doctor-design.md`
+
+Useful shared types:
+
+```ts
+type DoctorSeverity = "OK" | "WARN" | "FAIL";
+
+interface DoctorCheck {
+  severity: DoctorSeverity;
+  label: string;
+  fix?: string;
+}
+```
+
+Formatting should be intentionally simple:
+
+```txt
+OK    Config valid
+WARN  No Git remote origin configured
+FAIL  Service account file missing
+```
+
+## Relationship To status
+
+`status` should stay compact and operational.
+
+`doctor` can be more explicit:
+
+- reports all setup issues,
+- lists fixes,
+- may have more checks,
+- can return non-zero when failures exist.
+
+`status` should not grow into doctor.
+
+## Future Extensions
+
+Later versions can add:
+
+- `firevault doctor --verify`
+  - parse service account JSON,
+  - connect to Firestore,
+  - verify configured collections exist,
+  - verify read permissions,
+  - never write to Firestore.
+- GitHub API-backed checks:
+  - repository visibility,
+  - Actions enabled,
+  - secret exists,
+  - latest workflow run status.
+- structured output:
+  - `firevault doctor --json`.
+
+These should not be part of the first doctor implementation.

package/docs/github-actions-design.md

@@ -0,0 +1,317 @@
+# GitHub Actions Automation Design
+
+Firevault should help users create scheduled offsite Firestore snapshots using GitHub Actions.
+
+This is Phase 2 automation awareness and setup. It should stay local and explicit.
+
+## Goal
+
+Enable this model:
+
+```txt
+my-app/
+  .firevault/
+    config.json
+    firestore-backups/
+    .git/
+    .github/workflows/firevault-snapshot.yml
+```
+
+The `.firevault` workspace is its own Git repository. Users push that repository to a private GitHub repository for offsite recovery history.
+
+The workflow should:
+
+1. Run on a schedule.
+2. Install Node.
+3. Install Firevault.
+4. Write service account JSON from a GitHub secret.
+5. Run `firevault snapshot`.
+6. Push a commit only if backup files changed.
+
+## Command Name
+
+Recommended command:
+
+```bash
+firevault setup-github-action
+```
+
+Reasoning:
+
+- explicit that this is GitHub-specific,
+- clear that it creates a GitHub Actions workflow,
+- avoids implying broader automation support,
+- leaves room for future commands like `setup-gitlab-ci` without hiding provider-specific behavior.
+
+`firevault setup-action` is shorter, but too generic. Firevault should avoid multi-platform abstraction until the core recovery workflow is stable.
+
+## Workflow Location
+
+The workflow should be written inside the `.firevault` repository:
+
+```txt
+.firevault/.github/workflows/firevault-snapshot.yml
+```
+
+This keeps automation with the recovery repo, not the parent application repo.
+
+## Firevault Version In Workflow
+
+Default recommendation:
+
+```bash
+npm install -g firevault@next
+```
+
+For early prerelease dogfooding, `@next` matches the current publishing model and avoids silently installing an older stable line once one exists.
+
+Later, setup can support:
+
+- `--version exact` to pin the currently installed CLI version,
+- `--tag next` as the default prerelease tag,
+- `--tag latest` once Firevault has a stable release.
+
+The generated workflow currently installs `firevault@next`.
+
+## Secret Name
+
+Recommended secret:
+
+```txt
+FIREVAULT_SERVICE_ACCOUNT_JSON
+```
+
+This name is specific enough to avoid collision with application secrets and clear enough for GitHub repository settings.
+
+The workflow should write it to the configured service account path:
+
+```bash
+printf '%s' "$FIREVAULT_SERVICE_ACCOUNT_JSON" > .firevault/serviceAccountKey.json
+```
+
+In GitHub Actions syntax, prefer reading from `secrets.FIREVAULT_SERVICE_ACCOUNT_JSON` into an environment variable for one step only.
+
+## Schedule
+
+Default schedule:
+
+```yaml
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+```
+
+Daily is the right default because:
+
+- it is simple,
+- it limits operational cost and noise,
+- it is enough for initial dogfooding,
+- users can run manually through `workflow_dispatch`.
+
+Custom cron should be supported later with:
+
+```bash
+firevault setup-github-action --cron "0 */6 * * *"
+```
+
+Do not add cron customization in the first implementation unless it stays very small.
+
+## Setup Behavior
+
+Phase 2 setup should create only the local workflow file and print next steps.
+
+It should not:
+
+- create GitHub repositories,
+- call GitHub APIs,
+- create or set GitHub secrets,
+- push,
+- stage,
+- commit,
+- store secrets.
+
+After writing the workflow, print concise next steps:
+
+```txt
+Created .firevault/.github/workflows/firevault-snapshot.yml
+
+Next steps:
+1. Push .firevault to a private GitHub repository.
+2. Add GitHub secret FIREVAULT_SERVICE_ACCOUNT_JSON with the full service account JSON.
+3. Review and commit the workflow file yourself.
+4. Run the workflow manually once before relying on the schedule.
+```
+
+## Manual Commit Policy
+
+Firevault should not commit the workflow automatically.
+
+Rationale:
+
+- this is infrastructure configuration,
+- users must review secret handling,
+- Firevault and AI agents must not create commits automatically,
+- the current product posture keeps Git writes explicit.
+
+## Secret Safety
+
+The workflow must avoid exposing service account JSON.
+
+Rules:
+
+- never echo the secret,
+- never print the generated credential file,
+- write the secret directly to the configured service account path,
+- ensure `.firevault/.gitignore` ignores the service account path,
+- remove the credential file at the end of the job if practical,
+- do not upload backup artifacts containing credentials,
+- do not put the JSON in workflow YAML.
+
+The setup command should validate only local file paths and text generation. It should not inspect or store the secret value.
+
+## GitHub-Specific Without GitHub API Dependency
+
+Keep this as a local workflow-file generator.
+
+Provider-specific assumptions are acceptable in the generated YAML and command name, but Firevault should not depend on GitHub APIs for setup.
+
+This means:
+
+- no GitHub token required,
+- no `gh` dependency,
+- no repository creation,
+- no secret creation,
+- no workflow run polling.
+
+## Push Logic
+
+The workflow should commit and push only when backup files changed.
+
+Sketch:
+
+```yaml
+- name: Run snapshot
+  run: firevault snapshot
+
+- name: Push backup commit
+  run: |
+    if git diff --quiet origin/main..HEAD; then
+      echo "No new backup commit to push."
+      exit 0
+    fi
+
+    git push
+```
+
+Implementation should be careful here because `firevault snapshot` may create a commit only when backup files changed. The workflow needs to distinguish:
+
+- no changes: do nothing,
+- local backup commit created: push,
+- command failed: fail the workflow.
+
+The exact push check should be verified in a temporary Git repository before shipping.
+
+## Status Detection
+
+`firevault status` should detect Phase 2 by local file existence first:
+
+```txt
+.firevault/.github/workflows/firevault-snapshot.yml
+```
+
+Phase 2 status awareness can later inspect workflow text and report:
+
+- scheduled trigger present,
+- `workflow_dispatch` present,
+- `firevault snapshot` present,
+- `FIREVAULT_SERVICE_ACCOUNT_JSON` referenced,
+- workflow installed but not validated.
+
+No GitHub API calls should be used by `status` in Phase 2.
+
+## Initial Workflow Shape
+
+Draft workflow:
+
+```yaml
+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:
+          FIREVAULT_SERVICE_ACCOUNT_JSON: ${{ secrets.FIREVAULT_SERVICE_ACCOUNT_JSON }}
+        run: |
+          mkdir -p "$(dirname ".firevault/serviceAccountKey.json")"
+          printf '%s' "$FIREVAULT_SERVICE_ACCOUNT_JSON" > ".firevault/serviceAccountKey.json"
+
+      - 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 ".firevault/serviceAccountKey.json"
+```
+
+The implementation avoids hardcoding `main` by using `git rev-parse --abbrev-ref HEAD` in the checked-out recovery repository.
+
+## First Implementation Files
+
+Likely files:
+
+- `src/commands/setupGithubAction.ts`
+- `src/index.ts`
+- `package.json`
+- `README.md`
+- `docs/roadmap.md`
+- `docs/status-design.md`
+
+Tests should use temporary directories and local file reads only. No Firebase emulator is required for workflow generation.