@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/standard/workers/platform-mapper.ts

@@ -0,0 +1,482 @@
+/**
+ * Platform Mapper Worker
+ *
+ * Auto-discovers Cloudflare infrastructure every 15 minutes:
+ * - Cloudflare Workers (via REST API)
+ * - Merges with Service Registry (from KV)
+ * - Stores topology in D1 + KV
+ * - Runs attribution checks (which resources belong to which projects)
+ *
+ * Cron: Every 15 minutes
+ * Cost: $0/month (within free tier for typical usage)
+ *
+ * Extension points (uncomment when ready):
+ * - GitHub deployment discovery
+ * - Health endpoint monitoring
+ * - Custom resource discovery
+ */
+
+import {
+  withCronBudget,
+  withFeatureBudget,
+  CircuitBreakerError,
+  completeTracking,
+  createLogger,
+  createLoggerFromRequest,
+  health,
+  pingHeartbeat,
+  type Logger,
+} from '@littlebearapps/platform-consumer-sdk';
+import {
+  checkAttribution,
+  storeAttributionReport,
+  alertUnattributedResources,
+  type DiscoveredResource,
+} from './lib/mapper';
+
+// TODO: Update this feature ID to match your project slug
+const FEATURE_ID = 'platform:discovery:topology';
+const HEARTBEAT_ID = 'platform:health:mapper';
+
+interface Env {
+  PLATFORM_DB: D1Database;
+  PLATFORM_CACHE: KVNamespace;
+  SERVICE_REGISTRY: KVNamespace;
+  PLATFORM_TELEMETRY: Queue;
+  CLOUDFLARE_API_TOKEN: string;
+  CLOUDFLARE_ACCOUNT_ID: string;
+  GATUS_HEARTBEAT_URL?: string;
+  GATUS_TOKEN?: string;
+  SLACK_WEBHOOK_URL?: string;
+}
+
+interface Service {
+  id: string;
+  name: string;
+  type: string;
+  tier: number;
+  status: string;
+  version?: string;
+  health_endpoint?: string;
+  health_status?: string;
+  last_seen?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface Connection {
+  from_service: string;
+  to_service: string;
+  connection_type: string;
+  protocol?: string;
+  status: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface Topology {
+  services: Service[];
+  connections: Connection[];
+  timestamp: string;
+}
+
+interface ServiceRegistry {
+  metadata?: {
+    version: string;
+    lastUpdated: string;
+    autoDiscovery: boolean;
+  };
+  services: Service[];
+  connections: Connection[];
+}
+
+interface CloudflareWorkerScript {
+  id: string;
+  created_on: string;
+  modified_on: string;
+}
+
+interface CloudflareAPIResponse {
+  result: CloudflareWorkerScript[];
+  success: boolean;
+}
+
+export default {
+  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
+    const log = createLogger({ worker: 'platform-mapper', featureId: FEATURE_ID });
+    log.info('Starting infrastructure mapping');
+
+    try {
+      const trackedEnv = withCronBudget(env, FEATURE_ID, {
+        ctx,
+        cronExpression: '*/15 * * * *',
+      });
+
+      const topology = await discoverInfrastructure(trackedEnv, log);
+
+      // Store in D1 (historical)
+      await storeSnapshot(trackedEnv.PLATFORM_DB, topology, log);
+
+      // Cache in KV (latest)
+      await cacheTopology(trackedEnv.PLATFORM_CACHE, topology, log);
+
+      // Run attribution check
+      const resources = topology.services.map(
+        (s): DiscoveredResource => ({
+          resourceType: s.type,
+          resourceId: s.id,
+          resourceName: s.name,
+          metadata: s.metadata,
+        })
+      );
+      const attributionReport = checkAttribution(resources);
+      await storeAttributionReport(trackedEnv, attributionReport, log);
+      if (attributionReport.unattributedCount > 0) {
+        await alertUnattributedResources(trackedEnv, attributionReport, log);
+      }
+      log.debug('Attribution check complete', {
+        total: attributionReport.totalResources,
+        attributed: attributionReport.attributedCount,
+        unattributed: attributionReport.unattributedCount,
+      });
+
+      await completeTracking(trackedEnv);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await health(HEARTBEAT_ID, env.PLATFORM_CACHE as any, env.PLATFORM_TELEMETRY, ctx);
+
+      log.info('Infrastructure mapping complete', {
+        services: topology.services.length,
+        connections: topology.connections.length,
+      });
+
+      pingHeartbeat(ctx, env.GATUS_HEARTBEAT_URL, env.GATUS_TOKEN, true);
+    } catch (error) {
+      if (error instanceof CircuitBreakerError) {
+        log.warn('Circuit breaker STOP', error, { reason: error.reason });
+        return;
+      }
+
+      log.error('Infrastructure mapping failed', error);
+      pingHeartbeat(ctx, env.GATUS_HEARTBEAT_URL, env.GATUS_TOKEN, false);
+      throw error;
+    }
+  },
+
+  // Manual trigger endpoint for testing
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/health') {
+      return new Response('OK', { status: 200 });
+    }
+
+    const log = createLoggerFromRequest(request, env, 'platform-mapper', FEATURE_ID);
+
+    try {
+      const trackedEnv = withFeatureBudget(env, FEATURE_ID, { ctx });
+
+      if (url.pathname === '/trigger') {
+        try {
+          const topology = await discoverInfrastructure(trackedEnv, log);
+          await storeSnapshot(trackedEnv.PLATFORM_DB, topology, log);
+          await cacheTopology(trackedEnv.PLATFORM_CACHE, topology, log);
+          await completeTracking(trackedEnv);
+
+          return new Response(JSON.stringify(topology, null, 2), {
+            headers: { 'Content-Type': 'application/json' },
+          });
+        } catch (discoverError) {
+          const err =
+            discoverError instanceof Error ? discoverError : new Error(String(discoverError));
+          log.error('Discovery failed', err, { stack: err.stack });
+          return new Response(JSON.stringify({ error: err.message }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+      }
+
+      await completeTracking(trackedEnv);
+      return new Response('Not Found', { status: 404 });
+    } catch (error) {
+      if (error instanceof CircuitBreakerError) {
+        log.warn('Circuit breaker STOP', error, { reason: error.reason });
+        return new Response(JSON.stringify({ error: 'Service temporarily unavailable' }), {
+          status: 503,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      const err = error instanceof Error ? error : new Error(String(error));
+      return new Response(JSON.stringify({ error: err.message }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  },
+};
+
+async function discoverInfrastructure(env: Env, log: Logger): Promise<Topology> {
+  const topology: Topology = {
+    services: [],
+    connections: [],
+    timestamp: new Date().toISOString(),
+  };
+
+  // 1. Load base registry (static config)
+  const baseRegistry = await loadServiceRegistry(env, log);
+
+  // 2. Discover Cloudflare Workers via REST API
+  const cfWorkers = await discoverCloudflareWorkers(env, log);
+
+  // =============================================================================
+  // EXTENSION POINTS
+  // Uncomment and implement when ready:
+  //
+  // 3. Discover GitHub deployments
+  // const githubDeployments = await discoverGitHubDeployments(env, log);
+  //
+  // 4. Fetch health status from monitoring
+  // const healthStatuses = await fetchHealthStatuses(env, log);
+  // =============================================================================
+
+  // Merge all sources (priority: health > deployments > CF API > base config)
+  topology.services = mergeServiceData(baseRegistry.services, cfWorkers);
+
+  // Use connections from base registry (defensive filter)
+  topology.connections = (baseRegistry.connections ?? []).filter(
+    (conn): conn is Connection =>
+      conn != null &&
+      typeof conn.from_service === 'string' &&
+      typeof conn.to_service === 'string' &&
+      typeof conn.connection_type === 'string'
+  );
+
+  return topology;
+}
+
+async function loadServiceRegistry(env: Env, log: Logger): Promise<ServiceRegistry> {
+  const registryJSON = await env.SERVICE_REGISTRY.get('registry:latest');
+
+  if (!registryJSON) {
+    log.warn('Service registry not found in KV, using empty registry');
+    return { services: [], connections: [] };
+  }
+
+  return JSON.parse(registryJSON) as ServiceRegistry;
+}
+
+async function discoverCloudflareWorkers(env: Env, log: Logger): Promise<Service[]> {
+  const maxRetries = 2;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(
+        `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/workers/scripts`,
+        {
+          headers: {
+            Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`,
+            'Content-Type': 'application/json',
+          },
+        }
+      );
+
+      if (!response.ok) {
+        // Consume response body to avoid stalled connections
+        await response.text().catch(() => {});
+        if (response.status >= 500 && attempt < maxRetries) {
+          log.warn('Cloudflare API 5xx, retrying', undefined, { status: response.status, attempt });
+          await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+          continue;
+        }
+        log.error('Cloudflare API error', undefined, { status: response.status });
+        return [];
+      }
+
+      const data = (await response.json()) as CloudflareAPIResponse;
+
+      return data.result.map((script) => ({
+        id: `cloudflare-worker-${script.id}`,
+        name: script.id,
+        type: 'cloudflare-worker',
+        tier: 1,
+        status: 'deployed',
+        version: 'unknown',
+        health_status: 'unknown',
+        last_seen: new Date().toISOString(),
+        metadata: {
+          created_on: script.created_on,
+          modified_on: script.modified_on,
+        },
+      }));
+    } catch (error) {
+      if (attempt < maxRetries) {
+        log.warn(
+          'Cloudflare API fetch error, retrying',
+          error instanceof Error ? error : undefined,
+          { attempt }
+        );
+        await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+        continue;
+      }
+      log.error('Failed to discover Cloudflare Workers', error);
+      return [];
+    }
+  }
+  return [];
+}
+
+function mergeServiceData(...sources: (Service[] | Partial<Service>[])[]): Service[] {
+  const merged: Record<string, Partial<Service>> = {};
+
+  for (const source of sources) {
+    if (!source || !Array.isArray(source)) continue;
+
+    for (const service of source) {
+      if (!service || !service.id) continue;
+
+      if (!merged[service.id]) {
+        merged[service.id] = { ...service };
+      } else {
+        merged[service.id] = {
+          ...merged[service.id],
+          ...service,
+          health_status: service.health_status || merged[service.id].health_status,
+        };
+      }
+    }
+  }
+
+  return Object.values(merged)
+    .filter((service): service is Service => !!service.id)
+    .map((service) => ({
+      id: service.id,
+      name: service.name ?? service.id,
+      type: service.type ?? 'unknown',
+      tier: service.tier ?? 2,
+      status: service.status ?? 'unknown',
+      version: service.version,
+      health_endpoint: service.health_endpoint,
+      health_status: service.health_status ?? 'unknown',
+      last_seen: service.last_seen ?? new Date().toISOString(),
+      metadata: service.metadata,
+    }));
+}
+
+async function storeSnapshot(db: D1Database, topology: Topology, log: Logger): Promise<void> {
+  const snapshotData = JSON.stringify(topology);
+  const serviceCount = topology.services.length;
+  const connCount = topology.connections.length;
+
+  // Batch all D1 writes to minimise row-level overhead (cost rule #1)
+  const stmts: D1PreparedStatement[] = [];
+
+  // Snapshot insert
+  stmts.push(
+    db
+      .prepare(
+        'INSERT INTO topology_snapshots (data, change_summary, service_count, connection_count) VALUES (?, ?, ?, ?)'
+      )
+      .bind(snapshotData, '', serviceCount, connCount)
+  );
+
+  // Services upserts
+  for (const service of topology.services) {
+    stmts.push(
+      db
+        .prepare(
+          `INSERT INTO services (id, name, type, tier, status, version, health_endpoint, health_status, last_seen, metadata, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+           ON CONFLICT(id) DO UPDATE SET
+             name = excluded.name, type = excluded.type, tier = excluded.tier,
+             status = excluded.status, version = excluded.version,
+             health_endpoint = excluded.health_endpoint, health_status = excluded.health_status,
+             last_seen = excluded.last_seen, metadata = excluded.metadata,
+             updated_at = CURRENT_TIMESTAMP`
+        )
+        .bind(
+          service.id,
+          service.name ?? 'unknown',
+          service.type ?? 'unknown',
+          service.tier ?? 0,
+          service.status ?? 'unknown',
+          service.version ?? null,
+          service.health_endpoint ?? null,
+          service.health_status ?? 'unknown',
+          service.last_seen ?? new Date().toISOString(),
+          service.metadata ? JSON.stringify(service.metadata) : null
+        )
+    );
+  }
+
+  // Connections upserts
+  for (const conn of topology.connections) {
+    stmts.push(
+      db
+        .prepare(
+          `INSERT INTO connections (from_service, to_service, connection_type, protocol, status, metadata, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+           ON CONFLICT(from_service, to_service, connection_type) DO UPDATE SET
+             protocol = excluded.protocol, status = excluded.status,
+             metadata = excluded.metadata, updated_at = CURRENT_TIMESTAMP`
+        )
+        .bind(
+          conn.from_service,
+          conn.to_service,
+          conn.connection_type,
+          conn.protocol ?? null,
+          conn.status ?? 'unknown',
+          conn.metadata ? JSON.stringify(conn.metadata) : null
+        )
+    );
+  }
+
+  await db.batch(stmts);
+
+  log.debug('Snapshot stored in D1');
+}
+
+async function cacheTopology(kv: KVNamespace, topology: Topology, log: Logger): Promise<void> {
+  // Cache full topology (15-minute TTL matches cron interval)
+  await kv.put('topology:latest', JSON.stringify(topology), {
+    expirationTtl: 900,
+  });
+
+  // Cache derived health summary
+  const healthSummary = {
+    total: topology.services.length,
+    up: topology.services.filter((s) => s.health_status === 'up').length,
+    down: topology.services.filter((s) => s.health_status === 'down').length,
+    degraded: topology.services.filter((s) => s.health_status === 'degraded').length,
+    unknown: topology.services.filter((s) => s.health_status === 'unknown').length,
+    timestamp: topology.timestamp,
+  };
+
+  await kv.put('topology:health', JSON.stringify(healthSummary), {
+    expirationTtl: 900,
+  });
+
+  // Cache version matrix
+  const versionMatrix = topology.services
+    .filter((s) => s.version && s.version !== 'unknown')
+    .map((s) => ({
+      id: s.id,
+      name: s.name,
+      version: s.version,
+    }));
+
+  await kv.put('topology:versions', JSON.stringify(versionMatrix), {
+    expirationTtl: 900,
+  });
+
+  // Cache configuration gaps
+  const configGaps = topology.services.filter(
+    (s) =>
+      s.status === 'partial' ||
+      s.status === 'not-deployed' ||
+      (s.metadata && JSON.stringify(s.metadata).includes('TBD'))
+  );
+
+  await kv.put('topology:config-gaps', JSON.stringify(configGaps), {
+    expirationTtl: 900,
+  });
+
+  log.debug('Topology cached in KV');
+}

package/templates/standard/workers/platform-sdk-test-client.ts

@@ -0,0 +1,125 @@
+/**
+ * Platform SDK Test Client Worker
+ *
+ * Validates Platform SDK integration by triggering telemetry flow
+ * and testing circuit breaker functionality.
+ *
+ * Endpoints:
+ *   GET /trigger-usage  - Trigger SDK telemetry (KV operations)
+ *   GET /sdk-health     - Dual-plane health check (control + data plane)
+ *   GET /health         - Basic liveness probe
+ *
+ * Extension points:
+ * - Add cron schedule (every 6 hours) for automated SDK health monitoring
+ * - Extend coverage to test all SDK service proxies (D1, AI, R2, Queue, etc.)
+ */
+
+import {
+  withFeatureBudget,
+  CircuitBreakerError,
+  completeTracking,
+} from '@littlebearapps/platform-consumer-sdk';
+
+// TODO: Update these feature IDs to match your project slug
+const FEATURE_VALIDATION = 'platform:sdk-test:validation';
+const FEATURE_HEALTH_CHECK = 'platform:sdk-test:health-check';
+
+interface Env {
+  TEST_KV: KVNamespace; // Use a non-reserved name so SDK tracks operations
+  PLATFORM_CACHE: KVNamespace; // Reserved for SDK circuit breaker state
+  PLATFORM_TELEMETRY: Queue;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/trigger-usage') {
+      try {
+        // Wrap env with SDK tracking for test feature
+        const trackedEnv = withFeatureBudget(env, FEATURE_VALIDATION, { ctx });
+
+        // Make a test KV operation (will be tracked)
+        // Use TEST_KV (not PLATFORM_CACHE which is reserved and skipped by SDK)
+        const testKey = `test:${Date.now()}`;
+        await trackedEnv.TEST_KV.put(testKey, 'sdk-validation-test', { expirationTtl: 60 });
+        const value = await trackedEnv.TEST_KV.get(testKey);
+        await trackedEnv.TEST_KV.delete(testKey);
+
+        // Explicitly flush telemetry after all operations complete
+        await completeTracking(trackedEnv);
+
+        return Response.json({
+          success: true,
+          message: 'SDK telemetry triggered successfully',
+          featureId: FEATURE_VALIDATION,
+          operations: {
+            kvWrites: 1,
+            kvReads: 1,
+            kvDeletes: 1,
+          },
+          testValue: value,
+          timestamp: new Date().toISOString(),
+        });
+      } catch (e) {
+        if (e instanceof CircuitBreakerError) {
+          return Response.json(
+            {
+              success: false,
+              error: 'CircuitBreakerError',
+              featureId: e.featureId,
+              level: e.level,
+              reason: e.reason,
+              timestamp: new Date().toISOString(),
+            },
+            { status: 503 }
+          );
+        }
+        throw e;
+      }
+    }
+
+    if (url.pathname === '/sdk-health') {
+      try {
+        const trackedEnv = withFeatureBudget(env, FEATURE_HEALTH_CHECK, { ctx });
+        const healthResult = await trackedEnv.health();
+        await completeTracking(trackedEnv);
+
+        return Response.json({
+          success: true,
+          healthResult,
+          timestamp: new Date().toISOString(),
+        });
+      } catch (e) {
+        if (e instanceof CircuitBreakerError) {
+          return Response.json(
+            {
+              success: false,
+              error: 'CircuitBreakerError',
+              featureId: e.featureId,
+              level: e.level,
+              reason: e.reason,
+            },
+            { status: 503 }
+          );
+        }
+        return Response.json(
+          {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+          },
+          { status: 500 }
+        );
+      }
+    }
+
+    if (url.pathname === '/health') {
+      return Response.json({ status: 'ok', worker: 'platform-sdk-test-client' });
+    }
+
+    return Response.json(
+      { error: 'Not found', endpoints: ['/trigger-usage', '/sdk-health', '/health'] },
+      { status: 404 }
+    );
+  },
+};

package/templates/standard/wrangler.mapper.jsonc.hbs

@@ -0,0 +1,85 @@
+{
+  // =============================================================================
+  // Platform Mapper Worker
+  // =============================================================================
+  // Auto-discovers Cloudflare infrastructure and services.
+  //
+  // Deploy:     wrangler deploy -c wrangler.{{projectSlug}}-mapper.jsonc
+  // Tail logs:  wrangler tail {{projectSlug}}-mapper --format pretty
+  // Cron:       Every 15 minutes
+  // Secrets:    CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
+  // =============================================================================
+
+  "$schema": "node_modules/wrangler/config-schema.json",
+
+  "name": "{{projectSlug}}-mapper",
+  "main": "workers/platform-mapper.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+
+  // D1 Database
+  // TODO: Replace database_id with your D1 database ID
+  "d1_databases": [
+    {
+      "binding": "PLATFORM_DB",
+      "database_name": "{{projectSlug}}-metrics",
+      "database_id": "YOUR_D1_DATABASE_ID"
+    }
+  ],
+
+  // KV Namespaces
+  // TODO: Replace IDs with your KV namespace IDs
+  "kv_namespaces": [
+    {
+      "binding": "PLATFORM_CACHE",
+      "id": "YOUR_PLATFORM_CACHE_KV_ID"
+    },
+    {
+      "binding": "SERVICE_REGISTRY",
+      "id": "YOUR_SERVICE_REGISTRY_KV_ID"
+    }
+  ],
+
+  // Cron Triggers - Every 15 minutes
+  "triggers": {
+    "crons": ["*/15 * * * *"]
+  },
+
+  // Queue Producers (Platform SDK telemetry)
+  "queues": {
+    "producers": [
+      {
+        "queue": "platform-telemetry",
+        "binding": "PLATFORM_TELEMETRY"
+      }
+    ]
+  },
+
+  // Observability
+  "observability": {
+    "enabled": true,
+    "logs": {
+      "enabled": true,
+      "invocation_logs": true,
+      "head_sampling_rate": 1.0
+    },
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.1
+    }
+  },
+
+  // Source maps for readable stack traces
+  "upload_source_maps": true
+
+  // Tail Consumer (Error Collection) — uncomment if using error-collector
+  // "tail_consumers": [
+  //   { "service": "{{projectSlug}}-error-collector" }
+  // ]
+
+  // Secrets (add via: wrangler secret put <NAME> -c wrangler.{{projectSlug}}-mapper.jsonc)
+  // - CLOUDFLARE_API_TOKEN
+  // - CLOUDFLARE_ACCOUNT_ID
+  // - SLACK_WEBHOOK_URL (optional, for attribution alerts)
+  // - GATUS_TOKEN (optional, for heartbeat monitoring)
+}