postman-cli-completion 1.39.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,145 @@
+# postman-cli-completion
+
+Shell completion scripts for the [Postman CLI](https://learning.postman.com/docs/postman-cli/postman-cli-overview/) (`postman`) on **zsh**, **bash**, and **fish**.
+
+Completes:
+
+- All top-level commands (`login`, `collection`, `spec`, `monitor`, `workspace`, `flows`, etc.) and their subcommands.
+- Flags for each (sub)command.
+- Local file arguments such as `*.json` (collections, manifests) and `*.yaml`/`*.yml` (specs, simulate scenarios).
+
+Dynamic completion of remote IDs (collection / workspace / monitor IDs) is **not** supported — paste those yourself.
+
+## Install
+
+### Via npm (recommended)
+
+```sh
+npm install -g postman-cli-completion
+```
+
+This installs a `postman-completion` helper command — it does **not** shadow the real
+`postman` CLI (install that separately via `npm i -g postman-cli`). The helper prints the
+completion script for your shell to stdout; wire it in as follows.
+
+**zsh** — quick test in the current shell (requires `compinit` already initialised, see
+the note below):
+
+```sh
+source <(postman-completion zsh)
+```
+
+**zsh** — persistent. Add the packaged completions dir to `fpath` in `~/.zshrc`:
+
+```sh
+fpath=("$(postman-completion path zsh --dir)" $fpath)
+autoload -Uz compinit && compinit
+```
+
+**bash** — add to `~/.bashrc` (requires bash 4+; see the bash note below):
+
+```sh
+source <(postman-completion bash)
+```
+
+**fish** — source it in the current session, or install it persistently:
+
+```sh
+postman-completion fish | source
+# persistent:
+ln -sf "$(postman-completion path fish)" ~/.config/fish/completions/postman.fish
+```
+
+### From source
+
+Clone this repo somewhere, e.g. `~/.postman-cli-completion`:
+
+```sh
+git clone https://github.com/yokawasa/postman-cli-completion.git ~/.postman-cli-completion
+```
+
+### zsh
+
+Add the completions directory to `fpath` and rerun `compinit`. Put this in `~/.zshrc`:
+
+```sh
+fpath=(~/.postman-cli-completion/completions/zsh $fpath)
+autoload -Uz compinit && compinit
+```
+
+Or, for a quick test in the current shell:
+
+```sh
+source ~/.postman-cli-completion/completions/zsh/_postman
+```
+
+> **Note:** `compinit` must already be initialised in your shell for `source` to register the completion. Most zsh setups (oh-my-zsh, prezto, or a plain `.zshrc` that runs `autoload -Uz compinit && compinit`) do this automatically. If `postman <TAB>` still does nothing after sourcing, run `autoload -Uz compinit && compinit` first and try again.
+
+### bash
+
+Add to `~/.bashrc` (or `~/.bash_profile` on macOS):
+
+```sh
+source ~/.postman-cli-completion/completions/bash/postman.bash
+```
+
+Requires bash 4+ (`shopt -s extglob`). On macOS the system bash is 3.2 — install a newer bash via Homebrew (`brew install bash`) if needed.
+
+### fish
+
+Copy or symlink into fish's completion directory:
+
+```sh
+ln -s ~/.postman-cli-completion/completions/fish/postman.fish \
+      ~/.config/fish/completions/postman.fish
+```
+
+Or source it in the current session:
+
+```sh
+source ~/.postman-cli-completion/completions/fish/postman.fish
+```
+
+## Verify (manual checklist)
+
+After installing for your shell, open a fresh terminal and check each:
+
+| Input | Expected |
+| --- | --- |
+| `postman <TAB>` | All top-level commands appear |
+| `postman col<TAB>` | Completes to `collection` |
+| `postman collection <TAB>` | `migrate`, `lint`, `run` |
+| `postman collection run <TAB>` | `*.json` files in the current directory |
+| `postman collection run --<TAB>` | Flag list (`--environment`, `--iteration-data`, `--reporters`, …) |
+| `postman collection run -r <TAB>` | `cli`, `json`, `junit`, `html` |
+| `postman request <TAB>` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` |
+| `postman spec lint <TAB>` | `*.yaml` / `*.yml` / `*.json` files |
+| `postman flows <TAB>` | `list`, `trigger`, `deploy`, `run`, `update`, `list-runs`, `get-run` |
+| `postman --<TAB>` | `--silent`, `--color`, `--version`, `--help` |
+
+## 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:
+
+- **`catchup.yml`** runs daily, queries npm for the latest `postman-cli` version, introspects its `--help` surface, regenerates the spec and the three completion scripts, and opens an auto-merging PR whenever something changed.
+- **`release.yml`** fires when `spec/commands.json` lands on `main` and publishes a matching GitHub Release (e.g. tag `v1.39.0` mirrors Postman CLI 1.39.0).
+
+So this repo follows the latest published Postman CLI version automatically — pull the latest `main` (or grab the matching tag) and the completions will match whatever Postman CLI version you have installed.
+
+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:
+
+```sh
+postman --version
+```
+
+## License
+
+[MIT](./LICENSE) — see the LICENSE file.

package/bin/postman-completion.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 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).
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const FILES = {
+  zsh: resolve(PKG_ROOT, "completions/zsh/_postman"),
+  bash: resolve(PKG_ROOT, "completions/bash/postman.bash"),
+  fish: resolve(PKG_ROOT, "completions/fish/postman.fish"),
+};
+
+const USAGE = `postman-completion — shell completions for the Postman CLI
+
+Note: this installs the command "postman-completion"; it does NOT shadow the
+real "postman" CLI (install that separately via "npm i -g postman-cli").
+
+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 --help                   Show this help
+
+Wire it into your shell:
+
+  # bash — add to ~/.bashrc (requires bash 4+)
+  source <(postman-completion bash)
+
+  # zsh — quick test in the current shell (compinit must be initialised)
+  source <(postman-completion zsh)
+
+  # zsh — persistent, add to ~/.zshrc
+  fpath=("$(postman-completion path zsh --dir)" $fpath)
+  autoload -Uz compinit && compinit
+
+  # fish — in the current session
+  postman-completion fish | source
+`;
+
+function die(message) {
+  process.stderr.write(`postman-completion: ${message}\n`);
+  process.exit(1);
+}
+
+function emit(shell) {
+  const file = FILES[shell];
+  if (!file) die(`unknown shell: ${shell} (expected zsh, bash, or fish)`);
+  process.stdout.write(readFileSync(file, "utf8"));
+}
+
+function printPath(args) {
+  const dirOnly = args.includes("--dir");
+  const shell = args.find((a) => a !== "--dir");
+  const file = FILES[shell];
+  if (!file) die(`unknown shell: ${shell ?? "(none)"} (expected zsh, bash, or fish)`);
+  process.stdout.write(`${dirOnly ? dirname(file) : file}\n`);
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    process.stdout.write(USAGE);
+    return;
+  }
+
+  if (cmd === "path") {
+    printPath(rest);
+    return;
+  }
+
+  if (cmd in FILES) {
+    emit(cmd);
+    return;
+  }
+
+  die(`unknown command: ${cmd}\n\n${USAGE}`);
+}
+
+main(process.argv.slice(2));