@crossdelta/platform-sdk 0.13.2 → 0.13.4

package/bin/templates/hono-microservice/src/index.ts.hbs

@@ -0,0 +1,18 @@
+// IMPORTANT: telemetry must be imported first to patch modules before they're loaded
+import '@crossdelta/telemetry'
+
+import { Hono } from 'hono'
+
+const port = Number(process.env.{{envKey}}_PORT) || 8080
+const app = new Hono()
+
+app.get('/health', (c) => {
+  return c.json({ status: 'ok' })
+})
+
+Bun.serve({
+  port,
+  fetch: app.fetch,
+})
+
+console.log(`🚀 Service ready at http://localhost:${port}`)

package/bin/templates/hono-microservice/tsconfig.json.hbs

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "lib": ["ES2022"],
+    "types": ["bun"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}

package/bin/templates/nest-microservice/Dockerfile.hbs

@@ -0,0 +1,37 @@
+ARG NODE_VERSION={{nodeVersion}}
+ARG BUN_VERSION={{bunVersion}}
+
+# STAGE 1 — Build
+FROM oven/bun:${BUN_VERSION}-alpine AS builder
+WORKDIR /app
+
+COPY package.json tsconfig*.json nest-cli.json ./
+COPY src ./src
+
+RUN --mount=type=secret,id=NPM_TOKEN \
+  export NPM_TOKEN="$(cat /run/secrets/NPM_TOKEN)" && \
+  bun install
+
+RUN bun run build
+
+# STAGE 2 — Production dependencies
+FROM oven/bun:${BUN_VERSION}-alpine AS deps
+WORKDIR /app
+
+COPY package.json ./
+
+RUN --mount=type=secret,id=NPM_TOKEN \
+  export NPM_TOKEN="$(cat /run/secrets/NPM_TOKEN)" && \
+  bun install --production --omit=optional
+
+# STAGE 3 — Runtime
+FROM node:${NODE_VERSION}-alpine AS production
+WORKDIR /app
+
+COPY --from=builder /app/dist ./dist
+COPY --from=deps /app/node_modules ./node_modules
+
+USER node
+ENV NODE_ENV=production
+
+CMD ["node", "dist/main.js"]

package/bin/templates/nest-microservice/biome.json.hbs

@@ -0,0 +1,3 @@
+{
+  "extends": ["../../biome.json"]
+}

package/bin/templates/nest-microservice/src/app.context.ts.hbs

@@ -0,0 +1,17 @@
+import type { INestApplication, Type } from '@nestjs/common'
+
+let app: INestApplication
+
+export const setAppContext = (nestApp: INestApplication): void => {
+  app = nestApp
+}
+
+export const getAppContext = (): INestApplication => {
+  if (!app) throw new Error('App context not initialized')
+  return app
+}
+
+export const getService = <T>(serviceClass: Type<T>): T => {
+  return getAppContext().get(serviceClass)
+}
+

package/bin/templates/nest-microservice/src/events/events.module.ts.hbs

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common'
+import { EventsService } from './events.service'
+
+@Module({
+  providers: [EventsService],
+  exports: [EventsService],
+})
+export class EventsModule {}

package/bin/templates/nest-microservice/src/events/events.service.ts.hbs

@@ -0,0 +1,22 @@
+import { Injectable, Logger } from '@nestjs/common'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
+
+@Injectable()
+export class EventsService {
+  private readonly logger = new Logger(EventsService.name)
+
+  async startConsumers(): Promise<void> {
+    // Services NEVER create streams!
+    // - Development: pf dev auto-creates ephemeral streams from contracts
+    // - Production: Pulumi materializes persistent streams
+
+    // Uncomment and configure when you have events:
+    // consumeJetStreams({
+    //   streams: ['ORDERS'],
+    //   consumer: '{{serviceName}}',
+    //   discover: './src/events/**/*.event.ts',
+    // })
+
+    this.logger.log('Event consumers ready')
+  }
+}

package/bin/templates/nest-microservice/src/main.ts.hbs

@@ -0,0 +1,34 @@
+// IMPORTANT: telemetry must be imported first to patch modules before they're loaded
+import '@crossdelta/telemetry'
+
+import { env } from 'node:process'
+import { ConsoleLogger } from '@nestjs/common'
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+import { setAppContext } from './app.context'
+import { EventsService } from './events/events.service'
+
+const port = Number(process.env.{{envKey}}_PORT) || {{defaultPort}}
+const serviceName = '{{displayName}}'
+
+const logger = new ConsoleLogger({
+  json: env.JSON_LOGS === 'true',
+  prefix: serviceName,
+})
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { logger })
+
+  // Make app context available to event handlers
+  setAppContext(app)
+
+  // Start NATS event consumers
+  const eventsService = app.get(EventsService)
+  await eventsService.startConsumers()
+
+  await app
+    .listen(port)
+    .then(() => logger.log(`${serviceName} is running on port ${port}`))
+}
+
+bootstrap()

package/bin/templates/workspace/biome.json.hbs

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+  "formatter": {
+    "indentStyle": "space"
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "security": {
+        "recommended": true
+      },
+      "style": {
+        "recommended": true,
+        "useAsConstAssertion": "warn",
+        "noUselessElse": "error",
+        "useConst": "error",
+        "useImportType": "off"
+      },
+      "complexity": {
+        "recommended": true,
+        "noUselessEmptyExport": "error",
+        "noExcessiveCognitiveComplexity": {
+          "level": "warn",
+          "options": {
+            "maxAllowedComplexity": 15
+          }
+        }
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "indentWidth": 2,
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "lineWidth": 120,
+      "trailingCommas": "all",
+      "arrowParentheses": "always"
+    }
+  },
+  "files": {
+    "includes": [
+      "**/src/**/*.ts",
+      "infra/**/*.ts",
+      "!apps/storefront",
+      "!**/vendor",
+      "!**/dist",
+      "!**/node_modules",
+      "!reports",
+      "!coverage",
+      "!stryker-tmp",
+      "!**/.stryker-tmp"
+    ]
+  }
+}

package/bin/templates/workspace/bunfig.toml.hbs

@@ -0,0 +1,5 @@
+[install]
+workspaces = ["packages/*", "apps/*", "services/*"]
+
+[install.scopes]
+"@{{projectName}}" = { url = "https://npm.pkg.github.com", token = "$NPM_TOKEN" }

package/bin/templates/workspace/editorconfig.hbs

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

package/bin/templates/workspace/gitignore.hbs

@@ -0,0 +1,15 @@
+out/
+.env
+.turbo
+.idea/
+.temp
+.vscode/
+.env.local
+.temp/
+node_modules
+.artifacts/
+.changed/
+.nats-data
+dist/
+coverage/
+*.log

package/bin/templates/workspace/infra/Pulumi.dev.yaml.hbs

@@ -0,0 +1,5 @@
+config:
+  {{projectName}}-infra:logtailToken:
+    secure: # Add your encrypted token here
+  {{projectName}}-infra:registryCredentials:
+    secure: # Add your encrypted credentials here

package/bin/templates/workspace/infra/Pulumi.yaml.hbs

@@ -0,0 +1,6 @@
+name: {{projectName}}-infra
+runtime:
+  name: nodejs
+  options:
+    packagemanager: bun
+description: Infrastructure as Code for {{projectName}}

package/bin/templates/workspace/infra/index.ts.hbs

@@ -0,0 +1,56 @@
+import { join } from 'node:path'
+import {
+  buildExternalUrls,
+  buildIngressRules,
+  buildInternalUrls,
+  buildServicePortEnvs,
+  buildServices,
+  buildServiceUrlEnvs,
+  discoverServices,
+} from '@crossdelta/infrastructure'
+import { App } from '@pulumi/digitalocean'
+import { Config, getStack } from '@pulumi/pulumi'
+
+const allServiceConfigs = discoverServices(join(__dirname, 'services'))
+const serviceConfigs = allServiceConfigs.filter((config) => !config.skip)
+const cfg = new Config()
+const logtailToken = cfg.requireSecret('logtailToken')
+const registryCredentials = cfg.requireSecret('registryCredentials')
+
+const stack = getStack()
+
+const doAppName = `{{projectName}}-${stack}`
+
+const app = new App('{{projectName}}', {
+  spec: {
+    name: doAppName,
+    region: 'fra',
+
+    alerts: [{ rule: 'DEPLOYMENT_FAILED' }, { rule: 'DOMAIN_FAILED' }],
+
+    features: ['buildpack-stack=ubuntu-22'],
+
+    envs: [
+      ...buildServiceUrlEnvs(serviceConfigs),
+      ...buildServicePortEnvs(serviceConfigs),
+    ],
+
+    services: buildServices({
+      serviceConfigs,
+      registryCredentials,
+      logtailToken,
+    }),
+
+    ingress: {
+      rules: buildIngressRules(serviceConfigs),
+    },
+  },
+})
+
+// Outputs
+export const appId = app.id
+export const appDefaultIngress = app.defaultIngress
+export const internalUrls = buildInternalUrls(serviceConfigs)
+export const serviceUrls = app.defaultIngress.apply((baseUrl) =>
+  buildExternalUrls(serviceConfigs, baseUrl ?? ''),
+)

package/bin/templates/workspace/infra/package.json.hbs

@@ -0,0 +1,23 @@
+{
+  "name": "infra",
+  "private": true,
+  "scripts": {
+    "generate-env": "bunx generate-env",
+    "lint": "biome lint --fix",
+    "pulumi": "pulumi"
+  },
+  "dependencies": {
+    "@crossdelta/cloudevents": "^0.5.3",
+    "@crossdelta/infrastructure": "^0.5.2",
+    "{{scope}}/contracts": "workspace:*",
+    "@pulumi/digitalocean": "^4.55.0",
+    "@pulumi/kubernetes": "^4.21.0",
+    "@pulumi/pulumi": "^3.208.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  }
+}

package/bin/templates/workspace/infra/tsconfig.json.hbs

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist"
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/bin/templates/workspace/npmrc.hbs

@@ -0,0 +1,2 @@
+# Add private registry scopes here if needed
+# @your-org:registry=https://npm.pkg.github.com

package/bin/templates/workspace/package.json.hbs

@@ -0,0 +1,51 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "scripts": {
+    "dev": "pf dev",
+    "generate-env": "cd infra && bun run generate-env",
+    "build": "dotenv -e .env.local -- turbo run build",
+    "preview": "dotenv -e .env.local -- turbo run preview",
+    "lint": "turbo run lint",
+    "format": "turbo run format",
+    "pulumi": "cd infra && pulumi",
+    "test": "dotenv -e .env.local -- turbo run test"
+  },
+  "pf": {
+    "registry": "{{projectName}}/platform",
+    "commands": {
+      "pulumi": {
+        "cwd": "infra"
+      }
+    },
+    "paths": {
+      "services": {
+        "path": "services",
+        "watch": true
+      },
+      "apps": {
+        "path": "apps",
+        "watch": true
+      },
+      "packages": {
+        "path": "packages",
+        "watch": true
+      },
+      "contracts": {
+        "path": "packages/contracts"
+      }
+    }
+  },
+  "dependencies": {
+    "@crossdelta/cloudevents": "latest",
+    "@crossdelta/telemetry": "latest"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.7",
+    "@crossdelta/platform-sdk": "latest",
+    "dotenv-cli": "^8.0.0",
+    "turbo": "^2.5.6"
+  },
+  "packageManager": "{{packageManagerVersion}}",
+  "workspaces": ["packages/*", "apps/*", "services/*", "infra"]
+}

package/bin/templates/workspace/packages/contracts/README.md.hbs

@@ -0,0 +1,166 @@
+# {{scope}}/contracts
+
+Shared event contracts for cross-service event consumption.
+
+## Purpose
+
+This package contains **shared event definitions** (contracts) for events that are consumed by multiple services. When an event is used by more than one service, define it here to ensure type consistency across the platform.
+
+## Structure
+
+```
+src/
+├── events/                    # Event contracts grouped by domain
+│   ├── orders/               # Orders domain
+│   │   ├── created.ts        # orders.created event
+│   │   ├── updated.ts        # orders.updated event
+│   │   └── index.ts          # Re-exports
+│   ├── customers/            # Customers domain
+│   │   ├── updated.ts        # customers.updated event
+│   │   └── index.ts          # Re-exports
+│   └── index.ts              # Re-exports all domains
+├── stream-policies.ts        # NATS JetStream retention policies
+└── index.ts                  # Main export file
+```
+
+**Contract files contain:**
+- Zod schema definition
+- Contract object (type + schema + **channel metadata**)
+- TypeScript type inference
+
+**Channel metadata** defines which NATS JetStream stream the event belongs to. This enables infrastructure-as-code workflows where streams are auto-created in dev (`pf dev`) and materialized via Pulumi in production.
+
+## Adding New Events
+
+### Using the CLI (Recommended)
+
+```bash
+pf event add products.created --fields "productId:string,name:string,price:number"
+```
+
+This will create `src/events/products/created.ts` with proper domain structure.
+
+### Manual Creation
+
+See [Adding Events](#manual-creation) section below.
+
+## Usage
+
+### In Event Handlers (Consumers)
+
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+  // data is fully typed from contract
+  console.log(data.orderId, data.customerId)
+})
+```
+
+### In Publishers (REST APIs)
+
+```ts
+import { publish } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract } from '{{scope}}/contracts'
+
+// Type-safe publishing with contract
+await publish(OrdersCreatedContract, {
+  orderId: 'order-123',
+  customerId: 'cust-456',
+  total: 99.99,
+  items: [...]
+})
+```
+
+### In Use-Cases
+
+```ts
+import type { OrdersCreatedData } from '{{scope}}/contracts'
+
+export const processOrder = async (data: OrdersCreatedData) => {
+  // Use typed event data
+}
+```
+
+## Adding New Contracts
+
+Contracts are **auto-generated** when you create event handlers:
+
+```bash
+# 1. Create service with event handler
+pf new hono-micro notifications --ai -d "Sends emails on orders.created events"
+
+# 2. Add event (creates contract, mock, handler)
+pf event add orders.created --service services/notifications
+```
+
+This creates:
+- `packages/contracts/src/events/orders-created.ts` (contract)
+- `packages/contracts/src/events/orders-created.mock.json` (mock)
+- Updates `packages/contracts/src/index.ts` (exports)
+
+### Manual Contract Creation
+
+```ts
+// packages/contracts/src/events/orders/created.ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrdersCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+  items: z.array(z.object({
+    productId: z.string(),
+    quantity: z.number(),
+    price: z.number(),
+  })),
+})
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },  // Stream routing metadata
+  schema: OrdersCreatedSchema,
+})
+
+export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+```
+
+**Channel Metadata:**
+- `stream` - NATS JetStream stream name (e.g., `ORDERS`)
+- `subject` - Optional, defaults to event type (e.g., `orders.created`)
+
+**Stream Materialization:**
+1. **Development**: `pf dev` scans contracts and auto-creates ephemeral streams from channel metadata
+2. **Production**: Pulumi collects streams from contracts and materializes with retention policies
+
+See [`infra/streams/README.md`](../../infra/streams/README.md) for details.
+
+## Testing with Mocks
+
+```bash
+# List all available events
+pf event list
+
+# Publish mock event
+pf event publish orders.created
+
+# Publish with custom data
+pf event publish orders.created --data '{"orderId":"test-123"}'
+```
+
+## Guidelines
+
+- ✅ Use contracts for **shared events** (multi-consumer)
+- ✅ Export both contract and inferred type
+- ✅ Keep contracts minimal and focused
+- ✅ Generate mocks for all contracts
+- ❌ Don't put business logic in contracts
+- ❌ Don't include event handlers in this package
+
+**Naming conventions:**
+- Contracts: `OrdersCreatedContract` (plural namespace)
+- Types: `OrdersCreatedData`
+- Files: `orders-created.ts`
+- Event types: `orders.created` (plural namespace, dot notation)

package/bin/templates/workspace/packages/contracts/package.json.hbs

@@ -0,0 +1,22 @@
+{
+  "name": "{{scope}}/contracts",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@crossdelta/cloudevents": "^0.5.3",
+    "@crossdelta/infrastructure": "^0.5.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "typescript": "^5.7.2"
+  }
+}

package/bin/templates/workspace/packages/contracts/src/events/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Event Contracts Index
+ *
+ * Re-exports all event contracts for convenient importing.
+ * Services can import from '{{scope}}/contracts' instead of deep imports.
+ *
+ * Structure:
+ * - events/<domain>/<event>.ts - Individual event contracts
+ * - events/<domain>/index.ts - Domain-specific exports
+ * - This file: Re-exports all domains
+ */
+
+// Add your event domains here as you create them:
+// export * from './orders'
+// export * from './customers'
+// export * from './products'

package/bin/templates/workspace/packages/contracts/src/index.ts

@@ -0,0 +1,10 @@
+// Export your event contracts and schemas here
+// Use the CLI to generate contracts:
+//
+//   pf event add orders.created --fields "orderId:string,total:number"
+//
+// This will create: src/events/orders/created.ts
+// Then uncomment the exports below:
+
+// export * from './events'
+// export * from './stream-policies'