@i-santos/firestack 1.0.0 → 3.0.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 3.0.0-beta.0
+
+### Major Changes
+
+- Start Firestack v3 beta with develop/main branch strategy, environment-based workflows, and PR-first release orchestration.
+
+  Breaking change details:
+
+  - `develop` becomes the beta/staging branch and `main` becomes the stable/production branch.
+  - Release automation is now PR-first by default across both tracks.
+  - New staging/production/weekly workflow contracts define environment-scoped execution.
+
+## 2.0.0
+
+### Major Changes
+
+- e7ab55f: Rename package scope to `@i-santos` and adopt the Changesets-only release workflow.
+
+  Breaking change details:
+
+  - What changed: the package name moved from `@igorsantos-dev/firestack` to `@i-santos/firestack`.
+  - Why: align package identity with the standardized personal brand scope and the new release process.
+  - How to migrate: update installs/usages from `@igorsantos-dev/firestack` to `@i-santos/firestack` in scripts and docs.
+
 ## Unreleased
 
 - `firestack test`: added deterministic Functions env parity for test processes.

package/README.md

@@ -4,6 +4,13 @@ CLI para bootstrap e execução de testes/env em projetos Firebase sem copiar sc
 
 ## Modelo Híbrido
 
+Estratégia v3 beta (infra-first):
+
+- `release/beta`: trilha beta do pacote.
+- `main`: trilha estável e ambiente `production`.
+- GitHub Actions orquestra gatilhos, aprovações e segredos por ambiente.
+- Firestack define contratos de execução (`firestack env`, `firestack test`).
+
 Comandos principais:
 
 ```bash
@@ -24,7 +31,8 @@ npx firestack test --ci --docker --docker-rebuild
 
 ### `init`
 
-Cria `firestack.config.json`, `playwright.config.mjs`, `tests/Dockerfile` e `.dockerignore` no projeto alvo.
+Cria `firestack.config.json`, `playwright.config.mjs`, `tests/Dockerfile`, `.dockerignore`,
+workflows base em `.github/workflows/` e docs operacionais em `docs/`.
 O template organiza tudo de teste em `out/tests/...`:
 
 - `out/tests/unit`
@@ -199,14 +207,31 @@ npm run check
 npm run changeset
 npm run version-packages
 npm run release
+npm run beta:enter
+npm run beta:version
+npm run beta:publish
 ```
 
 Fluxo de release:
 
 1. Crie um changeset na sua PR (`npm run changeset`).
-2. Faça merge na branch `main`.
+2. Faça merge na branch alvo do track:
+- `release/beta` para beta/staging.
+- `main` para stable/production.
 3. O workflow `.github/workflows/release.yml` cria/atualiza a PR `chore: release packages`.
-4. Ao fazer merge dessa PR de release, o publish no npm e executado.
+4. O publish acontece apenas em commits `chore: release packages` (modelo PR-first).
+5. Em `release/beta`, o publish usa track beta. Em `main`, usa track estável.
+
+### Workflows de ambiente
+
+- Workflows de APP ficam nos templates do pacote:
+- `templates/workflows/staging.yml`
+- `templates/workflows/production.yml`
+- `templates/workflows/weekly-email-observability.yml`
+- `staging.yml` e `production.yml` dos templates incluem deploy Firebase via `firebase deploy`, usando:
+- secret `FIREBASE_SERVICE_ACCOUNT` (JSON)
+- secret `GCLOUD_PROJECT`
+- variable opcional `FIREBASE_DEPLOY_TARGETS` (para `--only`)
 
 ### Bootstrap de projeto existente
 
@@ -221,5 +246,6 @@ npx @i-santos/create-package-starter init --dir .
 - Configure npm Trusted Publishing para este pacote com:
 - owner/repo: `i-santos/firestack`
 - workflow: `.github/workflows/release.yml`
-- branch: `main`
-- Se `main` for protegida e exigir checks na release PR, configure o secret `CHANGESETS_GH_TOKEN`.
+- branch: `release/beta` (beta) e `main` (stable)
+- Se `release/beta` ou `main` forem protegidas e exigirem checks na release PR, configure os checks obrigatórios.
+- Use GitHub App auth para automações de release (`GH_APP_CLIENT_ID` + `GH_APP_PRIVATE_KEY`).

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@i-santos/firestack",
-  "version": "1.0.0",
+  "version": "3.0.0-beta.0",
   "description": "Portable DX and testing bootstrap for Node/Firebase projects",
   "type": "module",
   "private": false,
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/i-santos/firestack"
+  },
   "bin": {
     "firestack": "bin/firestack.mjs"
   },
@@ -26,7 +30,12 @@
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "npm run check && changeset publish",
-    "release:ci": "npm run check && npm run version-packages"
+    "release:ci": "npm run check && npm run version-packages",
+    "beta:enter": "changeset pre enter beta",
+    "beta:exit": "changeset pre exit",
+    "beta:version": "changeset version",
+    "beta:publish": "changeset publish",
+    "beta:promote": "npx @i-santos/create-package-starter@1.5.0-beta.13 promote-stable --dir ."
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",

package/scripts/cli/init.mjs

@@ -7,6 +7,13 @@ const TEMPLATE_CONFIG = join(ROOT, 'templates', 'firestack.config.json');
 const TEMPLATE_PLAYWRIGHT_CONFIG = join(ROOT, 'templates', 'playwright.config.mjs');
 const TEMPLATE_DOCKERFILE = join(ROOT, 'templates', 'tests.Dockerfile');
 const TEMPLATE_DOCKERIGNORE = join(ROOT, 'templates', 'dockerignore');
+const TEMPLATE_WORKFLOW_QUALITY_GATE = join(ROOT, 'templates', 'workflows', 'quality-gate.yml');
+const TEMPLATE_WORKFLOW_STAGING = join(ROOT, 'templates', 'workflows', 'staging.yml');
+const TEMPLATE_WORKFLOW_PRODUCTION = join(ROOT, 'templates', 'workflows', 'production.yml');
+const TEMPLATE_WORKFLOW_WEEKLY = join(ROOT, 'templates', 'workflows', 'weekly-email-observability.yml');
+const TEMPLATE_DOC_TEST_POLICY = join(ROOT, 'templates', 'docs', 'test-policy.md');
+const TEMPLATE_DOC_ENVIRONMENT_SECRETS = join(ROOT, 'templates', 'docs', 'environment-secrets.md');
+const TEMPLATE_DOC_INCIDENT_RUNBOOK = join(ROOT, 'templates', 'docs', 'incident-rollback-runbook.md');
 
 function printHelp() {
   console.log('Usage: firestack init [--target <dir>] [--force] [--dry-run]');
@@ -106,6 +113,25 @@ export function runInit(argv) {
     { template: TEMPLATE_CONFIG, relativePath: 'firestack.config.json', label: 'firestack.config.json' },
     { template: TEMPLATE_PLAYWRIGHT_CONFIG, relativePath: 'playwright.config.mjs', label: 'playwright.config.mjs' },
     { template: TEMPLATE_DOCKERFILE, relativePath: 'tests/Dockerfile', label: 'tests/Dockerfile' },
+    { template: TEMPLATE_WORKFLOW_QUALITY_GATE, relativePath: '.github/workflows/quality-gate.yml', label: '.github/workflows/quality-gate.yml' },
+    { template: TEMPLATE_WORKFLOW_STAGING, relativePath: '.github/workflows/staging.yml', label: '.github/workflows/staging.yml' },
+    { template: TEMPLATE_WORKFLOW_PRODUCTION, relativePath: '.github/workflows/production.yml', label: '.github/workflows/production.yml' },
+    {
+      template: TEMPLATE_WORKFLOW_WEEKLY,
+      relativePath: '.github/workflows/weekly-email-observability.yml',
+      label: '.github/workflows/weekly-email-observability.yml'
+    },
+    { template: TEMPLATE_DOC_TEST_POLICY, relativePath: 'docs/test-policy.md', label: 'docs/test-policy.md' },
+    {
+      template: TEMPLATE_DOC_ENVIRONMENT_SECRETS,
+      relativePath: 'docs/environment-secrets.md',
+      label: 'docs/environment-secrets.md'
+    },
+    {
+      template: TEMPLATE_DOC_INCIDENT_RUNBOOK,
+      relativePath: 'docs/incident-rollback-runbook.md',
+      label: 'docs/incident-rollback-runbook.md'
+    },
   ];
   let skippedExisting = false;
 

package/templates/docs/environment-secrets.md

@@ -0,0 +1,20 @@
+# Environment and Secrets
+
+## Branch Mapping
+
+- `develop` -> `staging`
+- `main` -> `production`
+
+## Secret Scope
+
+- Keep staging and production secrets isolated.
+- Use GitHub Environments with approval gates for `production`.
+
+## Baseline Variables
+
+- `GCLOUD_PROJECT`
+- `E2E_BASE_URL`
+- `BREVO_API_KEY`
+- `MAILOSAUR_API_KEY` or `MAILTRAP_API_TOKEN`
+- `FIREBASE_SERVICE_ACCOUNT` (JSON credential for deploy workflow)
+- `FIREBASE_DEPLOY_TARGETS` (environment variable, optional; ex: `hosting,functions`)

package/templates/docs/incident-rollback-runbook.md

@@ -0,0 +1,19 @@
+# Incident and Rollback Runbook
+
+## Immediate Actions
+
+1. Stop current rollout and freeze merges to `main`.
+2. Confirm failing workflow, scope, and blast radius.
+3. Re-run failing checks with verbose logs.
+
+## Rollback
+
+1. Revert the release commit/PR on `main`.
+2. Trigger production workflow with approved rollback.
+3. Validate `npx firestack test --ci --profile production`.
+
+## Follow-up
+
+1. Document root cause and timeline.
+2. Add/adjust tests to prevent recurrence.
+3. Promote fix from `develop` after staging validation.

package/templates/docs/test-policy.md

@@ -0,0 +1,16 @@
+# Test Policy
+
+## Daily / PR
+
+- Run `npx firestack test --ci --profile staging`.
+- Focus on unit + integration in emulator context and low-cost smoke checks.
+
+## Staging Smoke
+
+- Run `npx firestack test --staging --profile staging`.
+- Validate provider contract and traceability with low volume.
+
+## Weekly Extended
+
+- Run `npx firestack test --staging --full --profile staging`.
+- Enable observability level 3 with bounded polling and message caps.

package/templates/env/.env.production.example

@@ -1,2 +1,14 @@
 # Production app environment
 GCLOUD_PROJECT=prod-your-project
+E2E_BASE_URL=https://app.example.com
+ALLOW_NON_STAGING_E2E=false
+
+# Production credentials (approval-gated environment)
+BREVO_API_KEY=
+MAILOSAUR_API_KEY=
+MAILTRAP_API_TOKEN=
+
+# Conservative defaults for production checks
+FIRESTACK_EMAIL_OBSERVABILITY_LEVEL=1
+FIRESTACK_EMAIL_POLL_MAX_SECONDS=60
+FIRESTACK_EMAIL_MAX_TEST_MESSAGES=3

package/templates/env/.env.staging.example

@@ -2,3 +2,15 @@
 GCLOUD_PROJECT=staging-your-project
 E2E_BASE_URL=https://staging.example.com
 ALLOW_NON_STAGING_E2E=false
+
+# Provider checks (L1/L2) for staging smoke
+BREVO_API_KEY=
+
+# Optional observability provider (L3)
+MAILOSAUR_API_KEY=
+MAILTRAP_API_TOKEN=
+
+# Weekly extended guardrails
+FIRESTACK_EMAIL_OBSERVABILITY_LEVEL=2
+FIRESTACK_EMAIL_POLL_MAX_SECONDS=90
+FIRESTACK_EMAIL_MAX_TEST_MESSAGES=5

package/templates/env/.env.test.production.example

@@ -2,3 +2,11 @@
 GCLOUD_PROJECT=prod-your-project
 E2E_BASE_URL=https://app.example.com
 ALLOW_NON_STAGING_E2E=false
+
+# Production checks should stay low volume and approval-gated
+BREVO_API_KEY=
+MAILOSAUR_API_KEY=
+MAILTRAP_API_TOKEN=
+FIRESTACK_EMAIL_OBSERVABILITY_LEVEL=1
+FIRESTACK_EMAIL_POLL_MAX_SECONDS=60
+FIRESTACK_EMAIL_MAX_TEST_MESSAGES=3

package/templates/env/.env.test.staging.example

@@ -2,7 +2,19 @@
 GCLOUD_PROJECT=staging-your-project
 E2E_BASE_URL=https://staging.example.com
 ALLOW_NON_STAGING_E2E=false
+
+# Staging E2E credentials (fixed users are optional)
 E2E_STAGING_SMOKE_EMAIL=e2e-smoke@example.com
 E2E_STAGING_SMOKE_PASSWORD=change-me
 E2E_STAGING_FULL_EMAIL=e2e-full@example.com
 E2E_STAGING_FULL_PASSWORD=change-me
+
+# Email provider checks
+BREVO_API_KEY=
+MAILOSAUR_API_KEY=
+MAILTRAP_API_TOKEN=
+
+# Weekly extended guardrails
+FIRESTACK_EMAIL_OBSERVABILITY_LEVEL=2
+FIRESTACK_EMAIL_POLL_MAX_SECONDS=90
+FIRESTACK_EMAIL_MAX_TEST_MESSAGES=5

package/templates/firestack.config.json

@@ -84,6 +84,14 @@
         "E2E_STAGING_SMOKE_PASSWORD",
         "E2E_STAGING_FULL_EMAIL",
         "E2E_STAGING_FULL_PASSWORD",
+        "MAILHOG_HOST",
+        "MAILHOG_PORT",
+        "BREVO_API_KEY",
+        "MAILOSAUR_API_KEY",
+        "MAILTRAP_API_TOKEN",
+        "FIRESTACK_EMAIL_OBSERVABILITY_LEVEL",
+        "FIRESTACK_EMAIL_POLL_MAX_SECONDS",
+        "FIRESTACK_EMAIL_MAX_TEST_MESSAGES",
         "E2E_APP_CHECK_DEBUG_TOKEN",
         "FIREBASE_AUTH_EMULATOR_HOST",
         "FIRESTORE_EMULATOR_HOST",

package/templates/workflows/production.yml

@@ -0,0 +1,60 @@
+name: Production Deploy + Gate
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  production:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Prepare production env
+        run: npx firestack env --production
+
+      - name: Run production validation
+        run: npx firestack test --ci --profile production
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          credentials_json: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
+
+      - name: Setup Cloud SDK
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Install Firebase CLI
+        run: npm install -g firebase-tools
+
+      - name: Deploy to Firebase production
+        env:
+          GCLOUD_PROJECT: ${{ secrets.GCLOUD_PROJECT }}
+          FIREBASE_DEPLOY_TARGETS: ${{ vars.FIREBASE_DEPLOY_TARGETS }}
+        run: |
+          if [ -z "${GCLOUD_PROJECT}" ]; then
+            echo "Missing production secret GCLOUD_PROJECT"
+            exit 1
+          fi
+
+          if [ -n "${FIREBASE_DEPLOY_TARGETS}" ]; then
+            firebase deploy --project "${GCLOUD_PROJECT}" --only "${FIREBASE_DEPLOY_TARGETS}" --non-interactive
+          else
+            firebase deploy --project "${GCLOUD_PROJECT}" --non-interactive
+          fi

package/templates/workflows/quality-gate.yml

@@ -0,0 +1,31 @@
+name: Quality Gate
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Firestack CI contracts
+        run: |
+          npx firestack env --staging
+          npx firestack test --ci --profile staging

package/templates/workflows/staging.yml

@@ -0,0 +1,60 @@
+name: Staging Deploy + Smoke
+
+on:
+  push:
+    branches:
+      - develop
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  staging:
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Prepare staging env
+        run: npx firestack env --staging
+
+      - name: Run staging smoke
+        run: npx firestack test --staging --profile staging
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          credentials_json: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
+
+      - name: Setup Cloud SDK
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Install Firebase CLI
+        run: npm install -g firebase-tools
+
+      - name: Deploy to Firebase staging
+        env:
+          GCLOUD_PROJECT: ${{ secrets.GCLOUD_PROJECT }}
+          FIREBASE_DEPLOY_TARGETS: ${{ vars.FIREBASE_DEPLOY_TARGETS }}
+        run: |
+          if [ -z "${GCLOUD_PROJECT}" ]; then
+            echo "Missing staging secret GCLOUD_PROJECT"
+            exit 1
+          fi
+
+          if [ -n "${FIREBASE_DEPLOY_TARGETS}" ]; then
+            firebase deploy --project "${GCLOUD_PROJECT}" --only "${FIREBASE_DEPLOY_TARGETS}" --non-interactive
+          else
+            firebase deploy --project "${GCLOUD_PROJECT}" --non-interactive
+          fi

package/templates/workflows/weekly-email-observability.yml

@@ -0,0 +1,36 @@
+name: Weekly Email Observability
+
+on:
+  schedule:
+    - cron: '0 5 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  weekly-observability:
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Prepare staging env
+        run: npx firestack env --staging
+
+      - name: Run weekly extended path
+        env:
+          FIRESTACK_EMAIL_OBSERVABILITY_LEVEL: '3'
+          FIRESTACK_EMAIL_POLL_MAX_SECONDS: '180'
+          FIRESTACK_EMAIL_MAX_TEST_MESSAGES: '10'
+        run: npx firestack test --staging --full --profile staging