Release 0.4.0

.github/dependabot.yml

@@ -44,3 +44,12 @@ updates:
     ignore:
       - dependency-name: "*"
         update-types: ["version-update:semver-major"]
+
+  # The pinned base image of the container image (packaging/container/Dockerfile).
+  - package-ecosystem: "docker"
+    directory: "/packaging/container"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7

.github/scripts/openapi-drift-issue.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+# Keeps one open issue per label in step with the state of the OpenAPI check.
+#
+#   openapi-drift-issue.sh report <label> <title> <body-file> [<marker>]
+#       Opens an issue with the label, or comments on the open one. With a marker, nothing is
+#       posted when the issue or one of its comments already contains it.
+#   openapi-drift-issue.sh resolve <label> <comment>
+#       Comments on and closes the open issue with the label, if there is one.
+#
+# Needs gh, GH_TOKEN and GITHUB_REPOSITORY. Titles, bodies and comments are passed to gh as files or
+# arguments, never evaluated.
+set -euo pipefail
+
+mode=${1:?mode}
+label=${2:?label}
+
+ensure_label() {
+  local found
+  found=$(gh label list --repo "$GITHUB_REPOSITORY" --search "$label" --json name --jq '.[].name')
+  if ! grep -Fxq -- "$label" <<<"$found"; then
+    gh label create "$label" --repo "$GITHUB_REPOSITORY" --color D4C5F9 \
+      --description "Reported by the OpenAPI sync workflow" > /dev/null
+  fi
+}
+
+open_issue() {
+  gh issue list --repo "$GITHUB_REPOSITORY" --label "$label" --state open --json number --jq '.[0].number // empty'
+}
+
+case "$mode" in
+  report)
+    title=${3:?title}
+    body_file=${4:?body file}
+    marker=${5:-}
+    ensure_label
+    number=$(open_issue)
+    if [ -z "$number" ]; then
+      gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" --label "$label" --body-file "$body_file"
+    elif [ -n "$marker" ] && gh issue view "$number" --repo "$GITHUB_REPOSITORY" --json body,comments \
+      --jq '[.body, (.comments[].body)] | join("\n")' | grep -Fq -- "$marker"; then
+      echo "Issue #$number already reports this state"
+    else
+      gh issue comment "$number" --repo "$GITHUB_REPOSITORY" --body-file "$body_file"
+      echo "Commented on issue #$number"
+    fi
+    ;;
+  resolve)
+    comment=${3:?comment}
+    number=$(open_issue)
+    if [ -n "$number" ]; then
+      gh issue close "$number" --repo "$GITHUB_REPOSITORY" --reason completed --comment "$comment"
+      echo "Closed issue #$number"
+    else
+      echo "No open issue with the label $label"
+    fi
+    ;;
+  *)
+    echo "unknown mode: $mode" >&2
+    exit 2
+    ;;
+esac

.github/scripts/openapi-drift-report.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+"""Writes the issue body that reports a difference between openapi/v1.json and the published document.
+
+Usage: openapi-drift-report.py <oasdiff> <dir> <run-url>
+
+<dir> is the output directory of openapi-sync.py (it holds `published.json` and `vendored.json`);
+`body.md` is written there and `breaking=true|false` is printed for $GITHUB_OUTPUT.
+
+oasdiff runs in both directions, since either side may be the one that is behind:
+  vendored -> published  breaking: a client built from openapi/v1.json may fail against the published document
+  published -> vendored  breaking: a client built from the published document may fail against openapi/v1.json
+Breaking means an oasdiff change of level ERR, as `oasdiff breaking --fail-on ERR` counts it.
+
+The text oasdiff prints comes from the published document, so it is untrusted: it is truncated and
+only ever placed inside a code fence longer than any backtick run it contains. Any failure of
+oasdiff is an error (exit 1), never a quiet pass.
+"""
+
+import hashlib
+import json
+import pathlib
+import re
+import subprocess
+import sys
+
+MAX_CHARS = 8000
+ERR_LEVEL = 3
+
+
+def run(oasdiff, directory, *args):
+    result = subprocess.run(
+        [oasdiff, *args], cwd=directory, capture_output=True, text=True, errors="replace", timeout=300
+    )
+    if result.returncode != 0:
+        raise SystemExit(f"error: oasdiff {args[0]} failed (exit {result.returncode}): {result.stderr.strip()[:500]}")
+    return result.stdout
+
+
+def breaking(oasdiff, directory, base, revision):
+    try:
+        changes = json.loads(run(oasdiff, directory, "breaking", base, revision, "-f", "json") or "[]")
+    except ValueError as e:
+        raise SystemExit(f"error: oasdiff breaking printed output that is not JSON: {e}")
+    if not isinstance(changes, list):
+        raise SystemExit("error: oasdiff breaking printed an unexpected document")
+    return [c for c in changes if isinstance(c, dict) and c.get("level", 0) >= ERR_LEVEL]
+
+
+def clean(text):
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+
+
+def fenced(text):
+    """Truncates `text` and wraps it in a fence that no backtick run inside it can close."""
+    text = clean(text).strip()
+    note = ""
+    if len(text) > MAX_CHARS:
+        text, note = text[:MAX_CHARS], "\n[truncated]"
+    fence = "`" * max(3, max((len(m) for m in re.findall(r"`+", text)), default=0) + 1)
+    return f"{fence}text\n{text}{note}\n{fence}"
+
+
+def info_version(path):
+    return json.loads(path.read_text())["info"]["version"]
+
+
+def main():
+    oasdiff, directory, run_url = sys.argv[1], pathlib.Path(sys.argv[2]), sys.argv[3]
+    published = directory / "published.json"
+    digest = hashlib.sha256(published.read_bytes()).hexdigest()
+    vendored_digest = hashlib.sha256((directory / "vendored.json").read_bytes()).hexdigest()
+    forward = breaking(oasdiff, directory, "vendored.json", "published.json")
+    backward = breaking(oasdiff, directory, "published.json", "vendored.json")
+    changelog = run(oasdiff, directory, "changelog", "published.json", "vendored.json")
+    summary = run(oasdiff, directory, "summary", "published.json", "vendored.json")
+
+    def lines(changes):
+        return "\n".join(f"{c.get('operation', '')} {c.get('path', '')}: {c.get('text', '')}".strip() for c in changes) or "none"
+
+    def verdict(changes):
+        return f"**yes**, {len(changes)} breaking change(s)" if changes else "no"
+
+    body = f"""The published `/v1` OpenAPI document differs in content from the vendored `openapi/v1.json`. Key order and whitespace are not compared.
+
+| | Published document | `openapi/v1.json` |
+|---|---|---|
+| `info.version` | `{info_version(published)}` | `{info_version(directory / "vendored.json")}` |
+| SHA-256 | `{digest}` | `{vendored_digest}` |
+
+**Breaking changes, according to [oasdiff](https://github.com/oasdiff/oasdiff)**
+
+- From `openapi/v1.json` to the published document (a client built from the vendored copy may fail against the published one): {verdict(forward)}
+- From the published document to `openapi/v1.json` (a client built from the published document may fail against the vendored copy): {verdict(backward)}
+
+**Breaking changes from `openapi/v1.json` to the published document**
+
+{fenced(lines(forward))}
+
+**Breaking changes from the published document to `openapi/v1.json`**
+
+{fenced(lines(backward))}
+
+**Summary, published to vendored**
+
+{fenced(summary)}
+
+**Changelog, published to vendored**
+
+{fenced(changelog)}
+
+The vendored document is not updated automatically. Decide whether the API or the vendored copy is behind, then fix that side.
+
+Reported by the OpenAPI sync workflow: {run_url}
+
+<!-- openapi-drift:{digest} -->
+"""
+    (directory / "body.md").write_text(body)
+    print(f"breaking={'true' if forward or backward else 'false'}")
+    print(f"published_sha256={digest}")
+
+
+if __name__ == "__main__":
+    main()

.github/scripts/openapi-sync.py

@@ -1,29 +1,26 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
 # Copyright 2026 Hodeitek S.L.
-"""Compares openapi/v1.json with the document the API publishes and, when their content differs,
-replaces the vendored copy and updates what records it (openapi/README.md, xtask's EXPECTED_SHA256).
+"""Compares openapi/v1.json with the document the API publishes. Changes nothing in the repository.
 
 Usage: openapi-sync.py <url> <out-dir>
 
-Content means the JSON value: key order and whitespace do not count. On a difference the published
-bytes are written unchanged, as openapi/README.md requires, and <out-dir> receives `old.json` (the
-previous copy), `summary.md` and `version.txt`. Exits 0 in both cases and prints `changed=true` or
-`changed=false`; anything wrong with the published document is an error (exit 1).
+Content means the JSON value: key order and whitespace do not count. <out-dir> receives
+`published.json` (the published bytes, unchanged) and `vendored.json` (a copy of openapi/v1.json).
+Prints `changed=true` or `changed=false` and the two `info.version` values, as `key=value` lines
+fit for $GITHUB_OUTPUT, and exits 0 in both cases; anything wrong with the published document, or
+a failure to fetch it, is an error (exit 1) so the caller fails closed.
 
 Run from the repository root. Uses only the standard library.
 """
 
-import hashlib
 import json
 import pathlib
 import re
 import sys
 import urllib.request
 
 SPEC = pathlib.Path("openapi/v1.json")
-README = pathlib.Path("openapi/README.md")
-XTASK = pathlib.Path("xtask/src/main.rs")
 MAX_BYTES = 5 * 1024 * 1024
 USER_AGENT = "hodeishield-cli-openapi-sync (+https://github.com/Hodeitek/hodeishield-cli)"
 
@@ -41,7 +38,7 @@ def check(document, url):
     if not str(document.get("openapi", "")).startswith("3."):
         raise SystemExit(f"error: {url} is not an OpenAPI 3 document")
     version = document.get("info", {}).get("version")
-    # It ends up in a branch commit, a pull request title and workflow outputs: plain text only.
+    # It ends up in an issue and in workflow outputs: plain text only.
     if not isinstance(version, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+-]{0,39}", version):
         raise SystemExit(f"error: {url} has a missing or unusual info.version")
     if not document.get("paths"):
@@ -66,19 +63,12 @@ def canonical(document):
     return json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
 
 
-def operations(document):
-    methods = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
-    return {
-        f"{method.upper()} {path}"
-        for path, item in document["paths"].items()
-        for method in item
-        if method in methods
-    }
-
-
 def main():
     url, out = sys.argv[1], pathlib.Path(sys.argv[2])
-    published = fetch(url)
+    try:
+        published = fetch(url)
+    except OSError as e:
+        raise SystemExit(f"error: cannot fetch {url}: {e}")
     try:
         new = json.loads(published)
     except ValueError as e:
@@ -87,46 +77,13 @@ def main():
     local_refs_only(new, url)
     current = SPEC.read_bytes()
     old = json.loads(current)
-    if canonical(new) == canonical(old):
-        print("changed=false")
-        return
-
     out.mkdir(parents=True, exist_ok=True)
-    (out / "old.json").write_bytes(current)
-    SPEC.write_bytes(published)
-    digest = hashlib.sha256(published).hexdigest()
-    old_digest = hashlib.sha256(current).hexdigest()
-    version, old_version = new["info"]["version"], old["info"]["version"]
-    ops, old_ops = operations(new), operations(old)
-    non_get = sorted(op for op in ops if not op.startswith("GET "))
-    count = f"{len(ops)}, all `GET`" if not non_get else str(len(ops))
-
-    readme = README.read_text()
-    readme = re.sub(r"(\| `info\.version` \| `)[^`]*(` \|)", rf"\g<1>{version}\g<2>", readme)
-    readme = re.sub(r"(\| SHA-256 \| `)[0-9a-f]{64}(` \|)", rf"\g<1>{digest}\g<2>", readme)
-    readme = re.sub(r"(\| Operations \| )[^|\n]*?( \|)", rf"\g<1>{count}\g<2>", readme)
-    README.write_text(readme)
-    xtask = XTASK.read_text()
-    xtask, replaced = re.subn(
-        r'(const EXPECTED_SHA256: &str = ")[0-9a-f]{64}(";)', rf"\g<1>{digest}\g<2>", xtask
-    )
-    if replaced != 1:
-        raise SystemExit(f"error: EXPECTED_SHA256 not found in {XTASK}")
-    XTASK.write_text(xtask)
-
-    lines = [
-        f"- `info.version`: `{old_version}` → `{version}`",
-        f"- SHA-256: `{old_digest[:12]}…` → `{digest[:12]}…`",
-        f"- Operations: {len(old_ops)} → {len(ops)}",
-    ]
-    for label, items in (("Added", sorted(ops - old_ops)), ("Removed", sorted(old_ops - ops))):
-        if items:
-            lines.append(f"- {label} operations: " + ", ".join(f"`{op}`" for op in items))
-    if non_get:
-        lines.append("- **Not read-only**: " + ", ".join(f"`{op}`" for op in non_get))
-    (out / "summary.md").write_text("\n".join(lines) + "\n")
-    (out / "version.txt").write_text(version + "\n")
-    print("changed=true")
+    (out / "published.json").write_bytes(published)
+    (out / "vendored.json").write_bytes(current)
+    changed = canonical(new) != canonical(old)
+    print(f"changed={'true' if changed else 'false'}")
+    print(f"published_version={new['info']['version']}")
+    print(f"vendored_version={old['info'].get('version')}")
 
 
 if __name__ == "__main__":

.github/scripts/package-manifests.py

@@ -12,7 +12,9 @@
 
 Every URL points at an asset of the release and every hash comes from its SHA256SUMS, so a file
 missing from the release is an error. The winget installer is the MSI when the release has one
-(its product code must then be given), otherwise the zip with the portable exe inside.
+(its product code must then be given), otherwise the zip with the portable exe inside. The Scoop
+manifest also lists the arm64 zip when the release has one; winget stays x64 only until there is an
+arm64 MSI.
 
 Uses only the standard library.
 """
@@ -48,6 +50,9 @@ def asset(target, ext):
     x86_url, x86_sha = asset("x86_64-unknown-linux-musl", "tar.gz")
     arm_url, arm_sha = asset("aarch64-unknown-linux-musl", "tar.gz")
     zip_url, zip_sha = asset("x86_64-pc-windows-msvc", "zip")
+    # Releases before the Windows arm64 build do not have this zip: Scoop then lists 64bit only.
+    has_arm64_zip = f"hodeishield-{version}-aarch64-pc-windows-msvc.zip" in sums
+    arm64_zip_url, arm64_zip_sha = asset("aarch64-pc-windows-msvc", "zip") if has_arm64_zip else (None, None)
     msi_name = f"hodeishield-{version}-x86_64-pc-windows-msvc.msi"
     has_msi = msi_name in sums
     if has_msi and not (product_code and re.fullmatch(r"\{[0-9A-F-]{36}\}", product_code)):
@@ -98,18 +103,25 @@ def install
 
     manifest = out / "scoop" / "bucket" / "hodeishield.json"
     manifest.parent.mkdir(parents=True, exist_ok=True)
+    scoop_arch = {"64bit": {"url": zip_url, "hash": zip_sha}}
+    scoop_autoupdate = {"64bit": {
+        "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
+    }}
+    if has_arm64_zip:
+        scoop_arch["arm64"] = {"url": arm64_zip_url, "hash": arm64_zip_sha}
+        scoop_autoupdate["arm64"] = {
+            "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-aarch64-pc-windows-msvc.zip"
+        }
     manifest.write_text(json.dumps({
         "version": version,
         "description": DESCRIPTION,
         "homepage": "https://hodeishield.com",
         "license": "Apache-2.0",
-        "architecture": {"64bit": {"url": zip_url, "hash": zip_sha}},
+        "architecture": scoop_arch,
         "bin": "hodeishield.exe",
         "checkver": {"github": f"https://github.com/{REPO}"},
         "autoupdate": {
-            "architecture": {"64bit": {
-                "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
-            }},
+            "architecture": scoop_autoupdate,
             "hash": {"url": "$baseurl/SHA256SUMS"},
         },
     }, indent=4) + "\n")