Fix set_many examples to use list[FieldUpdate] (#138)

* docs(sdk): fix set_many examples to use list[FieldUpdate]

set_many() examples in quickstart.md, async.md, and the runnable
async-client example used a plain dict, but the real signature requires
list[FieldUpdate] and raises AttributeError at runtime when iterated.

- Fix all three call sites to construct FieldUpdate objects.
- Add a "Bulk writes" subsection to quickstart.md documenting FieldUpdate,
  including expected_checksum (optimistic concurrency) and
  value_description (per-value metadata).
- Extend the examples CI job to start a live decree server, seed it, and
  run each example end-to-end (not just py_compile), so a broken example
  like this one fails CI instead of silently passing.

Closes #133

* fix(examples): use --server flag for decree CLI in setup.py

The decree CLI's global flag for the server address is --server (env
DECREE_SERVER), not --addr. setup.py passed --addr, which cobra rejects
as an unknown flag. Because the root command sets SilenceErrors: true
and main.go exits without printing the error, the failure surfaced as
an empty 'Error seeding: ' message — only visible once CI actually
exercised this path (added in this PR for #133).

Refs #133

* fix(examples): pass --insecure to decree CLI for local plaintext server

The dockerized decree server in CI/local dev runs without TLS, but the
CLI defaults to TLS (--insecure must be explicitly set, mirroring how
the SDK clients and integration tests connect with insecure=True).
Without it, dialServer's TLS handshake fails and the silenced cobra
error surfaces only as an empty 'Error seeding: ' message.

Refs #133

* fix(examples): correct decree CLI invocation in setup.py

The seeding step was failing for three independent reasons, each
discovered by actually running it against a live server (the new
'Examples' CI job exercises this path for the first time):

1. The CLI's server-address flag is --server (env DECREE_SERVER), not
   --addr — cobra rejected the unknown flag, and because the root
   command sets SilenceErrors/SilenceUsage with no fallback print in
   main.go, the failure surfaced only as an empty 'Error seeding: '.
2. The local server runs in plaintext (INSECURE_LISTEN=1); the CLI
   defaults to TLS, so dialing requires --insecure (mirrors how the
   SDK's own integration tests connect with insecure=True).
3. The server rejects requests with no x-subject header as
   unauthenticated, and the CLI sets none by default — needs --subject.
4. Tenants can only be created against a published schema version, and
   imported schema versions start as unpublished drafts — needs
   --auto-publish.

Also switched the tenant-ID parsing from matching a 'Tenant: <id>'
line (a format the CLI has never produced — its seed output is a
RESOURCE/ID/CREATED/DETAILS table) to --output json, which gives a
stable [][]string the script can parse directly.

Verified end-to-end against a live decree server via docker-compose:
schema import + auto-publish + tenant creation + config import all
succeed and .tenant-id is written correctly.

Refs #133

* Fix examples to avoid pre-existing set()/set_many() type-coercion bug

quickstart and async-client demoed set()/set_many() against bool and
integer fields (app.debug, server.rate_limit). The SDK's
make_string_typed_value() always wraps values as TypedValue(string_value=...),
but the server validates the oneof variant against the field's declared
type with no coercion — so these calls always raised
InvalidArgumentError: expected bool/integer value.

Switch both examples to string fields (app.name, payments.currency),
which exercise the same list[FieldUpdate] syntax (the actual point of
this fix) without hitting the deeper SDK defect. That defect is filed
separately.

* Add missing smoke test for live-config example

The Makefile's EXAMPLES list already included live-config, but no
test_*.py existed for it — so 'make test' (now run by CI's Examples
job against a live server) failed with "file or directory not found:
test_*.py".

The example blocks on a changes() iterator, so the test starts it,
waits for the initial "Current values"/"Watching for changes" output,
then sends SIGINT (which the example's own handler turns into a clean
sys.exit(0)) rather than expecting a returncode of 0.

* Mark app.debug nullable in example schema

examples/error-handling/main.py demonstrates set_null()/nullable=True
on app.debug, but the seed schema never declared it nullable — so
set_null() failed live with "field app.debug: value is required (not
nullable)". The example was never exercised against a live server
before this PR added that CI step.

* Remove broken set() restore step from error-handling example

After demonstrating set_null()/nullable=True on app.debug, the example
tried to restore it via client.set(tenant_id, "app.debug", "false") —
which hits the same pre-existing set()/set_many() type-coercion defect
as #139 (make_string_typed_value always sends string_value; the server
requires bool_value for a bool field, raising "expected bool value").

The restore step wasn't load-bearing for the nullable demo (set_null +
get already shows the behavior), so drop it rather than work around the
defect here too.

Author: zeevdr

.github/workflows/ci.yml

@@ -1,8 +1,11 @@
 # CI pipeline for the OpenDecree Python SDK.
 #
 # Jobs: lint, typecheck, test (matrix: 3.11-3.13), examples → check (alls-green gate)
-# Integration job is optional — runs on workflow_dispatch or when
-# DECREE_TEST_ADDR secret is set, starting a live server via docker-compose.
+# The examples job compile-checks every example, then starts a live decree
+# server via docker-compose, seeds it, and runs each example end-to-end —
+# so a broken runnable example (e.g. wrong set_many() argument type) fails CI.
+# Integration job is optional — runs on workflow_dispatch with run-integration
+# enabled, exercising the SDK's own integration test suite against a live server.
 
 name: CI
 
@@ -109,31 +112,115 @@ jobs:
   examples:
     name: Examples
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: read
     steps:
-      - name: Checkout
+      - name: Checkout decree-python
         uses: actions/checkout@v6
         with:
           persist-credentials: false
 
+      - name: Checkout decree (for docker-compose + server + CLI)
+        uses: actions/checkout@v6
+        with:
+          repository: opendecree/decree
+          path: decree
+          persist-credentials: false
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
           cache-dependency-path: sdk/pyproject.toml
 
-      - name: Install SDK
-        run: pip install -e sdk/
+      - name: Install SDK with dev dependencies
+        run: pip install -e "sdk[dev]"
 
       - name: Compile-check all examples
+        # Syntax-only — catches typos but not runtime errors (e.g. iterating
+        # a dict where a list[FieldUpdate] is expected). The steps below
+        # actually execute the examples against a live server.
         run: |
           python -m py_compile examples/quickstart/main.py
           python -m py_compile examples/async-client/main.py
           python -m py_compile examples/live-config/main.py
           python -m py_compile examples/error-handling/main.py
           python -m py_compile examples/setup.py
 
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver: docker-container
+          driver-opts: network=host
+
+      - name: Build server image
+        uses: docker/build-push-action@v7
+        with:
+          context: decree
+          file: decree/build/Dockerfile
+          load: true
+          tags: decree-server
+          cache-from: |
+            type=registry,ref=ghcr.io/opendecree/decree:buildcache
+            type=gha,scope=py-examples-server
+          cache-to: type=gha,scope=py-examples-server,mode=max
+
+      - name: Build tools image (for migrations)
+        uses: docker/build-push-action@v7
+        with:
+          context: decree/build
+          file: decree/build/Dockerfile.tools
+          load: true
+          tags: decree-tools
+          cache-from: |
+            type=registry,ref=ghcr.io/opendecree/decree-tools:buildcache
+            type=gha,scope=py-examples-tools
+          cache-to: type=gha,scope=py-examples-tools,mode=max
+
+      - name: Set up Go (for CLI build)
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: decree/cmd/decree/go.mod
+          cache-dependency-path: decree/cmd/decree/go.sum
+
+      - name: Build decree CLI
+        # examples/setup.py shells out to `decree seed` to provision the
+        # schema/tenant/config that the examples read and write.
+        run: |
+          cd decree/cmd/decree && go build -o "$HOME/go/bin/decree" .
+          echo "$HOME/go/bin" >> "$GITHUB_PATH"
+
+      - name: Start decree service
+        run: docker compose -f decree/docker-compose.yml up -d --wait service
+        env:
+          SERVICE_IMAGE: decree-server
+          TOOLS_IMAGE: decree-tools
+
+      - name: Seed example data
+        run: cd examples && python setup.py
+        env:
+          DECREE_ADDR: "localhost:9090"
+
+      - name: Run examples against the live server
+        # Executes each runnable example end-to-end (including async-client's
+        # set_many call) so a broken example fails CI instead of silently
+        # passing a syntax-only check — see opendecree/decree-python#133.
+        run: cd examples && make test
+
+      - name: Tear down services
+        if: always()
+        run: docker compose -f decree/docker-compose.yml down -v
+
   wheel-check:
     name: Wheel contents
     runs-on: ubuntu-latest

examples/async-client/main.py

@@ -14,7 +14,7 @@
 from datetime import timedelta
 from pathlib import Path
 
-from opendecree import AsyncConfigClient
+from opendecree import AsyncConfigClient, FieldUpdate
 
 
 async def main() -> None:
@@ -49,18 +49,23 @@ async def main() -> None:
         print(f"  app.debug:         {debug}")
         print(f"  server.rate_limit: {rate_limit}")
 
-        # Atomic multi-write.
+        # Atomic multi-write — each update is a FieldUpdate, not a plain dict.
+        # Values are always strings — the server validates against the
+        # field's declared type, so this works cleanly for string fields.
         await client.set_many(
             tenant_id,
-            {"app.debug": "true", "server.rate_limit": "200"},
+            [
+                FieldUpdate("app.name", "Acme Corp App (async)"),
+                FieldUpdate("payments.currency", "EUR"),
+            ],
             description="async example update",
         )
-        print("\nUpdated app.debug=true, server.rate_limit=200")
+        print("\nUpdated app.name and payments.currency")
 
-        debug = await client.get(tenant_id, "app.debug", bool)
-        rate_limit = await client.get(tenant_id, "server.rate_limit", int)
-        print(f"  app.debug:         {debug}")
-        print(f"  server.rate_limit: {rate_limit}")
+        name = await client.get(tenant_id, "app.name")
+        currency = await client.get(tenant_id, "payments.currency")
+        print(f"  app.name:          {name}")
+        print(f"  payments.currency: {currency}")
 
 
 def get_tenant_id() -> str:

examples/error-handling/main.py

@@ -47,10 +47,6 @@ def main() -> None:
         value = client.get(tenant_id, "app.debug", str, nullable=True)
         print(f"app.debug (after set_null):  {value!r}")
 
-        # Restore it.
-        client.set(tenant_id, "app.debug", "false")
-        print(f"app.debug (restored):        {client.get(tenant_id, 'app.debug', bool)!r}")
-
         # --- Error hierarchy ---
         print("\n=== Error hierarchy ===")
 

examples/live-config/test_live_config.py

@@ -0,0 +1,33 @@
+"""Smoke test for the live-config example."""
+
+import signal
+import subprocess
+import sys
+
+import pytest
+
+
+@pytest.mark.example
+def test_live_config_runs() -> None:
+    """Verify the example connects, prints current values, then starts watching."""
+    proc = subprocess.Popen(
+        [sys.executable, "main.py"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        stdout, stderr = proc.communicate(timeout=10)
+    except subprocess.TimeoutExpired:
+        # Expected — the example blocks on changes(). SIGINT triggers its
+        # own handler (signal.signal(... lambda *_: sys.exit(0))), which
+        # flushes stdout on the way out.
+        proc.send_signal(signal.SIGINT)
+        try:
+            stdout, stderr = proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            stdout, stderr = proc.communicate()
+
+    assert "Current values:" in stdout, f"stdout: {stdout}\nstderr: {stderr}"
+    assert "Watching for changes" in stdout

examples/quickstart/main.py

@@ -37,12 +37,14 @@ def main() -> None:
         fee_rate = client.get(tenant_id, "payments.fee_rate", float)
         print(f"payments.fee_rate: {fee_rate}")
 
-        # set() and set_many() for writes.
-        client.set(tenant_id, "app.debug", "true")
-        print("\nSet app.debug = true")
+        # set() and set_many() for writes. The value is always a string —
+        # the server validates it against the field's declared type, so
+        # this works cleanly for string fields like app.name.
+        client.set(tenant_id, "app.name", "Acme Corp App (updated)")
+        print("\nSet app.name = 'Acme Corp App (updated)'")
 
-        debug = client.get(tenant_id, "app.debug", bool)
-        print(f"app.debug:         {debug}")
+        name = client.get(tenant_id, "app.name")
+        print(f"app.name:          {name}")
 
 
 def get_tenant_id() -> str:

examples/seed.yaml

@@ -9,6 +9,7 @@ schema:
     app.debug:
       type: bool
       description: Enable debug logging
+      nullable: true
     features.dark_mode:
       type: bool
       description: Enable dark mode UI

examples/setup.py

@@ -8,6 +8,7 @@
     python setup.py
 """
 
+import json
 import os
 import subprocess
 import sys
@@ -21,25 +22,40 @@ def main() -> None:
 
     # Use the decree CLI to seed — it handles schema creation, tenant
     # creation, and config import in one command.
+    # --auto-publish: tenants can only be created against a published
+    #   schema version, and imported versions start as unpublished drafts.
+    # --subject: the server rejects unauthenticated requests (empty
+    #   x-subject), and the CLI does not set one by default.
     result = subprocess.run(
-        ["decree", "seed", "--addr", addr, str(seed_file)],
+        [
+            "decree", "seed",
+            "--server", addr,
+            "--insecure",
+            "--auto-publish",
+            "--subject", "examples-setup",
+            "--output", "json",
+            str(seed_file),
+        ],
         capture_output=True,
         text=True,
     )
     if result.returncode != 0:
         print(f"Error seeding: {result.stderr}", file=sys.stderr)
         sys.exit(1)
 
-    # Parse tenant ID from output (line: "Tenant:  <id> (created=true)")
-    for line in result.stdout.splitlines():
-        if line.startswith("Tenant:"):
-            tenant_id = line.split()[1]
+    # `decree seed -o json` prints a [][string] table: a header row
+    # ["RESOURCE", "ID", "CREATED", "DETAILS"] followed by one row per
+    # resource, e.g. ["tenant", "<id>", "true", ""].
+    rows = json.loads(result.stdout)
+    for row in rows:
+        if row[0] == "tenant":
+            tenant_id = row[1]
             tenant_id_file.write_text(tenant_id)
-            print(result.stdout, end="")
+            print(f"Tenant: {tenant_id}")
             print("Tenant ID written to .tenant-id")
             return
 
-    print(f"Could not parse tenant ID from output:\n{result.stdout}", file=sys.stderr)
+    print(f"Could not find tenant row in output:\n{result.stdout}", file=sys.stderr)
     sys.exit(1)