@ninhache/probe 0.4.1 → 0.6.0

package/README.md

@@ -11,6 +11,7 @@ Declare your project's local services once. Check they are up with one command,
 $ probe check
 ✓ api    http://localhost:3000/health  200  12ms
 ✗ front  http://localhost:5173/        connection refused
+  nothing listens on :5173: is the service started?
 $ echo $?
 1
 ```
@@ -44,20 +45,44 @@ Want `make check` too? See [Makefile](#makefile): it is optional.
 | `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 open <name>`                                       | Open the URL of a service in the browser                               |
+| `probe curl <name>`                                       | Print the curl command that requests a service                         |
 | `probe status`                                            | CLI version, pending migration, Makefile block state, available update |
 | `probe sync`                                              | Add or regenerate the Makefile block (optional)                        |
 | `probe migrate`                                           | Migrate `.probe/config.yml` to the current schema                      |
+| `probe completion <zsh\|bash\|fish>`                      | Print the shell completion script                                      |
 
 Exit codes: `0` all up, `1` a service is down, `2` usage or config error.
 
+A service that is down comes with a hint when the cause is a known one: connection refused, timeout, host not
+found, unexpected status, certificate rejected after a redirect to https. With `--json` it is the `hint` field,
+next to `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, or the service's own `timeout`. Progress goes to stderr, the final
 report to stdout; exit code `1` names the services still down.
 
+`probe open` uses `open` on macOS and `xdg-open` elsewhere. Without it, the URL is printed and the exit code is
+`1`. `probe curl api` prints a command to copy, or to run: `probe curl api | sh`.
+
 `probe` works from any sub-directory: it walks up to the nearest `.probe/`.
 
+## Completion
+
+Tab completes the commands, their options and the names of your services (`probe check a<Tab>`).
+
+```sh
+eval "$(probe completion zsh)"     # in ~/.zshrc, after compinit
+eval "$(probe completion bash)"    # in ~/.bashrc (macOS: ~/.bash_profile)
+probe completion fish | source     # in ~/.config/fish/config.fish
+```
+
+In zsh you can also save it once instead: `probe completion zsh > ~/.zfunc/_probe`, with `~/.zfunc` in your
+`fpath`; in fish, `probe completion fish > ~/.config/fish/completions/probe.fish`. It works with the bash 3.2
+of macOS.
+
 ## Dashboard
 
 `probe` alone, on a terminal, opens a live list of your services and checks them every 2 s
@@ -137,12 +162,16 @@ outside the block is yours and is never touched. Without a block, no command cre
 Once the block is there, `probe add` and `probe rm` keep it up to date. Commit the `Makefile` and
 `.probe/lock.yml`.
 
-Targets: `help`, `check`, `status` and one `check-<name>` per service. The block uses `probe` when it is in
+Targets: `help`, `check`, `status`, `probe` (opens the [dashboard](#dashboard)) 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 and `probe add` / `probe rm` leave it alone. `probe sync`
 restores it.
 
+A newer `probe` can add targets to the block: `make probe` came with 0.6.0. A block written before that is
+reported as `outdated` by `probe status`. Run `probe sync` once to get the new targets.
+
 ## Migrations
 
 `config.yml` carries a `schemaVersion`. When a newer `probe` needs a newer schema, the first command you run:

package/dist/{chunk-HHTOVIAQ.js → chunk-YTTYVEYF.js}

@@ -27,6 +27,7 @@ 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 COMPLETE_COMMAND = "__complete";
 var EXIT_DOWN = 1;
 var EXIT_ERROR = 2;
 
@@ -93,19 +94,83 @@ 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"
+// src/checkers/diagnosis.ts
+var CONFIG = `${PROBE_DIR}/${CONFIG_FILE}`;
+var CERTIFICATE_CODES = /* @__PURE__ */ new Set([
+  "CERT_HAS_EXPIRED",
+  "CERT_NOT_YET_VALID",
+  "CERT_UNTRUSTED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "ERR_TLS_CERT_ALTNAME_INVALID"
+]);
+var hostNotFound = (service) => ({
+  error: "host not found",
+  hint: `"${service.host}" does not resolve: check \`host\` in ${CONFIG}`
+});
+var NETWORK = {
+  ECONNREFUSED: (service) => ({
+    error: "connection refused",
+    hint: `nothing listens on :${service.port}: is the service started?`
+  }),
+  ECONNRESET: (service) => ({
+    error: "connection reset",
+    hint: `:${service.port} closed the connection without answering: does it speak plain http?`
+  }),
+  ENOTFOUND: hostNotFound,
+  EAI_AGAIN: hostNotFound,
+  EHOSTUNREACH: (service) => ({
+    error: "host unreachable",
+    hint: `no route to ${service.host}: check the network or the VPN`
+  })
 };
+function diagnoseFailure(error, service, timeoutMs) {
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return {
+      error: `timeout after ${timeoutMs / 1e3}s`,
+      hint: `still starting, or stuck? Give it more time: \`timeout\` in ${CONFIG}`
+    };
+  }
+  const cause = error?.cause;
+  const code = cause?.code ?? cause?.errors?.[0]?.code;
+  if (!code) return { error: error instanceof Error ? error.message : String(error) };
+  if (CERTIFICATE_CODES.has(code)) {
+    return {
+      error: `certificate rejected (${code})`,
+      // Services are checked over http: a certificate can only come from a redirect to https.
+      hint: "a redirect led to https with a certificate that is not trusted: renew it, or add its CA with NODE_EXTRA_CA_CERTS"
+    };
+  }
+  return NETWORK[code]?.(service) ?? { error: code };
+}
+function describeExpected(expect) {
+  if (expect === void 0) return "2xx";
+  return Array.isArray(expect) ? expect.join(" or ") : String(expect);
+}
+function diagnoseStatus(service, status) {
+  const error = `expected ${describeExpected(service.expect)}, got ${status}`;
+  if (status >= 500) return { error, hint: "the service answers with an error: look at its logs" };
+  if (status === 404) {
+    return { error, hint: `nothing at ${service.path}: check \`path\` in ${CONFIG}` };
+  }
+  return { error, hint: `the service answers: check \`path\` and \`expect\` in ${CONFIG}` };
+}
+
+// src/checkers/http.ts
 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}`;
 }
+var shellQuoted = (text) => `'${text.replaceAll("'", "'\\''")}'`;
+function curlCommand(service) {
+  const follow = expectsRedirect(service.expect) ? "" : " -L";
+  const seconds = service.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+  return `curl -i${follow} --max-time ${seconds} ${shellQuoted(targetUrl(service))}`;
+}
 function isExpected(expect, status) {
   if (expect === void 0) return status >= 200 && status < 300;
   return Array.isArray(expect) ? expect.includes(status) : expect === status;
@@ -113,19 +178,6 @@ function isExpected(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 }) {
@@ -144,10 +196,10 @@ var httpChecker = {
       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 };
+      return { ...base, ok: false, status, latencyMs, ...diagnoseStatus(service, status) };
     } catch (error) {
-      return { ...base, ok: false, latencyMs: elapsed(), error: failureReason(error, timeoutMs) };
+      const diagnosis = diagnoseFailure(error, service, timeoutMs);
+      return { ...base, ok: false, latencyMs: elapsed(), ...diagnosis };
     }
   }
 };
@@ -251,7 +303,12 @@ function formatCheckResults(results, terminal) {
     } else {
       outcome = `${colors.green(String(result.status))}${GAP}${colors.dim(`${result.latencyMs}ms`)}`;
     }
-    return `${mark} ${name}${GAP}${target}${outcome}`;
+    const line = `${mark} ${name}${GAP}${target}${outcome}`;
+    if (!result.hint) return line;
+    const room = columns === void 0 ? void 0 : Math.max(1, columns - GAP.length);
+    const hint = room === void 0 ? result.hint : truncate(result.hint, room);
+    return `${line}
+${GAP}${colors.dim(hint)}`;
   }).join("\n");
 }
 function formatServices(config, terminal, skipped = /* @__PURE__ */ new Set()) {
@@ -299,6 +356,7 @@ export {
   UPDATE_CHECK_TTL_MS,
   UPDATE_CACHE_FILE,
   REFRESH_COMMAND,
+  COMPLETE_COMMAND,
   EXIT_DOWN,
   EXIT_ERROR,
   ProbeError,
@@ -307,6 +365,8 @@ export {
   isInteractive,
   truncate,
   stripStyles,
+  targetUrl,
+  curlCommand,
   runChecks,
   formatCheckResults,
   formatServices

package/dist/cli.js

@@ -3,6 +3,7 @@ import { createRequire as __createRequire } from "node:module";
 const require = __createRequire(import.meta.url);
 import {
   BACKUP_GLOB,
+  COMPLETE_COMMAND,
   CONFIG_FILE,
   DASHBOARD_INTERVAL_SECONDS,
   DEFAULT_MAKEFILE,
@@ -28,18 +29,20 @@ import {
   WAIT_BACKOFF_FACTOR,
   WAIT_LAST_PASS_MS,
   createColors,
+  curlCommand,
   detectTerminal,
   formatCheckResults,
   formatServices,
   isInteractive,
   runChecks,
-  stripStyles
-} from "./chunk-HHTOVIAQ.js";
+  stripStyles,
+  targetUrl
+} from "./chunk-YTTYVEYF.js";
 import "./chunk-M3ASEG5F.js";
 
 // src/cli.ts
 import {
-  defineCommand as defineCommand10,
+  defineCommand as defineCommand13,
   renderUsage,
   runCommand,
   runMain
@@ -316,7 +319,7 @@ async function writeLock(paths, lock) {
 }
 
 // src/version.ts
-var CLI_VERSION = true ? "0.4.1" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.6.0" : "0.0.0-dev";
 
 // src/makefile/generator.ts
 import { createHash } from "crypto";
@@ -331,13 +334,15 @@ function renderBlock(serviceNames) {
   return [
     BLOCK_START,
     `PROBE ?= $(shell command -v probe >/dev/null 2>&1 && echo probe || echo "${fallback}")`,
-    `.PHONY: ${["help", "check", "status", ...targets].join(" ")}`,
+    `.PHONY: ${["help", "check", "status", "probe", ...targets].join(" ")}`,
     "help: ## List available targets",
     `	${HELP_RECIPE}`,
     "check: ## Check that every service responds",
     "	@$(PROBE) check",
     "status: ## Show probe status",
     "	@$(PROBE) status",
+    "probe: ## Open the dashboard",
+    "	@$(PROBE)",
     ...serviceNames.flatMap((name) => [
       `check-${name}: ## Check ${name}`,
       `	@$(PROBE) check ${name}`
@@ -426,6 +431,11 @@ function secondsToMs(option, value) {
   }
   return Math.ceil(seconds2 * 1e3);
 }
+function namedService(config, name) {
+  const service = Object.hasOwn(config.services, name) ? config.services[name] : void 0;
+  if (!service) throw new ProbeError("SERVICE_UNKNOWN", `unknown service "${name}". See: probe ls`);
+  return service;
+}
 function rawServices(loaded) {
   return loaded.raw.services ?? {};
 }
@@ -466,25 +476,25 @@ var add_default = defineCommand({
       description: `Seconds to wait for this service (default: ${DEFAULT_TIMEOUT_SECONDS})`
     }
   },
-  async run({ args }) {
+  async run({ args: args2 }) {
     const loaded = await openProject();
     const services = rawServices(loaded);
-    if (Object.hasOwn(services, args.name)) {
+    if (Object.hasOwn(services, args2.name)) {
       throw new ProbeError(
         "SERVICE_EXISTS",
-        `service "${args.name}" already exists. Remove it first: probe rm ${args.name}`
+        `service "${args2.name}" already exists. Remove it first: probe rm ${args2.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));
-    if (args.timeout !== void 0) {
-      secondsToMs("--timeout", String(args.timeout));
-      service.timeout = Number(args.timeout);
+    const service = { port: parseInteger(String(args2.port), "--port") };
+    if (args2.host) service.host = args2.host;
+    if (args2.path) service.path = args2.path;
+    if (args2.expect) service.expect = parseExpect(String(args2.expect));
+    if (args2.timeout !== void 0) {
+      secondsToMs("--timeout", String(args2.timeout));
+      service.timeout = Number(args2.timeout);
     }
-    await saveServices(loaded, { ...services, [args.name]: service });
-    console.log(`Added ${args.name}. Try: probe check ${args.name}`);
+    await saveServices(loaded, { ...services, [args2.name]: service });
+    console.log(`Added ${args2.name}. Try: probe check ${args2.name}`);
   }
 });
 
@@ -606,13 +616,13 @@ var check_default = defineCommand2({
       description: `Seconds to wait for each service (default: its own timeout, else ${DEFAULT_TIMEOUT_SECONDS})`
     }
   },
-  async run({ args }) {
-    const forceTimeout = args.timeout !== void 0;
-    const timeoutMs = secondsToMs("--timeout", args.timeout ?? String(DEFAULT_TIMEOUT_SECONDS));
+  async run({ args: args2 }) {
+    const forceTimeout = args2.timeout !== void 0;
+    const timeoutMs = secondsToMs("--timeout", args2.timeout ?? String(DEFAULT_TIMEOUT_SECONDS));
     const { config, paths } = await openProject();
     const skipped = await readSkippedServices(paths);
-    const results = await runChecks(config, args._, { timeoutMs, forceTimeout }, skipped);
-    if (args.json) {
+    const results = await runChecks(config, args2._, { timeoutMs, forceTimeout }, skipped);
+    if (args2.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");
@@ -623,11 +633,190 @@ var check_default = defineCommand2({
   }
 });
 
+// src/commands/completion.ts
+import { defineCommand as defineCommand3 } from "citty";
+
+// src/completion/spec.ts
+var SHELLS = ["zsh", "bash", "fish"];
+var COMPLETION_COMMAND = "completion";
+var SERVICE_COMMANDS = ["rm", "check", "wait", "open", "curl"];
+var ROOT_OPTIONS = ["--interval", "--help", "--version"];
+var SERVICES_QUERY = `probe ${COMPLETE_COMMAND} services 2>/dev/null`;
+var HELP_OPTION = "--help";
+function completionSpec(commands2) {
+  return Object.entries(commands2).map(([name, command]) => {
+    const meta2 = command.meta ?? {};
+    const args2 = command.args ?? {};
+    const options = Object.entries(args2).filter(([, arg]) => arg.type !== "positional").map(([option]) => `--${option}`);
+    return {
+      name,
+      description: meta2.description ?? "",
+      options: [...options, HELP_OPTION],
+      words: name === COMPLETION_COMMAND ? [...SHELLS] : [],
+      services: SERVICE_COMMANDS.includes(name)
+    };
+  });
+}
+
+// src/completion/bash.ts
+function bashScript(commands2) {
+  const cases = (pick) => commands2.filter((command) => pick(command).length > 0).map((command) => `      ${command.name}) words="${pick(command).join(" ")}" ;;`);
+  const withServices = commands2.filter((command) => command.services).map(({ name }) => name);
+  return [
+    '# bash completion for probe. Load it with: eval "$(probe completion bash)"',
+    "_probe() {",
+    `  local cur="\${COMP_WORDS[COMP_CWORD]}" cmd="" words="" i`,
+    "  for ((i = 1; i < COMP_CWORD; i++)); do",
+    `    case "\${COMP_WORDS[i]}" in`,
+    "      -*) ;;",
+    `      *) cmd="\${COMP_WORDS[i]}"; break ;;`,
+    "    esac",
+    "  done",
+    '  if [ -z "$cmd" ]; then',
+    '    case "$cur" in',
+    `      -*) words="${ROOT_OPTIONS.join(" ")}" ;;`,
+    `      *) words="${commands2.map(({ name }) => name).join(" ")}" ;;`,
+    "    esac",
+    `  elif [ "\${cur#-}" != "$cur" ]; then`,
+    '    case "$cmd" in',
+    ...cases((command) => command.options),
+    "    esac",
+    "  else",
+    '    case "$cmd" in',
+    `      ${withServices.join("|")}) words="$(${SERVICES_QUERY})" ;;`,
+    ...cases((command) => command.words),
+    "    esac",
+    "  fi",
+    '  COMPREPLY=($(compgen -W "$words" -- "$cur"))',
+    "}",
+    "complete -F _probe probe",
+    ""
+  ].join("\n");
+}
+
+// src/completion/fish.ts
+var quoted = (text) => `'${text.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+var longOption = (option) => `-l ${option.replace(/^--/, "")}`;
+function fishScript(commands2) {
+  const inCommand = (names) => `-n '__fish_seen_subcommand_from ${names.join(" ")}'`;
+  const withServices = commands2.filter((command) => command.services).map(({ name }) => name);
+  return [
+    "# fish completion for probe. Load it with: probe completion fish | source",
+    "function __probe_services",
+    `    ${SERVICES_QUERY}`,
+    "end",
+    // No file names: probe takes none.
+    "complete -c probe -f",
+    ...ROOT_OPTIONS.map(
+      (option) => `complete -c probe -n __fish_use_subcommand ${longOption(option)}`
+    ),
+    ...commands2.map(
+      ({ name, description }) => `complete -c probe -n __fish_use_subcommand -a ${name} -d ${quoted(description)}`
+    ),
+    `complete -c probe ${inCommand(withServices)} -a '(__probe_services)'`,
+    ...commands2.flatMap((command) => [
+      ...command.options.map(
+        (option) => `complete -c probe ${inCommand([command.name])} ${longOption(option)}`
+      ),
+      ...command.words.length > 0 ? [`complete -c probe ${inCommand([command.name])} -a ${quoted(command.words.join(" "))}`] : []
+    ]),
+    ""
+  ].join("\n");
+}
+
+// src/completion/zsh.ts
+function described({ name, description }) {
+  const text = `${name}:${description.replaceAll(":", "\\:")}`;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+function zshScript(commands2) {
+  const cases = (pick) => commands2.filter((command) => pick(command).length > 0).map((command) => `    ${command.name}) compadd -- ${pick(command).join(" ")} ;;`);
+  const withServices = commands2.filter((command) => command.services).map(({ name }) => name);
+  return [
+    "#compdef probe",
+    '# zsh completion for probe. Load it after compinit with: eval "$(probe completion zsh)"',
+    "_probe() {",
+    "  local -a commands services",
+    "  commands=(",
+    ...commands2.map((command) => `    ${described(command)}`),
+    "  )",
+    "  if (( CURRENT == 2 )); then",
+    "    if [[ $words[CURRENT] == -* ]]; then",
+    `      compadd -- ${ROOT_OPTIONS.join(" ")}`,
+    "    else",
+    "      _describe 'command' commands",
+    "    fi",
+    "    return",
+    "  fi",
+    "  if [[ $words[CURRENT] == -* ]]; then",
+    "    case $words[2] in",
+    ...cases((command) => command.options).map((line) => `  ${line}`),
+    "    esac",
+    "    return",
+    "  fi",
+    "  case $words[2] in",
+    `    ${withServices.join("|")})`,
+    `      services=(\${(f)"$(${SERVICES_QUERY})"})`,
+    "      compadd -a services ;;",
+    ...cases((command) => command.words),
+    "  esac",
+    "}",
+    "if (( $+functions[compdef] )); then compdef _probe probe; fi",
+    "# Saved as _probe in $fpath, this file is the function itself: run it.",
+    'if [[ $funcstack[1] == _probe ]]; then _probe "$@"; fi',
+    ""
+  ].join("\n");
+}
+
+// src/commands/completion.ts
+var SCRIPTS = {
+  zsh: zshScript,
+  bash: bashScript,
+  fish: fishScript
+};
+var meta = {
+  name: COMPLETION_COMMAND,
+  description: `Print the shell completion script (${SHELLS.join(", ")})`
+};
+var args = {
+  shell: { type: "positional", description: SHELLS.join(", "), required: true }
+};
+function completion(others) {
+  const commands2 = { ...others, [COMPLETION_COMMAND]: { meta, args } };
+  return defineCommand3({
+    meta,
+    args,
+    run({ args: { shell } }) {
+      const script = Object.hasOwn(SCRIPTS, shell) ? SCRIPTS[shell] : void 0;
+      if (!script) {
+        throw new ProbeError(
+          "USAGE",
+          `no completion for the shell "${shell}". Supported: ${SHELLS.join(", ")}.`
+        );
+      }
+      process.stdout.write(script(completionSpec(commands2)));
+    }
+  });
+}
+
+// src/commands/curl.ts
+import { defineCommand as defineCommand4 } from "citty";
+var curl_default = defineCommand4({
+  meta: { name: "curl", description: "Print the curl command that requests a service" },
+  args: {
+    name: { type: "positional", description: "Service name", required: true }
+  },
+  async run({ args: args2 }) {
+    const { config } = await openProject();
+    console.log(curlCommand(namedService(config, args2.name)));
+  }
+});
+
 // src/commands/init.ts
 import { existsSync } from "fs";
 import { mkdir, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import { join as join5 } from "path";
-import { defineCommand as defineCommand3 } from "citty";
+import { defineCommand as defineCommand5 } 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}
@@ -643,7 +832,7 @@ async function ignoreLocalFiles(root) {
   await writeFile5(file, `${current}${separator}${missing.join("\n")}
 `);
 }
-var init_default = defineCommand3({
+var init_default = defineCommand5({
   meta: {
     name: "init",
     description: "Create .probe/ and the .gitignore entries"
@@ -661,8 +850,8 @@ var init_default = defineCommand3({
 });
 
 // src/commands/ls.ts
-import { defineCommand as defineCommand4 } from "citty";
-var ls_default = defineCommand4({
+import { defineCommand as defineCommand6 } from "citty";
+var ls_default = defineCommand6({
   meta: { name: "ls", description: "List services" },
   async run() {
     const { config, paths } = await openProject();
@@ -675,8 +864,8 @@ var ls_default = defineCommand4({
 });
 
 // src/commands/migrate.ts
-import { defineCommand as defineCommand5 } from "citty";
-var migrate_default = defineCommand5({
+import { defineCommand as defineCommand7 } from "citty";
+var migrate_default = defineCommand7({
   meta: { name: "migrate", description: "Migrate the config to the current schema version" },
   async run() {
     const paths = requireProbeDir(process.cwd());
@@ -688,27 +877,65 @@ var migrate_default = defineCommand5({
   }
 });
 
+// src/commands/open.ts
+import { defineCommand as defineCommand8 } from "citty";
+
+// src/open-url.ts
+import { spawn as nodeSpawn } from "child_process";
+function openerCommand(platform) {
+  return platform === "darwin" ? "open" : "xdg-open";
+}
+function openUrl(url, platform = process.platform, spawn2 = nodeSpawn) {
+  return new Promise((resolve2) => {
+    const child = spawn2(openerCommand(platform), [url], { detached: true, stdio: "ignore" });
+    child.once("error", () => resolve2(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve2(true);
+    });
+  });
+}
+
+// src/commands/open.ts
+var open_default = defineCommand8({
+  meta: { name: "open", description: "Open the URL of a service in the browser" },
+  args: {
+    name: { type: "positional", description: "Service name", required: true }
+  },
+  async run({ args: args2 }) {
+    const { config } = await openProject();
+    const url = targetUrl(namedService(config, args2.name));
+    if (await openUrl(url)) {
+      console.log(`Opened ${url}`);
+      return;
+    }
+    console.log(url);
+    console.error(`probe: ${openerCommand(process.platform)} not found, open the URL yourself.`);
+    process.exitCode = EXIT_DOWN;
+  }
+});
+
 // src/commands/rm.ts
-import { defineCommand as defineCommand6 } from "citty";
-var rm_default = defineCommand6({
+import { defineCommand as defineCommand9 } from "citty";
+var rm_default = defineCommand9({
   meta: { name: "rm", description: "Remove a service" },
   args: {
     name: { type: "positional", description: "Service name", required: true }
   },
-  async run({ args }) {
+  async run({ args: args2 }) {
     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`);
+    if (!Object.hasOwn(services, args2.name)) {
+      throw new ProbeError("SERVICE_UNKNOWN", `unknown service "${args2.name}". See: probe ls`);
     }
-    const { [args.name]: _removed, ...rest } = services;
+    const { [args2.name]: _removed, ...rest } = services;
     await saveServices(loaded, rest);
-    console.log(`Removed ${args.name}.`);
+    console.log(`Removed ${args2.name}.`);
   }
 });
 
 // src/commands/status.ts
-import { defineCommand as defineCommand7 } from "citty";
+import { defineCommand as defineCommand10 } from "citty";
 
 // src/update/notifier.ts
 import { spawn } from "child_process";
@@ -734,8 +961,8 @@ function writeCache(dir, cache) {
   writeFileSync(join6(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)];
+  const parse3 = (version) => (version.split("-")[0] ?? "").split(".").map(Number);
+  const [a, b] = [parse3(latest), parse3(current)];
   for (let index = 0; index < 3; index++) {
     const difference = (a[index] || 0) - (b[index] || 0);
     if (difference !== 0) return difference > 0;
@@ -797,7 +1024,7 @@ function describeUpdate(colors) {
   if (!readCache(cacheDir())?.latest) return colors.dim(`not checked yet (${CLI_VERSION})`);
   return colors.green(`up to date (${CLI_VERSION})`);
 }
-var status_default = defineCommand7({
+var status_default = defineCommand10({
   meta: { name: "status", description: "Show pending migration, Makefile state and updates" },
   async run() {
     const colors = stdoutColors();
@@ -819,8 +1046,8 @@ var status_default = defineCommand7({
 
 // src/commands/sync.ts
 import { relative as relative2 } from "path";
-import { defineCommand as defineCommand8 } from "citty";
-var sync_default = defineCommand8({
+import { defineCommand as defineCommand11 } from "citty";
+var sync_default = defineCommand11({
   meta: {
     name: "sync",
     description: "Add or regenerate the probe block of the Makefile (optional)"
@@ -836,7 +1063,7 @@ var sync_default = defineCommand8({
 });
 
 // src/commands/wait.ts
-import { defineCommand as defineCommand9 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
 
 // src/checkers/poll.ts
 import { setTimeout as delay } from "timers/promises";
@@ -885,7 +1112,7 @@ function progressReporter() {
     return lines;
   };
 }
-var wait_default = defineCommand9({
+var wait_default = defineCommand12({
   meta: {
     name: "wait",
     description: "Check again and again until services are up (all of them by default)"
@@ -908,14 +1135,14 @@ var wait_default = defineCommand9({
       default: String(DEFAULT_WAIT_MAX_INTERVAL_SECONDS)
     }
   },
-  async run({ args }) {
-    const deadlineMs = secondsToMs("--timeout", args.timeout);
-    const intervalMs = secondsToMs("--interval", args.interval);
-    const maxIntervalMs = secondsToMs("--max-interval", args["max-interval"]);
+  async run({ args: args2 }) {
+    const deadlineMs = secondsToMs("--timeout", args2.timeout);
+    const intervalMs = secondsToMs("--interval", args2.interval);
+    const maxIntervalMs = secondsToMs("--max-interval", args2["max-interval"]);
     if (intervalMs > maxIntervalMs) {
       throw new ProbeError(
         "USAGE",
-        `--interval (${args.interval}s) cannot be longer than --max-interval (${args["max-interval"]}s).`
+        `--interval (${args2.interval}s) cannot be longer than --max-interval (${args2["max-interval"]}s).`
       );
     }
     const { config, paths } = await openProject();
@@ -925,7 +1152,7 @@ var wait_default = defineCommand9({
       // A service with its own timeout keeps it here, within what is left of the total.
       (_passMs, remainingMs) => runChecks(
         config,
-        args._,
+        args2._,
         { timeoutMs: DEFAULT_TIMEOUT_SECONDS * 1e3, maxTimeoutMs: remainingMs },
         skipped
       ),
@@ -939,7 +1166,7 @@ var wait_default = defineCommand9({
         }
       }
     );
-    if (args.json) {
+    if (args2.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");
@@ -954,6 +1181,22 @@ var wait_default = defineCommand9({
   }
 });
 
+// src/completion/services.ts
+import { readFile as readFile6 } from "fs/promises";
+import { parse as parse2 } from "yaml";
+async function completableServices(cwd) {
+  try {
+    const paths = findProbeDir(cwd);
+    if (!paths) return [];
+    const raw = parse2(await readFile6(paths.config, "utf8"));
+    const services = raw?.services;
+    if (typeof services !== "object" || services === null) return [];
+    return Object.keys(services).filter((name) => SERVICE_NAME_PATTERN.test(name));
+  } catch {
+    return [];
+  }
+}
+
 // src/dashboard/saves.ts
 function describe(file, error) {
   const code = error?.code;
@@ -983,8 +1226,102 @@ function createSaveQueue() {
   };
 }
 
+// src/suggest.ts
+var SHORT_WORD = 4;
+var TYPOS_SHORT = 1;
+var TYPOS_LONG = 2;
+function typoDistance(a, b) {
+  const rows = Array.from(
+    { length: a.length + 1 },
+    (_, i) => Array.from({ length: b.length + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  const at = (i, j) => rows[i]?.[j] ?? 0;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const same = a[i - 1] === b[j - 1];
+      let best = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + (same ? 0 : 1));
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        best = Math.min(best, at(i - 2, j - 2) + 1);
+      }
+      rows[i][j] = best;
+    }
+  }
+  return at(a.length, b.length);
+}
+function closest(word, candidates) {
+  let found;
+  for (const candidate of candidates) {
+    const distance = typoDistance(word.toLowerCase(), candidate);
+    const allowed = candidate.length <= SHORT_WORD ? TYPOS_SHORT : TYPOS_LONG;
+    if (distance > allowed || distance >= candidate.length) continue;
+    if (!found || distance < found.distance) found = { candidate, distance };
+  }
+  return found?.candidate;
+}
+
+// src/ui/examples.ts
+var ROOT = "probe";
+var GAP = "  ";
+var INDENT = "  ";
+var ESC = "\x1B";
+var EXAMPLES = {
+  [ROOT]: [
+    { command: "probe init", note: "Start in this project" },
+    { command: "probe add api -p 3000 --path /health", note: "Declare a service" },
+    { command: "probe check", note: "Check every service" },
+    { command: "probe wait && pnpm test", note: "Run the tests once all are up" },
+    { command: "probe", note: "Open the dashboard (on a terminal)" }
+  ],
+  init: [{ command: "probe init", note: "Create .probe/ in this directory" }],
+  add: [
+    { command: "probe add api -p 3000", note: "http://localhost:3000/" },
+    { command: "probe add api -p 3000 --path /health", note: "Check another path" },
+    { command: "probe add admin -p 8080 --expect 200,204", note: "Accept these statuses only" },
+    { command: "probe add db -p 5432 --timeout 10", note: "Give it 10 s to answer" }
+  ],
+  rm: [{ command: "probe rm api", note: "Remove the service named api" }],
+  ls: [{ command: "probe ls", note: "List the services and their URL" }],
+  check: [
+    { command: "probe check", note: "Check every service" },
+    { command: "probe check api db", note: "Check these two only" },
+    { command: "probe check --json", note: "Print the results as JSON" },
+    { command: "probe check --timeout 10", note: "Give each service 10 s" }
+  ],
+  wait: [
+    { command: "probe wait && pnpm test", note: "Run the tests once all are up" },
+    { command: "probe wait api --timeout 120", note: "Wait for api, 2 minutes at most" },
+    { command: "probe wait --interval 1 --max-interval 10", note: "Check less often" }
+  ],
+  open: [{ command: "probe open front", note: "Open the URL of front in the browser" }],
+  curl: [
+    { command: "probe curl api", note: "Print the curl command for api" },
+    { command: "probe curl api | sh", note: "Run it" }
+  ],
+  status: [{ command: "probe status", note: "Version, migration, Makefile block" }],
+  sync: [{ command: "probe sync", note: "Write the probe block of the Makefile" }],
+  migrate: [{ command: "probe migrate", note: "Bring .probe/config.yml up to date" }],
+  completion: [
+    { command: "probe completion zsh", note: 'In ~/.zshrc: eval "$(probe completion zsh)"' },
+    { command: "probe completion bash", note: 'In ~/.bashrc: eval "$(probe completion bash)"' },
+    { command: "probe completion fish | source", note: "In ~/.config/fish/config.fish" }
+  ]
+};
+function formatExamples(name, color) {
+  const examples = EXAMPLES[name ?? ROOT] ?? [];
+  if (examples.length === 0) return "";
+  const style = (open, close) => (text) => color ? `${ESC}[${open}m${text}${ESC}[${close}m` : text;
+  const title = style("1;4", "22;24");
+  const cyan = style("36", "39");
+  const width = Math.max(...examples.map((example) => example.command.length));
+  const lines = examples.map(
+    ({ command, note }) => `${INDENT}${cyan(command.padEnd(width))}${GAP}${note}`
+  );
+  return [title("EXAMPLES"), "", ...lines].join("\n");
+}
+
 // src/cli.ts
-var main = defineCommand10({
+var commands = { init: init_default, add: add_default, rm: rm_default, ls: ls_default, check: check_default, wait: wait_default, open: open_default, curl: curl_default, status: status_default, sync: sync_default, migrate: migrate_default };
+var main = defineCommand13({
   meta: {
     name: "probe",
     version: CLI_VERSION,
@@ -998,16 +1335,21 @@ var main = defineCommand10({
       default: String(DASHBOARD_INTERVAL_SECONDS)
     }
   },
-  subCommands: { init: init_default, add: add_default, rm: rm_default, ls: ls_default, check: check_default, wait: wait_default, status: status_default, sync: sync_default, migrate: migrate_default }
+  subCommands: { ...commands, completion: completion(commands) }
 });
 async function printUsage(command, parent) {
   const usage = await renderUsage(command, parent);
-  console.log(`${stdoutTerminal().color ? usage : stripStyles(usage)}
-`);
+  const { color } = stdoutTerminal();
+  const meta2 = await (typeof command.meta === "function" ? command.meta() : command.meta);
+  const examples = formatExamples(command === main ? void 0 : meta2?.name, color);
+  console.log(`${color ? usage : stripStyles(usage)}
+${examples ? `
+${examples}
+` : ""}`);
 }
 function notifyUpdate(rawArgs) {
   const cliPath = process.argv[1];
-  if (updateCheckDisabled() || !cliPath) return;
+  if (updateCheckDisabled() || !cliPath || rawArgs[0] === COMPLETION_COMMAND) return;
   scheduleRefresh(cacheDir(), cliPath);
   if (!detectTerminal(process.stderr, process.env).isTTY || rawArgs.includes("--json") || rawArgs[0] === "status")
     return;
@@ -1043,7 +1385,7 @@ async function openedDashboard(rawArgs) {
     if (!asked) return false;
     throw new ProbeError("USAGE", "No services yet. Add one: probe add api -p 3000");
   }
-  const { openDashboard } = await import("./open-7LCTV2ZW.js");
+  const { openDashboard } = await import("./open-T3OQH2O4.js");
   let settings = initialDashboardSettings(askedMs, await readDashboardPreferences(paths));
   const saves = createSaveQueue();
   const local = `${PROBE_DIR}/${LOCAL_FILE}`;
@@ -1067,13 +1409,25 @@ async function openedDashboard(rawArgs) {
   for (const failure of saves.failures()) console.error(`probe: not saved: ${failure}`);
   return true;
 }
+var UNKNOWN_COMMAND = "E_UNKNOWN_COMMAND";
+function didYouMean(error, rawArgs) {
+  if (error.code !== UNKNOWN_COMMAND) return "";
+  const typed = rawArgs.find((arg) => !arg.startsWith("-"));
+  const command = typed && closest(typed, Object.keys(main.subCommands ?? {}));
+  return command ? ` Did you mean: probe ${command}?` : "";
+}
 function flushed(stream) {
   return new Promise((done) => {
     stream.write("", () => done());
   });
 }
+async function printCompletions(kind) {
+  if (kind !== "services") return;
+  for (const name of await completableServices(process.cwd())) console.log(name);
+}
 async function run(rawArgs) {
   if (rawArgs[0] === REFRESH_COMMAND) return refreshCache(cacheDir());
+  if (rawArgs[0] === COMPLETE_COMMAND) return printCompletions(rawArgs[1]);
   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, showUsage: printUsage });
@@ -1085,7 +1439,8 @@ async function run(rawArgs) {
       console.error(`probe: ${error.message}`);
     } else if (error instanceof Error && error.name === "CLIError") {
       if (rawArgs.length === 0) await printUsage(main);
-      console.error(`probe: ${error.message.replace(/\.$/, "")}. See: probe --help`);
+      const message = stripStyles(error.message).replace(/\.$/, "");
+      console.error(`probe: ${message}.${didYouMean(error, rawArgs)} See: probe --help`);
     } else {
       console.error(`probe: ${error instanceof Error ? error.message : String(error)}`);
     }

package/dist/{open-7LCTV2ZW.js → open-T3OQH2O4.js}

@@ -7,7 +7,7 @@ import {
   formatCheckResults,
   runChecks,
   truncate
-} from "./chunk-HHTOVIAQ.js";
+} from "./chunk-YTTYVEYF.js";
 import {
   __commonJS,
   __export,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninhache/probe",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Health checks for your local dev services, from the CLI or a generated Makefile",
   "license": "MIT",
   "author": "Ninhache",