tamias

Appearance

Ref grammar ​

A ref names where a package comes from. One grammar covers all sources; the impl is picked by shape.

./dir                                         local (dev loop)
git:9aia/peregrin//libraries/ci-gate#v0.2.0   git + in-repo subdir + ref
https://…/ci-gate-0.2.0.tgz#sha256:<hex>        tarball (+ digest pin)
cf:<account>/<bucket>/<name>@<ver>             Cloudflare registry

Git ​

  • //subdir splits the repo from the in-repo path (go-getter convention) — required because nested groups make bare a/b/c/d ambiguous. Without //, a two-segment prefix is the repo and the remainder is the in-repo path.
  • #ref is a branch, tag, sha, or relative rev (HEAD~2, main^) — the version pin. The resolved commit sha is recorded in the store regardless. Revs can't start with - or contain whitespace, .., or //, so a ref can't smuggle git options.
  • Clone URLs are allowlisted: https, http, ssh, git, file, and scp-style git@host:…. Anything else is rejected.
  • Fetches run with GIT_TERMINAL_PROMPT=0 — a credential prompt fails the fetch instead of hanging.
  • org/repo defaults to github.com; host/org/repo becomes https://host/org/repo; git@host:… and ssh:///file:// pass through.

HTTP ​

  • A .tgz / .tar.gz URL over http(s), with an optional #sha256:<hex> pin — verified against the downloaded bytes before unpack. An http:// URL without a pin fetches cleartext and prints a warning; prefer https:// or pin the digest.

Cloudflare registry ​

cf:<account>/<bucket…>/<name>@<version>

The address derives the base URL: a full http(s)://… passes through (local / dev registries), a first segment with no dot is a workers.dev subdomain, and later segments are a path prefix.

cf:9aia/myrepo/[email protected]        → https://9aia.workers.dev/myrepo
cf:reg.example.com/[email protected]    → https://reg.example.com
cf:http://127.0.0.1:8903/[email protected]    → http://127.0.0.1:8903

install fetches <base>/index.json, finds name@version, pulls the tarball (<base>/<file>), unpacks it, and verifies the unpacked payload against the index's recorded dir_digest — a mismatched payload fails the install. Note the digest covers the payload dir, not the tarball bytes, so it can't be checked at transport (see Security model).

Local ​

  • ./x, ../x, ~/x, /x, or a bare path.