Berta Pulse

Local multi-provider ops + SEO control plane. One dashboard to scan every hosting provider you use, diagnose what's broken, and apply battle-tested recovery playbooks — plus a sitemap/Search-Console pipeline and a GitHub/GitLab repo deck. Runs entirely on your machine; nothing leaves it but the API calls you configure.

Where the code lives: the shipping product is the standalone .mjs runtime under lib/ + bin/ + ui/. The TypeScript packages/ monorepo is an early skeleton and is deprecated — see packages/DEPRECATED.md. Build new features in lib/.

What it does

• Multi-provider scan / diagnose / fix across 12 providers — Railway, Vercel, Netlify, Render, Fly, Heroku, Koyeb, Cloudflare Pages, DigitalOcean App Platform, AWS Amplify, Google Cloud Run, and Coolify. Each service is classified (HEALTHY / AUTO_FIXABLE / NEEDS_CONFIRM) and matched to a recovery playbook.
• Recovery playbooks — 24 YAML recipes seeded from real fix sessions, with tiered steps (tier 0 = safe to auto-apply, tier 1+ = needs confirmation).
• Sitemap + SEO pipeline — discover routes, generate sitemap.xml, commit to GitHub or GitLab, and submit to Google Search Console with analytics enrichment.
• Repo Deck — a scored GitHub portfolio view linked back to the live scan.
• Cost-waste signals, a watch daemon, a local audit log, and an optional BYOK agent layer (incl. local Ollama).

Requirements

• Node.js 18+ (no npm install required for the standalone runtime)
• Per provider, the relevant CLI logged in or an API token in .berta-pulse.env. Railway/Vercel use their CLIs; the rest use API keys.
• Copy .berta-pulse.env.example → .berta-pulse.env (gitignored) and fill in only the providers you use. Missing keys degrade gracefully — that provider is simply skipped, never a crash.

Web UI (recommended)

cd stackpulse
node bin/berta-pulse.mjs ui

Opens http://127.0.0.1:3847. From there you can scan every configured provider, filter/search the service table, diagnose a service, preview or apply playbooks, run the sitemap pipeline, and browse the Repo Deck.

Custom port: node bin/berta-pulse.mjs ui --port 4000 Restart a stuck instance: node bin/berta-pulse.mjs ui --restart

CLI

Standalone (no npm install) — works on corporate TLS-restricted networks:

cd stackpulse
node bin/berta-pulse.mjs scan [--json] [--exclude <project>...]
node bin/berta-pulse.mjs watch [--interval 30] [--once]
node bin/berta-pulse.mjs diagnose <project> <service>
node bin/berta-pulse.mjs fix <project> <service> [--apply] [--playbook <id>]
node bin/berta-pulse.mjs playbooks

fix is a dry run by default and only ever auto-applies tier-0 steps with --apply; higher tiers are surfaced as manual/agent-confirmation steps.

Desktop (Electron)

Electron is optional — on networks with TLS inspection, npm install may fail for Electron. Install CLI packages first, then desktop separately:

npm install
npm run desktop:install   # may require corporate CA / npm strict-ssl off
npm run desktop

Tests

The suite uses Node's built-in test runner — no dependencies, no npm install, matching how the runtime ships:

npm test            # unit + smoke + playbook-integrity tests (node --test)
npm run test:syntax # deps-free `node --check` over every shipped script

• test/unit.test.mjs — pure decision logic (classification, fallback rules, service matching, waste analysis, TLS detection).
• test/smoke.test.mjs — every lib/*.mjs module imports without throwing.
• test/playbooks.test.mjs — the playbook library loads, ids are unique and well-formed, and every fallback id actually exists.

CI runs both on Node 18/20/22 — see .github/workflows/ci.yml.

Structure

stackpulse/
  bin/                 # entrypoints: berta-pulse.mjs (CLI) + berta-pulse-ui.mjs (HTTP server)
  lib/                 # the real product — engine, 12 provider connectors,
                       #   sitemap/GSC pipeline, repo deck, agent, watch, audit
  ui/                  # browser dashboard (index.html, app.js, styles.css)
  playbooks/<provider>/ # YAML recovery playbooks + compiled playbooks.json
  test/                # node --test suite (no deps)
  marketing/           # marketing page served at /marketing
  packages/            # DEPRECATED TypeScript monorepo skeleton — do not extend
  Cursor.md            # living backlog / roadmap (source of truth for what's next)

Default exclusions

The Instruments Railway project is excluded from scans by default (per ops policy). Override with --exclude or in settings.

Roadmap

Cursor.md is the living backlog (29 steps shipped, 9 open at last count). Current focus: Step 7 — sitemaps batch status banner. Remaining work is enrichment and polish (Cost Doctor $ estimates, traffic panel, github-manager bulk ops, Repo Deck caching) rather than new foundations.

License

Proprietary — Berta / Rondanini stack.