Skip to content

Singular Dream DevOps Tooling Manual (The Grimoire)

Philosophy: "Agents Act. Humans Supervise." This manual defines the standard operating procedures for the AI Agent to control our infrastructure.

1. Secrets Management (Doppler)

  • Role: The Source of Truth for all credentials.
  • Agent Protocol: CLI First.
  • Setup: Authenticate via doppler login.
  • Execution:
    • Read: doppler run -- command (Injects variables).
    • Write: doppler secrets set KEY="value".
  • Why: Never hardcode secrets. Never paste secrets in chat. Use Doppler as the secure bridge.
  • GitHub Secrets Automation:
    • Problem: GitHub Actions cannot always easily use Doppler injection (e.g., dependabot, gh-pages).
    • Solution: "Source of Truth" Sync.
    • Tool: scripts/ops/sync-gh-secrets.sh
    • Protocol: Run this script periodically or when adding new CI tokens to Doppler. It fetches from Doppler and sets them as Repo Secrets via gh secret set.
    • Command: ./scripts/ops/sync-gh-secrets.sh

2. Infrastructure (Firebase & Google Cloud)

  • Role: Backend, Database, Auth, Storage.
  • Agent Protocol: CLI First (firebase, gcloud).
  • Setup: firebase login:ci (Token stored in Doppler).
  • Execution:
    • Deploy: firebase deploy --only functions.
    • Emulators: npm run emulators:dev.
    • Data Seeding: npm run dataseeder:gold.
  • Agent Note: Use firebase-admin SDK for data manipulation (tools/*), use CLI for deployment.

3. Hosting & DNS (Vercel & Namecheap)

  • Role: Frontend Hosting, Edge Functions, Domain Resolution.
  • Agent Protocol: API First.
  • DNS Automation:
    • Tool: tools/dns-automation.ts
    • Method: Namecheap API (XML) via fetch.
  • Vercel Automation:
    • Protocol: CLI Scripted Deployment (No Git Integration).
    • Reason: "Project Drift" caused by auto-deployers. We control exactly what deploys and when.
    • Tool: vercel deploy --prod (via CI/CD script).

    • Execution: 

      # Local Deployment
vercel deploy --prod

# CI/CD Deployment (GitHub Actions)
vercel pull --yes --environment=production --token=$VERCEL_TOKEN
vercel build --prod --token=$VERCEL_TOKEN
vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN

      vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN ```

4. Remote Execution (The Beast)

  • Role: Offloading heavy tasks (Linting, Scraping, AI Training).
  • Target: sd-utility-server-dev (GCP).
  • Agent Protocol: Service Account Auth (Preferred) or Human Auth (Fallback).
  • Authentication Limitation:
    • The Wall: If the gcloud token expires, the Agent cannot refresh it because it requires an Interactive Browser Login.
    • The Spell: The Human must cast gcloud auth login to restore the Agent's power.
  • Credential: SYSOPS_SERVICE_ACCOUNT_JSON (Doppler) - Currently Deprecated/Invalid.
  • Execution Pattern:
    1. Agent attempts execution.
    2. If Reauthentication failed, Agent notifies Human.
    3. Human runs gcloud auth login.
    4. Agent resumes execution.
  • Command: ./scripts/ops/remote-lint-fix.sh

5. Source Control (GitHub)

  • Role: Version Control, CI/CD, Documentation Hosting.
  • Agent Protocol: API/CLI Hybrid.
  • Execution:
    • Secrets: gh secret set (CLI).
    • Workflows: .github/workflows/* (API).
    • Docs: tools/publish-docs.ts (Script).

5. Observability (Sentry)

  • Role: Error Tracking, Performance Monitoring.
  • Agent Protocol: SDK First.
  • Execution:
    • Setup: npx @sentry/wizard.
    • Runtime: @sentry/nextjs (Auto-instrumented).

6. Package Management (PNPM & Turbo)

  • Role: Dependency Resolution, Build Orchestration.
  • Agent Protocol: CLI First.
  • Execution:
    • Install: pnpm add -w package (Wait for workspace check).
    • Build: turbo run build.
    • Lint: turbo run lint.

Agent Guidelines for New Tools

When introducing a new tool: 1. Add Credentials to Doppler immediately. 2. Write a Wrapper Script in tools/ if the CLI is complex. 3. Document Here: Add the tool to this Grimoire with its Protocol.