@littlebearapps/create-platform 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,98 @@
+# Platform Admin SDK
+
+**`@littlebearapps/create-platform`** — Scaffold backend infrastructure for Cloudflare Workers cost protection.
+
+Generates workers, D1 migrations, and config files. Run once, then you own the code.
+
+## Usage
+
+```bash
+npx @littlebearapps/create-platform my-platform
+```
+
+The CLI prompts for:
+- **Project name** and slug
+- **GitHub organisation** (for error collection GitHub issues)
+- **Tier** — how much infrastructure to generate
+- **Gatus URL** (optional) — for heartbeat monitoring
+- **Default assignee** — GitHub username for error issues
+
+## Tiers
+
+| Tier | Workers | What You Get | Est. Cost |
+|------|---------|-------------|-----------|
+| **Minimal** | 1 | Budget enforcement, circuit breakers, usage telemetry | ~$0/mo |
+| **Standard** | 3 | + Error collector (auto GitHub issues), gap detection sentinel | ~$0/mo |
+| **Full** | 8 | + AI pattern discovery, alert router, notifications, search, settings | ~$5/mo |
+
+## What Gets Generated
+
+### All tiers
+
+```
+my-platform/
++-- platform/config/
+|   +-- services.yaml          # Project registry, feature definitions
+|   +-- budgets.yaml           # Daily limits, circuit breaker thresholds
++-- storage/d1/migrations/     # D1 schema (4 core migrations + seed)
++-- workers/
+|   +-- platform-usage.ts      # Data warehouse worker (cron + queue consumer)
+|   +-- lib/                   # Shared libraries (billing, analytics, budgets)
++-- scripts/
+|   +-- sync-config.ts         # Sync YAML config to D1/KV
++-- wrangler.*.jsonc           # Worker configs with binding placeholders
++-- package.json
++-- tsconfig.json
++-- README.md
+```
+
+### Standard tier adds
+
+- `workers/error-collector.ts` — Tail worker that creates GitHub issues from errors
+- `workers/platform-sentinel.ts` — Gap detection, cost monitoring, alerts
+- `workers/lib/error-collector/` — Fingerprinting, deduplication, digest
+- `workers/lib/sentinel/` — Project gap detection
+- `storage/d1/migrations/005_error_collection.sql`
+
+### Full tier adds
+
+- `workers/pattern-discovery.ts` — AI-assisted transient error pattern discovery
+- `workers/platform-alert-router.ts` — Unified alert normalisation and routing
+- `workers/platform-notifications.ts` — In-app notification API
+- `workers/platform-search.ts` — Full-text search (FTS5)
+- `workers/platform-settings.ts` — Settings management API
+- `workers/lib/pattern-discovery/` — Clustering, AI prompts, validation, shadow eval
+- `storage/d1/migrations/006_pattern_discovery.sql`
+- `storage/d1/migrations/007_notifications_search.sql`
+
+## Post-Scaffold Steps
+
+```bash
+cd my-platform
+npm install
+
+# Create Cloudflare resources
+npx wrangler d1 create my-platform-metrics
+npx wrangler kv namespace create PLATFORM_CACHE
+npx wrangler queues create my-platform-telemetry
+npx wrangler queues create my-platform-telemetry-dlq
+
+# Update resource IDs in wrangler.*.jsonc, then:
+npm run sync:config
+npx wrangler d1 migrations apply my-platform-metrics --remote
+npx wrangler deploy -c wrangler.my-platform-usage.jsonc
+```
+
+## Consumer SDK
+
+The generated workers use `@littlebearapps/platform-sdk` — the Consumer SDK. Install it in your application workers:
+
+```bash
+npm install @littlebearapps/platform-sdk
+```
+
+See the [Consumer SDK README](../sdk/README.md) for integration details.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -6,6 +6,11 @@
  * circuit breakers, and cost protection.
  *
  * Usage:
- *   npx @littlebearapps/create-platform [project-name]
+ *   npx @littlebearapps/create-platform [project-name] [options]
+ *
+ * Examples:
+ *   npx @littlebearapps/create-platform my-project
+ *   npx @littlebearapps/create-platform my-project --tier full --github-org myorg
+ *   npx @littlebearapps/create-platform my-project --tier minimal --skip-prompts
  */
 export {};

package/dist/index.js

@@ -6,20 +6,50 @@
  * circuit breakers, and cost protection.
  *
  * Usage:
- *   npx @littlebearapps/create-platform [project-name]
+ *   npx @littlebearapps/create-platform [project-name] [options]
+ *
+ * Examples:
+ *   npx @littlebearapps/create-platform my-project
+ *   npx @littlebearapps/create-platform my-project --tier full --github-org myorg
+ *   npx @littlebearapps/create-platform my-project --tier minimal --skip-prompts
  */
 import { resolve } from 'node:path';
+import { Command } from 'commander';
 import pc from 'picocolors';
-import { collectOptions } from './prompts.js';
+import { collectOptions, isValidTier } from './prompts.js';
 import { scaffold } from './scaffold.js';
 const BANNER = `
-  ${pc.bold(pc.cyan('Platform SDK'))} — Cloudflare Cost Protection
-  ${pc.dim('Automatic circuit breakers, budget enforcement, and error collection')}
+  ${pc.bold(pc.cyan('Platform Admin SDK'))} — Cloudflare Cost Protection
+  ${pc.dim('Scaffold backend infrastructure: circuit breakers, budget enforcement, error collection')}
 `;
+const program = new Command()
+    .name('create-platform')
+    .description('Scaffold a Cloudflare Workers platform with SDK integration')
+    .version('1.1.0')
+    .argument('[project-name]', 'Name of the project to create')
+    .option('--tier <tier>', 'Infrastructure tier (minimal, standard, full)')
+    .option('--github-org <org>', 'GitHub organisation for error issue creation')
+    .option('--gatus-url <url>', 'Gatus status page URL for heartbeat monitoring')
+    .option('--default-assignee <user>', 'Default GitHub assignee for error issues')
+    .option('--skip-prompts', 'Non-interactive mode — fail if required flags are missing');
 async function main() {
     console.log(BANNER);
-    const projectName = process.argv[2];
-    const options = await collectOptions(projectName);
+    program.parse();
+    const opts = program.opts();
+    const [projectNameArg] = program.args;
+    // Validate tier if provided
+    if (opts.tier && !isValidTier(opts.tier)) {
+        console.error(pc.red(`  Error: Invalid tier "${opts.tier}". Must be one of: minimal, standard, full`));
+        process.exit(1);
+    }
+    const options = await collectOptions({
+        projectName: projectNameArg,
+        tier: opts.tier,
+        githubOrg: opts.githubOrg,
+        gatusUrl: opts.gatusUrl,
+        defaultAssignee: opts.defaultAssignee,
+        skipPrompts: opts.skipPrompts,
+    });
     const outputDir = resolve(process.cwd(), options.projectName);
     console.log();
     console.log(`  ${pc.bold('Project')}: ${options.projectName}`);

package/dist/prompts.d.ts

@@ -1,7 +1,9 @@
 /**
  * Interactive CLI prompts for project scaffolding configuration.
  *
- * Falls back to sensible defaults when running non-interactively.
+ * When flags are provided via CLI, those values are used without prompting.
+ * Falls back to interactive prompts for missing values, or sensible defaults
+ * when running non-interactively.
  */
 export type Tier = 'minimal' | 'standard' | 'full';
 export interface ScaffoldOptions {
@@ -12,4 +14,14 @@ export interface ScaffoldOptions {
     gatusUrl: string;
     defaultAssignee: string;
 }
-export declare function collectOptions(projectNameArg?: string): Promise<ScaffoldOptions>;
+/** Pre-filled values from CLI flags. */
+export interface CLIFlags {
+    projectName?: string;
+    tier?: Tier;
+    githubOrg?: string;
+    gatusUrl?: string;
+    defaultAssignee?: string;
+    skipPrompts?: boolean;
+}
+export declare function isValidTier(value: string): value is Tier;
+export declare function collectOptions(flags?: CLIFlags): Promise<ScaffoldOptions>;

package/dist/prompts.js

@@ -1,9 +1,15 @@
 /**
  * Interactive CLI prompts for project scaffolding configuration.
  *
- * Falls back to sensible defaults when running non-interactively.
+ * When flags are provided via CLI, those values are used without prompting.
+ * Falls back to interactive prompts for missing values, or sensible defaults
+ * when running non-interactively.
  */
 import * as readline from 'node:readline';
+const VALID_TIERS = ['minimal', 'standard', 'full'];
+export function isValidTier(value) {
+    return VALID_TIERS.includes(value);
+}
 function slugify(name) {
     return name
         .toLowerCase()
@@ -40,13 +46,29 @@ async function promptSelect(question, options, defaultIndex = 0) {
     const idx = parseInt(answer, 10) - 1;
     return options[idx] ?? options[defaultIndex];
 }
-export async function collectOptions(projectNameArg) {
-    const projectName = projectNameArg || await prompt('Project name', 'my-platform');
+export async function collectOptions(flags = {}) {
+    if (flags.skipPrompts) {
+        if (!flags.projectName) {
+            throw new Error('--skip-prompts requires a project name argument');
+        }
+        if (!flags.tier) {
+            throw new Error('--skip-prompts requires --tier');
+        }
+        return {
+            projectName: flags.projectName,
+            projectSlug: slugify(flags.projectName),
+            githubOrg: flags.githubOrg ?? '',
+            tier: flags.tier,
+            gatusUrl: flags.gatusUrl ?? '',
+            defaultAssignee: flags.defaultAssignee ?? '',
+        };
+    }
+    const projectName = flags.projectName || await prompt('Project name', 'my-platform');
     const projectSlug = await prompt('Project slug (for resource names)', slugify(projectName));
-    const githubOrg = await prompt('GitHub org (for error issue creation)', '');
-    const tier = await promptSelect('Setup tier:', ['minimal', 'standard', 'full'], 1);
-    const gatusUrl = await prompt('Gatus status page URL (optional)', '');
-    const defaultAssignee = await prompt('Default GitHub assignee (optional)', '');
+    const tier = flags.tier || await promptSelect('Setup tier:', VALID_TIERS, 1);
+    const githubOrg = flags.githubOrg ?? await prompt('GitHub org (for error issue creation)', '');
+    const gatusUrl = flags.gatusUrl ?? await prompt('Gatus status page URL (optional)', '');
+    const defaultAssignee = flags.defaultAssignee ?? await prompt('Default GitHub assignee (optional)', '');
     return {
         projectName,
         projectSlug,

package/dist/templates.js

@@ -22,6 +22,54 @@ const SHARED_FILES = [
     { src: 'shared/package.json.hbs', dest: 'package.json', template: true },
     { src: 'shared/tsconfig.json', dest: 'tsconfig.json', template: false },
     { src: 'shared/README.md.hbs', dest: 'README.md', template: true },
+    // Workers — platform-usage (data warehouse, cron + queue consumer)
+    { src: 'shared/workers/platform-usage.ts', dest: 'workers/platform-usage.ts', template: false },
+    // Workers — root lib (shared utilities)
+    { src: 'shared/workers/lib/billing.ts', dest: 'workers/lib/billing.ts', template: false },
+    { src: 'shared/workers/lib/economics.ts', dest: 'workers/lib/economics.ts', template: false },
+    { src: 'shared/workers/lib/analytics-engine.ts', dest: 'workers/lib/analytics-engine.ts', template: false },
+    { src: 'shared/workers/lib/platform-settings.ts', dest: 'workers/lib/platform-settings.ts', template: false },
+    { src: 'shared/workers/lib/circuit-breaker-middleware.ts', dest: 'workers/lib/circuit-breaker-middleware.ts', template: false },
+    { src: 'shared/workers/lib/metrics.ts', dest: 'workers/lib/metrics.ts', template: false },
+    { src: 'shared/workers/lib/telemetry-sampling.ts', dest: 'workers/lib/telemetry-sampling.ts', template: false },
+    { src: 'shared/workers/lib/control.ts', dest: 'workers/lib/control.ts', template: false },
+    // Workers — lib/shared (cross-boundary types and utilities)
+    { src: 'shared/workers/lib/shared/types.ts', dest: 'workers/lib/shared/types.ts', template: false },
+    { src: 'shared/workers/lib/shared/allowances.ts', dest: 'workers/lib/shared/allowances.ts', template: false },
+    { src: 'shared/workers/lib/shared/cloudflare.ts', dest: 'workers/lib/shared/cloudflare.ts', template: false },
+    // Workers — lib/usage/shared
+    { src: 'shared/workers/lib/usage/shared/types.ts', dest: 'workers/lib/usage/shared/types.ts', template: false },
+    { src: 'shared/workers/lib/usage/shared/constants.ts', dest: 'workers/lib/usage/shared/constants.ts', template: false },
+    { src: 'shared/workers/lib/usage/shared/utils.ts', dest: 'workers/lib/usage/shared/utils.ts', template: false },
+    { src: 'shared/workers/lib/usage/shared/index.ts', dest: 'workers/lib/usage/shared/index.ts', template: false },
+    // Workers — lib/usage/handlers
+    { src: 'shared/workers/lib/usage/handlers/index.ts', dest: 'workers/lib/usage/handlers/index.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/data-queries.ts', dest: 'workers/lib/usage/handlers/data-queries.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/usage-metrics.ts', dest: 'workers/lib/usage/handlers/usage-metrics.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/usage-features.ts', dest: 'workers/lib/usage/handlers/usage-features.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/usage-settings.ts', dest: 'workers/lib/usage/handlers/usage-settings.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/usage-admin.ts', dest: 'workers/lib/usage/handlers/usage-admin.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/dlq-admin.ts', dest: 'workers/lib/usage/handlers/dlq-admin.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/health-trends.ts', dest: 'workers/lib/usage/handlers/health-trends.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/backfill.ts', dest: 'workers/lib/usage/handlers/backfill.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/audit.ts', dest: 'workers/lib/usage/handlers/audit.ts', template: false },
+    { src: 'shared/workers/lib/usage/handlers/behavioral.ts', dest: 'workers/lib/usage/handlers/behavioral.ts', template: false },
+    // Workers — lib/usage/queue
+    { src: 'shared/workers/lib/usage/queue/index.ts', dest: 'workers/lib/usage/queue/index.ts', template: false },
+    { src: 'shared/workers/lib/usage/queue/telemetry-processor.ts', dest: 'workers/lib/usage/queue/telemetry-processor.ts', template: false },
+    { src: 'shared/workers/lib/usage/queue/dlq-handler.ts', dest: 'workers/lib/usage/queue/dlq-handler.ts', template: false },
+    { src: 'shared/workers/lib/usage/queue/budget-enforcement.ts', dest: 'workers/lib/usage/queue/budget-enforcement.ts', template: false },
+    { src: 'shared/workers/lib/usage/queue/cost-calculator.ts', dest: 'workers/lib/usage/queue/cost-calculator.ts', template: false },
+    { src: 'shared/workers/lib/usage/queue/cost-budget-enforcement.ts', dest: 'workers/lib/usage/queue/cost-budget-enforcement.ts', template: false },
+    // Workers — lib/usage/scheduled
+    { src: 'shared/workers/lib/usage/scheduled/index.ts', dest: 'workers/lib/usage/scheduled/index.ts', template: false },
+    { src: 'shared/workers/lib/usage/scheduled/data-collection.ts', dest: 'workers/lib/usage/scheduled/data-collection.ts', template: false },
+    { src: 'shared/workers/lib/usage/scheduled/anomaly-detection.ts', dest: 'workers/lib/usage/scheduled/anomaly-detection.ts', template: false },
+    { src: 'shared/workers/lib/usage/scheduled/rollups.ts', dest: 'workers/lib/usage/scheduled/rollups.ts', template: false },
+    { src: 'shared/workers/lib/usage/scheduled/error-digest.ts', dest: 'workers/lib/usage/scheduled/error-digest.ts', template: false },
+    // Workers — lib/usage/collectors (pluggable interface + example)
+    { src: 'shared/workers/lib/usage/collectors/index.ts', dest: 'workers/lib/usage/collectors/index.ts', template: false },
+    { src: 'shared/workers/lib/usage/collectors/example.ts', dest: 'workers/lib/usage/collectors/example.ts', template: false },
 ];
 const STANDARD_FILES = [
     // Additional migrations
@@ -29,6 +77,20 @@ const STANDARD_FILES = [
     // Wrangler configs
     { src: 'standard/wrangler.error-collector.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-error-collector.jsonc', template: true },
     { src: 'standard/wrangler.sentinel.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-sentinel.jsonc', template: true },
+    // Workers — error-collector (tail worker → GitHub issues)
+    { src: 'standard/workers/error-collector.ts', dest: 'workers/error-collector.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/capture.ts', dest: 'workers/lib/error-collector/capture.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/fingerprint.ts', dest: 'workers/lib/error-collector/fingerprint.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/types.ts', dest: 'workers/lib/error-collector/types.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/github.ts', dest: 'workers/lib/error-collector/github.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/digest.ts', dest: 'workers/lib/error-collector/digest.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/gap-alerts.ts', dest: 'workers/lib/error-collector/gap-alerts.ts', template: false },
+    { src: 'standard/workers/lib/error-collector/email-health-alerts.ts', dest: 'workers/lib/error-collector/email-health-alerts.ts', template: false },
+    // Workers — platform-sentinel (gap detection, cost monitoring)
+    { src: 'standard/workers/platform-sentinel.ts', dest: 'workers/platform-sentinel.ts', template: false },
+    { src: 'standard/workers/lib/sentinel/gap-detection.ts', dest: 'workers/lib/sentinel/gap-detection.ts', template: false },
+    // Workers — shared lib (used by standard-tier workers)
+    { src: 'standard/workers/lib/shared/slack-alerts.ts', dest: 'workers/lib/shared/slack-alerts.ts', template: false },
 ];
 const FULL_FILES = [
     // Additional migrations
@@ -40,6 +102,22 @@ const FULL_FILES = [
     { src: 'full/wrangler.notifications.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-notifications.jsonc', template: true },
     { src: 'full/wrangler.search.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-search.jsonc', template: true },
     { src: 'full/wrangler.settings.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-settings.jsonc', template: true },
+    // Workers — pattern-discovery (AI-assisted transient error patterns)
+    { src: 'full/workers/pattern-discovery.ts', dest: 'workers/pattern-discovery.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/types.ts', dest: 'workers/lib/pattern-discovery/types.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/clustering.ts', dest: 'workers/lib/pattern-discovery/clustering.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/ai-prompt.ts', dest: 'workers/lib/pattern-discovery/ai-prompt.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/storage.ts', dest: 'workers/lib/pattern-discovery/storage.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/validation.ts', dest: 'workers/lib/pattern-discovery/validation.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/shadow-evaluation.ts', dest: 'workers/lib/pattern-discovery/shadow-evaluation.ts', template: false },
+    // Workers — platform-alert-router (unified alert normalisation)
+    { src: 'full/workers/platform-alert-router.ts', dest: 'workers/platform-alert-router.ts', template: false },
+    // Workers — platform-notifications (in-app notification API)
+    { src: 'full/workers/platform-notifications.ts', dest: 'workers/platform-notifications.ts', template: false },
+    // Workers — platform-search (full-text search FTS5)
+    { src: 'full/workers/platform-search.ts', dest: 'workers/platform-search.ts', template: false },
+    // Workers — platform-settings (settings management API)
+    { src: 'full/workers/platform-settings.ts', dest: 'workers/platform-settings.ts', template: false },
 ];
 export function getFilesForTier(tier) {
     const files = [...SHARED_FILES];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@littlebearapps/create-platform",
-  "version": "1.0.0",
-  "description": "Scaffold a Cloudflare Workers platform with SDK integration, circuit breakers, and cost protection",
+  "version": "1.1.0",
+  "description": "Platform Admin SDK — scaffold backend infrastructure with workers, circuit breakers, and cost protection for Cloudflare",
   "type": "module",
   "bin": {
     "create-platform": "./dist/index.js"
@@ -17,6 +17,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "commander": "^14.0.3",
     "handlebars": "^4.7.8",
     "picocolors": "^1.1.1"
   },