Distributing the Cookwala samples

Status (2026-10-06): published on PyPI, npm, Maven Central, NuGet, Homebrew and GHCR (tag samples-v0.3.0), with the single file and the .deb on GitHub Releases. Chocolatey is submitted and in moderation; RPM, pacman (AUR), apk, conda-forge and Snap have manifests ready but nothing submitted yet. JFrog Artifactory is a bring-your-own-instance channel — publish.sh pushes to whatever instance you point it at; there is no public one. Version: [VERSION](VERSION) (python packaging/build.py --check-versions fails CI if a manifest disagrees).

One payload, many channels #

The Python package is standard library only, so one file, cookwala-samples-<v>.pyz (a zipapp), runs on any Python 3.9+ on any OS. The OS package managers ship that file plus a one-line launcher; language registries ship their native port.

python samples/packaging/build.py builds the pyz, the wheel and sdist, the .deb, and renders every manifest below into samples/build/manifests/ with the version, URLs and sha256 filled in. Assets are expected at https://github.com/amado2k5/cookwala/releases/download/samples-v<v>/; pass --base-url to point them at another host, such as an Artifactory generic repository.

Channels #

Not provided, with the reason: winget needs a native Windows installer (exe or msi) and the samples ship a Python zipapp; Windows users have Chocolatey, Scoop, pip and npm. Go modules and crates.io have no sample port yet (the SDKs exist in sdk/go and sdk/rust).

Artifactory #

packaging/artifactory/publish.sh pushes each package type to a local repository of the matching type, with each ecosystem's own client: twine (PyPI), npm, Maven (-Partifactory) or Gradle, dotnet nuget push, Debian (with deb.distribution, deb.component, deb.architecture properties), RPM, Docker, and a generic repository for the pyz. Create the repositories first (default keys cookwala-<type>-local, overridable by environment variables listed in the script); then point remote or virtual repositories at them as usual.

Releasing #

1. Bump samples/VERSION and every manifest (python samples/packaging/build.py --check-versions lists them); add a line to the Python, npm, Maven and NuGet changelogs if you keep them.
2. Regenerate the bundle if the vocabularies, limits or example recipes changed: python samples/tools/build_bundle.py.
3. Merge, then tag: git tag samples-v0.3.0 && git push origin samples-v0.3.0.
4. CI tests every port, builds every package, creates the GitHub release, and publishes to each registry whose secret is set. The other channels take the rendered manifests from the release's samples-packages artifact.

Verified in this repository (2026-10-05) #

Installed the way a user installs, from local stand-ins for each registry #

packaging/install-test.sh repeats all of this, and CI runs it on every change (install job). No registry is contacted: npm gets a Verdaccio registry, pip a PEP 503 index, Maven and Gradle a file repository, NuGet a folder feed, apt a repository made with apt-ftparchive, Homebrew a local tap and a local copy of the release asset.

The first manual pass found two real bugs, now fixed and covered by tests: the JavaScript and Java run commands exited 0 when a job did not complete (Python and C# exited 1), and an unknown --fault kind was ignored instead of being a usage error. The four CLIs now give the same exit codes and the same reports.

Tests and builds #

Not run here #

The OpenShift template (needs a real cluster; Helm and Knative on a throwaway kind cluster are covered by the kind job). Everything else above runs in CI: snap install (samples-channel-snap.yml), choco install and scoop install on windows-latest (samples-channel-chocolatey.yml, samples-channel-scoop.yml), and all three cloud deploys — Azure Functions, AWS Lambda and Google Cloud Run functions — are proven against real accounts; see below.

Proven against real accounts: Azure Functions, AWS Lambda, Google Cloud #

Run 37443213472 (2026-10-06, samples-cloud.yml dispatched with target=azure behind the protected cloud-test environment):

• OIDC login via azure/login — a Microsoft Entra app registration (cookwala-ci) with a federated credential scoped to environment:cloud-test; no stored client secret.
• az group create + az deployment group create deployed samples/cloud/azure-functions/main.bicep (storage account, Y1 consumption plan, Application Insights, Function App) to eastus — overridable via the AZURE_REGION variable, since new subscriptions reject some regions (RequestDisallowedByAzure / "not accepting new customers").
• Zip-deployed samples/cloud/azure-functions/ with a remote build.
• Called the real endpoints: GET /api/health returned {"ok": true, ...}, POST /api/v1/samples/plan ranked the devices, and GET /api/v1/samples/demo?format=markdown produced the report with 3 completed.
• if: always() teardown deleted the resource group.

What the job actually did, from the run log:

$ az group create -n cw-samples-ci-37443213472 -l eastus --tags ttl=1d purpose=samples-ci
$ az deployment group create -g cw-samples-ci-37443213472 -f samples/cloud/azure-functions/main.bicep -p appName=cwci37443213472
$ az functionapp deployment source config-zip -g cw-samples-ci-37443213472 -n cwci37443213472 --src /tmp/app.zip --build-remote true
$ curl "https://cwci37443213472.azurewebsites.net/api/health?code=<key>"
{"ok": true, "service": "cookwala-samples", "version": "0.3.0", "core": "0.2.0"}
$ curl "https://cwci37443213472.azurewebsites.net/api/v1/samples/demo?format=markdown&code=<key>"
# Cookwala samples demo (offline, simulated kitchen) ... 3 completed ...
azure function demo verified
$ az group delete --yes --no-wait -n cw-samples-ci-37443213472

Required secrets in the cloud-test environment: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID. One setup detail worth noting: because this repository was renamed, GitHub emits the OIDC subject with numeric entity ids (repo:amado2k5@20147989/cookwala@1403544608:environment:cloud-test) — the federated credential's subject must match that form, not repo:amado2k5/cookwala:....

Run 37448439405 (2026-10-06, target=aws):

• OIDC role assumption via configure-aws-credentials — an IAM OIDC provider for token.actions.githubusercontent.com plus a cookwala-ci role whose trust policy matches repo:amado2k5*/cookwala*:environment:cloud-test; no stored access keys.
• sam build + sam deploy created the stack cw-samples-ci-37448439405 in eu-west-1: the Lambda function, its execution role, and an HTTP API.
• Called the public HttpApiUrl: /health returned {"ok": true, ...} and /v1/samples/demo?format=markdown produced the report with 3 completed.
• if: always() teardown ran sam delete.

Two findings this run exposed, both fixed in the same PR: the SAM template's AuthType: NONE needed an explicit AWS::Lambda::Permission for lambda:InvokeFunctionUrl, and anonymous Function-URL calls are blocked on brand-new AWS accounts regardless — so the workflow proves the deploy through the API Gateway HttpApiUrl output instead.

The blocked path and the working path, verified by hand against a real stack:

$ sam deploy --stack-name cw-debug --region eu-west-1 --parameter-overrides FunctionUrlAuth=NONE
Successfully created/updated stack - cw-debug
$ curl https://4yaogxj73phvz24wu7w3p6t5uu0hhhfh.lambda-url.eu-west-1.on.aws/health
{"Message":"Forbidden ..."}            # 403 even with AuthType NONE + public policy (new-account block)
$ curl https://eh00djbagh.execute-api.eu-west-1.amazonaws.com/health
{"ok": true, "service": "cookwala-samples", "version": "0.3.0", "core": "0.2.0"}
$ curl "https://eh00djbagh.execute-api.eu-west-1.amazonaws.com/v1/samples/demo?format=markdown"
# Cookwala samples demo (offline, simulated kitchen) ... 3 completed ...
$ sam delete --no-prompts --stack-name cw-debug    # Deleted successfully

Required secret in the cloud-test environment: AWS_ROLE_TO_ASSUME (the role ARN).

Run 37450278019 (2026-10-06, target=gcp):

• OIDC via google-github-actions/auth — a workload identity pool + provider on project cookwala-ci-5604 impersonating service account github-ci@, conditioned on the numeric repository_id (1403544608), so the repo-rename subject quirk cannot apply.
• gcloud functions deploy --gen2 created cookwala-samples-ci-37450278019 in europe-west1 (Cloud Run function, --allow-unauthenticated).
• Called the public .run.app URL: /health returned {"ok": true, ...} and /v1/samples/demo?format=markdown produced the report with 3 completed.
• if: always() teardown deleted the function.

What the job actually did, from the run log:

$ gcloud functions deploy cookwala-samples-ci-37450278019 --gen2 --runtime python312 \
    --region europe-west1 --source samples/cloud/gcp-functions --entry-point samples \
    --trigger-http --allow-unauthenticated --project cookwala-ci-5604
serviceConfig:
  uri: https://cookwala-samples-ci-37450278019-wokqyuqweq-ew.a.run.app
$ curl https://cookwala-samples-ci-37450278019-wokqyuqweq-ew.a.run.app/health
{"ok": true, "service": "cookwala-samples", "version": "0.3.0", "core": "0.2.0"}
$ curl "https://cookwala-samples-ci-37450278019-wokqyuqweq-ew.a.run.app/v1/samples/demo?format=markdown"
# Cookwala samples demo (offline, simulated kitchen) ... 3 completed ...
gcp function demo verified
$ gcloud functions delete cookwala-samples-ci-37450278019 --gen2 --region europe-west1

Required secrets in the cloud-test environment: GCP_PROJECT, GCP_SERVICE_ACCOUNT, GCP_WORKLOAD_IDENTITY_PROVIDER. Gen2 functions need an open billing account on the project — a fresh billing account's free trial plus the always-free 2M-invocation tier keeps CI cost at ~$0.