@crossdelta/platform-sdk 0.22.0 → 0.22.2

package/bin/templates/workspace/.claude/rules/cloudevents.md

@@ -0,0 +1,85 @@
+---
+paths:
+  - "services/*/src/events/**"
+  - "packages/contracts/**"
+---
+
+# @crossdelta/cloudevents Conventions
+
+Rules for working with the CloudEvents package and event handlers.
+
+## Handler Pattern
+
+- Handlers are files matching `*.handler.ts`, auto-discovered via glob pattern.
+- Every handler exports a **default** from `handleEvent()` — this returns a **class** (not an instance). The framework instantiates it with `new`.
+- Handlers are thin wrappers: parse → delegate to use-case. No business logic in handlers.
+- Handler file naming: `<event-type>.handler.ts` (e.g. `call-received.handler.ts`).
+
+## Wildcard Handler (`type: '*'`)
+
+- Use `type: '*'` for catch-all handlers (audit logging, metrics).
+- Wildcard is a **fallback** — specific handlers (`type: 'order.created'`) always win.
+- Schema should be `z.record(z.string(), z.unknown())` since any payload shape is valid.
+- Only one wildcard handler per consumer is recommended.
+
+## JetStream vs. NATS Core
+
+| Pattern       | Transport | Function                            | When to use                            |
+| ------------- | --------- | ----------------------------------- | -------------------------------------- |
+| Async events  | JetStream | `consumeJetStreams()` / `publish()` | Persistence needed, multiple consumers |
+| Sync commands | NATS Core | `consumeNatsEvents()` / `request()` | Caller needs immediate result          |
+
+**Rule of thumb:** If the caller can retry (e.g. PBX webhook) → Request-Reply. If the message must survive crashes → JetStream.
+
+**JetStream ↔ Core conflict:** A JetStream Stream whose subjects overlap with a NATS Core Request-Reply subject will silently intercept messages. If migrating from JetStream to Core, remove the stream first.
+
+## `consumeJetStreams` Options
+
+- `startFrom: 'all'` — replay full history (use for audit, analytics)
+- `startFrom: 'new'` — only new messages (default, use for domain services)
+- `consumer` — durable consumer name, must be unique per service
+- `discover` — glob pattern for handler auto-discovery
+
+## Contracts
+
+- Live in `packages/contracts/src/events/<domain>/<event>.ts`
+- Use `createContract({ type, channel, schema })` — schema is Zod v4
+- `channel.stream` defines the JetStream stream routing
+- **Subject = event `type`** (singular): a contract's NATS subject defaults to its `type` (e.g. `order.completed`) — **not** pluralized. Override explicitly with `channel.subject`. Keep domain events singular (`order.completed`, not `orders.completed`); the stream **name** is the plural collection (`ORDERS`).
+- **String helpers pluralize**: `publish('order.x')` / `request('order.x')` map the domain token to plural (`order.x` → `orders.x`), so Core request subjects like `orders.intake` live in the plural namespace. JetStream streams consuming contract events **must bind `order.*` (singular), never `orders.*`** — otherwise they miss contract events and intercept the plural Core request subjects (a real bug we hit: `order.completed` published, stream bound to `orders.*`, event lost).
+- Contracts are for **inter-service communication** only — not for HTTP ingress schemas
+- **Domain constants belong in the shared types package**, not in contracts. Contracts import them for their Zod enums. Never re-define a status or direction constant inside a contract file — two definitions drift, and the one in the contract wins silently at the wire.
+- **Contracts may import the types package, never the reverse.** Contracts pull in `@crossdelta/cloudevents`, which is Node.js-only; a types package that imports contracts stops being usable in a browser build.
+
+## NATS Migrations
+
+See [Infrastructure](infrastructure.md) for migration conventions (`infra/migrations/`).
+
+## Publishing Checklist
+
+1. Bump version in `package.json`
+2. Update `CHANGELOG.md`
+3. **Push to remote before publishing** — npm publish reads from the repo
+4. Trigger workflow: `gh workflow run publish-packages.yml -f package=cloudevents`
+5. After publishing: the `sync-templates` pre-commit hook auto-updates downstream `package.json` references
+
+## Distributed Tracing
+
+When `@crossdelta/telemetry` is installed (optional peer dep), trace context propagation is automatic — no service-level configuration needed:
+
+- **Publish**: `traceparent` is injected as a CloudEvent extension field.
+- **Consume**: `traceparent` is extracted and restored in ALS before handler execution.
+
+This gives end-to-end distributed traces across NATS in Grafana.
+
+## Logging
+
+- `createLogger(enabled)` gates `info`/`warn` behind `enabled` flag.
+- `debug` requires **both** `enabled` AND `LOG_LEVEL=debug` env var — otherwise suppressed.
+- `error` always logs regardless of `enabled`.
+- Set `LOG_LEVEL=debug` only in local dev or when explicitly troubleshooting — it is noisy in production.
+
+## Handler Testing
+
+- `handleEvent()` returns a class → use `new HandlerClass()` in tests, not `HandlerClass()`.
+- Access handler metadata via `HandlerClass.__eventarcMetadata`.

package/bin/templates/workspace/.github/README.md

@@ -0,0 +1,67 @@
+# CI/CD Workflows
+
+This project includes GitHub Actions workflows for continuous integration and deployment.
+
+## Workflows
+
+### Pull Request Checks (`lint-and-tests.yml`)
+
+Runs on every pull request to `main`:
+- Lints the codebase (`bun lint`)
+- Runs tests (`bun test`)
+- Uses dependency caching for faster builds
+
+### Build and Deploy (`build-and-deploy.yml`)
+
+Runs on pushes to `main` and after package publishing:
+- Builds Docker images for changed scopes (apps/services)
+- Pushes images to GitHub Container Registry (GHCR)
+- Deploys infrastructure using Pulumi
+
+## Required Secrets
+
+Configure these secrets in your GitHub repository settings:
+
+| Secret | Description |
+|--------|-------------|
+| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token for infrastructure deployment |
+| `DIGITALOCEAN_TOKEN` | DigitalOcean API token for DOKS/spaces access |
+
+## Required Variables
+
+Configure these variables in your GitHub repository settings:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `PULUMI_STACK_BASE` | Base name for Pulumi stacks | `myorg/myproject` |
+
+## Automatic Permissions
+
+These are handled automatically via `permissions` in workflows:
+- `GITHUB_TOKEN` - GitHub-provided token for GHCR push and API access
+
+## Custom Actions
+
+The workflows use these local actions:
+
+| Action | Purpose |
+|--------|---------|
+| `setup-bun-install` | Setup Bun runtime with caching |
+| `generate-scope-matrix` | Discover Docker-enabled scopes for matrix builds |
+| `check-image-tag-exists` | Skip builds if image tag already exists in GHCR |
+| `prepare-build-context` | Flatten turbo prune output for Docker builds |
+
+## Infrastructure Configuration
+
+Each service in `infra/services/*.ts` can be configured with:
+
+```typescript
+const config: K8sServiceConfig = {
+  name: 'my-service',
+  containerPort: 4001,
+  skip: false, // Set to true to skip deployment
+  // ... other config
+}
+```
+
+Services with `skip: true` will be excluded from deployment.

package/bin/templates/workspace/.github/actions/check-image-tag-exists/action.yml

@@ -0,0 +1,27 @@
+name: Check image tag exists
+inputs:
+  scope-short-name:
+    description: Short directory name of the scope (e.g., storefront)
+    required: true
+  image-tag:
+    description: Checksum-based image tag to look for
+    required: true
+  github-token:
+    description: GitHub token with read:packages to query GHCR
+    required: true
+  repository-owner:
+    description: GitHub organization or user that owns the container package
+    required: false
+  repository-prefix:
+    description: Prefix used for GHCR packages (defaults to $GHCR_REPOSITORY_PREFIX or "platform")
+    required: false
+  max-pages:
+    description: Maximum number of pagination pages to inspect (100 tags each)
+    required: false
+    default: '5'
+outputs:
+  exists:
+    description: 'true if the tag already exists in GHCR'
+runs:
+  using: node24
+  main: index.js

package/bin/templates/workspace/.github/actions/check-image-tag-exists/index.js

@@ -0,0 +1,179 @@
+/**
+ * Check Image Tag Exists Action
+ *
+ * Checks if a specific Docker image tag already exists in GitHub Container Registry (GHCR).
+ * Used to skip redundant builds when the image checksum hasn't changed.
+ *
+ * @example
+ * - uses: ./.github/actions/check-image-tag-exists
+ *   with:
+ *     scope-short-name: storefront
+ *     image-tag: abc123def456
+ *     github-token: ${{ secrets.GITHUB_TOKEN }}
+ *
+ * @outputs exists - 'true' if the tag exists, 'false' otherwise
+ */
+
+const { appendFileSync } = require('node:fs')
+const { exit } = require('node:process')
+
+/**
+ * Builds environment variable keys for GitHub Actions inputs.
+ * @param {string} name - Input name (e.g., 'scope-short-name')
+ * @returns {string[]} Possible environment variable keys
+ */
+const buildInputKeys = (name) => {
+  const trimmed = name.trim()
+  const upper = trimmed.toUpperCase()
+  const normalized = upper.replace(/[^A-Z0-9]+/g, '_')
+  return Array.from(new Set([`INPUT_${upper}`, `INPUT_${normalized}`]))
+}
+
+/**
+ * Retrieves a GitHub Actions input value from environment variables.
+ * @param {string} name - Input name as defined in action.yml
+ * @param {Object} options - Options
+ * @param {boolean} [options.required=false] - Whether the input is required
+ * @param {string} [options.defaultValue=''] - Default value if input is not set
+ * @returns {string} The input value
+ */
+const getInput = (name, { required = false, defaultValue = '' } = {}) => {
+  const keys = buildInputKeys(name)
+  const raw = keys.map((key) => process.env[key]).find((value) => typeof value === 'string')
+  const value = (typeof raw === 'string' ? raw : defaultValue).trim()
+
+  if (required && !value) {
+    console.error(`Input "${name}" is required`)
+    exit(1)
+  }
+
+  return value
+}
+
+/**
+ * Sets a GitHub Actions output value.
+ * @param {string} name - Output name
+ * @param {string} value - Output value
+ */
+const setOutput = (name, value) => {
+  const outputFile = process.env.GITHUB_OUTPUT
+  if (outputFile) {
+    appendFileSync(outputFile, `${name}=${value}\n`)
+  } else {
+    console.log(`${name}=${value}`)
+  }
+}
+
+// Required inputs
+const scopeShortName = getInput('scope-short-name', { required: true })
+const imageTag = getInput('image-tag', { required: true })
+const githubToken = getInput('github-token', { required: true })
+
+// Optional inputs - defaults from environment for portability
+const repositoryOwner = getInput('repository-owner', { defaultValue: process.env.GITHUB_REPOSITORY_OWNER })
+const repositoryPrefixInput = getInput('repository-prefix')
+const repositoryPrefix =
+  repositoryPrefixInput || process.env.GHCR_REPOSITORY_PREFIX || process.env.GITHUB_REPOSITORY?.split('/')[1] || 'platform'
+const maxPages = Number(getInput('max-pages', { defaultValue: '5' }))
+
+// GitHub API request headers
+const headers = {
+  Authorization: `Bearer ${githubToken}`,
+  Accept: 'application/vnd.github+json',
+  'X-GitHub-Api-Version': '2022-11-28',
+}
+
+// Construct the full package name (e.g., 'platform/storefront')
+const packageName = `${repositoryPrefix}/${scopeShortName}`
+const encodedPackage = encodeURIComponent(packageName)
+
+/**
+ * Fetches a page of container versions from the GitHub Packages API.
+ * @param {number} page - Page number (1-indexed)
+ * @returns {Promise<Object>} Result with versions array, hasMore flag, and notFound flag
+ */
+const fetchVersions = async (page) => {
+  const url = `https://api.github.com/orgs/${repositoryOwner}/packages/container/${encodedPackage}/versions?per_page=100&page=${page}`
+  const response = await fetch(url, { headers })
+
+  // 404 means the package doesn't exist yet (first build)
+  if (response.status === 404) {
+    return { notFound: true, versions: [], hasMore: false }
+  }
+
+  if (!response.ok) {
+    const body = await response.text()
+    throw new Error(`GitHub API error (${response.status}): ${body}`)
+  }
+
+  const data = await response.json()
+  const versions = Array.isArray(data) ? data : []
+  return {
+    versions,
+    hasMore: versions.length === 100, // Full page means there might be more
+    notFound: false,
+  }
+}
+
+/**
+ * Checks if the target tag exists in a list of container versions.
+ * @param {Object[]} versions - Array of version objects from GitHub API
+ * @param {string} targetTag - The tag to search for
+ * @returns {boolean} True if tag is found
+ */
+const tagExistsInVersions = (versions, targetTag) => {
+  for (const version of versions) {
+    const tags = version?.metadata?.container?.tags
+    if (!Array.isArray(tags)) continue
+    if (tags.includes(targetTag)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Checks if the image tag exists in GHCR by paginating through all versions.
+ * @returns {Promise<boolean>} True if tag exists
+ */
+const check = async () => {
+  const targetTag = imageTag.trim()
+
+  // Paginate through versions until we find the tag or run out of pages
+  for (let page = 1; page <= maxPages; page += 1) {
+    const { versions, hasMore, notFound } = await fetchVersions(page)
+
+    // Package doesn't exist yet - tag definitely doesn't exist
+    if (notFound) {
+      return false
+    }
+
+    // Check if target tag is in this page
+    if (tagExistsInVersions(versions, targetTag)) {
+      return true
+    }
+
+    // No more pages to check
+    if (!hasMore) {
+      break
+    }
+  }
+
+  return false
+}
+
+/**
+ * Main entry point - runs the check and outputs the result.
+ */
+const run = async () => {
+  try {
+    const exists = await check()
+    setOutput('exists', String(exists))
+  } catch (error) {
+    console.error('Failed to check image tag existence:', error)
+    setOutput('exists', 'false')
+    exit(1)
+  }
+}
+
+run()

package/bin/templates/workspace/.github/actions/generate-scope-matrix/action.yml

@@ -0,0 +1,21 @@
+name: Generate scope matrix
+description: Discover Docker scopes and output JSON matrix entries for changed scopes
+inputs:
+  scope-roots:
+    description: Comma/space separated list of directories containing scope folders
+    required: false
+  force-scope-short-names:
+    description: Optional short-name list to force into the matrix even if unchanged
+    required: false
+  force-all:
+    description: When true, include ALL discovered scopes regardless of changes
+    required: false
+    default: 'false'
+outputs:
+  scopes:
+    description: JSON array describing scopes for the matrix strategy
+  scopes_count:
+    description: Number of scopes detected in the matrix
+runs:
+  using: node24
+  main: index.js