@ninhache/probe 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ninhache
+
+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

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# probe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Declare your project's local services once. Check they are up with one command, or with `make check`.
+
+```console
+$ probe check
+✓ api    http://localhost:3000/health  200  12ms
+✗ front  http://localhost:5173/        connection refused
+$ echo $?
+1
+```
+
+## Install
+
+```sh
+brew install ninhache/tap/probe     # macOS, Linux
+npm install -g @ninhache/probe      # anywhere with Node >= 20
+npx @ninhache/probe check           # no install
+```
+
+Use the full name with `npx`: `npx probe` is another package.
+
+## Quick start
+
+1. `probe init` creates `.probe/` and a `probe` block in your `Makefile`.
+2. `probe add api -p 3000 --path /health` declares a service.
+3. `probe check` or `make check` checks everything. Exit code is 1 if a service is down.
+4. Commit `.probe/config.yml`, `.probe/lock.yml` and the `Makefile`.
+
+## Commands
+
+| Command                                                   | What it does                                                           |
+| --------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `probe init`                                              | Create `.probe/`, the Makefile block and the `.gitignore` entries      |
+| `probe add <name> -p <port> [--host] [--path] [--expect]` | Add a service                                                          |
+| `probe rm <name>`                                         | Remove a service                                                       |
+| `probe ls`                                                | List services                                                          |
+| `probe check [name...] [--json] [--timeout <seconds>]`    | Check all services, or the named ones                                  |
+| `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` works from any sub-directory: it walks up to the nearest `.probe/`.
+
+## Config
+
+`.probe/config.yml`:
+
+```yaml
+schemaVersion: 1
+services:
+  api: { port: 3000, path: /health }
+  front: { port: 5173 }
+  admin: { host: 127.0.0.1, port: 8080, expect: [200, 204] }
+```
+
+| Key      | Default     | Meaning                                |
+| -------- | ----------- | -------------------------------------- |
+| `port`   | required    | TCP port                               |
+| `host`   | `localhost` | Host name or IP                        |
+| `path`   | `/`         | Path requested with `GET`              |
+| `expect` | any 2xx     | Expected status, or a list of statuses |
+
+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.
+
+Never put secrets in `config.yml` or `lock.yml`.
+
+## Makefile
+
+`probe init` and `probe sync` write a block between two markers. Everything outside the block is yours and is
+never touched.
+
+```make
+# >>> probe (generated - do not edit, run `probe sync`)
+...
+# <<< probe
+```
+
+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.
+
+## Migrations
+
+`config.yml` carries a `schemaVersion`. When a newer `probe` needs a newer schema, the first command you run:
+
+1. Backs up the file to `.probe/config.v<n>.bak.yml` (ignored by git).
+2. Migrates it, keeping your comments.
+3. Prints what it did.
+
+Commit the migrated `config.yml` so your teammates get it.
+
+- `probe status` shows a pending migration without applying it.
+- A config written by a newer `probe` is refused with a message: upgrade `probe`.
+
+## Updates
+
+`probe` looks for a newer version at most once a day, in the background, and prints one line when there is one.
+It never updates itself. Turn it off with `PROBE_NO_UPDATE_CHECK=1`. It is off when `CI` is set.
+
+## Development
+
+```sh
+pnpm install
+pnpm test        # builds, then runs the tests
+pnpm lint
+```
+
+Try it on the demo project:
+
+```sh
+pnpm build
+cd examples/demo
+node server.mjs &
+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.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,844 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { defineCommand as defineCommand9, runCommand, runMain, showUsage } from "citty";
+
+// src/commands/add.ts
+import { defineCommand } from "citty";
+
+// 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 DEFAULT_MAKEFILE = "Makefile";
+var DEFAULT_CHECKER_TYPE = "http";
+var DEFAULT_TIMEOUT_SECONDS = 3;
+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/config/discovery.ts
+import { statSync } from "fs";
+import { dirname, join, resolve } from "path";
+function pathsFor(root) {
+  const dir = join(root, PROBE_DIR);
+  return {
+    root,
+    dir,
+    config: join(dir, CONFIG_FILE),
+    lock: join(dir, LOCK_FILE),
+    local: join(dir, LOCAL_FILE)
+  };
+}
+function isDirectory(path) {
+  return statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+}
+function findProbeDir(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (isDirectory(join(current, PROBE_DIR))) return pathsFor(current);
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function requireProbeDir(startDir) {
+  const paths = findProbeDir(startDir);
+  if (!paths) {
+    throw new ProbeError(
+      "NO_PROBE_DIR",
+      `no ${PROBE_DIR}/ found in ${resolve(startDir)} or any parent directory. Run \`probe init\` at the repo root.`
+    );
+  }
+  return paths;
+}
+
+// src/config/loader.ts
+import { copyFile, readFile, writeFile } from "fs/promises";
+import { join as join2, relative } from "path";
+import { parseDocument } from "yaml";
+
+// src/config/schema.ts
+import { z } from "zod";
+var CURRENT_SCHEMA_VERSION = 1;
+var SERVICE_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+var statusCode = z.number().int().min(100).max(599);
+var serviceSchemaV1 = z.strictObject({
+  host: z.string().min(1).default("localhost"),
+  port: z.number().int().min(1).max(65535),
+  path: z.string().startsWith("/").default("/"),
+  expect: z.union([statusCode, z.array(statusCode).min(1)]).optional()
+});
+var configSchemaV1 = z.strictObject({
+  schemaVersion: z.literal(1),
+  services: z.record(
+    z.string().regex(SERVICE_NAME_PATTERN, "letters, digits, _ and - only"),
+    serviceSchemaV1
+  ).nullish().transform((services) => services ?? {})
+});
+var schemas = {
+  1: configSchemaV1
+};
+
+// src/config/migrations.ts
+var migrations = {};
+function formatIssues(error) {
+  return error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+}
+function readSchemaVersion(raw) {
+  const version = raw?.schemaVersion;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    throw new ProbeError(
+      "CONFIG_INVALID",
+      `config has no valid \`schemaVersion\` (found: ${JSON.stringify(version)}). Expected a positive integer.`
+    );
+  }
+  return version;
+}
+function planMigration(from, target = CURRENT_SCHEMA_VERSION) {
+  if (from > target) {
+    throw new ProbeError(
+      "CONFIG_TOO_NEW",
+      `config uses schema v${from}, but this probe only knows up to v${target}. It was created by a newer version: upgrade probe.`
+    );
+  }
+  if (from === target) return null;
+  const steps = Array.from({ length: target - from }, (_, index) => from + index);
+  return { from, to: target, steps };
+}
+function runMigrations(raw, options = {}) {
+  const registry = options.registry ?? migrations;
+  const schemas2 = options.schemas ?? schemas;
+  const plan = planMigration(readSchemaVersion(raw), options.target);
+  if (!plan) return { config: raw, plan };
+  const source = schemas2[plan.from]?.safeParse(raw);
+  if (source && !source.success) {
+    throw new ProbeError(
+      "CONFIG_INVALID",
+      `config is not a valid schema v${plan.from}, cannot migrate it:
+${formatIssues(source.error)}`
+    );
+  }
+  let config = raw;
+  for (const step of plan.steps) {
+    const migrate = registry[step];
+    if (!migrate) {
+      throw new ProbeError(
+        "MIGRATION_MISSING",
+        `no migration from schema v${step} to v${step + 1}. This is a bug in probe.`
+      );
+    }
+    config = { ...migrate(structuredClone(config)), schemaVersion: step + 1 };
+  }
+  return { config, plan };
+}
+
+// src/config/yaml-document.ts
+import { isDeepStrictEqual } from "util";
+import { isCollection, isMap, isScalar, isSeq } from "yaml";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrimitive(value) {
+  return value === null || typeof value !== "object";
+}
+function containsMap(node) {
+  if (!isCollection(node)) return false;
+  return node.items.some((item) => {
+    const child = isMap(node) ? item.value : item;
+    return isMap(child) || containsMap(child);
+  });
+}
+function createNode(doc, value) {
+  const node = doc.createNode(value);
+  if (isCollection(node) && !containsMap(node)) node.flow = true;
+  return node;
+}
+function keyOf(key) {
+  return String(isScalar(key) ? key.value : key);
+}
+function reconcileMap(doc, map, value) {
+  for (const pair of [...map.items]) {
+    if (!Object.hasOwn(value, keyOf(pair.key))) map.delete(pair.key);
+  }
+  if (map.items.length === 0) map.flow = false;
+  for (const [key, next] of Object.entries(value)) {
+    const current = map.get(key, true);
+    if (isMap(current) && isPlainObject(next)) {
+      reconcileMap(doc, current, next);
+    } else if (isScalar(current) && isPrimitive(next)) {
+      if (current.value !== next) current.value = next;
+    } else if (isSeq(current) && isDeepStrictEqual(current.toJSON(), next)) {
+    } else {
+      map.set(key, createNode(doc, next));
+    }
+  }
+}
+function reconcileDocument(doc, value) {
+  if (isMap(doc.contents) && isPlainObject(value)) {
+    reconcileMap(doc, doc.contents, value);
+  } else {
+    doc.contents = createNode(doc, value);
+  }
+}
+
+// src/config/loader.ts
+async function readDocument(paths) {
+  let text;
+  try {
+    text = await readFile(paths.config, "utf8");
+  } catch {
+    throw new ProbeError("CONFIG_MISSING", `cannot read ${paths.config}. Run \`probe init\`.`);
+  }
+  const doc = parseDocument(text);
+  const [syntaxError] = doc.errors;
+  if (syntaxError) {
+    throw new ProbeError(
+      "CONFIG_INVALID",
+      `${paths.config} is not valid YAML: ${syntaxError.message}`
+    );
+  }
+  const raw = doc.toJS();
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new ProbeError("CONFIG_INVALID", `${paths.config} must be a YAML mapping.`);
+  }
+  return { doc, raw };
+}
+function validate(raw, paths, options) {
+  const target = options.target ?? CURRENT_SCHEMA_VERSION;
+  const schema = (options.schemas ?? schemas)[target];
+  if (!schema) throw new ProbeError("MIGRATION_MISSING", `no schema for config v${target}.`);
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    throw new ProbeError(
+      "CONFIG_INVALID",
+      `${paths.config} is invalid:
+${formatIssues(result.error)}`
+    );
+  }
+  return result.data;
+}
+function backupPath(paths, version) {
+  return join2(paths.dir, `config.v${version}.bak.yml`);
+}
+async function pendingMigration(paths, options = {}) {
+  const { raw } = await readDocument(paths);
+  return planMigration(readSchemaVersion(raw), options.target);
+}
+async function loadConfig(paths, options = {}) {
+  const { doc, raw } = await readDocument(paths);
+  const { config: migrated, plan } = runMigrations(raw, options);
+  const config = validate(migrated, paths, options);
+  if (plan) {
+    const backup = backupPath(paths, plan.from);
+    await copyFile(paths.config, backup);
+    reconcileDocument(doc, migrated);
+    await writeFile(paths.config, doc.toString());
+    const log = options.log ?? ((message) => console.error(message));
+    log(
+      `probe: migrated ${relative(paths.root, paths.config)} from schema v${plan.from} to v${plan.to} (backup: ${relative(paths.root, backup)})`
+    );
+  }
+  return { config, raw: migrated, doc, paths, migratedFrom: plan?.from ?? null };
+}
+async function saveConfig(loaded, raw, options = {}) {
+  const config = validate(raw, loaded.paths, options);
+  reconcileDocument(loaded.doc, raw);
+  await writeFile(loaded.paths.config, loaded.doc.toString());
+  return { ...loaded, config, raw };
+}
+
+// src/makefile/sync.ts
+import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/config/lock.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { parse, stringify } from "yaml";
+import { z as z2 } from "zod";
+var lockSchema = z2.object({
+  cliVersion: z2.string(),
+  makefile: z2.object({ hash: z2.string() })
+});
+var HEADER = "# Generated by probe. Do not edit.\n";
+async function readLock(paths) {
+  try {
+    const result = lockSchema.safeParse(parse(await readFile2(paths.lock, "utf8")));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+async function writeLock(paths, lock) {
+  await writeFile2(paths.lock, HEADER + stringify(lock));
+}
+
+// src/version.ts
+var CLI_VERSION = true ? "0.1.1" : "0.0.0-dev";
+
+// src/makefile/generator.ts
+import { createHash } from "crypto";
+var BLOCK_START = "# >>> probe (generated - do not edit, run `probe sync`)";
+var BLOCK_END = "# <<< probe";
+var START_PATTERN = /^# >>> probe\b.*$/m;
+var END_PATTERN = /^# <<< probe[ \t]*$/m;
+var HELP_RECIPE = `@awk -F':.*## ' '/^[a-zA-Z0-9_-]+:.*## /{printf "  %-20s %s\\n", $$1, $$2}' $(MAKEFILE_LIST)`;
+function renderBlock(serviceNames) {
+  const targets = serviceNames.map((name) => `check-${name}`);
+  const fallback = `npx -y ${PACKAGE_NAME}@latest`;
+  return [
+    BLOCK_START,
+    `PROBE ?= $(shell command -v probe >/dev/null 2>&1 && echo probe || echo "${fallback}")`,
+    `.PHONY: ${["help", "check", "status", ...targets].join(" ")}`,
+    "help: ## List available targets",
+    `	${HELP_RECIPE}`,
+    "check: ## Check that every service responds",
+    "	@$(PROBE) check",
+    "status: ## Show probe status",
+    "	@$(PROBE) status",
+    ...serviceNames.flatMap((name) => [
+      `check-${name}: ## Check ${name}`,
+      `	@$(PROBE) check ${name}`
+    ]),
+    BLOCK_END
+  ].join("\n");
+}
+function hashBlock(block) {
+  return createHash("sha256").update(block).digest("hex");
+}
+function locate(makefile) {
+  const start = START_PATTERN.exec(makefile);
+  if (!start) return null;
+  const end = END_PATTERN.exec(makefile.slice(start.index));
+  if (!end) {
+    throw new ProbeError(
+      "MAKEFILE_BLOCK_CORRUPT",
+      `the Makefile has a probe start marker but no "${BLOCK_END}" line. Restore the marker or delete the block, then run \`probe sync\`.`
+    );
+  }
+  return { start: start.index, end: start.index + end.index + end[0].length };
+}
+function extractBlock(makefile) {
+  const found = locate(makefile);
+  return found ? makefile.slice(found.start, found.end) : null;
+}
+function replaceBlock(makefile, block) {
+  if (!makefile?.trim()) return `${block}
+`;
+  const found = locate(makefile);
+  if (found) return makefile.slice(0, found.start) + block + makefile.slice(found.end);
+  return `${makefile.replace(/\n*$/, "\n\n")}${block}
+`;
+}
+
+// src/makefile/sync.ts
+function makefilePath(paths) {
+  return join3(paths.root, DEFAULT_MAKEFILE);
+}
+async function readMakefile(paths) {
+  try {
+    return await readFile3(makefilePath(paths), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function syncMakefile(paths, config, cliVersion = CLI_VERSION) {
+  const block = renderBlock(Object.keys(config.services));
+  const hash = hashBlock(block);
+  const current = await readMakefile(paths);
+  const next = replaceBlock(current, block);
+  const changed = next !== current;
+  if (changed) await writeFile3(makefilePath(paths), next);
+  if ((await readLock(paths))?.makefile.hash !== hash) {
+    await writeLock(paths, { cliVersion, makefile: { hash } });
+  }
+  return { created: current === null, changed, hash };
+}
+async function blockState(paths, config) {
+  const makefile = await readMakefile(paths);
+  const block = makefile === null ? null : extractBlock(makefile);
+  if (block === null) return "missing";
+  if (block === renderBlock(Object.keys(config.services))) return "in-sync";
+  const lock = await readLock(paths);
+  return lock?.makefile.hash === hashBlock(block) ? "outdated" : "modified";
+}
+
+// src/ui/colors.ts
+function colorEnabled(stream, env) {
+  return Boolean(stream.isTTY) && !env.NO_COLOR;
+}
+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/commands/shared.ts
+function openProject() {
+  return loadConfig(requireProbeDir(process.cwd()));
+}
+function stdoutColors() {
+  return createColors(colorEnabled(process.stdout, process.env));
+}
+function rawServices(loaded) {
+  return loaded.raw.services ?? {};
+}
+async function saveServices(loaded, services) {
+  const saved = await saveConfig(loaded, { ...loaded.raw, services });
+  await syncMakefile(saved.paths, saved.config);
+}
+
+// src/commands/add.ts
+function parseInteger(value, flag) {
+  if (!/^\d+$/.test(value)) {
+    throw new ProbeError("USAGE", `${flag} expects a number, got "${value}".`);
+  }
+  return Number(value);
+}
+function parseExpect(value) {
+  const codes = value.split(",").map((code) => parseInteger(code.trim(), "--expect"));
+  return codes.length === 1 ? codes[0] : codes;
+}
+var add_default = defineCommand({
+  meta: { name: "add", description: "Add a service" },
+  args: {
+    name: { type: "positional", description: "Service name", required: true },
+    port: { type: "string", alias: "p", description: "Port", required: true },
+    host: { type: "string", description: "Host (default: localhost)" },
+    path: { type: "string", description: "Path to request (default: /)" },
+    expect: { type: "string", description: "Expected status, e.g. 200 or 200,204 (default: 2xx)" }
+  },
+  async run({ args }) {
+    const loaded = await openProject();
+    const services = rawServices(loaded);
+    if (Object.hasOwn(services, args.name)) {
+      throw new ProbeError(
+        "SERVICE_EXISTS",
+        `service "${args.name}" already exists. Remove it first: probe rm ${args.name}`
+      );
+    }
+    const service = { port: parseInteger(String(args.port), "--port") };
+    if (args.host) service.host = args.host;
+    if (args.path) service.path = args.path;
+    if (args.expect) service.expect = parseExpect(String(args.expect));
+    await saveServices(loaded, { ...services, [args.name]: service });
+    console.log(`Added ${args.name}. Try: probe check ${args.name}`);
+  }
+});
+
+// src/commands/check.ts
+import { defineCommand as defineCommand2 } from "citty";
+
+// 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 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 }) {
+    const target = targetUrl(service);
+    const base = { name, type: "http", target };
+    const started = performance.now();
+    const elapsed = () => Math.round(performance.now() - started);
+    try {
+      const response = await fetch(target, { signal: AbortSignal.timeout(timeoutMs) });
+      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) {
+  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;
+      return getChecker(type).check(name, service, context);
+    })
+  );
+}
+
+// src/ui/report.ts
+function width(values) {
+  return Math.max(0, ...values.map((value) => value.length));
+}
+function formatCheckResults(results, colors) {
+  const nameWidth = width(results.map((result) => result.name));
+  const targetWidth = width(results.map((result) => result.target));
+  return results.map((result) => {
+    const mark = result.ok ? colors.green("\u2713") : colors.red("\u2717");
+    const name = colors.bold(result.name.padEnd(nameWidth));
+    const target = colors.dim(result.target.padEnd(targetWidth));
+    const outcome = result.ok ? `${colors.green(String(result.status))}  ${colors.dim(`${result.latencyMs}ms`)}` : colors.red(result.error ?? "down");
+    return `${mark} ${name}  ${target}  ${outcome}`;
+  }).join("\n");
+}
+function formatServices(config, colors) {
+  const entries = Object.entries(config.services);
+  const nameWidth = width(entries.map(([name]) => name));
+  return entries.map(([name, service]) => {
+    const expect = service.expect === void 0 ? "" : colors.dim(`  expect ${service.expect}`);
+    return `${colors.bold(name.padEnd(nameWidth))}  ${targetUrl(service)}${expect}`;
+  }).join("\n");
+}
+
+// src/commands/check.ts
+var MAX_TIMEOUT_SECONDS = 2147483;
+var check_default = defineCommand2({
+  meta: { name: "check", description: "Check that services respond (all of them by default)" },
+  args: {
+    json: { type: "boolean", description: "Print results as JSON" },
+    timeout: {
+      type: "string",
+      description: "Seconds to wait for each service",
+      default: String(DEFAULT_TIMEOUT_SECONDS)
+    }
+  },
+  async run({ args }) {
+    const seconds = Number(args.timeout);
+    if (!Number.isFinite(seconds) || seconds <= 0 || seconds > MAX_TIMEOUT_SECONDS) {
+      throw new ProbeError(
+        "USAGE",
+        `--timeout expects seconds between 0 and ${MAX_TIMEOUT_SECONDS}, got "${args.timeout}".`
+      );
+    }
+    const { config } = await openProject();
+    const results = await runChecks(config, args._, { timeoutMs: Math.ceil(seconds * 1e3) });
+    if (args.json) {
+      console.log(JSON.stringify(results, null, 2));
+    } else if (results.length === 0) {
+      console.log("No services yet. Add one: probe add api -p 3000");
+    } else {
+      console.log(formatCheckResults(results, stdoutColors()));
+    }
+    if (results.some((result) => !result.ok)) process.exitCode = EXIT_DOWN;
+  }
+});
+
+// src/commands/init.ts
+import { existsSync } from "fs";
+import { mkdir, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { join as join4 } from "path";
+import { defineCommand as defineCommand3 } from "citty";
+var IGNORED = [`${PROBE_DIR}/${LOCAL_FILE}`, `${PROBE_DIR}/${BACKUP_GLOB}`];
+var INITIAL_CONFIG = `# probe - local services to health-check. Edit by hand or with \`probe add\`.
+schemaVersion: ${CURRENT_SCHEMA_VERSION}
+services: {}
+`;
+async function ignoreLocalFiles(root) {
+  const file = join4(root, ".gitignore");
+  const current = existsSync(file) ? await readFile4(file, "utf8") : "";
+  const lines = current.split("\n").map((line) => line.trim());
+  const missing = IGNORED.filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) return;
+  const separator = current === "" || current.endsWith("\n") ? "" : "\n";
+  await writeFile4(file, `${current}${separator}${missing.join("\n")}
+`);
+}
+var init_default = defineCommand3({
+  meta: {
+    name: "init",
+    description: "Create .probe/, the .gitignore entries and the Makefile block"
+  },
+  async run() {
+    const paths = pathsFor(process.cwd());
+    if (existsSync(paths.dir)) {
+      throw new ProbeError("ALREADY_INITIALIZED", `${PROBE_DIR}/ already exists here.`);
+    }
+    await mkdir(paths.dir);
+    await writeFile4(paths.config, INITIAL_CONFIG);
+    await ignoreLocalFiles(paths.root);
+    const { config } = await loadConfig(paths);
+    await syncMakefile(paths, config);
+    console.log(`Created ${PROBE_DIR}/ and the Makefile block. Next: probe add api -p 3000`);
+  }
+});
+
+// src/commands/ls.ts
+import { defineCommand as defineCommand4 } from "citty";
+var ls_default = defineCommand4({
+  meta: { name: "ls", description: "List services" },
+  async run() {
+    const { config } = await openProject();
+    if (Object.keys(config.services).length === 0) {
+      console.log("No services yet. Add one: probe add api -p 3000");
+      return;
+    }
+    console.log(formatServices(config, stdoutColors()));
+  }
+});
+
+// src/commands/migrate.ts
+import { defineCommand as defineCommand5 } from "citty";
+var migrate_default = defineCommand5({
+  meta: { name: "migrate", description: "Migrate the config to the current schema version" },
+  async run() {
+    const paths = requireProbeDir(process.cwd());
+    if (!await pendingMigration(paths)) {
+      console.log(`Config is already at schema v${CURRENT_SCHEMA_VERSION}. Nothing to do.`);
+      return;
+    }
+    await loadConfig(paths);
+  }
+});
+
+// src/commands/rm.ts
+import { defineCommand as defineCommand6 } from "citty";
+var rm_default = defineCommand6({
+  meta: { name: "rm", description: "Remove a service" },
+  args: {
+    name: { type: "positional", description: "Service name", required: true }
+  },
+  async run({ args }) {
+    const loaded = await openProject();
+    const services = rawServices(loaded);
+    if (!Object.hasOwn(services, args.name)) {
+      throw new ProbeError("SERVICE_UNKNOWN", `unknown service "${args.name}". See: probe ls`);
+    }
+    const { [args.name]: _removed, ...rest } = services;
+    await saveServices(loaded, rest);
+    console.log(`Removed ${args.name}.`);
+  }
+});
+
+// src/commands/status.ts
+import { defineCommand as defineCommand7 } from "citty";
+
+// src/update/notifier.ts
+import { spawn } from "child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join5 } from "path";
+function cacheDir(env = process.env) {
+  return join5(env.XDG_CACHE_HOME || join5(homedir(), ".cache"), "probe");
+}
+function updateCheckDisabled(env = process.env) {
+  return env.PROBE_NO_UPDATE_CHECK === "1" || Boolean(env.CI);
+}
+function readCache(dir) {
+  try {
+    const cache = JSON.parse(readFileSync(join5(dir, UPDATE_CACHE_FILE), "utf8"));
+    return typeof cache.checkedAt === "number" ? cache : null;
+  } catch {
+    return null;
+  }
+}
+function writeCache(dir, cache) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join5(dir, UPDATE_CACHE_FILE), JSON.stringify(cache));
+}
+function isNewer(latest, current) {
+  const parse2 = (version) => (version.split("-")[0] ?? "").split(".").map(Number);
+  const [a, b] = [parse2(latest), parse2(current)];
+  for (let index = 0; index < 3; index++) {
+    const difference = (a[index] || 0) - (b[index] || 0);
+    if (difference !== 0) return difference > 0;
+  }
+  return false;
+}
+function updateNotice(current, dir) {
+  const latest = readCache(dir)?.latest;
+  if (!latest || !isNewer(latest, current)) return null;
+  return `probe ${latest} available (you have ${current}) \u2192 \`brew upgrade probe\` or \`npm i -g ${PACKAGE_NAME}\``;
+}
+function scheduleRefresh(dir, cliPath, now = Date.now()) {
+  try {
+    const cache = readCache(dir);
+    if (cache && now - cache.checkedAt < UPDATE_CHECK_TTL_MS) return false;
+    writeCache(dir, { latest: cache?.latest ?? null, checkedAt: now });
+    spawn(process.execPath, [cliPath, REFRESH_COMMAND], {
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function fetchLatestVersion() {
+  const response = await fetch(REGISTRY_LATEST_URL, {
+    signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+  });
+  if (!response.ok) throw new Error(`registry answered ${response.status}`);
+  const { version } = await response.json();
+  if (typeof version !== "string") throw new Error("registry answer has no version");
+  return version;
+}
+async function refreshCache(dir, fetchLatest = fetchLatestVersion, now = Date.now()) {
+  try {
+    writeCache(dir, { latest: await fetchLatest(), checkedAt: now });
+  } catch {
+  }
+}
+
+// src/commands/status.ts
+function describeBlock(state, colors) {
+  switch (state) {
+    case "in-sync":
+      return colors.green("in sync");
+    case "modified":
+      return colors.yellow("block edited by hand \u2192 run `probe sync` to restore it");
+    case "outdated":
+      return colors.yellow("out of date \u2192 run `probe sync`");
+    case "missing":
+      return colors.yellow("no probe block \u2192 run `probe sync`");
+  }
+}
+function describeUpdate(colors) {
+  if (updateCheckDisabled()) return colors.dim(`check disabled (${CLI_VERSION})`);
+  const notice = updateNotice(CLI_VERSION, cacheDir());
+  if (notice) return colors.yellow(notice);
+  if (!readCache(cacheDir())?.latest) return colors.dim(`not checked yet (${CLI_VERSION})`);
+  return colors.green(`up to date (${CLI_VERSION})`);
+}
+var status_default = defineCommand7({
+  meta: { name: "status", description: "Show pending migration, Makefile state and updates" },
+  async run() {
+    const colors = stdoutColors();
+    const paths = requireProbeDir(process.cwd());
+    const pending = await pendingMigration(paths);
+    const line = (label, value) => console.log(`${label.padEnd(10)} ${value}`);
+    if (pending) {
+      const change = `schema v${pending.from} \u2192 v${pending.to}`;
+      line("migration", colors.yellow(`pending (${change}) \u2192 run \`probe migrate\``));
+      line("makefile", colors.dim("checked after the migration"));
+    } else {
+      const { config } = await loadConfig(paths);
+      line("migration", colors.green("none pending"));
+      line("makefile", describeBlock(await blockState(paths, config), colors));
+    }
+    line("update", describeUpdate(colors));
+  }
+});
+
+// src/commands/sync.ts
+import { relative as relative2 } from "path";
+import { defineCommand as defineCommand8 } from "citty";
+var sync_default = defineCommand8({
+  meta: { name: "sync", description: "Regenerate the probe block of the Makefile" },
+  async run() {
+    const { config, paths } = await openProject();
+    const { created, changed } = await syncMakefile(paths, config);
+    const file = relative2(process.cwd(), makefilePath(paths)) || "Makefile";
+    if (created) console.log(`Created ${file}. Try: make help`);
+    else if (changed) console.log(`Updated the probe block in ${file}.`);
+    else console.log(`${file} is already in sync.`);
+  }
+});
+
+// src/cli.ts
+var main = defineCommand9({
+  meta: {
+    name: "probe",
+    version: CLI_VERSION,
+    description: "Health checks for your local dev services"
+  },
+  subCommands: { init: init_default, add: add_default, rm: rm_default, ls: ls_default, check: check_default, status: status_default, sync: sync_default, migrate: migrate_default }
+});
+function notifyUpdate(rawArgs) {
+  const cliPath = process.argv[1];
+  if (updateCheckDisabled() || !cliPath) return;
+  scheduleRefresh(cacheDir(), cliPath);
+  if (!process.stderr.isTTY || rawArgs.includes("--json") || rawArgs[0] === "status") return;
+  const notice = updateNotice(CLI_VERSION, cacheDir());
+  if (notice) console.error(`
+${notice}`);
+}
+async function run(rawArgs) {
+  if (rawArgs[0] === REFRESH_COMMAND) return refreshCache(cacheDir());
+  const wantsHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
+  const wantsVersion = rawArgs.length === 1 && ["--version", "-v"].includes(rawArgs[0]);
+  if (wantsHelp || wantsVersion) return runMain(main, { rawArgs });
+  try {
+    await runCommand(main, { rawArgs });
+  } catch (error) {
+    process.exitCode = EXIT_ERROR;
+    if (error instanceof ProbeError) {
+      console.error(`probe: ${error.message}`);
+    } else if (error instanceof Error && error.name === "CLIError") {
+      if (rawArgs.length === 0) await showUsage(main);
+      console.error(`probe: ${error.message.replace(/\.$/, "")}. See: probe --help`);
+    } else {
+      console.error(`probe: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  notifyUpdate(rawArgs);
+}
+await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@ninhache/probe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Health checks for your local dev services, from the CLI or a generated Makefile",
+  "license": "MIT",
+  "author": "Ninhache",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ninhache/probe.git"
+  },
+  "type": "module",
+  "bin": {
+    "probe": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write ."
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.7",
+    "@types/node": "^20.19.43",
+    "tsup": "^9.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}