Skip to main content

Swamp Version

@sntxrr/swamp-versionv2026.10.14.1· MIT(was none)· 1mo agoBEHAVIORS
01README

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.

02Release Notes

Declare SPDX license (MIT) in manifest.

03Behaviors1
@sntxrr/swamp-version/targetv2026.08.15.1swamp_target.ts

Global Arguments

ArgumentTypeDescription
probeenumHow to reach the target: run the binary here (`local`), inside a container (`docker`), or over SSH (`ssh`).
container?stringContainer name for the `docker` probe, e.g. swamp-serve.
dockerContext?stringDocker 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?stringSSH destination for the `ssh` probe, e.g. docker or user@host. Uses your SSH config.
binary?stringName or path of the swamp binary on the target. Override when it is not on PATH.
platform?stringArtifact 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?stringPublished channel alias to resolve, as used by install.sh. `stable` unless you deliberately track another.
artifactBaseUrl?stringArtifact host. Override only for a mirror.
verifyArtifact?booleanAfter 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?stringShort stable name for this target in resource names. Derived from the probe settings when omitted.
timeoutMs?numberAbort each probe command and each HTTP call after this long. A drift check must never hang a workflow.
repoDir?stringPath INSIDE the target to the git checkout `swamp serve` runs from. Only used by `repoDrift`.
repoRef?stringBranch the deployment tracks. `repoDrift` compares the checkout against `origin/<repoRef>`.
repoFetch?booleanRun `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?recordEnvironment 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.
fn sync()
Record the swamp version and platform the target reports. Read-only.
fn drift()
Compare the target's swamp version against the newest build published for its platform, and report the resolved artifact a rebuild would pin to. Read-only; updates nothing.
fn repoDrift()
Compare the git checkout the target serves against the branch it tracks, and report how many commits it has not deployed. Read-only with respect to the working tree: it fetches and reads refs, and never checks anything out.

Resources

target(infinite)— What the target reports about itself: the swamp version it runs and the platform it runs on.
drift(infinite)— Comparison of the target's version against the newest build published for its platform.
repo(infinite)— Comparison of the git checkout the target serves against the branch it tracks.
04Previous Versions1
2026.08.08.1
05Stats
A
100 / 100
Downloads
49
Archive size
23.1 KB
  • 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
06Platforms
07Labels