sigildocs

(sigil cli manager remote)

(sigil cli manager remote) - Remote release/API helpers (post-bootstrap)

Holds every sigil cli action that touches the network: upgrade (fetch the latest release metadata + binary), use (fetch a specific version's metadata + binary), install (current binary install + zig toolchain fetch). Factored out of (sigil cli manager) so the bootstrap CLI does not have to import (sigil json) or (sigil http). Loaded lazily from cli-handler in the parent module.

============================================================ UPGRADE FLOW (METADATA-FILE DESIGN) ============================================================

The binary hardcodes ONE URL: *release-metadata-url* below. Everything else (per-platform binary URLs, sha256 checksums, release notes URL) comes from a metadata JSON file fetched at upgrade time. Shape:

{ "latest": "0.14.0", "platforms": { "linux-amd64": "https://.../v0.14.0/sigil-linux-amd64", "linux-amd64-static": "...", ; static musl variant "linux-arm64": "...", "macos-arm64": "...", "macos-amd64": "...", "windows-amd64": "..." }, "sha256": { "linux-amd64": "abc123...", ... }, "release-notes-url": "https://.../tag/v0.14.0" }

The linux-amd64 target ships as two artifacts — a dynamic glibc build (linux-amd64) and a static musl build (linux-amd64-static). The client picks the one matching the running binary's own linkage; see resolve-platform-key + running-binary-static?.

Why this shape:

  • Decouples binary-upgrade flow from any specific release-repo URL. Future repo renames are invisible to upgrade — only the metadata file gets updated, and *release-metadata-url* stays constant.
  • Per-platform binary URLs centralized in one place.
  • sha256 verification is mandatory (signature is the metadata-file domain's HTTPS cert + the JSON-encoded sha256s, end-to-end).
  • Easily extensible: add channel: later to support stable / beta / nightly without changing the fetch protocol.

Mirrors the rustup / nvm / volta / bun-upgrade / deno-upgrade pattern.

Per-version metadata files live at <base-url>/v<version>.json. The latest.json file is updated to point at whichever version is current "latest." Both shapes are identical.

Exports

*release-metadata-url*variable

The single hardcoded URL that all remote operations route through.

This is the metadata-file URL, NOT the source-repo URL and NOT a per-binary URL. Compromising or moving this URL breaks the upgrade flow; everything downstream is rename-immune.

The metadata files live in codeberg:sigil/releases and are served via Codeberg's raw-content endpoint.

*release-metadata-base-url*variable

Base URL for per-version metadata files. Composed as: <base>/v<version>.json e.g. https://codeberg.org/sigil/releases/raw/branch/main/v0.14.0.json. Used by sigil cli use <ver> to fetch metadata for an arbitrary version (not just the latest).

fetch-jsonprocedure

Fetch JSON from a URL. Returns: (ok . <parsed-json>) - successful fetch + parse (error . network) - connection failed or non-2xx (error . parse) - JSON parsing failed

download-fileprocedure

Stream a file to disk. Returns #t on success, #f on failure.

fetch-release-metadataprocedure

Fetch the latest-release metadata file.

fetch-version-metadataprocedure

Fetch metadata for a specific version (e.g. "0.14.0").

resolve-platform-keyprocedure

Resolve the release platform key to download for THIS host, given the fetched metadata and the command opts.

The base key comes from detect-platform (e.g. "linux-amd64"). When the host wants the static/musl variant AND the metadata actually publishes a <base>-static asset, we return that key (e.g. "linux-amd64-static"); otherwise we return the base key.

"Wants static" is decided by, in priority order:

  1. --static / --dynamic override flags (edge cases, CI).
  2. The variant of the running binary itself — a static build needs static again; a dynamic build proves the host has a working glibc loader, so dynamic is fine.

The <base>-static existence guard means platforms that ship a single (already-static) artifact under the bare key — e.g. linux-arm64 — resolve correctly with no -static suffix, and hosts whose platform has no static asset gracefully fall back to the dynamic key rather than erroring on a missing variant.

compute-sha256procedure

Compute the sha256 of a file via the system sha256sum (Linux/BSD) or shasum -a 256 (macOS). Returns the lowercase hex digest, or #f if neither tool is available.

verify-sha256procedure

Verify a file's sha256 against an expected hex digest. Returns #t on match, #f otherwise.

install-via-mv-danceprocedure

Atomically replace a binary at dest-path with src-path.

On Linux, you can't write to a binary that's currently executing ("text file busy"). The standard workaround is to rename the existing file out of the way first, then move the new one into place. rename(2) works even on a running executable because the kernel tracks the inode, not the dirent.

  1. Rename dest-path → dest-path.old (if it exists).
  2. Move src-path → dest-path.
  3. Make the new binary executable.
  4. Best-effort: delete dest-path.old (ignore if held open).

Returns #t on success, #f on failure.

resolve-zig-download-urlprocedure

Resolve the pinned zig download URL from ziglang.org/download/index.json.

install-zig!procedure

Download and install zig to ~/.sigil/toolchain/zig/.

handle-installprocedure

sigil cli install - Install the currently-running binary to ~/.sigil. (Local operation: no remote fetch; included here because it shares helpers with handle-upgrade and the zig toolchain fetch.)

handle-upgradeprocedure

sigil cli upgrade - Fetch the latest-release metadata, compare to the running binary's version, download + verify + install if newer.

handle-useprocedure

sigil cli use <version> - Switch active version. Downloads if missing by fetching the per-version metadata file at <base>/v<version>.json.

metadata->latestvariable

(No description)

metadata->platform-urlvariable

(No description)

metadata->platform-sha256variable

(No description)

metadata->release-notes-urlvariable

(No description)