@crossdelta/platform-sdk 0.14.0 → 0.16.0

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

@@ -0,0 +1,70 @@
+# 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 |
+| `check-path-changes` | Detect file changes for conditional steps |
+| `prepare-build-context` | Flatten turbo prune output for Docker builds |
+| `resolve-scope-tags` | Map scope names to image tags for deployment |
+| `detect-skipped-services` | Find services marked with `skip: true` in infra config |
+
+## 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: node20
+  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/check-path-changes/action.yml

@@ -0,0 +1,21 @@
+name: Detect path changes
+description: Reports whether the specified paths changed between two git references.
+
+inputs:
+  paths:
+    description: Newline or comma-delimited list of paths to check.
+    required: true
+  base-ref:
+    description: Base git ref/sha to diff from. Falls back to GITHUB_EVENT_BEFORE or parent commit.
+    default: ''
+  head-ref:
+    description: Head git ref/sha to diff against. Falls back to GITHUB_SHA.
+    default: ''
+
+outputs:
+  changed:
+    description: 'true' if any of the provided paths changed.
+
+runs:
+  using: node20
+  main: index.js

package/bin/templates/workspace/.github/actions/check-path-changes/index.js

@@ -0,0 +1,192 @@
+/**
+ * Check Path Changes Action
+ *
+ * Detects whether specified paths have changed between two git references.
+ * Useful for conditional workflow steps based on file changes.
+ *
+ * @example
+ * - uses: ./.github/actions/check-path-changes
+ *   with:
+ *     paths: infra,packages/cloudevents
+ *     base-ref: main
+ *
+ * @outputs changed - 'true' if any of the provided paths changed
+ */
+
+const { appendFileSync } = require('node:fs')
+const { spawnSync } = require('node:child_process')
+
+/**
+ * Builds environment variable keys for GitHub Actions inputs.
+ * @param {string} name - Input 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
+ * @param {Object} options - Options
+ * @param {boolean} [options.required=false] - Whether the input is required
+ * @param {string} [options.defaultValue=''] - Default value if 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.trim() : defaultValue
+
+  if (required && !value) {
+    console.error(`Input "${name}" is required`)
+    process.exit(1)
+  }
+
+  return value
+}
+
+/**
+ * Sets a GitHub Actions output value.
+ * @param {string} name - Output name
+ * @param {string|object} value - Output value
+ */
+const setOutput = (name, value) => {
+  const outputFile = process.env.GITHUB_OUTPUT
+  const stringValue = typeof value === 'string' ? value : JSON.stringify(value)
+  if (outputFile) {
+    appendFileSync(outputFile, `${name}=${stringValue}\n`)
+  } else {
+    console.log(`${name}=${stringValue}`)
+  }
+}
+
+/**
+ * Parses a comma/newline-separated list of paths.
+ * @param {string} value - Input string
+ * @returns {string[]} Array of paths
+ */
+const parseList = (value) => {
+  if (!value) return []
+  return value
+    .split(/[^a-zA-Z0-9._\-\/]+/)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+/**
+ * Runs a git command and returns stdout.
+ * @param {string[]} args - Git command arguments
+ * @returns {string} Command output
+ */
+const runGit = (args) => {
+  const result = spawnSync('git', args, { encoding: 'utf8' })
+  if (result.error) {
+    throw result.error
+  }
+  if (result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr || result.stdout}`)
+  }
+  return result.stdout.trim()
+}
+
+const resolveHeadRef = (headRefInput) => {
+  if (headRefInput) {
+    return headRefInput
+  }
+  if (process.env.GITHUB_SHA) {
+    return process.env.GITHUB_SHA
+  }
+  return runGit(['rev-parse', 'HEAD'])
+}
+
+/**
+ * Checks if a ref is a zero (null) ref.
+ * @param {string} ref - Git reference
+ * @returns {boolean} True if zero ref
+ */
+const isZeroRef = (ref) => !ref || /^0+$/.test(ref)
+
+/**
+ * Resolves the base ref for comparison.
+ * @param {string} baseRefInput - User-provided base ref
+ * @param {string} headRef - Resolved head ref
+ * @returns {string} Base ref to use
+ */
+const resolveBaseRef = (baseRefInput, headRef) => {
+  if (baseRefInput && !isZeroRef(baseRefInput)) {
+    return baseRefInput
+  }
+
+  const eventBefore = process.env.GITHUB_EVENT_BEFORE
+  if (eventBefore && !isZeroRef(eventBefore)) {
+    return eventBefore
+  }
+
+  try {
+    const parent = runGit(['rev-parse', `${headRef}^`])
+    if (parent) {
+      return parent
+    }
+  } catch (error) {
+    // ignore and fall through
+  }
+
+  return headRef
+}
+
+/**
+ * Checks if a specific path has changed between two commits.
+ * @param {string} baseRef - Base commit ref
+ * @param {string} headRef - Head commit ref
+ * @param {string} targetPath - Path to check
+ * @returns {boolean} True if path has changes
+ */
+const pathChanged = (baseRef, headRef, targetPath) => {
+  const result = spawnSync('git', ['diff', '--name-only', baseRef, headRef, '--', targetPath], { encoding: 'utf8' })
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `git diff exited with status ${result.status}`)
+  }
+
+  return result.stdout.trim().length > 0
+}
+
+/**
+ * Main entry point.
+ */
+const main = () => {
+  const pathsInput = getInput('paths', { required: true })
+  const baseRefInput = getInput('base-ref')
+  const headRefInput = getInput('head-ref')
+
+  const paths = parseList(pathsInput)
+  if (paths.length === 0) {
+    console.error('At least one valid path must be provided via the paths input')
+    process.exit(1)
+  }
+
+  const headRef = resolveHeadRef(headRefInput)
+  const baseRef = resolveBaseRef(baseRefInput, headRef)
+
+  let changed = false
+  for (const targetPath of paths) {
+    if (pathChanged(baseRef, headRef, targetPath)) {
+      changed = true
+      break
+    }
+  }
+
+  setOutput('changed', changed ? 'true' : 'false')
+}
+
+main().catch((error) => {
+  console.error('check-path-changes action failed:', error)
+  process.exit(1)
+})

package/bin/templates/workspace/.github/actions/detect-skipped-services/action.yml

@@ -0,0 +1,38 @@
+name: Detect skipped services
+description: Detects services with skip:true and outputs them for workflow use
+inputs:
+  services-dir:
+    description: Directory containing service configuration files
+    required: false
+    default: infra/services
+outputs:
+  skipped-services:
+    description: Comma-separated list of skipped service names
+    value: ${{ steps.detect.outputs.skipped_services }}
+runs:
+  using: composite
+  steps:
+    - name: Detect skipped services
+      id: detect
+      shell: bash
+      env:
+        SERVICES_DIR: ${{ inputs.services-dir }}
+      run: |
+        set -euo pipefail
+        
+        SKIPPED=""
+        for file in "$SERVICES_DIR"/*.ts; do
+          if [ -f "$file" ] && grep -q "skip:\s*true" "$file" 2>/dev/null; then
+            SERVICE_NAME=$(grep -oP "name:\s*['\"]?\K[a-zA-Z0-9_-]+" "$file" | head -1)
+            if [ -n "$SERVICE_NAME" ]; then
+              if [ -z "$SKIPPED" ]; then
+                SKIPPED="$SERVICE_NAME"
+              else
+                SKIPPED="$SKIPPED,$SERVICE_NAME"
+              fi
+            fi
+          fi
+        done
+        
+        echo "skipped_services=$SKIPPED" >> "$GITHUB_OUTPUT"
+        echo "Detected skipped services: $SKIPPED"

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

@@ -0,0 +1,17 @@
+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
+outputs:
+  scopes:
+    description: JSON array describing scopes for the matrix strategy
+  scopes_count:
+    description: Number of scopes detected in the matrix
+runs:
+  using: node20
+  main: index.js