ensure-running

Chainable CLI to ensure local services are ready before running commands

er docker postgres -- vite dev - ensure services, then run your script.

Get Started • Features • CLI • Services • Development

What Is ensure-running?

ensure-running is a CLI and library for chaining readiness checks before a command runs. Instead of one-off shell scripts per dependency, you compose services on the command line or in package.json scripts.

  package.json script
         |
         v
   er docker postgres -- vite dev
         |
    +----+----+
    |         |
    v         v
 docker     postgres
 (built-in) (.er/services)
    |         |
    +----+----+
         v
    vite dev (spawned with inherited stdio)

The first built-in service is Docker. More built-ins (Postgres, Redis, etc.) can be added under src/services/. Projects can also define custom services in .er/services/.

Features

• Chainable CLI: er docker, er docker -- vite dev, er docker postgres -- npm test.
• Docker service: install detection via docker --version, daemon checks via docker info, cross-platform auto-start.
• Custom services: drop files in .er/services/ with export default defineEnsureService({ ... }).
• Library API: ensureRunning, ensureDocker, ensureDockerRunning, and typed Docker errors from one package.
• Service registry: extensible core with parse/run contracts.
• package.json friendly: one command prefix instead of nested shell scripts.
• Fully tested: mocked child_process in unit tests - no real Docker required in CI.

Get Started

Install

npm install ensure-running

CLI

er docker
er docker --check
er docker -- vite dev
ensure-running docker --timeout 60000 -- npm test

| Invocation | Behavior | |------------|----------| | er docker | Ensure Docker is installed, started, and ready | | er docker --check | Exit 0 only when the daemon responds; never auto-start | | er docker -- vite dev | Ensure Docker, then run vite dev | | er docker postgres -- npm test | Chain services, then run command (postgres = custom or future built-in) |

-- is required before the command. Without it, er docker vite dev is an error.

Custom services (.er/services)

Create project-local services that the CLI discovers automatically:

.er/
  services/
    postgres.ts

import { defineEnsureService } from "ensure-running";

export default defineEnsureService({
    id: "postgres",
    parseArgs(argv) {
        return { options: {}, remaining: argv };
    },
    async run() {
        // wait for postgres, return 0 or 1
        return 0;
    },
    printHelp() {
        console.log("postgres - ensure local Postgres is ready");
    }
});

Then chain it like a built-in service:

er docker postgres -- npm run migrate

package.json

{
    "scripts": {
        "dev": "er docker -- vite dev",
        "test:integration": "er docker -- vitest run --config vitest.integration.ts",
        "db:up": "er docker postgres -- npm run migrate"
    }
}

Use -- to separate services from the command. It is required when running a trailing command.

API

import {
    ensureRunning,
    runEnsureRunning,
    ensureDocker,
    ensure
} from "ensure-running";

// Chain services (same model as the CLI)
await ensureRunning(["docker"]);

await ensureRunning({
    services: [
        { service: "docker", options: { timeout: 60_000 } }
    ]
});

// Ensure, then spawn a command (like `er docker -- vite dev`)
const exitCode = await runEnsureRunning({
    services: ["docker"],
    command: ["vite", "dev"]
});

// Docker shorthand with typed errors
await ensureDocker();
await ensure.docker({ check: true });

// Low-level docker helpers (re-exported from ensure-running)
import { ensureDockerRunning, detectDocker } from "ensure-running";
await ensureDockerRunning({ autoStart: true });

| API | Description | |-----|-------------| | ensureRunning(services) | Ensure one or more services; throws EnsureRunningError | | ensureRunning({ services, command? }) | Same, with optional structured request | | runEnsureRunning({ services, command? }) | Ensure services, then spawn command; returns exit code | | ensureDocker(options?) | Docker-only helper; throws DockerError subclasses | | ensure.docker() / ensure.running() | Namespaced aliases |

CLI

Global options

| Flag | Description | |------|-------------| | -h, --help | Show top-level help | | -v, --version | Print CLI version | | er docker --help | Docker service help |

Docker service flags

| Flag | Description | |------|-------------| | --check | Exit 0 when daemon is reachable; never auto-start | | --timeout <ms> | Max wait for readiness (default: 120000) | | --interval <ms> | Poll interval (default: 1000) | | --no-auto-start | Fail when daemon is down | | -q, --quiet | Suppress progress output |

Bin names

| Command | Package | |---------|---------| | er | ensure-running | | ensure-running | ensure-running |

Services

Built-in services ship inside ensure-running. Custom services live in .er/services/.

| Service | Source | Description | |---------|--------|-------------| | docker | built-in (src/services/docker) | Docker detection, auto-start, polling, typed errors | | * | .er/services/* | Project-local export default services |

Public exports

| Export | Description | |--------|-------------| | ensureRunning(services) | Chain services programmatically | | runEnsureRunning(request) | Ensure services, then run a command | | ensureDocker(options?) | Docker shorthand with typed errors | | ensure | { docker, running } namespace | | runCli(argv) | Programmatic CLI entry (returns exit code) | | createServiceRegistry() | Built-in + .er/services registry | | createBuiltInServiceRegistry() | Built-in services only | | defineEnsureService(service) | Define a custom or built-in service with type checking | | EnsureService | Service contract type | | EnsureRunningError | Service failure with serviceId and exitCode | | ensureDockerRunning(options?) | Full Docker install + daemon + readiness flow | | isDockerRunning() | Returns true when daemon is reachable; never throws | | detectDocker() | { installed, running, version?, executable? } | | dockerService | CLI service object for custom registries | | DockerError subclasses | Typed errors with stable code values |

Architecture

src/
  cli/       -> core (parseInvocation) + services (registry)
  api/       -> core + services/docker
  services/
    docker/  -> ensure / detect / wait / platforms / commands / utils
    LoadCustomServices.ts  -> .er/services/*

See ARCHITECTURE.md for module graphs, platform start order, and how to add services.

FAQ

How is this different from ensure-docker-running?

This repo ships Docker as a built-in service. The CLI is ensure-running / er with service names as the first tokens.

Does er docker -- vite run vite on PATH?

Yes. Tokens after -- are spawned as a command with inherited stdio (shell: true on Windows).

WSL2 / Colima / Rancher Desktop

Works when docker info succeeds in the same environment as the Node process. WSL bridging is not automatic.

Linux permissions

If docker info fails with permission denied, add your user to the docker group. This tool does not change system permissions.

Development

From Pacotes/ensure-running/:

npm ci
npm test
npm run lint
npm run typecheck
npm run build
npm run test:coverage

Run the CLI from source:

yarn dev docker
yarn dev docker --check
yarn dev docker -- vite --version

Link the published bins:

npm run build
npm link
er docker --version

| Script | Purpose | |--------|---------| | yarn dev docker ... | Run CLI via tsx without building | | npm run build | Build library + bin | | npm test | Vitest unit tests | | npm run ci | Lint, typecheck, coverage, and build (same gate as release) | | yarn deploy | Local publish (prefer CI tag releases) |

Publish (GitHub Actions + npm Trusted Publishing)

Releases are published from CI when you push a v* tag. No NPM_TOKEN secret is required - npm authenticates the workflow via OIDC.

One-time setup on npmjs.com:

1. Package settings -> Trusted publishing -> GitHub Actions
2. Owner callmeteus, repo ensure-running, workflow publish.yml
3. Allow action npm publish

Release:

# bump version in package.json first
git tag v1.0.1
git push origin v1.0.1

CI validates lint/tests/build, checks that the tag matches package.json, then runs npm publish with provenance.

See docs/PUBLISHING.md for full setup, npm requirements, and troubleshooting.

Local publish (fallback)

npm run deploy

Requires npm login against registry.npmjs.org. If you use Yarn globally, this repo pins npm via .npmrc and publishConfig.registry so yarn deploy does not target registry.yarnpkg.com. Prefer tag-based CI releases.

Requires Node.js >= 20.

Documentation

| Document | Contents | |----------|----------| | docs/PUBLISHING.md | npm Trusted Publishing, tags, CI release flow | | ARCHITECTURE.md | Package layout, service contract, Docker internals, custom services | | LICENSE | MIT |

License

MIT