postman-cli-completion 1.71.0 → 1.74.0

package/README.md

@@ -119,6 +119,74 @@ After installing for your shell, open a fresh terminal and check each:
 | `postman flows <TAB>` | `list`, `trigger`, `deploy`, `run`, `update`, `list-runs`, `get-run` |
 | `postman --<TAB>` | `--silent`, `--color`, `--version`, `--help` |
 
+## Check your Postman CLI version
+
+The completions are generated for a specific Postman CLI version, so a CLI that has
+drifted from that version may complete commands it does not have (or miss ones it does).
+`doctor` reports both kinds of drift:
+
+```sh
+postman-completion doctor
+```
+
+It performs two independent checks:
+
+1. **Installed CLI vs. the latest published `postman-cli`** — if yours is older, it warns
+   and tells you how to upgrade.
+2. **Installed CLI vs. the version these completions were generated for** — if they differ,
+   it warns and tells you how to update the completions.
+
+```console
+$ postman-completion doctor
+Your Postman CLI is outdated: installed 1.60.0, latest 1.73.0.
+  Upgrade with: npm install -g postman-cli@latest
+These completions were generated for Postman CLI 1.73.0, but 1.60.0 is installed.
+  Completions may offer commands your CLI does not have.
+  Update them with: npm install -g postman-cli-completion@latest
+```
+
+Check 1 queries the npm registry. To skip it — offline, or in a hook where you do not want
+a network call — use `--offline`, which still runs check 2:
+
+```sh
+postman-completion doctor --offline
+```
+
+`doctor` exits **1** when you should act (outdated CLI, or completions that no longer match
+it) and **0** when everything is current, so it works as a shell-startup or CI check. A
+missing Postman CLI is reported as a notice and exits 0. A failed registry lookup never
+fails the command — it degrades to the offline check and explains itself on stderr.
+
+### Automatic notice on install
+
+You do not have to remember to run `doctor`. Installing or updating this package prints a
+notice if your Postman CLI does not match the version the completions were built for:
+
+```console
+$ npm install -g postman-cli-completion
+
+postman-cli-completion:
+  These completions were generated for Postman CLI 1.73.0, but 1.60.0 is installed.
+    Completions may offer commands your CLI does not have.
+    Update them with: npm install -g postman-cli-completion@latest
+
+  Silence this check with POSTMAN_COMPLETION_NO_VERSION_CHECK=1
+```
+
+This check is deliberately conservative:
+
+- **Never fails the install** — it exits 0 on every path, including unexpected errors.
+- **Never touches the network** — the comparison is local, so installs stay fast and
+  offline-safe. The "is my CLI older than the latest release?" question needs the
+  registry, so it belongs to `doctor`.
+- **Silent unless it matters** — nothing is printed when the versions match, when the
+  Postman CLI is not installed, in CI, for non-global installs, or when stderr is not a
+  terminal. Set `POSTMAN_COMPLETION_NO_VERSION_CHECK=1` to disable it entirely.
+
+Because it runs at install time, it catches drift when you install or update this package.
+If you upgrade the Postman CLI itself some time later, run `postman-completion doctor` to
+check on demand.
+
 ## Versioning
 
 The completion scripts are auto-generated from a single source of truth (`spec/commands.json`) and tracked against the upstream Postman CLI by two GitHub Actions workflows:
@@ -130,16 +198,12 @@ So this repo follows the latest published Postman CLI version automatically —
 
 Suspicious catchup diffs (≥30 % flag drop, a known fixed command missing, semver regression) are blocked by `scripts/validate-diff.mjs` and stay open for human review instead of auto-merging.
 
-To check the version the committed spec was generated against:
-
-```sh
-node -p "require('./spec/commands.json').postmanCliVersion"
-```
-
-And your installed Postman CLI:
+To compare the version the completions were built for against your installed CLI, use
+[`postman-completion doctor`](#check-your-postman-cli-version). The underlying values are:
 
 ```sh
-postman --version
+node -p "require('./spec/commands.json').postmanCliVersion"   # what the completions target
+postman --version                                             # what you have installed
 ```
 
 ## License

package/bin/postman-completion.mjs

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkVersions } from "../lib/version-check.mjs";
 
 // bin/ lives one level under the package root. Resolve completion files relative
 // to this module (NOT process.cwd(), which is the user's shell directory).
@@ -13,6 +14,9 @@ const FILES = {
   fish: resolve(PKG_ROOT, "completions/fish/postman.fish"),
 };
 
+const SPEC_PATH = resolve(PKG_ROOT, "spec/commands.json");
+const PKG_JSON_PATH = resolve(PKG_ROOT, "package.json");
+
 const USAGE = `postman-completion — shell completions for the Postman CLI
 
 Note: this installs the command "postman-completion"; it does NOT shadow the
@@ -22,6 +26,8 @@ Usage:
   postman-completion <zsh|bash|fish>          Print the completion script to stdout
   postman-completion path <zsh|bash|fish>     Print the packaged file's absolute path
   postman-completion path <shell> --dir       Print the file's directory (for zsh fpath)
+  postman-completion doctor                   Check your Postman CLI version for updates
+  postman-completion doctor --offline         Same, without querying the npm registry
   postman-completion --help                   Show this help
 
 Wire it into your shell:
@@ -59,7 +65,30 @@ function printPath(args) {
   process.stdout.write(`${dirOnly ? dirname(file) : file}\n`);
 }
 
-function main(argv) {
+// Exit 0 when everything is current, 1 when the user should act (outdated CLI
+// or completions that no longer match it), so `doctor` is usable in a script.
+async function doctor(args) {
+  const offline = args.includes("--offline");
+  const report = await checkVersions({
+    specPath: SPEC_PATH,
+    packageJsonPath: PKG_JSON_PATH,
+    offline,
+  });
+
+  for (const line of report.lines) process.stdout.write(`${line}\n`);
+
+  // Surface *why* a comparison was skipped, but only when it hid information:
+  // an explicit --offline is the user's own choice and needs no explanation.
+  if (!offline && report.latestError) {
+    process.stderr.write(
+      `postman-completion: could not check npm for the latest version (${report.latestError})\n`,
+    );
+  }
+
+  process.exit(report.level === "warn" ? 1 : 0);
+}
+
+async function main(argv) {
   const [cmd, ...rest] = argv;
 
   if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
@@ -72,6 +101,11 @@ function main(argv) {
     return;
   }
 
+  if (cmd === "doctor") {
+    await doctor(rest);
+    return;
+  }
+
   if (cmd in FILES) {
     emit(cmd);
     return;
@@ -80,4 +114,4 @@ function main(argv) {
   die(`unknown command: ${cmd}\n\n${USAGE}`);
 }
 
-main(process.argv.slice(2));
+main(process.argv.slice(2)).catch((err) => die(err.message));