@littlebearapps/platform-admin-sdk 1.4.2 → 1.5.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/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/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"
+    }
+  }
+}

package/templates/shared/contracts/types/telemetry-envelope.types.ts

@@ -0,0 +1,139 @@
+/**
+ * Telemetry Envelope Types
+ *
+ * TypeScript interfaces for Platform SDK telemetry messages and error reports.
+ * These types mirror the JSON schemas in contracts/schemas/ and provide
+ * compile-time type safety.
+ *
+ * @see contracts/schemas/envelope.v1.schema.json
+ * @see contracts/schemas/error_report.v1.schema.json
+ */
+
+// =============================================================================
+// Telemetry Message Types
+// =============================================================================
+
+/**
+ * Feature metrics payload — maps to FeatureMetrics from consumer SDK.
+ * Each field corresponds to a Cloudflare service metric.
+ */
+export interface TelemetryMetrics {
+  // D1 Database
+  d1Writes?: number;
+  d1Reads?: number;
+  d1RowsRead?: number;
+  d1RowsWritten?: number;
+
+  // KV Namespace
+  kvReads?: number;
+  kvWrites?: number;
+  kvDeletes?: number;
+  kvLists?: number;
+
+  // Workers AI
+  aiRequests?: number;
+  aiNeurons?: number;
+
+  // Vectorize
+  vectorizeQueries?: number;
+  vectorizeInserts?: number;
+
+  // Durable Objects
+  doRequests?: number;
+  doGbSeconds?: number;
+
+  // R2 Storage
+  r2ClassA?: number;
+  r2ClassB?: number;
+
+  // Queues
+  queueMessages?: number;
+
+  // General
+  requests?: number;
+  cpuMs?: number;
+}
+
+/**
+ * Telemetry message envelope — the standard format for SDK telemetry
+ * sent through the platform-telemetry queue.
+ */
+export interface TelemetryEnvelope {
+  /** Fully qualified feature key (project:category:feature) */
+  feature_key: string;
+  /** Project identifier */
+  project: string;
+  /** Feature category within the project */
+  category: string;
+  /** Feature name within the category */
+  feature: string;
+  /** Feature metrics payload */
+  metrics: TelemetryMetrics;
+  /** Unix timestamp in milliseconds when the event occurred */
+  timestamp: number;
+  /** If true, this is a heartbeat message (no metrics, just liveness) */
+  is_heartbeat?: boolean;
+}
+
+// =============================================================================
+// Error Report Types
+// =============================================================================
+
+/** Worker outcome types captured by the error collector */
+export type ErrorOutcome =
+  | 'exception'
+  | 'exceededCpu'
+  | 'exceededMemory'
+  | 'canceled'
+  | 'responseStreamDisconnected'
+  | 'scriptNotFound'
+  | 'soft_error'
+  | 'warning';
+
+/** Priority levels for error reports */
+export type ErrorPriority = 'P0' | 'P1' | 'P2' | 'P3' | 'P4';
+
+/**
+ * Error report structure — captured by the error-collector tail worker
+ * and optionally escalated to GitHub issues.
+ */
+export interface ErrorReport {
+  /** Name of the worker that produced the error */
+  script_name: string;
+  /** Unique error identifier for deduplication */
+  fingerprint: string;
+  /** Error message text */
+  message: string;
+  /** Full stack trace if available */
+  stack_trace?: string;
+  /** Worker outcome type */
+  outcome?: ErrorOutcome;
+  /** Assigned priority level */
+  priority?: ErrorPriority;
+  /** Error category (e.g., unhandled-exception, quota-exhausted) */
+  category?: string;
+  /** Project the error belongs to */
+  project?: string;
+  /** When the error occurred (ISO 8601 UTC) */
+  timestamp?: string;
+  /** Unix timestamp in milliseconds from the tail event */
+  event_timestamp?: number;
+}
+
+// =============================================================================
+// Circuit Breaker Types
+// =============================================================================
+
+/** Circuit breaker states stored in KV */
+export type CircuitBreakerState = 'active' | 'warning' | 'paused';
+
+/**
+ * Circuit breaker KV entry — stored at cb:{project}:{feature} key.
+ */
+export interface CircuitBreakerEntry {
+  state: CircuitBreakerState;
+  tripped_at?: string;
+  reason?: string;
+  d1_writes_24h?: number;
+  d1_limit?: number;
+}

package/templates/shared/dashboard/astro.config.mjs

@@ -0,0 +1,21 @@
+import { defineConfig } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+import tailwind from '@astrojs/tailwind';
+import react from '@astrojs/react';
+
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare({
+    mode: 'directory',
+    imageService: 'passthrough',
+  }),
+  integrations: [tailwind(), react()],
+  vite: {
+    optimizeDeps: {
+      include: ['react', 'react-dom', 'react-dom/client'],
+    },
+    resolve: {
+      conditions: ['workerd', 'browser', 'import', 'module', 'default'],
+    },
+  },
+});

package/templates/shared/dashboard/package.json.hbs

@@ -0,0 +1,29 @@
+{
+  "name": "{{projectSlug}}-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "check": "astro check"
+  },
+  "dependencies": {
+    "astro": "^5.0.0",
+    "@astrojs/cloudflare": "^12.0.0",
+    "@astrojs/react": "^4.0.0",
+    "@astrojs/tailwind": "^6.0.0",
+    "clsx": "^2.1.0",
+    "jose": "^5.2.0",
+    "lucide-react": "^0.300.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0"
+  }
+}