@mieweb/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Medical Informatics Engineering, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# `@mieweb/cli` — the `mieweb` command
+
+Target-aware wrapper over `wrangler`. On the `cloudflare` target (default)
+every command is forwarded verbatim to `wrangler`; on `local`/`mieweb` the CLI
+runs your unchanged worker on the Node host harness backed by the matching
+adapters. See the [root README](../../README.md) for the full model.
+
+```sh
+mieweb [--target <cloudflare|local|mieweb>] <command> [...args]
+```
+
+## Images (Cloudflare Containers)
+
+Build container images once, distribute them with **skopeo**
+(see [container-plan.md](../../container-plan.md)).
+
+**Prerequisites:** `skopeo` plus a builder — `buildah` (preferred) or `docker`.
+
+```sh
+brew install skopeo buildah        # macOS
+# apt/dnf install skopeo buildah   # Linux
+```
+
+The CLI reads the `containers` array in `wrangler.jsonc` (class → Dockerfile)
+and the per-target `registry` block in `mieweb.jsonc`:
+
+```jsonc
+// mieweb.jsonc
+{
+  "targets": {
+    "mieweb": {
+      "registry": {
+        "url": "cr.os.mieweb.org",
+        "project": "cloud-apps",
+        "username": "robot$cloud-apps+ci",
+        "authFile": "~/.config/mieweb/registry-auth.json"
+      }
+    }
+  }
+}
+```
+
+### Commands
+
+```sh
+mieweb images build                  # build every containers[] image (buildah/docker)
+mieweb images push --target mieweb   # build + skopeo copy → registry, pin digests
+mieweb images push                   # cloudflare target: delegates to `wrangler containers push`
+mieweb images inspect CONVERTER      # skopeo inspect by binding name or class name
+mieweb images status                 # lockfile pins vs. what's live in the registry
+
+mieweb registry login --target mieweb    # skopeo login (writes authFile; password prompted, never argv)
+mieweb registry logout --target mieweb
+```
+
+### Conventions
+
+- **Naming:** `docker://<registry.url>/<project>/<class_name lowercased>:<git short SHA>`,
+  plus a `latest` moving tag. `project` defaults to the wrangler app `name`.
+- **Lockfile:** pushes pin the manifest digest per class per target in
+  `.mieweb/images.lock.json` (commit it — it's what makes deploys reproducible).
+  `mieweb images status` reports drift between the pin and the registry's `latest`.
+- **Auth:** prefer `authFile` (written by `mieweb registry login`) over inline
+  credentials; secrets are never passed on the command line or logged.
+  Harbor robot accounts (`robot$project+name`) are the expected CI identity.
+- **Cloudflare:** the managed registry is wrangler's job — `images push` on the
+  `cloudflare` target hands off to `wrangler containers push` rather than
+  reimplementing its auth with skopeo.

package/mieweb-config.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "mieweb.jsonc",
+  "description": "Portability sidecar consumed by the @mieweb CLI. wrangler.jsonc remains the source of truth for bindings; this file only records the active target and non-Cloudflare adapter hints.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "wrangler": {
+      "type": "string",
+      "description": "Path to the canonical wrangler config the CLI reads bindings from and delegates to on Cloudflare."
+    },
+    "target": {
+      "type": "string",
+      "enum": ["cloudflare", "local", "mieweb", "aws", "gcp"],
+      "description": "Default deployment target when none is given via --target or MIEWEB_TARGET."
+    },
+    "targets": {
+      "type": "object",
+      "description": "Per-target adapter configuration. Only consulted for non-cloudflare targets.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "runtime": { "type": "string" },
+          "port": { "type": "number" },
+          "registry": {
+            "type": "object",
+            "description": "OCI registry the CLI pushes container images to for this target (skopeo copy destination). Harbor for the mieweb target; unused on cloudflare (wrangler's managed registry).",
+            "properties": {
+              "url": { "type": "string", "description": "Registry host, e.g. cr.os.mieweb.org." },
+              "project": { "type": "string", "description": "Registry project/namespace images are pushed under." },
+              "username": { "type": "string", "description": "Registry user (e.g. a Harbor robot account: robot$project+name)." },
+              "authFile": { "type": "string", "description": "Path to a containers-auth.json written by `skopeo login` / `mieweb registry login`. Preferred over inline credentials." },
+              "insecureSkipTlsVerify": { "type": "boolean", "description": "Disable TLS verification (dev registries only)." }
+            },
+            "required": ["url"],
+            "additionalProperties": true
+          },
+          "bindings": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "driver": {
+                  "type": "string",
+                  "enum": [
+                    "sqlite",
+                    "sqlite-vec",
+                    "fs",
+                    "memory",
+                    "redis",
+                    "inproc",
+                    "ai",
+                    "libsql",
+                    "libsql-vec",
+                    "s3",
+                    "valkey",
+                    "valkey-queue",
+                    "docker",
+                    "unsupported"
+                  ]
+                },
+                "path": { "type": "string" },
+                "url": { "type": "string" },
+                "queue": { "type": "string" },
+                "dim": {
+                  "type": "number",
+                  "description": "Vector dimension for the sqlite-vec / libsql-vec drivers (default 768)."
+                },
+                "backend": {
+                  "type": "string",
+                  "description": "AI backend for the ai driver (e.g. 'ollama')."
+                },
+                "host": {
+                  "type": "string",
+                  "description": "Hostname/base URL for service-backed drivers (ai's Ollama host, valkey host)."
+                },
+                "port": {
+                  "type": "number",
+                  "description": "Port for service-backed drivers (e.g. valkey/valkey-queue)."
+                },
+                "namespace": {
+                  "type": "string",
+                  "description": "Key namespace for the valkey / valkey-queue drivers."
+                },
+                "authToken": {
+                  "type": "string",
+                  "description": "Auth token for the libsql / libsql-vec drivers."
+                },
+                "table": {
+                  "type": "string",
+                  "description": "Table name for the libsql-vec driver (default vec_items)."
+                },
+                "endpoint": {
+                  "type": "string",
+                  "description": "S3 endpoint URL for the s3 driver (e.g. MinIO)."
+                },
+                "region": {
+                  "type": "string",
+                  "description": "S3 region for the s3 driver (default us-east-1)."
+                },
+                "bucket": {
+                  "type": "string",
+                  "description": "Bucket name for the s3 driver."
+                },
+                "accessKeyId": {
+                  "type": "string",
+                  "description": "S3 access key id for the s3 driver."
+                },
+                "secretAccessKey": {
+                  "type": "string",
+                  "description": "S3 secret access key for the s3 driver."
+                },
+                "forcePathStyle": {
+                  "type": "boolean",
+                  "description": "Use path-style S3 addressing (required by MinIO)."
+                },
+                "models": {
+                  "type": "object",
+                  "description": "Model names for the ai driver, e.g. { \"embed\": \"nomic-embed-text\" }.",
+                  "additionalProperties": { "type": "string" }
+                }
+              },
+              "required": ["driver"],
+              "additionalProperties": true
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mieweb/cli",
+  "version": "0.1.0",
+  "description": "`mieweb` CLI — a thin, target-aware wrapper over wrangler. On the cloudflare target it delegates verbatim to the real wrangler binary; on other targets it drives the matching @mieweb adapter (e.g. the local Node host harness).",
+  "type": "module",
+  "license": "MIT",
+  "author": "MIEWEB",
+  "homepage": "https://github.com/mieweb/cloud#readme",
+  "bugs": "https://github.com/mieweb/cloud/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mieweb/cloud.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mieweb",
+    "cloudflare",
+    "wrangler",
+    "workers",
+    "cli",
+    "serverless"
+  ],
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "bin": {
+    "mieweb": "./src/index.mjs"
+  },
+  "dependencies": {
+    "@mieweb/cloud-local": "0.1.0",
+    "@mieweb/cloud-os": "0.1.0"
+  },
+  "files": [
+    "src",
+    "mieweb-config.schema.json"
+  ]
+}

package/src/cloudflare.mjs

@@ -0,0 +1,34 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Delegate a command verbatim to the real `wrangler` binary.
+ *
+ * Used on the `cloudflare` target so that `mieweb dev`, `mieweb deploy`,
+ * `mieweb tail`, `mieweb d1 migrations apply ...`, etc. behave exactly like
+ * their wrangler equivalents — Cloudflare stays first-class with zero
+ * translation. We resolve wrangler through the package manager so the repo's
+ * pinned version is used.
+ *
+ * @param {string[]} args arguments to forward to wrangler
+ * @param {{ cwd?: string }} [opts]
+ * @returns {Promise<number>} wrangler's exit code
+ */
+export function delegateToWrangler(args, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+
+  // Prefer an explicit escape hatch, then a repo-local wrangler, then PATH.
+  const real = process.env.MIEWEB_REAL_WRANGLER;
+  const command = real || 'wrangler';
+  // When falling back to the bare name we go through the package runner so the
+  // workspace-pinned wrangler resolves even if it isn't on PATH globally.
+  const useRunner = !real;
+
+  const finalCmd = useRunner ? 'pnpm' : command;
+  const finalArgs = useRunner ? ['exec', 'wrangler', ...args] : args;
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(finalCmd, finalArgs, { cwd, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('exit', (code) => resolvePromise(code ?? 0));
+  });
+}

package/src/config.mjs

@@ -0,0 +1,106 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { parseJsonc } from './jsonc.mjs';
+
+/**
+ * @typedef {'cloudflare'|'local'|'mieweb'|'aws'|'gcp'} CloudTarget
+ *
+ * @typedef {Object} MiewebConfig
+ * @property {string} configPath  absolute path to mieweb.jsonc (or wrangler.jsonc if no sidecar)
+ * @property {string} root        absolute repo root (dir holding the config)
+ * @property {CloudTarget} target resolved active target
+ * @property {string} wranglerPath absolute path to wrangler.jsonc
+ * @property {Record<string, unknown>} wrangler parsed wrangler.jsonc
+ * @property {Record<string, unknown>} raw      parsed mieweb.jsonc (or {} )
+ * @property {Record<string, any>} targetConfig adapter config for the active target
+ * @property {Array<Record<string, any>>} containers wrangler `containers` entries (Cloudflare Containers)
+ * @property {Record<string, Record<string, any>>} containerBindings DO binding name → its wrangler `containers` entry, for container-backed bindings
+ */
+
+/**
+ * Locate and load the mieweb/wrangler configuration.
+ *
+ * Resolution order for the active target:
+ *   1. explicit `--target <t>` (passed in `overrideTarget`)
+ *   2. `MIEWEB_TARGET` env var
+ *   3. `target` field in mieweb.jsonc
+ *   4. `'cloudflare'` (the reference default)
+ *
+ * @param {{ cwd?: string, overrideTarget?: string|null }} [opts]
+ * @returns {MiewebConfig}
+ */
+export function loadConfig(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const miewebPath = findUp('mieweb.jsonc', cwd);
+  const root = miewebPath ? dirname(miewebPath) : (findUp('wrangler.jsonc', cwd) ? dirname(/** @type {string} */ (findUp('wrangler.jsonc', cwd))) : cwd);
+
+  /** @type {Record<string, any>} */
+  let raw = {};
+  if (miewebPath && existsSync(miewebPath)) {
+    raw = /** @type {Record<string, any>} */ (parseJsonc(readFileSync(miewebPath, 'utf8')));
+  }
+
+  const wranglerRel = typeof raw.wrangler === 'string' ? raw.wrangler : './wrangler.jsonc';
+  const wranglerPath = isAbsolute(wranglerRel) ? wranglerRel : resolve(root, wranglerRel);
+  /** @type {Record<string, unknown>} */
+  let wrangler = {};
+  if (existsSync(wranglerPath)) {
+    wrangler = /** @type {Record<string, unknown>} */ (parseJsonc(readFileSync(wranglerPath, 'utf8')));
+  }
+
+  const target = /** @type {CloudTarget} */ (
+    opts.overrideTarget || process.env.MIEWEB_TARGET || raw.target || 'cloudflare'
+  );
+
+  const targetConfig = (raw.targets && raw.targets[target]) || {};
+
+  // Cloudflare Containers: wrangler's `containers` array pairs a DO class with
+  // an image; a DO binding whose class appears there is a container binding.
+  // (Reserved surface — see container-plan.md. wrangler handles these natively
+  // on the cloudflare target; other targets throw UnsupportedBindingError on
+  // use until a runtime adapter exists.)
+  const containers = Array.isArray(wrangler.containers)
+    ? /** @type {Array<Record<string, any>>} */ (wrangler.containers)
+    : [];
+  /** @type {Record<string, Record<string, any>>} */
+  const containerBindings = {};
+  const doBindings =
+    /** @type {{ bindings?: Array<{ name: string, class_name: string }> }} */ (
+      wrangler.durable_objects
+    )?.bindings ?? [];
+  for (const c of containers) {
+    for (const b of doBindings) {
+      if (b.class_name === c.class_name) containerBindings[b.name] = c;
+    }
+  }
+
+  return {
+    configPath: miewebPath ?? wranglerPath,
+    root,
+    target,
+    wranglerPath,
+    wrangler,
+    raw,
+    targetConfig,
+    containers,
+    containerBindings,
+  };
+}
+
+/**
+ * Walk up from `start` looking for `name`.
+ * @param {string} name
+ * @param {string} start
+ * @returns {string|null}
+ */
+function findUp(name, start) {
+  let dir = start;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = resolve(dir, name);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/src/images.mjs

@@ -0,0 +1,331 @@
+import { spawn } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * `mieweb images …` / `mieweb registry …` — container image plumbing.
+ *
+ * Build once, distribute with skopeo (container-plan.md Milestone 2):
+ *
+ *   mieweb images build                       build every wrangler `containers` image
+ *   mieweb images push [--target mieweb]      build + skopeo copy to the target registry
+ *   mieweb images inspect <BINDING|class>     skopeo inspect what the target would run
+ *   mieweb images status                      digest lockfile vs. registry
+ *   mieweb registry login|logout              skopeo login against the target registry
+ *
+ * On `--target cloudflare`, push delegates to `wrangler containers push`
+ * (Cloudflare's managed registry has its own auth dance) — skopeo is only used
+ * for self-managed registries (Harbor on the `mieweb` target, local dev).
+ *
+ * Naming convention (container-plan.md Milestone 3):
+ *   docker://<registry.url>/<registry.project>/<class_name lowercased>:<git short SHA>
+ * plus a `latest` moving tag. Pushed digests are pinned in
+ * `.mieweb/images.lock.json` so deploys are reproducible.
+ */
+
+/* ---------------------------------------------------------------- helpers */
+
+/**
+ * Run a command, inheriting stdio (interactive-friendly).
+ * @param {string} cmd @param {string[]} args @param {{cwd?: string}} [opts]
+ * @returns {Promise<number>}
+ */
+function run(cmd, args, opts = {}) {
+  return new Promise((res, rej) => {
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: 'inherit' });
+    child.on('error', rej);
+    child.on('exit', (code) => res(code ?? 0));
+  });
+}
+
+/**
+ * Run a command capturing stdout (for skopeo inspect etc.).
+ * @param {string} cmd @param {string[]} args @param {{cwd?: string}} [opts]
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+function capture(cmd, args, opts = {}) {
+  return new Promise((res, rej) => {
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', rej);
+    child.on('exit', (code) => res({ code: code ?? 0, stdout, stderr }));
+  });
+}
+
+/** @param {string} cmd */
+async function commandExists(cmd) {
+  const { code } = await capture('sh', ['-c', `command -v ${cmd}`]);
+  return code === 0;
+}
+
+/**
+ * Prefer buildah, fall back to docker. Determines both the build command and
+ * the skopeo *source* transport for the built image.
+ * @returns {Promise<{ name: 'buildah'|'docker', srcTransport: (ref: string) => string }>}
+ */
+export async function detectBuilder() {
+  if (await commandExists('buildah')) {
+    return { name: 'buildah', srcTransport: (ref) => `containers-storage:${ref}` };
+  }
+  if (await commandExists('docker')) {
+    return { name: 'docker', srcTransport: (ref) => `docker-daemon:${ref}` };
+  }
+  throw new Error(
+    'mieweb images: neither buildah nor docker found on PATH. ' +
+      'Install one of them (and skopeo) — e.g. `brew install buildah skopeo`.',
+  );
+}
+
+/** Git short SHA of HEAD (falls back to "dev" outside a repo). */
+async function gitShortSha(cwd) {
+  const { code, stdout } = await capture('git', ['rev-parse', '--short', 'HEAD'], { cwd });
+  return code === 0 ? stdout.trim() : 'dev';
+}
+
+/** Expand a leading `~` (authFile paths). @param {string} p */
+function expandHome(p) {
+  return p.startsWith('~') ? join(homedir(), p.slice(1)) : p;
+}
+
+/**
+ * The wrangler `containers` entries that are locally built (image is a
+ * Dockerfile path, not a remote ref).
+ * @param {import('./config.mjs').MiewebConfig} config
+ */
+function buildableContainers(config) {
+  return (config.containers ?? []).filter(
+    (c) => typeof c.image === 'string' && !c.image.includes('://') && !c.image.startsWith('registry.'),
+  );
+}
+
+/**
+ * Registry config for the active target (mieweb.jsonc `targets.<t>.registry`).
+ * @param {import('./config.mjs').MiewebConfig} config
+ */
+function registryFor(config) {
+  const reg = config.targetConfig?.registry;
+  if (!reg || typeof reg.url !== 'string') {
+    throw new Error(
+      `mieweb images: no registry configured for target "${config.target}". ` +
+        `Add targets.${config.target}.registry = { url, project, … } to mieweb.jsonc.`,
+    );
+  }
+  return reg;
+}
+
+/**
+ * Fully-qualified repo ref (no tag) for a container class on a registry.
+ * @param {{ url: string, project?: string }} reg
+ * @param {Record<string, any>} c wrangler containers entry
+ * @param {import('./config.mjs').MiewebConfig} config
+ */
+function repoRef(reg, c, config) {
+  const project = reg.project ?? config.wrangler?.name ?? 'mieweb';
+  return `${reg.url}/${project}/${String(c.class_name).toLowerCase()}`;
+}
+
+/** skopeo auth/TLS flags for a destination registry. @param {any} reg @param {'src'|'dest'} side */
+function skopeoAuthFlags(reg, side) {
+  const flags = [];
+  if (reg.authFile) flags.push(`--${side}-authfile`, expandHome(reg.authFile));
+  if (reg.insecureSkipTlsVerify) flags.push(`--${side}-tls-verify=false`);
+  return flags;
+}
+
+/* ------------------------------------------------------------- lockfile */
+
+/** @param {string} root */
+function lockPath(root) {
+  return resolve(root, '.mieweb/images.lock.json');
+}
+
+/** @param {string} root */
+function readLock(root) {
+  const p = lockPath(root);
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} root @param {Record<string, any>} lock */
+function writeLock(root, lock) {
+  const p = lockPath(root);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, `${JSON.stringify(lock, null, 2)}\n`);
+}
+
+/* ------------------------------------------------------------ operations */
+
+/**
+ * Build one container image locally.
+ * @param {{ name: 'buildah'|'docker' }} builder
+ * @param {Record<string, any>} c wrangler containers entry
+ * @param {string} root
+ * @param {string} tag local ref, e.g. mieweb/jobrunner:abc1234
+ */
+export async function buildImage(builder, c, root, tag) {
+  const dockerfile = resolve(root, c.image);
+  const context = dirname(dockerfile);
+  const args =
+    builder.name === 'buildah'
+      ? ['bud', '-f', dockerfile, '-t', tag, context]
+      : ['build', '-f', dockerfile, '-t', tag, context];
+  const code = await run(builder.name, args, { cwd: root });
+  if (code !== 0) throw new Error(`mieweb images: ${builder.name} build failed for ${c.class_name} (exit ${code})`);
+}
+
+/**
+ * skopeo copy a locally built image to the registry (sha tag + latest).
+ * @returns {Promise<string>} the pushed manifest digest
+ */
+export async function pushImage(builder, reg, localRef, remoteRepo, sha) {
+  if (!(await commandExists('skopeo'))) {
+    throw new Error('mieweb images: skopeo not found on PATH (`brew install skopeo`).');
+  }
+  for (const tag of [sha, 'latest']) {
+    const dest = `docker://${remoteRepo}:${tag}`;
+    const code = await run('skopeo', [
+      'copy',
+      ...skopeoAuthFlags(reg, 'dest'),
+      builder.srcTransport(localRef),
+      dest,
+    ]);
+    if (code !== 0) throw new Error(`mieweb images: skopeo copy to ${dest} failed (exit ${code})`);
+  }
+  return inspectDigest(reg, `${remoteRepo}:${sha}`);
+}
+
+/** skopeo inspect a remote ref and return its digest. */
+async function inspectDigest(reg, ref) {
+  const { code, stdout, stderr } = await capture('skopeo', [
+    'inspect',
+    ...skopeoAuthFlags(reg, 'src'),
+    `docker://${ref}`,
+  ]);
+  if (code !== 0) throw new Error(`mieweb images: skopeo inspect docker://${ref} failed: ${stderr.trim()}`);
+  return JSON.parse(stdout).Digest;
+}
+
+/* -------------------------------------------------------------- commands */
+
+/**
+ * Entry point for `mieweb images <build|push|inspect|status> [...]`.
+ * @param {string[]} args after "images"
+ * @param {import('./config.mjs').MiewebConfig} config
+ * @returns {Promise<number>}
+ */
+export async function runImagesCommand(args, config) {
+  const sub = args[0];
+  const containers = buildableContainers(config);
+  if (containers.length === 0) {
+    console.error('mieweb images: no `containers` entries with a local Dockerfile in wrangler.jsonc.');
+    return 1;
+  }
+
+  const sha = await gitShortSha(config.root);
+
+  if (sub === 'build' || sub === 'push') {
+    const builder = await detectBuilder();
+    /** @type {Record<string, any>} */
+    const lock = readLock(config.root);
+
+    for (const c of containers) {
+      const localRef = `mieweb/${String(c.class_name).toLowerCase()}:${sha}`;
+      console.log(`[mieweb] building ${c.class_name} → ${localRef} (${builder.name})`);
+      await buildImage(builder, c, config.root, localRef);
+
+      if (sub === 'push') {
+        const reg = registryFor(config);
+        const repo = repoRef(reg, c, config);
+        console.log(`[mieweb] pushing ${localRef} → ${repo}:{${sha},latest} (skopeo)`);
+        const digest = await pushImage(builder, reg, localRef, repo, sha);
+        lock[c.class_name] = { ...(lock[c.class_name] ?? {}), [config.target]: { repo, tag: sha, digest } };
+        console.log(`[mieweb] pinned ${c.class_name}@${digest}`);
+      }
+    }
+    if (sub === 'push') writeLock(config.root, lock);
+    return 0;
+  }
+
+  if (sub === 'inspect') {
+    const reg = registryFor(config);
+    const nameArg = args[1];
+    const targets = nameArg
+      ? containers.filter(
+          (c) => c.class_name === nameArg || config.containerBindings?.[nameArg]?.class_name === c.class_name,
+        )
+      : containers;
+    if (targets.length === 0) {
+      console.error(`mieweb images: no container matches "${nameArg}".`);
+      return 1;
+    }
+    for (const c of targets) {
+      const code = await run('skopeo', [
+        'inspect',
+        ...skopeoAuthFlags(reg, 'src'),
+        `docker://${repoRef(reg, c, config)}:latest`,
+      ]);
+      if (code !== 0) return code;
+    }
+    return 0;
+  }
+
+  if (sub === 'status') {
+    const lock = readLock(config.root);
+    if (Object.keys(lock).length === 0) {
+      console.log('mieweb images: no lockfile yet (.mieweb/images.lock.json) — run `mieweb images push`.');
+      return 0;
+    }
+    const reg = registryFor(config);
+    for (const [className, perTarget] of Object.entries(lock)) {
+      const pinned = perTarget?.[config.target];
+      if (!pinned) {
+        console.log(`${className}: no pin for target "${config.target}"`);
+        continue;
+      }
+      try {
+        const live = await inspectDigest(reg, `${pinned.repo}:latest`);
+        const match = live === pinned.digest ? 'in sync' : `DRIFT (latest=${live})`;
+        console.log(`${className}: pinned ${pinned.tag} ${pinned.digest} — ${match}`);
+      } catch (err) {
+        console.log(`${className}: pinned ${pinned.tag} ${pinned.digest} — inspect failed: ${/** @type {Error} */ (err).message}`);
+      }
+    }
+    return 0;
+  }
+
+  console.error('Usage: mieweb images <build|push|inspect [BINDING|Class]|status>');
+  return 1;
+}
+
+/**
+ * Entry point for `mieweb registry <login|logout>`.
+ * @param {string[]} args after "registry"
+ * @param {import('./config.mjs').MiewebConfig} config
+ * @returns {Promise<number>}
+ */
+export async function runRegistryCommand(args, config) {
+  const sub = args[0];
+  if (sub !== 'login' && sub !== 'logout') {
+    console.error('Usage: mieweb registry <login|logout>');
+    return 1;
+  }
+  if (!(await commandExists('skopeo'))) {
+    console.error('mieweb registry: skopeo not found on PATH (`brew install skopeo`).');
+    return 1;
+  }
+  const reg = registryFor(config);
+  const flags = [];
+  if (reg.authFile) flags.push('--authfile', expandHome(reg.authFile));
+  if (reg.insecureSkipTlsVerify) flags.push('--tls-verify=false');
+  if (sub === 'login' && reg.username) flags.push('--username', reg.username);
+  // Interactive: skopeo prompts for the password itself — never passed via argv.
+  return run('skopeo', [sub, ...flags, reg.url]);
+}

package/src/index.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * `mieweb` — target-aware wrapper over wrangler.
+ *
+ *   mieweb dev
+ *   mieweb deploy
+ *   mieweb tail
+ *   mieweb d1 migrations apply bluehive-hum
+ *
+ * On the `cloudflare` target (the default) every command is forwarded
+ * verbatim to the real `wrangler` binary, so Cloudflare behavior is identical
+ * and nothing about the existing workflow changes. Select another environment
+ * with `--target <t>` or `MIEWEB_TARGET=<t>`; those commands are handled by the
+ * matching @mieweb adapter instead.
+ *
+ * This file is plain ESM JavaScript on purpose so `mieweb` runs with bare
+ * `node` — no build step, no transpiler, no extra runtime dependency.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.mjs';
+import { delegateToWrangler } from './cloudflare.mjs';
+import { runHostTarget } from './local.mjs';
+import { runInit } from './init.mjs';
+import { runImagesCommand, runRegistryCommand } from './images.mjs';
+
+/** Read this CLI's version from its package.json. */
+function miewebVersion() {
+  try {
+    const pkgUrl = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** @param {string[]} argv */
+async function main(argv) {
+  // Pull a leading `--target <t>` / `--target=<t>` out of the arg list before
+  // it reaches wrangler (which wouldn't understand it).
+  let overrideTarget = null;
+  /** @type {string[]} */
+  const args = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--target' || a === '-t') {
+      overrideTarget = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--target=')) {
+      overrideTarget = a.slice('--target='.length);
+      continue;
+    }
+    args.push(a);
+  }
+
+  if (args[0] === 'help' || args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp();
+    return 0;
+  }
+
+  // Version flags: always show the mieweb version first. On cloudflare we then
+  // let wrangler print its own version below; other targets show mieweb only.
+  if (args[0] === '--version' || args[0] === '-v' || args[0] === '-V') {
+    process.stdout.write(`mieweb ${miewebVersion()}\n`);
+  }
+
+  // `init` scaffolds a NEW project, so it runs before config resolution (there
+  // is no mieweb.jsonc to load yet) and is target-independent.
+  if (args[0] === 'init') {
+    return runInit(args.slice(1));
+  }
+
+  const config = loadConfig({ overrideTarget });
+
+  // Container image plumbing (build once, skopeo copy — container-plan.md M2).
+  // `images push` on the cloudflare target delegates to wrangler's managed
+  // registry; every other target goes through skopeo to its own registry.
+  if (args[0] === 'images') {
+    if (config.target === 'cloudflare' && args[1] === 'push') {
+      return delegateToWrangler(['containers', 'push', ...args.slice(2)], { cwd: config.root });
+    }
+    return runImagesCommand(args.slice(1), config).catch((err) => {
+      console.error(err?.message ?? err);
+      return 1;
+    });
+  }
+  if (args[0] === 'registry') {
+    return runRegistryCommand(args.slice(1), config).catch((err) => {
+      console.error(err?.message ?? err);
+      return 1;
+    });
+  }
+
+  if (config.target === 'cloudflare') {
+    // Reference path: hand everything to wrangler untouched.
+    return delegateToWrangler(args, { cwd: config.root });
+  }
+
+  // Node "host" targets run the unchanged worker via the host harness. `local`
+  // uses the in-process adapters; `mieweb` (os.mieweb.org) uses the networked
+  // ones (libSQL/S3/Valkey), registered when local.mjs imports @mieweb/cloud-os.
+  if (config.target === 'local' || config.target === 'mieweb') {
+    return runHostTarget(args, config);
+  }
+
+  console.error(
+    `mieweb: target "${config.target}" has no adapter yet. ` +
+      `Supported today: cloudflare (delegates to wrangler), local + mieweb (Node host harness).`,
+  );
+  return 1;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'mieweb — target-aware wrapper over wrangler',
+      '',
+      'Usage:',
+      '  mieweb [--target <cloudflare|local|mieweb>] <command> [...args]',
+      '',
+      'Targets:',
+      '  cloudflare (default)  Forward the command verbatim to wrangler.',
+      '  local                 Run against the local Node host harness / adapters.',
+      '  mieweb                Run against os.mieweb.org adapters (libSQL/S3/Valkey).',
+      '',
+      'Common commands:',
+      '  mieweb init [dir]                   Scaffold a new mieweb project.',
+      '  mieweb dev                          Start a dev server for the active target.',
+      '  mieweb deploy                       Deploy (cloudflare only).',
+      '  mieweb tail                         Stream logs (cloudflare only).',
+      '  mieweb d1 migrations apply <db>     Apply ./migrations to the target DB.',
+      '  mieweb images build|push|inspect|status   Build & skopeo-push container images.',
+      '  mieweb registry login|logout        skopeo login to the target registry.',
+      '',
+      'Selecting a target:',
+      '  mieweb --target local dev           Flag form.',
+      '  mieweb --target mieweb dev          Run the os.mieweb.org adapters.',
+      '  MIEWEB_TARGET=local mieweb dev      Env form.',
+      '  (or set "target" in mieweb.jsonc)',
+      '',
+      'Escape hatch:',
+      '  MIEWEB_REAL_WRANGLER=/path/to/wrangler mieweb deploy',
+      '',
+    ].join('\n'),
+  );
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/src/init.mjs

@@ -0,0 +1,260 @@
+/**
+ * `mieweb init [dir]` — scaffold a new mieweb project.
+ *
+ * Stamps out a minimal, runnable worker plus the three config surfaces the
+ * layer expects:
+ *
+ *   wrangler.jsonc          source of truth for bindings (Cloudflare shapes)
+ *   mieweb.jsonc            off-Cloudflare driver hints + default target
+ *   worker/index.mjs        a normal `export default { fetch }` worker
+ *   package.json            wired to @mieweb/cli with dev/deploy scripts
+ *   .gitignore              ignores .data/ + node_modules
+ *
+ * Mirrors `wrangler init` / `npm create cloudflare`: it only writes files, then
+ * prints next steps. It never installs deps or touches anything outside the
+ * target directory.
+ */
+import { mkdirSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+
+/**
+ * @param {string[]} args  args after the `init` verb (e.g. ['my-app'])
+ * @param {{ cwd?: string }} [opts]
+ * @returns {number} exit code
+ */
+export function runInit(args, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+
+  // First non-flag arg is the target directory; default to '.' (cwd).
+  const dirArg = args.find((a) => !a.startsWith('-')) ?? '.';
+  const force = args.includes('--force') || args.includes('-f');
+
+  const targetDir = resolve(cwd, dirArg);
+  const projectName = sanitizeName(basename(targetDir));
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !force) {
+    console.error(
+      `mieweb init: "${dirArg}" already exists and is not empty. ` +
+        `Pass --force to scaffold into it anyway.`,
+    );
+    return 1;
+  }
+
+  mkdirSync(join(targetDir, 'worker'), { recursive: true });
+
+  /** @type {Array<[string, string]>} */
+  const files = [
+    ['package.json', packageJson(projectName)],
+    ['wrangler.jsonc', wranglerJsonc(projectName)],
+    ['mieweb.jsonc', miewebJsonc()],
+    ['worker/index.mjs', workerIndex()],
+    ['.gitignore', gitignore()],
+    ['README.md', readme(projectName)],
+  ];
+
+  for (const [rel, contents] of files) {
+    const dest = join(targetDir, rel);
+    if (existsSync(dest) && !force) {
+      console.error(`mieweb init: refusing to overwrite ${rel} (use --force)`);
+      return 1;
+    }
+    writeFileSync(dest, contents);
+  }
+
+  const where = dirArg === '.' ? '.' : dirArg;
+  process.stdout.write(
+    [
+      `Created a mieweb project in ${where}`,
+      '',
+      'Next steps:',
+      ...(dirArg === '.' ? [] : [`  cd ${dirArg}`]),
+      '  npm install            # or: pnpm install',
+      '  npx mieweb --target local dev',
+      '',
+      'Then deploy to Cloudflare with:',
+      '  npx mieweb deploy',
+      '',
+    ].join('\n'),
+  );
+  return 0;
+}
+
+/** npm package names must be lowercase, url-safe. */
+function sanitizeName(name) {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[-_.]+|[-_.]+$/g, '');
+  return cleaned || 'mieweb-app';
+}
+
+function packageJson(name) {
+  return (
+    JSON.stringify(
+      {
+        name,
+        version: '0.0.0',
+        private: true,
+        type: 'module',
+        scripts: {
+          dev: 'mieweb --target local dev',
+          'dev:cf': 'mieweb dev',
+          deploy: 'mieweb deploy',
+        },
+        devDependencies: {
+          '@mieweb/cli': '^0.1.0',
+        },
+      },
+      null,
+      2,
+    ) + '\n'
+  );
+}
+
+function wranglerJsonc(name) {
+  return `{
+  // wrangler.jsonc is the source of truth for your bindings. On the cloudflare
+  // target \`mieweb\` forwards verbatim to wrangler; other targets read these
+  // shapes and back each binding with an adapter (see mieweb.jsonc).
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "${name}",
+  "main": "worker/index.mjs",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // A starter D1 + KV binding. Add R2/Queues/Durable Objects/Vectorize/AI as
+  // you need them — every contract surface is portable across targets.
+  "d1_databases": [
+    { "binding": "DB", "database_name": "${name}", "database_id": "local-${name}" }
+  ],
+  "kv_namespaces": [{ "binding": "CACHE", "id": "local-${name}-cache" }]
+}
+`;
+}
+
+function miewebJsonc() {
+  return `{
+  // Off-Cloudflare driver hints. wrangler.jsonc stays the source of truth for
+  // WHICH bindings exist; this sidecar only says which adapter backs each one
+  // per target. Pick a target with \`mieweb --target <t> dev\` or the field below.
+  "$schema": "node_modules/@mieweb/cli/mieweb-config.schema.json",
+  "wrangler": "./wrangler.jsonc",
+  "target": "local",
+  "targets": {
+    // local: in-process Node adapters, zero external services.
+    "local": {
+      "port": 8787,
+      "bindings": {
+        "DB": { "driver": "sqlite", "path": ".data/local/d1.sqlite" },
+        "CACHE": { "driver": "memory" }
+      }
+    },
+
+    // mieweb (os.mieweb.org): libSQL + Valkey. Bring the backing services up
+    // with the docker-compose.yml from @mieweb/cloud-os.
+    "mieweb": {
+      "port": 8787,
+      "bindings": {
+        "DB": { "driver": "libsql", "url": "http://localhost:8080" },
+        "CACHE": { "driver": "valkey", "host": "127.0.0.1", "port": 6379, "namespace": "app" }
+      }
+    }
+  }
+}
+`;
+}
+
+function workerIndex() {
+  return `/**
+ * A normal Cloudflare worker — \`export default { fetch }\`. The same module runs
+ * unchanged on every target:
+ *
+ *   cloudflare : \`mieweb dev\` (wrangler / Miniflare) with native bindings
+ *   local      : \`mieweb --target local dev\` (SQLite + in-memory KV)
+ *   mieweb/os  : \`mieweb --target mieweb dev\` (libSQL + Valkey)
+ *
+ * @typedef {Object} Env
+ * @property {D1Database} DB
+ * @property {KVNamespace} CACHE
+ */
+
+const json = (data, status = 200) =>
+  new Response(JSON.stringify(data, null, 2), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+
+export default {
+  /**
+   * @param {Request} request
+   * @param {Env} env
+   */
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/') {
+      return json({ ok: true, hint: 'try /hits' });
+    }
+
+    // /hits — a tiny D1 + KV example: count requests in D1, cache the last
+    // count in KV. Touches two portable surfaces with no Cloudflare lock-in.
+    if (url.pathname === '/hits') {
+      await env.DB.prepare(
+        'CREATE TABLE IF NOT EXISTS hits (id INTEGER PRIMARY KEY, at TEXT)',
+      ).run();
+      await env.DB.prepare('INSERT INTO hits (at) VALUES (?)')
+        .bind(new Date().toISOString())
+        .run();
+      const { results } = await env.DB.prepare(
+        'SELECT COUNT(*) AS n FROM hits',
+      ).all();
+      const n = results?.[0]?.n ?? 0;
+      await env.CACHE.put('last-count', String(n));
+      return json({ hits: n });
+    }
+
+    return json({ error: 'not found' }, 404);
+  },
+};
+`;
+}
+
+function gitignore() {
+  return `node_modules/
+.data/
+.wrangler/
+*.log
+`;
+}
+
+function readme(name) {
+  return `# ${name}
+
+A [mieweb](https://github.com/mieweb/cloud) project — one worker, portable across
+Cloudflare, local Node, and os.mieweb.org.
+
+## Develop
+
+\`\`\`sh
+npm install
+
+# local Node adapters (SQLite + in-memory KV), no external services
+npx mieweb --target local dev
+
+# Cloudflare (wrangler / Miniflare)
+npx mieweb dev
+\`\`\`
+
+Hit a route:
+
+\`\`\`sh
+curl localhost:8787/hits
+\`\`\`
+
+## Deploy
+
+\`\`\`sh
+npx mieweb deploy        # forwards to wrangler on the cloudflare target
+\`\`\`
+`;
+}

package/src/jsonc.mjs

@@ -0,0 +1,68 @@
+/**
+ * Minimal JSONC reader shared by the mieweb CLI.
+ *
+ * wrangler.jsonc (and mieweb.jsonc) use comments and trailing commas, which
+ * `JSON.parse` rejects. Rather than pull in a dependency (and to keep the CLI
+ * runnable with bare `node`), we strip comments + trailing commas in a
+ * string-aware single pass, then hand the result to `JSON.parse`.
+ *
+ * This is deliberately small: it understands `//` line comments, `/​* *​/`
+ * block comments, double-quoted strings with escapes, and trailing commas
+ * before `}`/`]`. That covers everything wrangler emits.
+ *
+ * @param {string} text raw JSONC source
+ * @returns {unknown} parsed value
+ */
+export function parseJsonc(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  let inString = false;
+
+  while (i < n) {
+    const ch = text[i];
+    const next = text[i + 1];
+
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        // Copy the escaped character verbatim.
+        out += text[i + 1] ?? '';
+        i += 2;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '/' && next === '/') {
+      // Line comment: skip to end of line.
+      i += 2;
+      while (i < n && text[i] !== '\n') i += 1;
+      continue;
+    }
+
+    if (ch === '/' && next === '*') {
+      // Block comment: skip to closing */.
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i += 2;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  // Remove trailing commas (`,]` / `,}`), tolerating whitespace between.
+  out = out.replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(out);
+}

package/src/local.mjs

@@ -0,0 +1,94 @@
+import { resolve } from 'node:path';
+
+/**
+ * Dispatch a command on a Node "host" target (`local`, `mieweb`, …) through the
+ * shared Node host harness in @mieweb/cloud-local.
+ *
+ *   * `local`  → @mieweb/cloud-local drivers (SQLite / fs / memory / in-proc).
+ *   * `mieweb` → @mieweb/cloud-os drivers (libSQL / S3 / Valkey). Importing that
+ *     package registers its drivers into the shared registry; the very same
+ *     host harness then builds the env and runs the unchanged worker.
+ *
+ * Supported commands:
+ *   * `mieweb [--target <t>] d1 migrations apply [db]`  (local / sqlite only)
+ *   * `mieweb [--target <t>] dev`                       → start the host harness
+ *
+ * Anything else returns a clear "not implemented" message rather than silently
+ * doing the wrong thing.
+ *
+ * @param {string[]} args command + args (target flag already stripped)
+ * @param {import('./config.mjs').MiewebConfig} config
+ * @returns {Promise<number>} exit code
+ */
+export async function runHostTarget(args, config) {
+  // Non-local host targets ship their drivers in a separate package; importing
+  // it is enough to register them into @mieweb/cloud-local's shared registry.
+  if (config.target === 'mieweb') {
+    await import('@mieweb/cloud-os');
+  }
+
+  const [cmd, ...rest] = args;
+
+  if (cmd === 'd1' && rest[0] === 'migrations' && rest[1] === 'apply') {
+    return d1MigrationsApply(config);
+  }
+
+  if (cmd === 'dev') {
+    return dev(config);
+  }
+
+  console.error(
+    `mieweb: command "${args.join(' ')}" is not implemented for target "${config.target}" yet.\n` +
+      'Supported commands: `d1 migrations apply` (local), `dev`.',
+  );
+  return 1;
+}
+
+/**
+ * Apply migrations to the local SQLite DB configured for the DB binding.
+ * @param {import('./config.mjs').MiewebConfig} config
+ */
+async function d1MigrationsApply(config) {
+  const dbCfg = config.targetConfig?.bindings?.DB;
+  if (!dbCfg || dbCfg.driver !== 'sqlite') {
+    console.error(
+      `mieweb: target "${config.target}" has no sqlite DB binding to migrate. ` +
+        'Migrations are only wired for the local/sqlite driver today; other ' +
+        'targets manage schema with their own tooling (e.g. libSQL).',
+    );
+    return 1;
+  }
+  const migrationsDir = resolve(
+    config.root,
+    /** @type {string} */ (config.wrangler?.d1_databases?.[0]?.migrations_dir) || 'migrations',
+  );
+  const dbPath = resolve(config.root, dbCfg.path);
+
+  const { applyMigrations } = await import('@mieweb/cloud-local/migrate');
+  const { applied, skipped } = await applyMigrations({ dbPath, migrationsDir });
+
+  console.log(
+    `[mieweb] migrations applied to ${dbPath}\n` +
+      `  applied: ${applied.length}${applied.length ? ` (${applied[applied.length - 1]})` : ''}\n` +
+      `  already up to date: ${skipped.length}`,
+  );
+  return 0;
+}
+
+/**
+ * Start the local Node host harness.
+ * @param {import('./config.mjs').MiewebConfig} config
+ */
+async function dev(config) {
+  const { startLocalHost } = await import('@mieweb/cloud-local/host');
+  const handle = await startLocalHost({ config });
+  // Keep the process alive until interrupted.
+  return new Promise((resolvePromise) => {
+    const shutdown = () => {
+      handle.stop();
+      resolvePromise(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+}