Osy#betaRun it on Osyrin: osyrin.com

Reference / Local

Working offline

osy restore [path] · osy lock [path] [--offline]

`osy restore` fetches everything a project needs into the package cache — every release it pins or would pin, and every answer the bridge search asks GitHub — and writes nothing in the project. After it, `osy lock`, `osy validate` and `osy test` of that project run with no network at all.

stablelocalcli

Summary#

Run osy restore once where there is a network; from then on the project locks, validates and tests where there is none — a CI job with no egress, a sandboxed agent, a plane. It is the step dotnet restore or npm ci is in other toolchains: it fills the package cache and leaves your files exactly as they were.

Signature#

osy restore                 # this project, into this machine's package cache
osy restore path/to/app     # another project
osy lock                    # keeps every pin its `use` still accepts — no network for those
osy lock --offline          # asks no network at all, even for what is not cached

Description#

Two verbs make a project independent of the network. osy restore runs where there is one and fills the package cache; osy lock reads that cache before it asks GitHub anything, and keeps every pin the lock already holds while your use lines still accept it. osy validate and osy test read the lock and the cache and never search.

What osy restore fetches#

It resolves the project exactly as osy lock would — the same resolution, with the write left out — and keeps what that resolution needed in the package cache:

  • every release the project's use lines and their own dependencies resolve to, and every release the osyrin.lock on disk pins today;
  • the release lists each package's versions were chosen from;
  • the bridge search's answers — which published packages complete the ones your app uses — with the note each was given under, so an offline lock records the same bridges section an online one does.

It exits 0 when all of that is in the cache, and 1 with one line per thing it could not fetch. It never writes osyrin.lock; osy lock does that.

$ osy restore
  Osysharp.Charts 1.8.0
  Osysharp.Identity 0.9.0
  …
✓ Restored 9 packages and the catalog answers into /home/you/.osy/packages — this project now locks, validates and tests with no network

Where the cache is#

The package cache is packages/ under $OSY_HOME (default ~/.osy/packages), shared by every project on the machine. Point OSY_HOME somewhere else to give a job a cache of its own — fill it with osy restore on a host with a network, then hand the directory to the job. The job only reads it.

Locking with no network#

osy lock keeps a pin osyrin.lock already holds when the project's use still accepts that version and its archive is in the cache: nothing is asked of the network for it. So a lock of an unchanged project, with the network gone, writes a lock byte for byte the same as before. Moving a pin to a newer release inside its major is osy update's job (package.osy), never osy lock's.

When GitHub cannot be reached, everything else the lock needs is answered from what the cache remembers: the release lists and the bridge search's last answer. The lock then prints one line saying the answer was read from the cache, and records the search as it was made.

--offline asks no network at all: the bridge search reads only the remembered answer, and when there is none it records that the public search was skipped.

When it still needs the network#

A use the cache cannot answer — one you just added, a constraint you changed, a cache never filled — needs the network, and the lock says so for each one, naming the cache and the command that fills it:

✗ PACKAGE_FETCH_FAILED: Acme.Crm: Connection refused — GitHub could not be reached, and `use Acme.Crm@0;` needs a release this machine does not hold, so it needs the network. The package cache (/home/you/.osy/packages) holds no answer to use instead — run `osy restore` where there is a network to fill it, then run this again offline.

Nothing is written when that happens; the lock on disk is left as it was.

When the tools reach GitHub#

A project whose osyrin.lock pins every package it uses, with those archives in the cache, is checked with no request at all — so a loop of validate and test never spends a GitHub token's hourly limit.

VerbReaches GitHub when
osy validate, lint, test, check, explain, model, compilea pinned release is not in the cache (one download of exactly that version, not an API call), or a use is pinned by no lock this project reads (one version list)
the same verbs in a workspace package (packages/<name>/ of an app's repository)only as above: a package with no lock of its own is checked against the releases the app's osyrin.lock pins
osy lockfor a use no lock pins yet, and for the bridge search
osy updatealways — its question is "what is the newest release"; a remembered version list is re-checked with a conditional request, which costs no API budget when nothing changed
osy restoreto fill the cache
osy kit, osy kit atoms, osy docsnever

A version list GitHub answered is kept in the package cache. Within ten minutes it is used with no request; after that it is re-checked conditionally; and when GitHub cannot be reached, or the token's limit is spent, the kept list stands in. When nothing can stand in, the refusal names the package, the constraint and the time the limit resets:

✗ PACKAGE_FETCH_FAILED: Acme.Crm: the versions of acme/crm (to choose one for `@0`) could not be listed: GitHub's API limit for your token is spent — it resets at 21:07 (in 4 min). No lock this project reads pins it, and this machine has never listed them, so nothing can stand in. Run it again then; a project whose `osyrin.lock` pins every package it uses needs no listing at all.

osy lock in the project that uses the package records the pin, after which nothing asks again.

See also#

Related

The local loop (running your app on your own machine)

Everything the `osy` CLI does to the project in front of you — run it, look at what it did, check it before you ship…

package.osy

The manifest that makes a git repository a publishable Osy# package. It names the package, says which of the…

Bridges — a package that arrives when an app uses the two it completes

A bridge is a package whose manifest says `completes A@0, B@0;`. An app that uses every package it completes gets it…

Checking your app

Checks your app against production best-practice rules and reports where it falls short — the maturity signal, beside…