Build a dependency upgrade decision from official sources

This Recipe answers a recurring question: when a dependency has a new release, should you upgrade now, test first, or defer? It checks official material live, asks SoyaOS Cloud to analyze the changes and risks, and produces a machine-checked single-file HTML report.

Goal

The default case compares the Developer Portal’s wrangler 4.122.0 dependency with Cloudflare’s latest official stable release. The report must identify both versions, relevant changes, risks, trade-offs, validation steps, and a reasoned recommendation.

Versions, publication time, comparison state, and source URLs are determined by code. The model cannot rewrite them.

How it works

1. A Node.js client reads the official GitHub Release.
2. It retrieves the repository CHANGELOG and Cloudflare’s Wrangler documentation.
3. SoyaOS Cloud analyzes changes, risks, and validation steps only within those collected sources.
4. A closed JSON schema rejects unknown sources and contradictory decisions.
5. A deterministic template renders HTML, which is written only after content, structure, design, and security gates pass.

This is client-side Recipe orchestration plus Cloud inference. It does not depend on Tool Calls, which Cloud v0.2.0 does not provide.

Prepare and run

Install Node.js 22 or later and create an API Key through the Cloud quickstart. Treat the Key as an opaque string and keep it in an environment variable.

git clone https://github.com/soyaos/cloud-recipes.git
cd cloud-recipes
export SOYA_API_KEY='your-soyaos-api-key'
npm run run:dependency-upgrade-advisor

The default output is output/dependency-upgrade-advisor.html.

Use another version

node recipes/dependency-upgrade-advisor/run.mjs \
  --repository cloudflare/workers-sdk \
  --package wrangler \
  --current 4.122.0 \
  --changelog packages/wrangler/CHANGELOG.md \
  --docs-url https://developers.cloudflare.com/workers/wrangler/ \
  --output output/wrangler-upgrade.html

The current security contract accepts documentation only from developers.cloudflare.com, preventing an arbitrary URL from becoming an SSRF surface. GitHub sources must belong to the selected public repository.

Success criteria

Successful output includes three official sources, the deterministic version state, Cloud requestIds, and all four quality gates. Decisions must match the facts: an up-to-date dependency can only use “no change”; an available update cannot use it; and a current-ahead version must defer.

The HTML cannot contain scripts, iframes, forms, external styles, fonts, or images. Model text and remote documents are untrusted and escaped.

Common errors

• missing_api_key: SOYA_API_KEY is not set in this shell.
• release_not_found: no matching stable package release was found.
• unverified_source: the model cited a URL that was not collected.
• inconsistent_decision: the recommendation contradicts the version state.
• quality_gate_failed: the HTML did not pass every gate.

Source and tests: soyaos/cloud-recipes

Edit this page on GitHub