@ninhache/probe 0.1.1 → 0.2.0

package/README.md

@@ -1,5 +1,10 @@
 # probe
 
+[![npm](https://img.shields.io/npm/v/@ninhache/probe)](https://www.npmjs.com/package/@ninhache/probe)
+[![Homebrew](https://img.shields.io/badge/homebrew-ninhache%2Ftap-orange)](https://github.com/Ninhache/homebrew-tap)
+[![CI](https://github.com/Ninhache/probe/actions/workflows/ci.yml/badge.svg)](https://github.com/Ninhache/probe/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/@ninhache/probe)](LICENSE)
+
 Declare your project's local services once. Check they are up with one command, or with `make check`.
 
 ```console
@@ -14,7 +19,7 @@ $ echo $?
 
 ```sh
 brew install ninhache/tap/probe     # macOS, Linux
-npm install -g @ninhache/probe      # anywhere with Node >= 20
+npm install -g @ninhache/probe      # anywhere with Node >= 22
 npx @ninhache/probe check           # no install
 ```
 
@@ -36,14 +41,44 @@ Use the full name with `npx`: `npx probe` is another package.
 | `probe rm <name>`                                         | Remove a service                                                       |
 | `probe ls`                                                | List services                                                          |
 | `probe check [name...] [--json] [--timeout <seconds>]`    | Check all services, or the named ones                                  |
+| `probe wait [name...] [--json] [--timeout <seconds>]`     | Check again until every service is up, or give up after the timeout    |
 | `probe status`                                            | CLI version, pending migration, Makefile block state, available update |
 | `probe sync`                                              | Regenerate the Makefile block                                          |
 | `probe migrate`                                           | Migrate `.probe/config.yml` to the current schema                      |
 
 Exit codes: `0` all up, `1` a service is down, `2` usage or config error.
 
+`probe wait` is for scripts: `probe wait && pnpm test`. It checks at once, then again after 0.5 s, 1 s, 2 s, 4 s
+and every 5 s, for 60 s in total. `--timeout` sets the total, `--interval` the first pause, `--max-interval` the
+longest one. Unlike `check --timeout`, which is the time given to each service, `wait --timeout` covers the whole
+wait; each check inside it still gets 3 s. Progress goes to stderr, the final report to stdout; exit code `1` names the services still down.
+
 `probe` works from any sub-directory: it walks up to the nearest `.probe/`.
 
+## Dashboard
+
+`probe` alone, on a terminal, opens a live list of your services and checks them every 2 s
+(`probe --interval 5` for another pace). Off a terminal, in CI or in a pipe, nothing changes: use `probe check`.
+
+| Key             | What it does                                     |
+| --------------- | ------------------------------------------------ |
+| `↑` `↓` `j` `k` | Move                                             |
+| `r`             | Check now                                        |
+| `Enter`         | Open the panel of the selected service (skip it) |
+| `o`             | Options: interval and timeout                    |
+| `q`             | Quit                                             |
+
+What you change there is saved in `.probe/local.yml`, for your machine only:
+
+```yaml
+dashboard: { interval: 5, timeout: 3 }
+services:
+  db: { skip: true }
+```
+
+A skipped service is left out of `probe check`, `probe wait` and the dashboard, and shown as `skipped`. Name it
+(`probe check db`) and it is checked anyway.
+
 ## Config
 
 `.probe/config.yml`:
@@ -63,11 +98,14 @@ services:
 | `path`   | `/`         | Path requested with `GET`              |
 | `expect` | any 2xx     | Expected status, or a list of statuses |
 
+Redirects are followed and the final status is judged, unless `expect` contains a 3xx: then the first response
+is judged as is.
+
 Files in `.probe/`:
 
 - `config.yml`: services. Commit it.
 - `lock.yml`: CLI version and hash of the Makefile block. Commit it.
-- `local.yml`: per-machine values. Ignored by git. Unused for now.
+- `local.yml`: per-machine values (dashboard settings, skipped services). Ignored by git.
 
 Never put secrets in `config.yml` or `lock.yml`.
 
@@ -85,7 +123,8 @@ never touched.
 Targets: `help`, `check`, `status` and one `check-<name>` per service. The block uses `probe` when it is in
 your `PATH`, else `npx -y @ninhache/probe@latest`. It works with GNU Make 3.81 (the macOS default).
 
-Edited the block by hand? `probe status` says so, `probe sync` restores it.
+Edited the block by hand? `probe status` says so and `probe add` / `probe rm` leave it alone. `probe sync`
+restores it.
 
 ## Migrations
 
@@ -125,7 +164,7 @@ make check PROBE="node ../../dist/cli.js"
 Release: bump `version` in `package.json`, merge, then push a `v<version>` tag. The Release workflow publishes
 to npm through trusted publishing: no token, the package trusts this repo's `release.yml` (set on npmjs.com,
 package Settings, Trusted Publisher). It then opens a PR on `ninhache/homebrew-tap` with the new `url` and
-`sha256` (secret `HOMEBREW_TAP_TOKEN`): merge it once the tap's CI is green.
+`sha256` (secret `HOMEBREW_TAP_TOKEN`), which merges itself once the tap's CI is green.
 
 ## License
 

package/dist/chunk-M3ASEG5F.js

@@ -0,0 +1,48 @@
+import { createRequire as __createRequire } from "node:module";
+const require = __createRequire(import.meta.url);
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __require,
+  __commonJS,
+  __export,
+  __toESM
+};

package/dist/chunk-ZCAUPLQS.js

@@ -0,0 +1,305 @@
+import { createRequire as __createRequire } from "node:module";
+const require = __createRequire(import.meta.url);
+
+// src/constants.ts
+var PACKAGE_NAME = "@ninhache/probe";
+var PROBE_DIR = ".probe";
+var CONFIG_FILE = "config.yml";
+var LOCK_FILE = "lock.yml";
+var LOCAL_FILE = "local.yml";
+var BACKUP_GLOB = "*.bak.yml";
+var LOCAL_DRAFT_FILE = "local.draft.bak.yml";
+var LOCAL_FILE_MODE = 384;
+var DEFAULT_MAKEFILE = "Makefile";
+var DEFAULT_CHECKER_TYPE = "http";
+var DEFAULT_TIMEOUT_SECONDS = 3;
+var DASHBOARD_INTERVAL_SECONDS = 2;
+var DASHBOARD_INTERVAL_CHOICES_SECONDS = [0.5, 1, 2, 5, 10, 30, 60];
+var DASHBOARD_TIMEOUT_CHOICES_SECONDS = [1, 2, 3, 5, 10, 30];
+var MAX_TIMEOUT_SECONDS = 2147483;
+var DEFAULT_WAIT_TIMEOUT_SECONDS = 60;
+var DEFAULT_WAIT_INTERVAL_SECONDS = 0.5;
+var DEFAULT_WAIT_MAX_INTERVAL_SECONDS = 5;
+var WAIT_BACKOFF_FACTOR = 2;
+var WAIT_LAST_PASS_MS = 1e3;
+var REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var REGISTRY_TIMEOUT_MS = 5e3;
+var UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
+var UPDATE_CACHE_FILE = "latest.json";
+var REFRESH_COMMAND = "__refresh-update-cache";
+var EXIT_DOWN = 1;
+var EXIT_ERROR = 2;
+
+// src/errors.ts
+var ProbeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ProbeError";
+  }
+  code;
+  exitCode = EXIT_ERROR;
+};
+
+// src/ui/terminal.ts
+function version(text) {
+  const [major, minor] = (text ?? "").split(".").map((part) => Number.parseInt(part, 10));
+  return [major || 0, minor || 0];
+}
+function supportsHyperlinks(env) {
+  if (env.TMUX || /^(screen|tmux)/.test(env.TERM ?? "")) return false;
+  const [major, minor] = version(env.TERM_PROGRAM_VERSION);
+  switch (env.TERM_PROGRAM) {
+    case "iTerm.app":
+      return major > 3 || major === 3 && minor >= 1;
+    case "vscode":
+      return major > 1 || major === 1 && minor >= 72;
+    case "WezTerm":
+    case "ghostty":
+    case "WarpTerminal":
+    case "zed":
+      return true;
+  }
+  if (/^\d{4,}$/.test(env.VTE_VERSION ?? "")) return Number(env.VTE_VERSION) >= 5001;
+  return env.TERM === "alacritty" || env.TERM === "xterm-kitty";
+}
+function supportsUnicode(env) {
+  if (env.TERM === "linux") return false;
+  return /UTF-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || "");
+}
+function detectTerminal(stream, env) {
+  const isTTY = Boolean(stream.isTTY);
+  const capable = isTTY && env.TERM !== "dumb";
+  const columns = isTTY && stream.columns && stream.columns > 0 ? stream.columns : void 0;
+  return {
+    isTTY,
+    color: capable && !env.NO_COLOR,
+    columns,
+    hyperlinks: capable && supportsHyperlinks(env),
+    unicode: capable && supportsUnicode(env)
+  };
+}
+function isInteractive(stdin, stdout, env) {
+  return Boolean(stdin.isTTY) && Boolean(stdout.isTTY) && env.TERM !== "dumb" && !env.CI;
+}
+var ELLIPSIS = "\u2026";
+function truncate(text, max) {
+  const characters = Array.from(text);
+  if (characters.length <= max) return text;
+  return max <= 1 ? ELLIPSIS : `${characters.slice(0, max - 1).join("")}${ELLIPSIS}`;
+}
+var SGR_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function stripStyles(text) {
+  return text.replace(SGR_PATTERN, "");
+}
+
+// src/checkers/http.ts
+var REASONS = {
+  ECONNREFUSED: "connection refused",
+  ECONNRESET: "connection reset",
+  ENOTFOUND: "host not found",
+  EAI_AGAIN: "host not found",
+  EHOSTUNREACH: "host unreachable"
+};
+function targetUrl(service) {
+  const bareIpv6 = service.host.includes(":") && !service.host.startsWith("[");
+  const host = bareIpv6 ? `[${service.host}]` : service.host;
+  return `http://${host}:${service.port}${service.path}`;
+}
+function isExpected(expect, status) {
+  if (expect === void 0) return status >= 200 && status < 300;
+  return Array.isArray(expect) ? expect.includes(status) : expect === status;
+}
+function expectsRedirect(expect) {
+  return [expect ?? []].flat().some((status) => status >= 300 && status < 400);
+}
+function describeExpected(expect) {
+  if (expect === void 0) return "2xx";
+  return Array.isArray(expect) ? expect.join(" or ") : String(expect);
+}
+function failureReason(error, timeoutMs) {
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return `timeout after ${timeoutMs / 1e3}s`;
+  }
+  const cause = error?.cause;
+  const code = cause?.code ?? cause?.errors?.[0]?.code;
+  if (code) return REASONS[code] ?? code;
+  return error instanceof Error ? error.message : String(error);
+}
+var httpChecker = {
+  type: "http",
+  async check(name, service, { timeoutMs, signal }) {
+    const target = targetUrl(service);
+    const base = { name, type: "http", target };
+    const started = performance.now();
+    const elapsed = () => Math.round(performance.now() - started);
+    const timeout = AbortSignal.timeout(timeoutMs);
+    try {
+      const response = await fetch(target, {
+        signal: signal ? AbortSignal.any([timeout, signal]) : timeout,
+        // Following a redirect hides its status: an expected 3xx could never match.
+        redirect: expectsRedirect(service.expect) ? "manual" : "follow"
+      });
+      const latencyMs = elapsed();
+      await response.body?.cancel();
+      const { status } = response;
+      if (isExpected(service.expect, status)) return { ...base, ok: true, status, latencyMs };
+      const error = `expected ${describeExpected(service.expect)}, got ${status}`;
+      return { ...base, ok: false, status, latencyMs, error };
+    } catch (error) {
+      return { ...base, ok: false, latencyMs: elapsed(), error: failureReason(error, timeoutMs) };
+    }
+  }
+};
+
+// src/checkers/registry.ts
+var checkers = new Map([httpChecker].map((checker) => [checker.type, checker]));
+function getChecker(type) {
+  const checker = checkers.get(type);
+  if (!checker) {
+    const known = [...checkers.keys()].join(", ");
+    throw new ProbeError("CHECKER_UNKNOWN", `unknown service type "${type}". Known: ${known}.`);
+  }
+  return checker;
+}
+
+// src/checkers/run.ts
+async function runChecks(config, names, context, skipped = /* @__PURE__ */ new Set()) {
+  const known = Object.keys(config.services);
+  const unknown = names.filter((name) => !known.includes(name));
+  if (unknown.length > 0) {
+    throw new ProbeError(
+      "SERVICE_UNKNOWN",
+      `unknown service: ${unknown.join(", ")}. Known: ${known.join(", ") || "(none)"}.`
+    );
+  }
+  const selected = names.length > 0 ? [...new Set(names)] : known;
+  return Promise.all(
+    selected.map((name) => {
+      const service = config.services[name];
+      const type = service.type ?? DEFAULT_CHECKER_TYPE;
+      if (names.length === 0 && skipped.has(name)) {
+        const result = {
+          name,
+          type,
+          ok: true,
+          skipped: true,
+          target: targetUrl(service),
+          latencyMs: 0
+        };
+        return result;
+      }
+      return getChecker(type).check(name, service, context);
+    })
+  );
+}
+
+// src/ui/colors.ts
+function createColors(enabled) {
+  const wrap = (open, close) => (text) => enabled ? `\x1B[${open}m${text}\x1B[${close}m` : text;
+  return {
+    green: wrap(32, 39),
+    red: wrap(31, 39),
+    yellow: wrap(33, 39),
+    dim: wrap(2, 22),
+    bold: wrap(1, 22)
+  };
+}
+
+// src/ui/report.ts
+var GAP = "  ";
+var SKIPPED = "skipped";
+function width(values) {
+  return Math.max(0, ...values.map((value) => value.length));
+}
+function nameBudget(nameWidth, columns, reserved) {
+  return Math.max(1, Math.min(nameWidth, Math.floor((columns - reserved) / 2)));
+}
+function formatCheckResults(results, terminal) {
+  const colors = createColors(terminal.color);
+  const nameWidth = width(results.map((result) => result.name));
+  const targetWidth = width(results.map((result) => result.target));
+  const outcomes = results.map((result) => {
+    if (result.skipped) return SKIPPED;
+    return result.ok ? `${result.status}${GAP}${result.latencyMs}ms` : result.error ?? "down";
+  });
+  const fullWidth = 2 + nameWidth + GAP.length + targetWidth + GAP.length + width(outcomes);
+  const { columns } = terminal;
+  const compact = columns !== void 0 && fullWidth > columns;
+  const nameMax = compact ? nameBudget(nameWidth, columns, 2 + GAP.length) : nameWidth;
+  const outcomeMax = compact ? Math.max(1, columns - 2 - nameMax - GAP.length) : void 0;
+  return results.map((result, index) => {
+    const mark = result.skipped ? colors.dim("-") : result.ok ? colors.green("\u2713") : colors.red("\u2717");
+    const name = colors.bold(truncate(result.name, nameMax).padEnd(nameMax));
+    const target = compact ? "" : `${colors.dim(result.target.padEnd(targetWidth))}${GAP}`;
+    const plain = outcomes[index];
+    let outcome;
+    if (result.skipped) {
+      outcome = colors.dim(outcomeMax === void 0 ? plain : truncate(plain, outcomeMax));
+    } else if (!result.ok) {
+      outcome = colors.red(outcomeMax === void 0 ? plain : truncate(plain, outcomeMax));
+    } else if (outcomeMax !== void 0 && plain.length > outcomeMax) {
+      outcome = colors.green(truncate(String(result.status), outcomeMax));
+    } else {
+      outcome = `${colors.green(String(result.status))}${GAP}${colors.dim(`${result.latencyMs}ms`)}`;
+    }
+    return `${mark} ${name}${GAP}${target}${outcome}`;
+  }).join("\n");
+}
+function formatServices(config, terminal, skipped = /* @__PURE__ */ new Set()) {
+  const colors = createColors(terminal.color);
+  const rows = Object.entries(config.services).map(([name, service]) => ({
+    name,
+    url: targetUrl(service),
+    notes: (service.expect === void 0 ? "" : `${GAP}expect ${service.expect}`) + (skipped.has(name) ? `${GAP}${SKIPPED}` : "")
+  }));
+  const nameWidth = width(rows.map((row) => row.name));
+  const fullWidth = width(rows.map((row) => " ".repeat(nameWidth) + GAP + row.url + row.notes));
+  const { columns } = terminal;
+  const compact = columns !== void 0 && fullWidth > columns;
+  const nameMax = compact ? nameBudget(nameWidth, columns, GAP.length) : nameWidth;
+  const urlMax = compact ? Math.max(1, columns - nameMax - GAP.length) : void 0;
+  return rows.map((row) => {
+    const name = colors.bold(truncate(row.name, nameMax).padEnd(nameMax));
+    const url = urlMax === void 0 ? row.url : truncate(row.url, urlMax);
+    return `${name}${GAP}${url}${compact || !row.notes ? "" : colors.dim(row.notes)}`;
+  }).join("\n");
+}
+
+export {
+  PACKAGE_NAME,
+  PROBE_DIR,
+  CONFIG_FILE,
+  LOCK_FILE,
+  LOCAL_FILE,
+  BACKUP_GLOB,
+  LOCAL_DRAFT_FILE,
+  LOCAL_FILE_MODE,
+  DEFAULT_MAKEFILE,
+  DEFAULT_TIMEOUT_SECONDS,
+  DASHBOARD_INTERVAL_SECONDS,
+  DASHBOARD_INTERVAL_CHOICES_SECONDS,
+  DASHBOARD_TIMEOUT_CHOICES_SECONDS,
+  MAX_TIMEOUT_SECONDS,
+  DEFAULT_WAIT_TIMEOUT_SECONDS,
+  DEFAULT_WAIT_INTERVAL_SECONDS,
+  DEFAULT_WAIT_MAX_INTERVAL_SECONDS,
+  WAIT_BACKOFF_FACTOR,
+  WAIT_LAST_PASS_MS,
+  REGISTRY_LATEST_URL,
+  REGISTRY_TIMEOUT_MS,
+  UPDATE_CHECK_TTL_MS,
+  UPDATE_CACHE_FILE,
+  REFRESH_COMMAND,
+  EXIT_DOWN,
+  EXIT_ERROR,
+  ProbeError,
+  createColors,
+  detectTerminal,
+  isInteractive,
+  truncate,
+  stripStyles,
+  runChecks,
+  formatCheckResults,
+  formatServices
+};