Provider versions

Where each built-in service’s provider comes from, how baseline.lock pins it, and how to run without a network.

Each built-in service runs a provider package, such as @deploybaseline/stripe, in its own process. The CLI finds that package before it starts the service, pins the exact version in baseline.lock, and prints where it came from:

  stripe  http://localhost:4009
    Source: stripe
    Provider: @deploybaseline/stripe 0.14.1 (cache)

Where a provider comes from

For each built-in service, the CLI takes the first of these that has a version in range:

Order	Source	Printed as
1	The project’s node_modules (npm install -D @deploybaseline/stripe)	project
2	The exact version baseline.lock pins, from the cache or a pull	cache, pull
3	The newest version in range already in the provider cache	cache
4	A pull of the newest version in range from the npm registry	pull
5	In a checkout of the Baseline repository only, the workspace package	workspace

A pull is a plain registry fetch: the CLI reads the package’s metadata, downloads its tarball, checks the tarball’s SHA-512 integrity, and unpacks it into the cache. No install scripts run and no dependencies are installed, because a provider’s entry is a self-contained bundle.

The CLI package itself ships no providers. The first start on a machine downloads each provider it runs and says so once: Pulled @deploybaseline/github 0.14.0, ... into ~/.cache/baseline. Later starts use the cache. Every later start runs them from the cache, even with no network.

When the registry cannot be reached and no version in range is cached, start fails for that service and says how to get it: connect once, run npx @deploybaseline/cli pull, or install the provider as a dev dependency.

Pick a version

Each CLI release names a default range for every built-in provider (CLI 0.14.0 runs ^0.14.0 for each), so a CLI picks up compatible releases of its providers without a CLI release. Providers release on their own, so their versions drift apart over time. Set version on a service to choose another range:

{
  "stripe": {
    "version": "^0.14",
    "customers": [
      {
        "email": "[e-mail]"
      }
    ]
  }
}

Or under services:

{
  "services": {
    "billing": {
      "emulator": "stripe",
      "version": "0.14.1"
    }
  }
}

version takes an exact version, ^, ~, x wildcards, comparators such as >=0.14.0 <0.16, and ||. It applies to built-in providers only; a custom emulator is your own code.

baseline.lock

With a config file, start writes baseline.lock next to it once every service is running. Commit it: every machine and CI run then starts the same provider versions.

lockfileVersion: 1
providers:
  stripe:
    package: "@deploybaseline/stripe"
    version: 0.14.1
    integrity: sha512-...

• start adds a service that is not in the lockfile, and never changes an entry whose version is still in range. A failed start leaves the lockfile alone.
• An entry from the project’s node_modules has source: project and no integrity: npm already checked it. In the Baseline repository itself, the workspace package gives source: workspace. A lockfile from an earlier CLI that says source: bundled still reads: the next start pulls that pinned version and records its integrity.
• A cached copy that does not match the lockfile’s integrity is pulled again. A registry tarball that does not match is refused.
• With no config file there is no lockfile, and the cache and range decide.
• A provider: service (a provider package that is not built in) has trusted: true once you have trusted that version. Trust covers that version and integrity only.

Commands

Command	What it does
npx @deploybaseline/cli pull	Put every configured provider in the cache and pin it in baseline.lock
npx @deploybaseline/cli update [services...]	Move providers to the newest version in their range and rewrite baseline.lock
npx @deploybaseline/cli providers	List cached providers and the projects whose baseline.lock uses them (--json for scripts)
npx @deploybaseline/cli prune	Remove cached providers that no known baseline.lock uses (--dry-run to preview)
npx @deploybaseline/cli trust [services...]	Trust provider: services and pin them in baseline.lock with trusted: true

pull and update take --config and --service like start.

Offline and CI

--offline (or BASELINE_OFFLINE=1) never touches the network: providers come from the project or the cache, and a provider that is in neither fails with a message naming it. Run npx @deploybaseline/cli pull once (or any start with the network) before going offline.

• CI: cache the provider cache directory keyed on baseline.lock, run npx @deploybaseline/cli pull, then npx @deploybaseline/cli start --offline.
• Docker: run pull during the image build with BASELINE_CACHE_DIR inside the image.
• Vendored dependencies: install the providers you use as dev dependencies. They resolve from node_modules with no cache at all.

The cache and the registry

The cache lives in BASELINE_CACHE_DIR, else $XDG_CACHE_HOME/baseline, else ~/.cache/baseline (%LOCALAPPDATA%\baseline on Windows). Registry metadata is reused for an hour, and a registry that could not be reached is left alone for five minutes.

Pulls follow npm’s own settings: registry, scoped registries (@acme:registry=), and auth (//host/path/:_authToken=, _auth, username and _password) from the project’s .npmrc, your user .npmrc, and npm_config_* environment variables, with ${VAR} expanded. A token is only ever sent to URLs under the registry it is set for.

The programmatic API

createEmulator resolves its provider the same way, from the current directory, without a lockfile:

import { createEmulator } from "@deploybaseline/cli";

const stripe = await createEmulator({ service: "stripe", version: "^0.14", offline: true });