@littlebearapps/create-platform 1.0.0

package/templates/shared/package.json.hbs

@@ -0,0 +1,21 @@
+{
+  "name": "{{projectSlug}}-platform",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "sync:config": "npx tsx scripts/sync-config.ts",
+    "deploy:usage": "wrangler deploy -c wrangler.{{projectSlug}}-usage.jsonc"
+  },
+  "dependencies": {
+    "@littlebearapps/platform-sdk": "^{{sdkVersion}}",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250214.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.3",
+    "wrangler": "^3.100.0"
+  }
+}

package/templates/shared/scripts/sync-config.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env npx tsx
+/**
+ * Sync Service Registry Configuration
+ *
+ * Reads services.yaml and budgets.yaml from platform/config/ and syncs to:
+ * - D1: project_registry + feature_registry tables
+ * - KV: CONFIG:FEATURE:{feature_key}:BUDGET keys
+ *
+ * Usage:
+ *   npx tsx scripts/sync-config.ts [--dry-run] [--verbose]
+ *
+ * YAML files in git are the Source of Truth.
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { parse as parseYAML } from 'yaml';
+
+// =============================================================================
+// CONFIGURATION — Update these after creating your Cloudflare resources
+// =============================================================================
+
+const CONFIG_DIR = join(process.cwd(), 'platform', 'config');
+const SERVICES_FILE = join(CONFIG_DIR, 'services.yaml');
+const BUDGETS_FILE = join(CONFIG_DIR, 'budgets.yaml');
+
+// TODO: Replace with your actual KV namespace ID and D1 database name
+const KV_NAMESPACE_ID = 'YOUR_KV_NAMESPACE_ID';
+const D1_DATABASE_NAME = 'YOUR_D1_DATABASE_NAME';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface FeatureDefinition {
+  display_name: string;
+  feature_id?: string;
+  circuit_breaker: boolean;
+  description?: string;
+  cost_tier: string;
+}
+
+interface FeatureCategory {
+  [feature: string]: FeatureDefinition;
+}
+
+interface Project {
+  display_name: string;
+  status: string;
+  tier: string;
+  repository?: string;
+  features?: Record<string, FeatureCategory>;
+}
+
+interface Services {
+  metadata: { version: string };
+  projects: Record<string, Project>;
+}
+
+interface BudgetLimit {
+  d1_writes?: number;
+  d1_reads?: number;
+  kv_reads?: number;
+  kv_writes?: number;
+  queue_messages?: number;
+  requests?: number;
+  cpu_ms?: number;
+}
+
+interface Budgets {
+  defaults: {
+    daily: BudgetLimit;
+    circuit_breaker: {
+      auto_reset_seconds: number;
+      cooldown_seconds: number;
+    };
+    thresholds: { warning: number; critical: number };
+  };
+  feature_overrides: Record<string, BudgetLimit>;
+}
+
+// =============================================================================
+// YAML 1.2 UNDERSCORE FIX
+// =============================================================================
+
+/**
+ * YAML 1.2 parses numbers with underscores (e.g. 1_000_000) as strings.
+ * This normalises them back to numbers.
+ */
+function normaliseBudgetLimits(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'string' && /^\d[\d_]*$/.test(obj)) {
+    return Number(obj.replace(/_/g, ''));
+  }
+  if (Array.isArray(obj)) return obj.map(normaliseBudgetLimits);
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+      result[key] = normaliseBudgetLimits(value);
+    }
+    return result;
+  }
+  return obj;
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const VERBOSE = process.argv.includes('--verbose');
+
+function log(msg: string): void {
+  console.log(`[sync-config] ${msg}`);
+}
+
+function verbose(msg: string): void {
+  if (VERBOSE) console.log(`  ${msg}`);
+}
+
+function sanitise(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+function runD1(sql: string): void {
+  if (DRY_RUN) {
+    verbose(`[dry-run] D1: ${sql.substring(0, 100)}...`);
+    return;
+  }
+
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sync-config-'));
+  const sqlFile = join(tmpDir, 'query.sql');
+  writeFileSync(sqlFile, sql);
+
+  try {
+    execSync(
+      `wrangler d1 execute ${D1_DATABASE_NAME} --remote --file="${sqlFile}"`,
+      { stdio: VERBOSE ? 'inherit' : 'pipe' }
+    );
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+function runKVPut(key: string, value: string): void {
+  if (DRY_RUN) {
+    verbose(`[dry-run] KV PUT: ${key} = ${value.substring(0, 60)}...`);
+    return;
+  }
+
+  execSync(
+    `wrangler kv key put --namespace-id="${KV_NAMESPACE_ID}" "${key}" '${sanitise(value)}'`,
+    { stdio: VERBOSE ? 'inherit' : 'pipe' }
+  );
+}
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+function main(): void {
+  log('Starting config sync...');
+
+  if (!existsSync(SERVICES_FILE)) {
+    console.error(`Missing: ${SERVICES_FILE}`);
+    process.exit(1);
+  }
+  if (!existsSync(BUDGETS_FILE)) {
+    console.error(`Missing: ${BUDGETS_FILE}`);
+    process.exit(1);
+  }
+
+  const services = normaliseBudgetLimits(
+    parseYAML(readFileSync(SERVICES_FILE, 'utf-8'))
+  ) as Services;
+  const budgets = normaliseBudgetLimits(
+    parseYAML(readFileSync(BUDGETS_FILE, 'utf-8'))
+  ) as Budgets;
+
+  // Sync projects to D1 project_registry
+  const projectSql: string[] = [];
+  for (const [projectId, project] of Object.entries(services.projects)) {
+    projectSql.push(
+      `INSERT INTO project_registry (project_id, display_name, status, tier, repository)
+       VALUES ('${sanitise(projectId)}', '${sanitise(project.display_name)}', '${sanitise(project.status)}', '${sanitise(String(project.tier))}', '${sanitise(project.repository ?? '')}')
+       ON CONFLICT (project_id) DO UPDATE SET
+         display_name = excluded.display_name,
+         status = excluded.status,
+         tier = excluded.tier,
+         repository = excluded.repository;`
+    );
+  }
+
+  if (projectSql.length > 0) {
+    log(`Syncing ${projectSql.length} project(s) to D1...`);
+    runD1(projectSql.join('\n'));
+  }
+
+  // Sync features to D1 feature_registry + KV budgets
+  let featureCount = 0;
+  const featureSql: string[] = [];
+
+  for (const [projectId, project] of Object.entries(services.projects)) {
+    if (!project.features) continue;
+
+    for (const [category, features] of Object.entries(project.features)) {
+      for (const [featureName, feature] of Object.entries(features)) {
+        const featureKey = feature.feature_id ?? `${projectId}:${category}:${featureName}`;
+        const cbEnabled = feature.circuit_breaker ? 1 : 0;
+
+        featureSql.push(
+          `INSERT INTO feature_registry (feature_key, project, category, feature, display_name, circuit_breaker_enabled, cost_tier)
+           VALUES ('${sanitise(featureKey)}', '${sanitise(projectId)}', '${sanitise(category)}', '${sanitise(featureName)}', '${sanitise(feature.display_name)}', ${cbEnabled}, '${sanitise(feature.cost_tier)}')
+           ON CONFLICT (feature_key) DO UPDATE SET
+             display_name = excluded.display_name,
+             circuit_breaker_enabled = excluded.circuit_breaker_enabled,
+             cost_tier = excluded.cost_tier;`
+        );
+
+        // Sync budget to KV
+        const override = budgets.feature_overrides?.[featureKey];
+        const budget = override ?? budgets.defaults.daily;
+        const kvKey = `CONFIG:FEATURE:${featureKey}:BUDGET`;
+        runKVPut(kvKey, JSON.stringify(budget));
+
+        featureCount++;
+      }
+    }
+  }
+
+  if (featureSql.length > 0) {
+    log(`Syncing ${featureCount} feature(s) to D1...`);
+    runD1(featureSql.join('\n'));
+  }
+
+  log(`Done! ${projectSql.length} projects, ${featureCount} features synced.`);
+  if (DRY_RUN) log('(dry run — no changes made)');
+}
+
+main();

package/templates/shared/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["workers/**/*", "scripts/**/*"]
+}

package/templates/shared/wrangler.usage.jsonc.hbs

@@ -0,0 +1,58 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "{{projectSlug}}-usage",
+  "main": "workers/platform-usage.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "observability": { "enabled": true },
+
+  // Cron: hourly data collection + midnight rollups
+  "triggers": {
+    "crons": ["0 * * * *", "0 0 * * *"]
+  },
+
+  "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": {
+    "consumers": [
+      {
+        "queue": "{{projectSlug}}-telemetry",
+        "max_batch_size": 100,
+        "max_batch_timeout": 30,
+        "dead_letter_queue": "{{projectSlug}}-telemetry-dlq",
+        "max_retries": 3
+      }
+    ],
+    "producers": [
+      { "binding": "TELEMETRY_QUEUE", "queue": "{{projectSlug}}-telemetry" },
+      { "binding": "TELEMETRY_DLQ", "queue": "{{projectSlug}}-telemetry-dlq" }
+    ]
+  },
+
+  "analytics_engine_datasets": [
+    { "binding": "PLATFORM_ANALYTICS", "dataset": "{{projectSlug}}-analytics" }
+  ],
+
+  "vars": {
+    "CLOUDFLARE_ACCOUNT_ID": "YOUR_CLOUDFLARE_ACCOUNT_ID"
+  }
+
+  // Uncomment when you add error-collector (standard tier):
+  // "services": [
+  //   { "binding": "NOTIFICATIONS_API", "service": "{{projectSlug}}-notifications" }
+  // ]
+}

package/templates/standard/migrations/005_error_collection.sql

@@ -0,0 +1,162 @@
+-- =============================================================================
+-- 005_error_collection.sql — Error tracking (standard tier)
+-- =============================================================================
+-- Consolidated from original migrations: 038, 039, 041, 043
+--
+-- Tables:
+--   error_occurrences      — Error tracking with deduplication and GitHub linkage
+--   warning_digests        — Daily digest tracking for P4 warnings
+--   fingerprint_decisions  — Fingerprint decision audit log for post-hoc analysis
+--
+-- The error_occurrences table uses the FINAL schema from migration 043 which
+-- recreated the table with the correct CHECK constraint (adding 'pending_digest'
+-- and 'digested' status values) and merged columns from 039 and 041.
+-- =============================================================================
+
+
+-- =============================================================================
+-- ERROR OCCURRENCES (final schema from 043, merging 038 + 039 + 041)
+-- =============================================================================
+-- Error tracking table for deduplication, GitHub issue linkage, and history.
+-- Includes digest columns (from 039) and error_category (from 041).
+
+CREATE TABLE IF NOT EXISTS error_occurrences (
+  id TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  script_name TEXT NOT NULL,
+  project TEXT NOT NULL,
+  error_type TEXT NOT NULL CHECK (error_type IN ('exception', 'cpu_limit', 'memory_limit', 'soft_error', 'warning')),
+  priority TEXT NOT NULL CHECK (priority IN ('P0', 'P1', 'P2', 'P3', 'P4')),
+
+  -- GitHub linkage
+  github_issue_number INTEGER,
+  github_issue_url TEXT,
+  github_repo TEXT NOT NULL,
+
+  -- Status tracking (includes 'pending_digest' and 'digested' from 043)
+  status TEXT DEFAULT 'open' CHECK (status IN ('open', 'resolved', 'wont_fix', 'pending_digest', 'digested')),
+  resolved_at INTEGER,
+  resolved_by TEXT,                        -- Commit SHA or 'auto-close'
+
+  -- Occurrence tracking
+  first_seen_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  occurrence_count INTEGER DEFAULT 1,
+
+  -- Request context (last occurrence)
+  last_request_url TEXT,
+  last_request_method TEXT,
+  last_colo TEXT,
+  last_country TEXT,
+  last_cf_ray TEXT,
+
+  -- Error details (last occurrence)
+  last_exception_name TEXT,
+  last_exception_message TEXT,
+  last_logs_json TEXT,                     -- JSON array of last 20 log entries
+
+  -- Digest columns (from 039)
+  digest_date TEXT,
+  digest_issue_number INTEGER,
+  normalized_message TEXT,
+
+  -- Error category for transient error grouping (from 041)
+  error_category TEXT,
+
+  -- Timestamps
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch()),
+
+  UNIQUE(fingerprint)
+);
+
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_status ON error_occurrences(status);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_project ON error_occurrences(project);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_script ON error_occurrences(script_name);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_fingerprint ON error_occurrences(fingerprint);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_last_seen ON error_occurrences(last_seen_at DESC);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_priority ON error_occurrences(priority, status);
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_github ON error_occurrences(github_issue_number) WHERE github_issue_number IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_pending_digest ON error_occurrences(status, error_type, script_name, fingerprint) WHERE status = 'pending_digest';
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_digest_date ON error_occurrences(digest_date, script_name) WHERE digest_date IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_error_occurrences_category ON error_occurrences(error_category) WHERE error_category IS NOT NULL;
+
+
+-- =============================================================================
+-- WARNING DIGESTS (from 039)
+-- =============================================================================
+-- Tracks daily digest issues. Allows finding/updating existing digest issues
+-- for a given day to batch P4 warnings into single GitHub issues.
+
+CREATE TABLE IF NOT EXISTS warning_digests (
+  id TEXT PRIMARY KEY,
+  digest_date TEXT NOT NULL,               -- YYYY-MM-DD
+  script_name TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,               -- Normalised fingerprint (groups similar warnings)
+  normalized_message TEXT NOT NULL,        -- Human-readable warning type
+  github_repo TEXT NOT NULL,
+  github_issue_number INTEGER,
+  github_issue_url TEXT,
+  occurrence_count INTEGER DEFAULT 0,
+  first_occurrence_at INTEGER NOT NULL,
+  last_occurrence_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(digest_date, script_name, fingerprint)
+);
+
+CREATE INDEX IF NOT EXISTS idx_warning_digests_lookup
+  ON warning_digests(digest_date, script_name);
+
+
+-- =============================================================================
+-- FINGERPRINT DECISIONS (from 041)
+-- =============================================================================
+-- Stores fingerprint decisions for post-hoc analysis of error classification.
+-- Tracks why each error was handled the way it was.
+
+CREATE TABLE IF NOT EXISTS fingerprint_decisions (
+  id TEXT PRIMARY KEY,
+  timestamp INTEGER NOT NULL DEFAULT (unixepoch()),
+
+  -- Context
+  script_name TEXT NOT NULL,
+  error_type TEXT NOT NULL,
+
+  -- Fingerprint details
+  raw_message TEXT,                        -- Original error message (first 500 chars)
+  normalized_message TEXT,                 -- Normalised message used for fingerprinting
+  computed_fingerprint TEXT NOT NULL,
+  category TEXT,                           -- Transient error category if classified
+
+  -- Decision outcome
+  decision TEXT NOT NULL CHECK (decision IN (
+    'new_issue',                           -- Created new GitHub issue
+    'existing_issue',                      -- Updated existing issue
+    'transient_window',                    -- Transient error, issue exists for today
+    'suppressed',                          -- Suppressed (e.g., muted issue)
+    'rate_limited',                        -- Rate limited, no action taken
+    'digest'                               -- Stored for daily digest
+  )),
+
+  -- GitHub linkage
+  github_issue_number INTEGER,
+  github_repo TEXT,
+
+  -- Metadata
+  is_transient INTEGER DEFAULT 0,
+  occurrence_count INTEGER,
+
+  created_at INTEGER DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_fingerprint_decisions_script
+  ON fingerprint_decisions(script_name, timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_fingerprint_decisions_fingerprint
+  ON fingerprint_decisions(computed_fingerprint);
+CREATE INDEX IF NOT EXISTS idx_fingerprint_decisions_category
+  ON fingerprint_decisions(category) WHERE category IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_fingerprint_decisions_decision
+  ON fingerprint_decisions(decision, timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_fingerprint_decisions_timestamp
+  ON fingerprint_decisions(timestamp DESC);

package/templates/standard/wrangler.error-collector.jsonc.hbs

@@ -0,0 +1,44 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "{{projectSlug}}-error-collector",
+  "main": "workers/error-collector.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "observability": { "enabled": true },
+
+  // Cron: 15-minute error processing + midnight daily digest
+  "triggers": {
+    "crons": ["*/15 * * * *", "0 0 * * *"]
+  },
+
+  // Tail worker: receives logs from other workers
+  "tail_consumers": [
+    { "service": "{{projectSlug}}-usage" }
+  ],
+
+  "d1_databases": [
+    {
+      "binding": "PLATFORM_DB",
+      "database_name": "{{projectSlug}}-metrics",
+      "database_id": "YOUR_D1_DATABASE_ID"
+    }
+  ],
+
+  "kv_namespaces": [
+    {
+      "binding": "PLATFORM_CACHE",
+      "id": "YOUR_KV_NAMESPACE_ID"
+    }
+  ],
+
+  "vars": {
+    "GITHUB_ORG": "{{githubOrg}}",
+    "DEFAULT_ASSIGNEE": "{{defaultAssignee}}",
+    "GATUS_HEARTBEAT_URL": "{{gatusUrl}}"
+  }
+
+  // Secrets needed (set via wrangler secret put):
+  //   GITHUB_APP_ID
+  //   GITHUB_APP_PRIVATE_KEY
+  //   GITHUB_APP_INSTALLATION_ID
+}

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

@@ -0,0 +1,45 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "{{projectSlug}}-sentinel",
+  "main": "workers/platform-sentinel.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "observability": { "enabled": true },
+
+  // Cron: 15-minute gap detection + cost spike monitoring
+  "triggers": {
+    "crons": ["*/15 * * * *"]
+  },
+
+  "d1_databases": [
+    {
+      "binding": "PLATFORM_DB",
+      "database_name": "{{projectSlug}}-metrics",
+      "database_id": "YOUR_D1_DATABASE_ID"
+    }
+  ],
+
+  "kv_namespaces": [
+    {
+      "binding": "PLATFORM_CACHE",
+      "id": "YOUR_KV_NAMESPACE_ID"
+    },
+    {
+      "binding": "PLATFORM_ALERTS",
+      "id": "YOUR_KV_ALERTS_NAMESPACE_ID"
+    }
+  ],
+
+  "services": [
+    { "binding": "ERROR_COLLECTOR", "service": "{{projectSlug}}-error-collector" }
+  ],
+
+  "vars": {
+    "CLOUDFLARE_ACCOUNT_ID": "YOUR_CLOUDFLARE_ACCOUNT_ID",
+    "GATUS_HEARTBEAT_URL": "{{gatusUrl}}"
+  }
+
+  // Secrets needed (set via wrangler secret put):
+  //   CLOUDFLARE_API_TOKEN
+  //   SLACK_WEBHOOK_URL (optional)
+}