@crossdelta/platform-sdk 0.21.29 → 0.22.1

package/bin/templates/workspace/.github/workflows/publish-packages.yml

@@ -0,0 +1,228 @@
+name: 📦 Publish Packages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/*/**'
+      - 'bun.lock'
+      - 'bunfig.toml'
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Package to publish (slug from packages/ directory, or "all")'
+        type: string
+        default: all
+        required: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  determine-packages:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.set-matrix.outputs.packages }}
+      count: ${{ steps.set-matrix.outputs.count }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed packages
+        id: changed
+        uses: tj-actions/changed-files@v47
+        with:
+          json: true
+          safe_output: false
+          files: packages/*/**
+
+      - name: Build package matrix
+        id: set-matrix
+        env:
+          INPUT_PACKAGE: ${{ github.event.inputs.package || '' }}
+          CHANGED_FILES: ${{ steps.changed.outputs.all_changed_files }}
+        run: |
+          declare -a packages=()
+          declare -A changed_packages
+
+          # Compare semver: true if $1 > $2
+          version_gt() {
+            [ "$(printf '%s\n' "$1" "$2" | sort -V | tail -1)" = "$1" ] && [ "$1" != "$2" ]
+          }
+
+          # Extract package names from changed file paths (e.g. packages/platform-sdk/src/foo.ts → platform-sdk)
+          if [ "${{ github.event_name }}" == "push" ] && [ -n "$CHANGED_FILES" ]; then
+            CLEAN_FILES=$(echo "$CHANGED_FILES" | sed 's/\\"/"/g')
+            for file in $(echo "$CLEAN_FILES" | jq -r '.[]' 2>/dev/null); do
+              if [[ $file =~ ^packages/([^/]+)/ ]]; then
+                changed_packages["${BASH_REMATCH[1]}"]=1
+              fi
+            done
+          fi
+          
+          # Iterate all packages
+          for dir in packages/*/; do
+            [ ! -f "$dir/package.json" ] && continue
+            
+            slug=$(basename "$dir")
+            dir="${dir%/}"  # Remove trailing slash
+            name=$(jq -r '.name // empty' "$dir/package.json")
+            is_private=$(jq -r '.private // false' "$dir/package.json")
+            
+            [ "$is_private" = "true" ] && continue
+            [ -z "$name" ] && continue
+            
+            # Include package?
+            should_include=false
+            if [ -n "$INPUT_PACKAGE" ]; then
+              [ "$INPUT_PACKAGE" = "all" ] || [ "$INPUT_PACKAGE" = "$slug" ] && should_include=true
+            else
+              [ -n "${changed_packages[$slug]}" ] && should_include=true
+            fi
+            
+            [ "$should_include" = true ] || continue
+
+            # Skip if local version <= npm version
+            local_ver=$(jq -r '.version' "$dir/package.json")
+            npm_ver=$(npm view "$name" version 2>/dev/null || echo "0.0.0")
+            if ! version_gt "$local_ver" "$npm_ver"; then
+              echo "⏭️  $name@$local_ver — npm has $npm_ver (same or newer) — skipping"
+              continue
+            fi
+
+            echo "📦 $name@$local_ver (npm: $npm_ver) — will publish"
+            packages+=("{\"name\":\"$name\",\"dir\":\"$dir\"}")
+          done
+          
+          # Output
+          if [ ${#packages[@]} -eq 0 ]; then
+            echo "packages=[]" >> "$GITHUB_OUTPUT"
+            echo "count=0" >> "$GITHUB_OUTPUT"
+          else
+            echo "packages=[$(IFS=,; echo "${packages[*]}")]" >> "$GITHUB_OUTPUT"
+            echo "count=${#packages[@]}" >> "$GITHUB_OUTPUT"
+            echo "📦 Packages to publish: ${#packages[@]}"
+          fi
+
+  # Build all packages in dependency order using Turborepo
+  # This ensures infrastructure is built AFTER cloudevents (which it depends on)
+  build-all:
+    name: Build all packages
+    needs: determine-packages
+    if: needs.determine-packages.outputs.count != '0'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Bun and install dependencies
+        uses: ./.github/actions/setup-bun-install
+        with:
+          enable-cache: 'true'
+          cache-key: bun-v4-${{ runner.os }}-${{ hashFiles('bun.lock', 'bunfig.toml') }}
+          cache-restore-keys: bun-v4-${{ runner.os }}-
+
+      - name: Build all packages
+        run: bunx turbo run build --filter='./packages/*'
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist-packages
+          # Required: the action drops every path beginning with a dot by default, and the
+          # workspace template the SDK ships is largely dotted (.claude/, .github/, .vscode/,
+          # .gitkeep). Without this the published package carries a template that `pf new
+          # workspace` cannot scaffold from, and nothing in the build or publish log says so.
+          include-hidden-files: true
+          path: |
+            packages/*/dist
+            packages/*/bin
+            packages/*/*.md
+            packages/*/LICENSE
+            packages/*/*.png
+            packages/*/schemas
+            packages/*/*.sh
+          retention-days: 1
+
+  # Publish packages (parallel, no git push needed)
+  # Only packages with local version > npm reach this job
+  # Uses npm Trusted Publishing (OIDC) — no token required
+  publish:
+    name: Publish ${{ matrix.package.name }}
+    needs: [determine-packages, build-all]
+    if: needs.determine-packages.outputs.count != '0'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      matrix:
+        package: ${{ fromJson(needs.determine-packages.outputs.packages) }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist-packages
+          path: packages
+
+      - name: Verify build artifacts
+        run: |
+          echo "📂 Checking ${{ matrix.package.dir }}"
+          ls -la "${{ matrix.package.dir }}" || true
+          if [ ! -d "${{ matrix.package.dir }}/dist" ] && [ ! -d "${{ matrix.package.dir }}/bin" ]; then
+            echo "❌ Build artifacts missing for ${{ matrix.package.name }}"
+            echo "📂 packages/ contents:"
+            ls -la packages/
+            exit 1
+          fi
+          echo "✅ Build artifacts found for ${{ matrix.package.name }}"
+
+      # A present bin/ is not a complete bin/. Artifact upload silently drops dotted paths unless
+      # include-hidden-files is set, which shipped a workspace template without .github/ for months
+      # while every build and publish log stayed green.
+      - name: Verify the workspace template survived the artifact round-trip
+        run: |
+          template="${{ matrix.package.dir }}/bin/templates/workspace"
+          if [ ! -d "$template" ]; then
+            echo "ℹ️  ${{ matrix.package.name }} ships no workspace template, nothing to verify"
+            exit 0
+          fi
+          missing=0
+          for required in .claude/rules .github/workflows .vscode; do
+            if [ ! -d "$template/$required" ]; then
+              echo "❌ $template/$required is missing from the artifact"
+              missing=1
+            fi
+          done
+          if [ "$missing" = "1" ]; then
+            echo "Hidden paths were dropped. Check include-hidden-files on the upload step."
+            exit 1
+          fi
+          echo "✅ Workspace template complete"
+
+      - name: Publish to npm
+        working-directory: ${{ matrix.package.dir }}
+        run: |
+          # Resolve workspace:* to real versions from sibling packages
+          for pkg in ../*/package.json; do
+            n=$(jq -r .name "$pkg"); v=$(jq -r .version "$pkg")
+            tmp=$(mktemp)
+            jq --arg n "$n" --arg v "^$v" '
+              (if .dependencies[$n] then .dependencies[$n] = $v else . end) |
+              (if .peerDependencies[$n] then .peerDependencies[$n] = $v else . end)
+            ' package.json > "$tmp" && mv "$tmp" package.json
+          done
+          VERSION=$(jq -r '.version' package.json)
+          echo "📦 Publishing ${{ matrix.package.name }}@$VERSION"
+          npm publish --access=public --ignore-scripts

package/bin/templates/workspace/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "biomejs.biome",
+    "github.copilot",
+    "github.copilot-chat",
+    "pulumi.pulumi-lsp-client"
+  ]
+}

package/bin/templates/workspace/.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  }
+}

package/bin/templates/workspace/CLAUDE.md

@@ -0,0 +1,76 @@
+# Project Instructions (Project-Agnostic, TypeScript-Focused)
+
+You are assisting in TypeScript-first monorepos using modern TypeScript tooling such as Bun or Node, Turborepo, Hono, NestJS, Zod, event-driven patterns, and Pulumi/Kubernetes infrastructure.
+
+## Core Principles
+
+- Functional style: pure functions, composition over inheritance, side effects isolated in adapters.
+- Separation of concerns: validation → logic → I/O. Domain logic separate from transport.
+- Minimal diffs: change only what's needed, no full rewrites, no extra abstractions.
+- Configuration over constants: avoid hard-coded values.
+
+## Safety Rules
+
+- **NEVER** echo secrets/credentials into terminal output: they become conversation context sent to the AI provider.
+- Use `source .env.local 2>/dev/null`. Never inline secrets as command arguments.
+- **Never commit or push without explicit user confirmation.**
+
+## Before Writing Code
+
+- **Search first**: Check the codebase for existing utilities before implementing new ones. Reuse > reinvent.
+- **Check installed versions**: Verify the actual API of installed packages (`package.json`, `node_modules/`), don't assume.
+- **Check generators**: Look for `gen`/`generate`/`codegen` scripts in `package.json` before editing files that might be auto-generated.
+
+## After Writing Code
+
+- **Test consumers**: When changing a shared package (`packages/*`), run tests in **all consuming services**, not just the package itself. Changes to shared code have blast radius.
+- **Push before publish**: Always push commits to remote before triggering npm publish workflows. The CI reads from the repo, not your local machine.
+- **Pre-commit hooks exist**: The repo has a `sync-templates` hook that auto-updates downstream `package.json` refs after version bumps. Never bypass with `--no-verify`.
+- **Capture lessons**: When a convention or pitfall emerges, propose updating a scoped `.claude/rules/` file. Ask before creating new files. Keep `CLAUDE.md` project-agnostic; domain-specific rules go in scoped files with `paths:`.
+
+## Monorepo Awareness
+
+- Internal dependencies use `workspace:*` protocol. Never pin specific versions for workspace packages.
+- Docker builds use `prepare-build-context` which flattens the monorepo, so root `package.json` `overrides` are **lost** in the Docker build. If a transitive dependency needs pinning, the fix must be in the package's own `package.json`.
+- Turborepo caches builds. When debugging stale output, try `turbo run build --force`.
+
+## Scoped Rules
+
+This workspace comes with one rule:
+
+- [CloudEvents & Event Handling](.claude/rules/cloudevents.md): handler pattern, wildcard handlers, JetStream vs Core, contracts, NATS migrations (`services/*/src/events/**`, `packages/contracts/**`)
+
+Add your own as they earn their place. A rule is worth writing once a convention has cost you
+something: a pitfall someone hit, a boundary someone crossed. Rules written ahead of that describe
+a codebase that does not exist yet, and get ignored.
+
+To add one: create `.claude/rules/<name>.md`, give it a `paths:` list of globs the repo actually
+has, and keep it to what the code cannot say about itself. A rule with `paths:` loads when a
+matching file is touched. Leave `paths:` out only for something that binds in every session
+regardless of which file is open, because that cost is paid on every turn.
+
+Code style and testing conventions are not rules here: the `pf` generators carry their own, and they
+load whenever the generator writes code.
+
+## Key Packages
+
+Installed from npm, not vendored into this repo. Read their APIs in `node_modules/`, not from memory.
+
+- `@crossdelta/cloudevents` - Event handling with NATS and CloudEvents
+- `@crossdelta/telemetry` - OpenTelemetry instrumentation
+- `@crossdelta/infrastructure` - Pulumi/K8s configuration
+
+## AI Output Format
+
+- Provide only necessary files.
+- Use relative paths.
+- Keep comments minimal.
+- Do not generate abstractions not already present.
+
+## Writing Style for Documentation
+
+When writing to files (README, docs, plan documents, comments):
+
+- No em dashes (`—`). Use a colon or restructure the sentence.
+- No AI-speak: avoid "ships with", "wired up", "out of the box", "seamlessly", "ready to use", "powerful", "robust".
+- Plain sentences. If a phrase sounds like marketing copy, rewrite it as a statement of fact.

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

@@ -21,7 +21,6 @@
   "dependencies": {
     "@crossdelta/cloudevents": "^0.8.4",
     "@crossdelta/infrastructure": "^0.15.2",
-    "{{scope}}/types": "workspace:*",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.21.29",
+  "version": "0.22.1",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",