Swamp Version
Read the swamp version a host or container is running and report how far it has drifted behind the published channel. Read-only — it never updates, installs, or restarts anything; it tells you a newer build exists and stops there. Fills the gap swamp update --check leaves: that answers for the binary invoking it, on the platform invoking it, which is no help when the install you care about is a pinned binary inside a container on another host. sync records what a target reports about itself — its version and, via uname, the artifact platform it runs on. drift resolves the newest build published on a channel for THAT platform and reports status (current/behind/ahead) plus the lag in hours. repoDrift covers the second, independent axis a swamp serve install goes stale on — the git checkout it serves. A container can run the newest published binary while serving a branch it last fetched weeks ago, because a serve entrypoint typically fetches at boot only; drift reports current throughout and so does every healthcheck. It fetches before comparing, which is load-bearing rather than tidy: a checkout's own origin/<ref> is frozen at its last boot, so trusting it reports a badly stale target as up to date. It then reports the exact number of commits behind — enumerable here, unlike the binary axis, because git has the list — the lag in hours, and current/behind/ahead/diverged, keeping diverged distinct because the fix for behind is a restart and a restart hard-resets, destroying the very commits that make a checkout diverged. Targets are reached three ways: the local binary, docker exec (optionally through a named docker context, so one host can check a container on another), or SSH with BatchMode so an unattended run fails fast instead of hanging on a password prompt. The channel is resolved by a single HEAD against the stable alias, reading the resolved version out of its website-redirect metadata — one request rather than the ~90 MB the archive weighs — and the same pass verifies the platform-specific archive is actually fetchable, which is the precondition for pinning a rebuild to it. Versions are compared numerically because the build ordinal in YYYYMMDD.HHMMSS.N is not zero-padded: as strings 20260808.001107.10 sorts below ...9, so a string compare reports a target one build behind as up to date the day a tenth build ships. hoursBehind is derived from the timestamps embedded in each version and is documented as a lag, not a count of missed builds — swamp publishes no release list, so the builds in between cannot be enumerated and this extension does not pretend otherwise. An unreachable target, an unparseable version at either end, a channel alias that answers without its redirect header, and a resolved archive that 404s are all raised as errors rather than folded into a reassuring current.
Declare SPDX license (MIT) in manifest.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| probe | enum | How to reach the target: run the binary here (`local`), inside a container (`docker`), or over SSH (`ssh`). |
| container? | string | Container name for the `docker` probe, e.g. swamp-serve. |
| dockerContext? | string | Docker context to run against, e.g. np-docker. Omit to use the active context. Lets one host check a container on another without SSHing itself. |
| host? | string | SSH destination for the `ssh` probe, e.g. docker or user@host. Uses your SSH config. |
| binary? | string | Name or path of the swamp binary on the target. Override when it is not on PATH. |
| platform? | string | Artifact platform to compare against, e.g. linux-x86_64 or darwin-aarch64. Detected from the target with `uname` when omitted — which is almost always what you want, since comparing a container against the checking host's platform is the mistake this field exists to prevent. |
| channel? | string | Published channel alias to resolve, as used by install.sh. `stable` unless you deliberately track another. |
| artifactBaseUrl? | string | Artifact host. Override only for a mirror. |
| verifyArtifact? | boolean | After resolving the channel, HEAD the resolved platform-specific archive to confirm it is actually fetchable. This is the precondition for pinning a rebuild to it; turning it off saves one request and gives up that guarantee. |
| label? | string | Short stable name for this target in resource names. Derived from the probe settings when omitted. |
| timeoutMs? | number | Abort each probe command and each HTTP call after this long. A drift check must never hang a workflow. |
| repoDir? | string | Path INSIDE the target to the git checkout `swamp serve` runs from. Only used by `repoDrift`. |
| repoRef? | string | Branch the deployment tracks. `repoDrift` compares the checkout against `origin/<repoRef>`. |
| repoFetch? | boolean | Run `git fetch` before comparing, so `origin/<repoRef>` reflects the real remote. Leaving this off compares against whatever the target last fetched — which is exactly the stale reading that makes a behind container look current. Turn it off only when the target has no network or no credential. |
| execEnv? | record | Environment variables to set for probe commands. The motivating case is `GIT_SSH_COMMAND`: a container's entrypoint may export it in-process, in which case `docker exec` does NOT inherit it and git fetch fails `Permission denied (publickey)` even though the deploy key is fine. Set it here to reproduce the credential the target itself uses. |
Resources
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned