@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/full/wrangler.auditor.jsonc.hbs

@@ -0,0 +1,75 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "{{projectSlug}}-auditor",
+  "main": "workers/platform-auditor.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+
+  "observability": {
+    "enabled": true,
+    "logs": {
+      "enabled": true,
+      "sampling_rate": 1,
+      "invocation_logs": true
+    },
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.1
+    }
+  },
+  "upload_source_maps": true,
+
+  "triggers": {
+    "crons": [
+      "0 0 * * SUN",
+      "0 0 * * WED"
+    ]
+  },
+
+  "d1_databases": [
+    {
+      "binding": "PLATFORM_DB",
+      "database_name": "{{projectSlug}}-metrics",
+      "database_id": "YOUR_D1_DATABASE_ID",
+      "migrations_dir": "storage/d1/migrations"
+    }
+  ],
+
+  "kv_namespaces": [
+    {
+      "binding": "PLATFORM_CACHE",
+      "id": "YOUR_KV_NAMESPACE_ID"
+    }
+  ],
+
+  "queues": {
+    "producers": [
+      {
+        "binding": "PLATFORM_TELEMETRY",
+        "queue": "{{projectSlug}}-telemetry"
+      }
+    ]
+  },
+
+  "services": [
+    {
+      "binding": "ALERT_ROUTER",
+      "service": "{{projectSlug}}-alert-router"
+    }
+  ],
+
+  "ai": {
+    "binding": "AI"
+  },
+
+  "vars": {
+    "CLOUDFLARE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
+    "GATUS_HEARTBEAT_URL": ""
+  },
+
+  "tail_consumers": [
+    {
+      "service": "{{projectSlug}}-error-collector"
+    }
+  ]
+}

package/templates/shared/.github/workflows/contract-check.yml.hbs

@@ -0,0 +1,42 @@
+# Contract Schema Validation
+#
+# Validates JSON schemas and TypeScript types match expected contracts.
+# Runs schema validation against fixture data.
+#
+# Checks performed:
+# - JSON schema validation (envelope, error_report)
+# - TypeScript type compilation
+# - Contract fixture validation
+
+name: Contract Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'contracts/**'
+      - 'tests/contract/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'contracts/**'
+      - 'tests/contract/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Validate schemas
+        run: npm run validate:schemas
+
+      - name: Run contract tests
+        run: npx vitest run tests/contract/

package/templates/shared/.github/workflows/dashboard-deploy.yml.hbs

@@ -0,0 +1,39 @@
+name: Deploy Dashboard
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'dashboard/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+
+      - name: Install dependencies
+        working-directory: dashboard
+        run: npm ci
+
+      - name: Build
+        working-directory: dashboard
+        run: npm run build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: $\{{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: $\{{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy dist --project-name={{projectSlug}}-dashboard
+          workingDirectory: dashboard

package/templates/shared/.github/workflows/platform-check.yml.hbs

@@ -0,0 +1,28 @@
+# Platform SDK Integration Check
+#
+# Validates Platform SDK usage, wrangler configs, and cost safety patterns.
+# Uses the reusable workflow from the Platform SDKs repository.
+#
+# Checks performed:
+# - SDK installation and version
+# - Wrangler configs (PLATFORM_CACHE, telemetry queue, observability, tail_consumers)
+# - Budget wrappers (withFeatureBudget, withCronBudget, withQueueBudget)
+# - Feature ID format (project:category:feature)
+# - CircuitBreakerError handling
+# - Cost safety (D1 batch writes, ON CONFLICT, SELECT LIMIT, no SQL injection)
+#
+# See: https://github.com/littlebearapps/platform-sdks
+
+name: Platform SDK Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  sdk-check:
+    uses: littlebearapps/platform-sdks/.github/workflows/consumer-check.yml@main
+    with:
+      project-name: {{projectSlug}}

package/templates/shared/.github/workflows/security.yml

@@ -0,0 +1,33 @@
+# Security Scanning
+#
+# Runs dependency audit and secret detection on pushes and PRs.
+
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+        continue-on-error: true
+
+      - name: Check for secrets
+        uses: trufflesecurity/trufflehog@main
+        with:
+          extra_args: --only-verified

package/templates/shared/config/observability.yaml.hbs

@@ -0,0 +1,276 @@
+# Observability Configuration
+#
+# Single Source of Truth for Workers observability standards.
+# Defines sampling rates, logging patterns, and audit criteria.
+#
+# Used by:
+# - platform-auditor: Reference standard for audits (Full tier)
+# - AI Judge: Audit checklist and scoring rubrics (Full tier)
+# - Developers: Reference for wrangler config settings
+#
+# Version: 1.0.0
+
+metadata:
+  version: "1.0.0"
+  lastUpdated: "{{currentDate}}"
+  linkedRegistry: "./services.yaml"
+
+# ============================================================
+# GLOBAL STANDARDS (Required for ALL workers)
+# ============================================================
+# These settings must be present in every wrangler config
+# ============================================================
+
+standards:
+  # Source maps - ALWAYS required for readable stack traces
+  source_maps:
+    required: true
+    setting: "upload_source_maps"
+    value: true
+    severity: critical
+    rationale: "Essential for debugging production errors"
+
+  # Observability block - ALWAYS required
+  observability:
+    required: true
+    setting: "observability.enabled"
+    value: true
+    severity: critical
+    rationale: "Base requirement for all logging and tracing"
+
+  # Logs - ALWAYS required
+  logs:
+    required: true
+    settings:
+      enabled: true
+      invocation_logs: true
+    severity: critical
+    rationale: "Essential for debugging and monitoring"
+
+  # Traces - Recommended (beta but valuable)
+  traces:
+    required: false
+    recommended: true
+    settings:
+      enabled: true
+    severity: high
+    rationale: "Automatic instrumentation for performance debugging"
+
+# ============================================================
+# SAMPLING RATE PROFILES
+# ============================================================
+# Profiles based on worker characteristics.
+# Assign a profile to each worker in the projects section below.
+# ============================================================
+
+sampling_profiles:
+  # Critical path workers (auth, payments, etc.)
+  critical:
+    logs:
+      head_sampling_rate: 1.0    # 100% - never miss errors
+    traces:
+      head_sampling_rate: 0.5    # 50% - high visibility
+    applies_to:
+      - "workers with auth responsibilities"
+      - "workers handling payments"
+      - "workers with revenue impact"
+
+  # Low traffic workers (<1K requests/day)
+  low_traffic:
+    logs:
+      head_sampling_rate: 1.0    # 100%
+    traces:
+      head_sampling_rate: 1.0    # 100%
+    applies_to:
+      - "scheduled/cron workers"
+      - "admin/internal tools"
+      - "audit workers"
+
+  # Medium traffic workers (1K-100K requests/day)
+  medium_traffic:
+    logs:
+      head_sampling_rate: 0.5    # 50%
+    traces:
+      head_sampling_rate: 0.1    # 10%
+    applies_to:
+      - "API endpoints with moderate traffic"
+      - "dashboard workers"
+
+  # High traffic workers (>100K requests/day)
+  high_traffic:
+    logs:
+      head_sampling_rate: 0.1    # 10%
+    traces:
+      head_sampling_rate: 0.05   # 5%
+    applies_to:
+      - "public API endpoints"
+      - "high-volume queue consumers"
+
+  # Staging/Development (always full visibility)
+  staging:
+    logs:
+      head_sampling_rate: 1.0    # 100%
+    traces:
+      head_sampling_rate: 1.0    # 100%
+    applies_to:
+      - "any worker in staging environment"
+      - "test workers"
+
+# ============================================================
+# PROJECT OBSERVABILITY SETTINGS
+# ============================================================
+
+projects:
+  {{projectSlug}}:
+    status: pending  # Update to 'compliant' after verification
+    profile: low_traffic
+    workers:
+      {{projectSlug}}-usage:
+        profile: medium_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 0.1 }
+        notes: "Central data warehouse — full logging essential"
+
+{{#if isStandard}}
+      {{projectSlug}}-error-collector:
+        profile: low_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 0.5 }
+        notes: "Tail worker — captures all error outcomes"
+
+      {{projectSlug}}-sentinel:
+        profile: low_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 0.5 }
+        notes: "Gap detection and cost monitoring"
+
+      {{projectSlug}}-mapper:
+        profile: low_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 0.5 }
+        notes: "Resource topology mapping"
+
+      {{projectSlug}}-sdk-test-client:
+        profile: staging
+        optional: true
+        notes: "SDK validation — on-demand only"
+{{/if}}
+
+{{#if isFull}}
+      {{projectSlug}}-pattern-discovery:
+        profile: low_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 1.0 }
+        notes: "Daily AI discovery cron — full visibility"
+
+      {{projectSlug}}-alert-router:
+        profile: critical
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 0.5 }
+        notes: "Critical — routes all alerts"
+
+      {{projectSlug}}-auditor:
+        profile: low_traffic
+        sampling:
+          logs: { head_sampling_rate: 1.0 }
+          traces: { head_sampling_rate: 1.0 }
+        notes: "Weekly cron — full visibility always"
+{{/if}}
+
+# ============================================================
+# STRUCTURED LOGGING SCHEMA
+# ============================================================
+# Standard fields for console.log() JSON objects.
+# Use the Platform SDK createLogger() for automatic formatting.
+# ============================================================
+
+logging_schema:
+  required_fields:
+    - name: event
+      type: string
+      description: "Event type (e.g., 'api_request', 'db_query', 'error')"
+
+  recommended_fields:
+    - name: requestId
+      type: string
+      description: "CF ray ID or custom request ID"
+      source: "request.headers.get('cf-ray')"
+
+    - name: projectId
+      type: string
+      description: "Project identifier"
+
+    - name: featureId
+      type: string
+      description: "Feature being used (matches services.yaml)"
+
+    - name: durationMs
+      type: number
+      description: "Operation duration in milliseconds"
+
+  error_fields:
+    - name: error.message
+      type: string
+      required: true
+
+    - name: error.name
+      type: string
+      required: true
+
+    - name: error.stack
+      type: string
+      required: false
+
+# ============================================================
+# AUDIT CHECKLIST
+# ============================================================
+# Items verified by AI Judge for observability audits (Full tier).
+# Severity: critical (must fix), high (should fix), medium (nice to have)
+# ============================================================
+
+audit_checklist:
+  - id: source_maps_enabled
+    check: "upload_source_maps === true"
+    severity: critical
+    message: "Source maps must be enabled for readable stack traces"
+
+  - id: observability_enabled
+    check: "observability.enabled === true"
+    severity: critical
+    message: "Observability must be enabled"
+
+  - id: logs_enabled
+    check: "observability.logs.enabled === true"
+    severity: critical
+    message: "Logs must be enabled"
+
+  - id: traces_enabled
+    check: "observability.traces.enabled === true"
+    severity: high
+    message: "Traces should be enabled for automatic instrumentation"
+
+  - id: sampling_rate_appropriate
+    check: "sampling rate matches traffic profile"
+    severity: medium
+    message: "Sampling rate should match worker traffic level"
+
+  - id: structured_logging_used
+    check: "console.log uses JSON objects, not string interpolation"
+    severity: medium
+    message: "Use structured JSON logging for queryability"
+
+  - id: error_context_included
+    check: "error logs include requestId and relevant context"
+    severity: medium
+    message: "Error logs should include request context for debugging"
+
+  - id: invocation_logs_enabled
+    check: "observability.logs.invocation_logs !== false"
+    severity: low
+    message: "Invocation logs provide request/response metadata"

package/templates/shared/contracts/schemas/envelope.v1.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "envelope.v1.schema.json",
+  "title": "Telemetry Message Envelope v1",
+  "description": "Standard envelope for Platform SDK telemetry messages sent via queue",
+  "type": "object",
+  "required": ["feature_key", "project", "category", "feature", "metrics", "timestamp"],
+  "properties": {
+    "feature_key": {
+      "type": "string",
+      "description": "Fully qualified feature key (project:category:feature)",
+      "pattern": "^[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+$"
+    },
+    "project": {
+      "type": "string",
+      "description": "Project identifier",
+      "minLength": 1
+    },
+    "category": {
+      "type": "string",
+      "description": "Feature category within the project",
+      "minLength": 1
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name within the category",
+      "minLength": 1
+    },
+    "metrics": {
+      "type": "object",
+      "description": "Feature metrics payload (FeatureMetrics type from consumer SDK)",
+      "properties": {
+        "d1Writes": { "type": "number", "minimum": 0 },
+        "d1Reads": { "type": "number", "minimum": 0 },
+        "d1RowsRead": { "type": "number", "minimum": 0 },
+        "d1RowsWritten": { "type": "number", "minimum": 0 },
+        "kvReads": { "type": "number", "minimum": 0 },
+        "kvWrites": { "type": "number", "minimum": 0 },
+        "kvDeletes": { "type": "number", "minimum": 0 },
+        "kvLists": { "type": "number", "minimum": 0 },
+        "aiRequests": { "type": "number", "minimum": 0 },
+        "aiNeurons": { "type": "number", "minimum": 0 },
+        "vectorizeQueries": { "type": "number", "minimum": 0 },
+        "vectorizeInserts": { "type": "number", "minimum": 0 },
+        "doRequests": { "type": "number", "minimum": 0 },
+        "doGbSeconds": { "type": "number", "minimum": 0 },
+        "r2ClassA": { "type": "number", "minimum": 0 },
+        "r2ClassB": { "type": "number", "minimum": 0 },
+        "queueMessages": { "type": "number", "minimum": 0 },
+        "requests": { "type": "number", "minimum": 0 },
+        "cpuMs": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "timestamp": {
+      "type": "number",
+      "description": "Unix timestamp in milliseconds when the event occurred"
+    },
+    "is_heartbeat": {
+      "type": "boolean",
+      "description": "If true, this is a heartbeat message (no metrics, just liveness)"
+    }
+  }
+}

package/templates/shared/contracts/schemas/error_report.v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "error_report.v1.schema.json",
+  "title": "Error Report v1",
+  "description": "Error report captured by the error-collector tail worker",
+  "type": "object",
+  "required": ["script_name", "fingerprint", "message"],
+  "properties": {
+    "script_name": {
+      "type": "string",
+      "description": "Name of the worker that produced the error",
+      "minLength": 1
+    },
+    "fingerprint": {
+      "type": "string",
+      "description": "Unique error identifier for deduplication (SHA-256 hash of normalised message + script)",
+      "minLength": 1
+    },
+    "message": {
+      "type": "string",
+      "description": "Error message text",
+      "minLength": 1
+    },
+    "stack_trace": {
+      "type": "string",
+      "description": "Full stack trace if available"
+    },
+    "outcome": {
+      "type": "string",
+      "description": "Worker outcome type",
+      "enum": [
+        "exception",
+        "exceededCpu",
+        "exceededMemory",
+        "canceled",
+        "responseStreamDisconnected",
+        "scriptNotFound",
+        "soft_error",
+        "warning"
+      ]
+    },
+    "priority": {
+      "type": "string",
+      "description": "Assigned priority level",
+      "enum": ["P0", "P1", "P2", "P3", "P4"]
+    },
+    "category": {
+      "type": "string",
+      "description": "Error category (e.g., unhandled-exception, quota-exhausted, rate-limited)"
+    },
+    "project": {
+      "type": "string",
+      "description": "Project the error belongs to (resolved from SCRIPT_MAP KV)"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the error occurred (ISO 8601 UTC)"
+    },
+    "event_timestamp": {
+      "type": "number",
+      "description": "Unix timestamp in milliseconds from the tail event"
+    }
+  }
+}