@littlebearapps/platform-admin-sdk 1.5.0 → 2.1.0

package/templates/shared/scripts/ops/backfill-monthly-rollups.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env npx tsx
+/**
+ * Monthly Rollup Backfill Script
+ *
+ * Aggregates daily_usage_rollups into monthly_usage_rollups via the D1 REST API.
+ * Queries existing daily data and rolls it up to monthly granularity.
+ *
+ * Prerequisites:
+ *   CLOUDFLARE_API_TOKEN  — API token with D1:Write permissions
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ *   D1_DATABASE_ID        — Your platform-metrics D1 database ID
+ *
+ * Usage:
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --dry-run
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --start 2026-01 --end 2026-03
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --limit 12
+ */
+
+const REST_API_BASE = 'https://api.cloudflare.com/client/v4';
+
+interface Args {
+  start?: string;
+  end?: string;
+  dryRun: boolean;
+  limit: number;
+}
+
+function parseArgs(): Args {
+  const args = process.argv.slice(2);
+  const result: Args = { dryRun: false, limit: 12 };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--start' && args[i + 1]) result.start = args[++i];
+    else if (args[i] === '--end' && args[i + 1]) result.end = args[++i];
+    else if (args[i] === '--limit' && args[i + 1]) result.limit = Number(args[++i]);
+    else if (args[i] === '--dry-run') result.dryRun = true;
+  }
+
+  if (!result.start) {
+    const d = new Date();
+    d.setMonth(d.getMonth() - 6);
+    result.start = d.toISOString().slice(0, 7);
+  }
+  if (!result.end) {
+    result.end = new Date().toISOString().slice(0, 7);
+  }
+
+  return result;
+}
+
+function getEnvOrThrow(key: string): string {
+  const val = process.env[key];
+  if (!val) throw new Error(`Missing required env var: ${key}`);
+  return val;
+}
+
+async function d1Query(accountId: string, dbId: string, token: string, sql: string, params: unknown[] = []) {
+  const res = await fetch(`${REST_API_BASE}/accounts/${accountId}/d1/database/${dbId}/query`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql, params }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`D1 query failed (${res.status}): ${text}`);
+  }
+  return res.json() as Promise<{ result: Array<{ results: unknown[] }> }>;
+}
+
+async function main() {
+  const args = parseArgs();
+  const token = getEnvOrThrow('CLOUDFLARE_API_TOKEN');
+  const accountId = getEnvOrThrow('CLOUDFLARE_ACCOUNT_ID');
+  const dbId = getEnvOrThrow('D1_DATABASE_ID');
+
+  console.log(`Backfilling monthly rollups: ${args.start} → ${args.end} (limit: ${args.limit}, dry-run: ${args.dryRun})`);
+
+  // Generate month list
+  const months: string[] = [];
+  const current = new Date(args.start + '-01');
+  const endDate = new Date(args.end + '-01');
+  while (current <= endDate && months.length < args.limit) {
+    months.push(current.toISOString().slice(0, 7));
+    current.setMonth(current.getMonth() + 1);
+  }
+
+  let inserted = 0;
+  for (const month of months) {
+    const monthStart = `${month}-01`;
+    const nextMonth = new Date(monthStart);
+    nextMonth.setMonth(nextMonth.getMonth() + 1);
+    const monthEnd = nextMonth.toISOString().slice(0, 10);
+
+    if (args.dryRun) {
+      console.log(`[DRY-RUN] Would roll up ${month}`);
+      continue;
+    }
+
+    await d1Query(accountId, dbId, token, `
+      INSERT OR REPLACE INTO monthly_usage_rollups (
+        project, snapshot_month,
+        d1_reads, d1_writes, kv_reads, kv_writes,
+        r2_reads, r2_writes, worker_requests, total_cost_usd
+      )
+      SELECT
+        project, ? as snapshot_month,
+        SUM(d1_reads), SUM(d1_writes), SUM(kv_reads), SUM(kv_writes),
+        SUM(r2_reads), SUM(r2_writes), SUM(worker_requests), SUM(total_cost_usd)
+      FROM daily_usage_rollups
+      WHERE project = 'all' AND snapshot_date >= ? AND snapshot_date < ?
+      GROUP BY project
+    `, [month, monthStart, monthEnd]);
+
+    inserted++;
+    console.log(`  Rolled up ${month} (${inserted}/${months.length})`);
+  }
+
+  console.log(`Done. Inserted ${inserted} monthly rollup rows.`);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/templates/shared/scripts/ops/validate-controls.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Validate Controls Script
+ *
+ * Validates budgets.yaml configuration:
+ * - No zero or negative limits
+ * - All features have d1_write_limit
+ * - Warns on suspiciously high/low values
+ * - Checks for orphaned entries (feature keys not in services.yaml)
+ *
+ * Usage:
+ *   node scripts/ops/validate-controls.js
+ *   node scripts/ops/validate-controls.js --strict
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'yaml';
+
+const ROOT = resolve(import.meta.dirname, '..', '..');
+const strict = process.argv.includes('--strict');
+
+let exitCode = 0;
+let warnings = 0;
+let errors = 0;
+
+function warn(msg) {
+  console.warn(`  WARN: ${msg}`);
+  warnings++;
+  if (strict) exitCode = 1;
+}
+
+function error(msg) {
+  console.error(`  ERROR: ${msg}`);
+  errors++;
+  exitCode = 1;
+}
+
+function normaliseBudgetValue(val) {
+  if (typeof val === 'number') return val;
+  if (typeof val === 'string') return Number(val.replace(/_/g, ''));
+  return NaN;
+}
+
+// Load budgets.yaml
+let budgets;
+try {
+  const raw = readFileSync(resolve(ROOT, 'platform/config/budgets.yaml'), 'utf-8');
+  budgets = parse(raw);
+} catch (err) {
+  console.error('Failed to load budgets.yaml:', err.message);
+  process.exit(1);
+}
+
+// Load services.yaml for cross-reference
+let services;
+try {
+  const raw = readFileSync(resolve(ROOT, 'platform/config/services.yaml'), 'utf-8');
+  services = parse(raw);
+} catch {
+  services = null;
+}
+
+console.log('Validating budgets.yaml...\n');
+
+// Validate feature budgets
+const featureBudgets = budgets?.features ?? budgets?.feature_budgets ?? {};
+const featureKeys = Object.keys(featureBudgets);
+
+console.log(`Found ${featureKeys.length} feature budget entries\n`);
+
+for (const key of featureKeys) {
+  const budget = featureBudgets[key];
+  console.log(`  Checking ${key}...`);
+
+  if (!budget || typeof budget !== 'object') {
+    error(`${key}: budget is not an object`);
+    continue;
+  }
+
+  // Check for zero limits
+  for (const [field, rawValue] of Object.entries(budget)) {
+    const value = normaliseBudgetValue(rawValue);
+    if (isNaN(value)) {
+      error(`${key}.${field}: value "${rawValue}" is not a valid number`);
+    } else if (value <= 0) {
+      error(`${key}.${field}: value is ${value} (must be positive)`);
+    } else if (value < 100 && field.includes('d1')) {
+      warn(`${key}.${field}: suspiciously low D1 limit (${value})`);
+    } else if (value > 100_000_000_000) {
+      warn(`${key}.${field}: suspiciously high limit (${value})`);
+    }
+  }
+
+  // Check for d1_write_limit
+  const hasD1Write = Object.keys(budget).some(
+    (f) => f.includes('d1') && (f.includes('write') || f.includes('written'))
+  );
+  if (!hasD1Write) {
+    warn(`${key}: no d1_write_limit or d1_rows_written field`);
+  }
+
+  // Check feature key format (project:category:feature)
+  const parts = key.split(':');
+  if (parts.length < 3) {
+    warn(`${key}: feature key should have format project:category:feature (has ${parts.length} parts)`);
+  }
+}
+
+// Cross-reference with services.yaml
+if (services) {
+  const registeredProjects = new Set();
+  const projects = services?.projects ?? [];
+  for (const p of Array.isArray(projects) ? projects : Object.keys(projects)) {
+    const name = typeof p === 'string' ? p : p?.name ?? p?.id;
+    if (name) registeredProjects.add(name);
+  }
+
+  for (const key of featureKeys) {
+    const project = key.split(':')[0];
+    if (registeredProjects.size > 0 && !registeredProjects.has(project)) {
+      warn(`${key}: project "${project}" not found in services.yaml`);
+    }
+  }
+}
+
+// Global budget check
+const globalBudget = budgets?.global ?? budgets?.global_budget;
+if (!globalBudget) {
+  warn('No global budget section found');
+} else {
+  for (const [field, rawValue] of Object.entries(globalBudget)) {
+    const value = normaliseBudgetValue(rawValue);
+    if (isNaN(value) || value <= 0) {
+      error(`global.${field}: invalid value "${rawValue}"`);
+    }
+  }
+}
+
+console.log(`\nResults: ${errors} errors, ${warnings} warnings`);
+process.exit(exitCode);

package/templates/shared/tests/contract/validate-schemas.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Contract Tests for JSON Schemas
+ *
+ * Validates telemetry envelope + error report schemas against fixtures.
+ * Ensures contracts remain valid as schemas evolve.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function loadJson(relativePath: string): unknown {
+  const fullPath = resolve(__dirname, '..', '..', relativePath);
+  return JSON.parse(readFileSync(fullPath, 'utf-8'));
+}
+
+// ===========================================================================
+// Envelope Schema
+// ===========================================================================
+
+describe('telemetry envelope schema', () => {
+  const schema = loadJson('contracts/schemas/envelope.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required version 1 schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+    expect(Array.isArray(schema.required)).toBe(true);
+  });
+
+  it('requires core fields', () => {
+    const required = schema.required ?? [];
+    expect(required).toContain('version');
+    expect(required).toContain('project');
+    expect(required).toContain('feature');
+  });
+
+  it('defines resource_usage properties', () => {
+    const props = schema.properties ?? {};
+    expect(props.resource_usage).toBeDefined();
+  });
+});
+
+// ===========================================================================
+// Valid Fixture
+// ===========================================================================
+
+describe('valid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-valid.json') as Record<string, unknown>;
+
+  it('has version 1', () => {
+    expect(fixture.version).toBe(1);
+  });
+
+  it('has valid project and feature format', () => {
+    expect(typeof fixture.project).toBe('string');
+    expect(typeof fixture.feature).toBe('string');
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('has resource_usage with numeric values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    expect(usage).toBeDefined();
+    expect(typeof usage.d1_reads).toBe('number');
+    expect(typeof usage.d1_writes).toBe('number');
+    expect(usage.d1_reads).toBeGreaterThanOrEqual(0);
+    expect(usage.d1_writes).toBeGreaterThanOrEqual(0);
+  });
+
+  it('has valid handler_type', () => {
+    expect(['fetch', 'scheduled', 'queue', 'alarm', 'tail']).toContain(fixture.handler_type);
+  });
+
+  it('has valid outcome', () => {
+    expect(['ok', 'error', 'exception', 'canceled']).toContain(fixture.outcome);
+  });
+});
+
+// ===========================================================================
+// Invalid Fixture
+// ===========================================================================
+
+describe('invalid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-invalid.json') as Record<string, unknown>;
+
+  it('has wrong version', () => {
+    expect(fixture.version).not.toBe(1);
+  });
+
+  it('has empty project', () => {
+    expect(fixture.project).toBe('');
+  });
+
+  it('has malformed feature ID (missing colons)', () => {
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeLessThan(3);
+  });
+
+  it('has invalid resource_usage values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    const hasInvalid = Object.values(usage).some(
+      (v) => typeof v !== 'number' || v < 0
+    );
+    expect(hasInvalid).toBe(true);
+  });
+});
+
+// ===========================================================================
+// Error Report Schema
+// ===========================================================================
+
+describe('error report schema', () => {
+  const schema = loadJson('contracts/schemas/error_report.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+  });
+
+  it('requires error identification fields', () => {
+    const required = schema.required ?? [];
+    expect(required.length).toBeGreaterThan(0);
+  });
+});