Merge remote-tracking branch 'origin/main' into miro/sleep

Author: miro-cl

.github/workflows/breaking-changes.yml

@@ -0,0 +1,147 @@
+name: Breaking changes
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches: [main]
+    # Re-run when override labels are added or removed
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  proto-breaking:
+    runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:proto') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
+    steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=Proto breaking check skipped::This PR has label breaking-change:proto or breaking-change:approved. A maintainer acknowledged an intentional proto break. Remove the label to re-enable buf breaking."
+
+      - name: Checkout code
+        if: env.SKIP != 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Bun
+        if: env.SKIP != 'true'
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.12
+
+      - name: Install dependencies
+        if: env.SKIP != 'true'
+        run: bun install --frozen-lockfile
+
+      # cre-sdk's buf.yaml points at ../../submodules/chainlink-protos/cre, which buf rejects when
+      # --against uses subdir=packages/cre-sdk (module path escapes the context). Run breaking on
+      # the chainlink-protos workspace instead, comparing HEAD to the submodule commit pinned on main.
+      - name: Buf breaking (proto)
+        if: env.SKIP != 'true'
+        run: |
+          set -euo pipefail
+          REPO="${{ github.workspace }}"
+          SUBMODULE="${REPO}/submodules/chainlink-protos"
+          BASE_COMMIT=$(git -C "$REPO" rev-parse origin/main:submodules/chainlink-protos)
+          BASE_DIR="${RUNNER_TEMP}/chainlink-protos-baseline"
+          if ! git -C "$SUBMODULE" cat-file -e "${BASE_COMMIT}^{commit}" 2>/dev/null; then
+            git -C "$SUBMODULE" fetch --no-tags origin "${BASE_COMMIT}"
+          fi
+          git -C "$SUBMODULE" worktree add "${BASE_DIR}" "${BASE_COMMIT}" --detach
+          cleanup() {
+            git -C "$SUBMODULE" worktree remove "${BASE_DIR}" --force || true
+          }
+          trap cleanup EXIT
+          (cd "$SUBMODULE" && bun x @bufbuild/buf breaking cre --against "${BASE_DIR}/cre" --error-format github-actions)
+
+  ts-api-surface:
+    runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:typescript-api') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
+    steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=TypeScript API check skipped::This PR has label breaking-change:typescript-api or breaking-change:approved. Commit an updated api-baseline.d.ts when appropriate; this label only bypasses CI."
+
+      - name: Checkout code
+        if: env.SKIP != 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Bun
+        if: env.SKIP != 'true'
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.12
+
+      - name: Install dependencies
+        if: env.SKIP != 'true'
+        run: bun install --frozen-lockfile
+
+      - name: Diff TypeScript public API vs baseline
+        if: env.SKIP != 'true'
+        working-directory: packages/cre-sdk
+        run: |
+          bun run update-api-baseline
+
+          if ! git diff --exit-code api-baseline.d.ts; then
+            echo "::error::TypeScript public API surface changed. Run 'bun run update-api-baseline' locally and commit the updated api-baseline.d.ts."
+            exit 1
+          fi
+
+  host-bindings:
+    runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:host-bindings') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
+    steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=Host bindings check skipped::This PR has label breaking-change:host-bindings or breaking-change:approved. Update snapshots and host-imports-baseline.txt when appropriate; this label only bypasses CI."
+
+      - name: Checkout code
+        if: env.SKIP != 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Bun
+        if: env.SKIP != 'true'
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.12
+
+      - name: Install dependencies
+        if: env.SKIP != 'true'
+        run: bun install --frozen-lockfile
+
+      - name: JS host bindings snapshot test
+        if: env.SKIP != 'true'
+        working-directory: packages/cre-sdk
+        run: bun test src/sdk/wasm/host-bindings-contract.test.ts
+
+      - name: Diff Rust host imports vs baseline
+        if: env.SKIP != 'true'
+        run: |
+          grep -E '^\s+fn [a-z_]+\(' \
+            packages/cre-sdk-javy-plugin/src/javy_chainlink_sdk/src/lib.rs \
+            | grep -v '{$' > /tmp/current-imports.txt
+
+          if ! diff packages/cre-sdk-javy-plugin/src/javy_chainlink_sdk/host-imports-baseline.txt \
+                   /tmp/current-imports.txt; then
+            echo "::error::Rust host import signatures changed. Update host-imports-baseline.txt if intentional."
+            exit 1
+          fi

.github/workflows/ci.yml

@@ -110,6 +110,8 @@ jobs:
             echo ""
             echo "=========================================="
             echo "Uncommitted file changes detected after full-checks!"
+            echo "Changed files:"
+            git diff --name-only
             echo "Run 'bun full-checks' locally and commit the resulting changes."
             echo "=========================================="
             exit 1

.github/workflows/template-compatibility-comment.yml

@@ -40,5 +40,5 @@ jobs:
         with:
           script: |
             const path = require('path');
-            const run = require(path.join(process.env.GITHUB_WORKSPACE, 'scripts', 'template-compatibility-comment.js'));
+            const run = require(path.join(process.env.GITHUB_WORKSPACE, 'scripts', 'template-compatibility-comment.cjs'));
             await run({ github, context });

PUBLISHING.md

@@ -23,6 +23,12 @@ There are 2 possible scenarios that you might encounter:
 
 Below ale the steps for two scenarios.
 
+> **Breaking changes:** If the release includes any intentional breaking changes to the
+> TypeScript API surface, JS host bindings, or Rust host imports, the corresponding baseline
+> files (`api-baseline.d.ts`, `__snapshots__/host-bindings-contract.test.ts.snap`,
+> `host-imports-baseline.txt`) must already be committed on the release branch before
+> tagging. The `breaking-changes` CI job must be green before publishing.
+
 ### 1. Both packages need an update
 
 1. Create a new branch from `main` with the name `release-candidate-vx.y.z` (for example `release-candidate-v1.0.8`).

README.md

@@ -266,6 +266,32 @@ bun generate:chain-selectors  # Update chain selector types
 bun generate:sdk          # Generate all SDK types and code
 ```
 
+### Breaking Changes
+
+The [`breaking-changes`](./.github/workflows/breaking-changes.yml) workflow blocks PRs that alter any of the three protected contracts. If your change is intentional, update the relevant baseline before pushing:
+
+| Contract | What triggers the failure | How to update |
+|---|---|---|
+| Proto fields | Field deleted, renamed, renumbered, or type changed | No baseline file — CI runs `buf breaking` on `submodules/chainlink-protos` (`cre` module) against the submodule commit pinned on `main` |
+| TypeScript public API | An exported type/interface was removed or changed | Run `bun run update-api-baseline` inside `packages/cre-sdk` and commit `api-baseline.d.ts` |
+| JS host binding names | A binding was added, removed, or renamed in `host-bindings.ts` | Run `bun test --update-snapshots` inside `packages/cre-sdk` and commit the updated `__snapshots__` file |
+| Rust host imports | An `extern "C"` import was added or removed in `lib.rs` | Re-run the sed extraction (see `breaking-changes.yml`) and commit `host-imports-baseline.txt` |
+
+#### CI override labels
+
+When a change is **intentionally** breaking and cannot be fixed by updating a baseline (e.g. a coordinated proto break before `main` catches up), a **maintainer** adds the matching label on the PR (this re-runs the workflow):
+
+| Label | Skips |
+|-------|--------|
+| `breaking-change:proto` | `proto-breaking` (`buf breaking`) |
+| `breaking-change:typescript-api` | `ts-api-surface` |
+| `breaking-change:host-bindings` | `host-bindings` |
+| `breaking-change:approved` | All three jobs |
+
+Labels are an audit trail in the PR timeline, not a substitute for review. Prefer updating baselines (`api-baseline.d.ts`, snapshots, `host-imports-baseline.txt`) when the new contract is the new source of truth. For proto breaks, coordinate the `chainlink-protos` submodule bump and document migration notes in the PR.
+
+Restrict who can add these labels in the repo’s **Labels** settings (e.g. maintainers only).
+
 For detailed development setup, see individual package READMEs:
 
 - [CRE SDK Development](./packages/cre-sdk/README.md#building-from-source)

packages/cre-rust-inject-alpha/src/lib.rs

@@ -3,11 +3,11 @@ use javy_plugin_api::javy::quickjs::prelude::*;
 use javy_plugin_api::javy::quickjs::{Ctx, Object};
 
 pub fn register(ctx: &Ctx<'_>) {
-    let obj = Object::new(ctx.clone()).unwrap();
+    let obj = Object::new(ctx.clone()).expect("failed to create rustAlpha export object");
     obj.set(
         "greet",
         Func::from(|| -> String { "Hello from alpha".to_string() }),
     )
-    .unwrap();
+    .expect("failed to set rustAlpha.greet export");
     extend_wasm_exports(ctx, "rustAlpha", obj);
 }

packages/cre-rust-inject-beta/src/lib.rs

@@ -3,11 +3,11 @@ use javy_plugin_api::javy::quickjs::prelude::*;
 use javy_plugin_api::javy::quickjs::{Ctx, Object};
 
 pub fn register(ctx: &Ctx<'_>) {
-    let obj = Object::new(ctx.clone()).unwrap();
+    let obj = Object::new(ctx.clone()).expect("failed to create rustBeta export object");
     obj.set(
         "greet",
         Func::from(|| -> String { "Hello from beta".to_string() }),
     )
-    .unwrap();
+    .expect("failed to set rustBeta.greet export");
     extend_wasm_exports(ctx, "rustBeta", obj);
 }

packages/cre-sdk-examples/.gitignore

@@ -2,4 +2,5 @@ node_modules
 dist
 .turbo
 tmp.js
-tmp.wasm
+tmp.wasm
+.cre_build_tmp.js

packages/cre-sdk-examples/src/workflows/confidential-http-with-body/config.json

@@ -0,0 +1,4 @@
+{
+	"schedule": "0 */1 * * * *",
+	"url": "https://api.mathjs.org/v4?expr=randomInt(1,101)"
+}

packages/cre-sdk-examples/src/workflows/confidential-http-with-body/index.ts

@@ -0,0 +1,79 @@
+import {
+	ConfidentialHTTPClient,
+	CronCapability,
+	handler,
+	httpRequest,
+	json,
+	ok,
+	Runner,
+	type Runtime,
+	text,
+} from '@chainlink/cre-sdk'
+import { z } from 'zod'
+
+const configSchema = z.object({
+	schedule: z.string(),
+	url: z.string(),
+})
+type Config = z.infer<typeof configSchema>
+
+// Workflow demonstrate a usage of `httpRequest` helper
+// to build type-safe payloads for `ConfidentialHTTPClient`.
+const onCronTrigger = (runtime: Runtime<Config>) => {
+	const client = new ConfidentialHTTPClient()
+
+	// Example 1: request config as separate variable
+	const separateRequestConfig = {
+		request: httpRequest({
+			url: runtime.config.url,
+			method: 'POST',
+			bodyString: '{ hello: "world" }',
+			multiHeaders: {
+				'content-type': { values: ['application/json'] },
+			},
+		}),
+	}
+
+	client.sendRequest(runtime, separateRequestConfig).result()
+
+	// Example 2: using helper inline
+	client
+		.sendRequest(runtime, {
+			request: httpRequest({
+				url: runtime.config.url,
+				method: 'POST',
+				body: { hello: 'world' },
+				multiHeaders: {
+					'content-type': { values: ['application/json'] },
+				},
+			}),
+		})
+		.result()
+
+	// Example 3: not using helper at all
+	client
+		.sendRequest(runtime, {
+			request: {
+				url: runtime.config.url,
+				method: 'POST',
+				// no helper -> must use bodyString/bodyBytes (proto oneof keys)
+				bodyString: JSON.stringify({ hello: 'world' }),
+				multiHeaders: {
+					'content-type': { values: ['application/json'] },
+				},
+			},
+		})
+		.result()
+
+	return { success: true }
+}
+
+const initWorkflow = (config: Config) => {
+	const cron = new CronCapability()
+	return [handler(cron.trigger({ schedule: config.schedule }), onCronTrigger)]
+}
+
+export async function main() {
+	const runner = await Runner.newRunner<Config>({ configSchema })
+	await runner.run(initWorkflow)
+}