@kolatts/pncli 2.0.0 → 4.0.0

package/dist/{config-YHYQTGKT.js → config-JGBUUXQX.js}

@@ -9,7 +9,7 @@ import {
   setRepoConfigValue,
   writeGlobalConfig,
   writeRepoConfig
-} from "./chunk-PXKUQPPF.js";
+} from "./chunk-LH7WBP7W.js";
 export {
   getGlobalConfigPath,
   loadConfig,
@@ -21,4 +21,4 @@ export {
   writeGlobalConfig,
   writeRepoConfig
 };
-//# sourceMappingURL=config-YHYQTGKT.js.map
+//# sourceMappingURL=config-JGBUUXQX.js.map

package/dist/{http-6QJU2SWP.js → http-44W5CSDF.js}

@@ -2,10 +2,10 @@
 import {
   HttpClient,
   createHttpClient
-} from "./chunk-ZDJYOI3W.js";
+} from "./chunk-7MFRRV5V.js";
 import "./chunk-HZF6WQPU.js";
 export {
   HttpClient,
   createHttpClient
 };
-//# sourceMappingURL=http-6QJU2SWP.js.map
+//# sourceMappingURL=http-44W5CSDF.js.map

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@kolatts/pncli",
-  "version": "2.0.0",
-  "description": "The Paperwork Nightmare CLI — One command does what three meetings couldn't.",
+  "version": "4.0.0",
+  "description": "The Paperwork Nightmare CLI — structured JSON access to Jira, Bitbucket, GitHub, Confluence, Azure DevOps, SonarQube, Jenkins, and more, built for AI coding agents. One command does what three meetings couldn't.",
   "type": "module",
   "bin": {
     "pncli": "./dist/cli.js"
   },
   "engines": {
-    "node": ">=22.4"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "build": "tsup",
@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepare": "husky"
+    "sync-readme": "tsx scripts/sync-readme.ts"
   },
   "dependencies": {
     "@inquirer/checkbox": "^5.2.1",
@@ -25,14 +25,14 @@
     "@inquirer/password": "^5.0.13",
     "@inquirer/select": "^5.1.5",
     "chalk": "^5.4.1",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "undici": "^8.10.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
     "@typescript-eslint/eslint-plugin": "^8.31.0",
     "@typescript-eslint/parser": "^8.31.0",
     "eslint": "^9.25.1",
-    "husky": "^9.1.7",
     "tsup": "^8.4.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
@@ -45,8 +45,37 @@
     "developer-tools",
     "code-review",
     "agent",
-    "automation"
+    "automation",
+    "ai-agent",
+    "agent-skills",
+    "skills",
+    "claude",
+    "claude-code",
+    "github-copilot",
+    "codex",
+    "github",
+    "confluence",
+    "azure-devops",
+    "sonarqube",
+    "jenkins",
+    "artifactory",
+    "checkmarx",
+    "servicenow",
+    "sdelements",
+    "sonatype",
+    "contrast-security",
+    "openshift",
+    "kubernetes",
+    "dynatrace",
+    "logscale",
+    "figma",
+    "enterprise",
+    "json-cli"
   ],
+  "homepage": "https://kolatts.github.io/pncli/",
+  "bugs": {
+    "url": "https://github.com/kolatts/pncli/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/kolatts/pncli"
@@ -57,7 +86,6 @@
     "skills",
     "LICENSE",
     "NOTICE",
-    "README.md",
-    "copilot-instructions.md"
+    "README.md"
   ]
 }

package/skills/pncli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pncli
-description: Use when asked to set up pncli, configure a service, initialize a repo, or run pncli commands. Walks through identity, work item tracking, source control, and optional services. For any specific service, read the included <service>.md file.
+description: Use when working with enterprise tools through pncli — querying or updating Jira issues, Bitbucket/GitHub/Azure DevOps pull requests, Confluence pages, SonarQube findings, Jenkins builds, ServiceNow records, and more — or when asked to set up pncli, configure a service, or initialize a repo. Walks through identity, work item tracking, source control, and optional services. For any specific service, read the included <service>.md file.
 compatibility: Designed for Claude Code. Requires pncli installed and accessible in PATH.
 user-invocable: true
 metadata:
@@ -9,10 +9,39 @@ metadata:
   services: config
 ---
 
-pncli gives AI agents and humans unified CLI access to enterprise tools: Jira, Bitbucket, Confluence, SonarQube, SDElements, Azure DevOps, Jenkins, Artifactory, Checkmarx, ServiceNow, Contrast Security IAST, Sonatype IQ Server, OpenShift / Kubernetes, Dynatrace, LogScale, and Figma.
+pncli gives AI agents and humans unified CLI access to enterprise tools: Jira, Bitbucket, GitHub, Confluence, SonarQube, SDElements, Azure DevOps, Jenkins, Artifactory, Checkmarx, ServiceNow, Contrast Security IAST, Sonatype IQ Server, OpenShift / Kubernetes, Dynatrace, LogScale, Split.IO, and Figma.
 
 Every service authenticates the same way: a personal access token you generate in that tool's own UI and put in an env var or the config file. If a tool you need is missing from the table below, it is not out of scope by default — pncli covers enterprise tooling broadly, and the only hard requirement is personal-access-token auth.
 
+## Output and errors
+
+All commands return JSON to stdout — parse it rather than scraping text.
+
+- Success: `{ "ok": true, "data": { ... }, "meta": { "service": "...", "action": "...", "timestamp": "...", "duration_ms": N } }`
+- Error: `{ "ok": false, "error": { "status": N, "message": "...", "url": "..." }, "meta": { ... } }` (`url` is null when the failure was not an HTTP call)
+
+Always check `ok` before reading `data`. Errors are JSON too, so a non-zero exit still gives you a structured reason.
+
+Run commands from the repository root — project and repo are auto-detected from git remotes.
+
+## Provider detection
+
+Before running provider-specific commands, establish which tools the repo actually uses:
+
+1. **Work item tracking** — Jira or Azure DevOps? Determines `pncli jira ...` vs `pncli ado work ...`.
+2. **Source control** — GitHub, Bitbucket, or Azure DevOps? Determines `pncli github ...`, `pncli bitbucket ...`, or `pncli ado repo ...`.
+
+Ask the user and cache the answers for the session. If they don't know, run `git remote -v`: a URL containing `/_git/` is Azure DevOps, `/scm/` is Bitbucket, `github.com` (or a GitHub Enterprise host) is GitHub.
+
+## Useful flags
+
+- `--dry-run` — print the API request without executing it
+- `--verbose` — extra progress detail on stderr (stdout stays pure JSON)
+- `--debug` — trace every API call (method, URL, status) on stderr; never logs credentials
+- `--pretty` — human-readable output when running by hand
+- `--output-file <path>` — write JSON to a file instead of stdout; use it for large payloads (search, logs, `--all` pagination) so they don't flood agent context
+- Defaults from `.pncli.json` are applied automatically — you rarely need `--project`, `--repo`, `--type`, or `--priority`
+
 ## Two config levels
 
 **Env vars** — ephemeral, per-session, override the config file. Set before running pncli:
@@ -30,13 +59,32 @@ Repo-level defaults (project key, target branch) are stored in `.pncli.json` in
 pncli config set --repo defaults.<service>.<key> <value>
 ```
 
+## Corporate proxies and TLS
+
+pncli honours the standard proxy variables for every service. Set them before running:
+
+```
+export HTTPS_PROXY=http://proxy.imagile.dev:8080
+export HTTP_PROXY=http://proxy.imagile.dev:8080
+export NO_PROXY=.imagile.dev,localhost,127.0.0.1
+```
+
+`NO_PROXY` exclusions are respected, so self-hosted services on the internal
+network stay direct while SaaS ones route out through the proxy. If a proxy
+variable is set but the proxy cannot be configured, pncli warns on stderr rather
+than silently bypassing it.
+
+TLS verification is **off** by default, because most self-hosted enterprise
+installs sit behind SSL-inspecting proxies that break the certificate chain.
+Set `PNCLI_VERIFY_TLS=1` to turn it back on.
+
 ## Large text fields (descriptions, acceptance criteria)
 
 For commands with long rich-text fields (Jira `create-issue`/`update-issue`, ADO `work create`/`work update`), use `--input-file <path>` (`-` for stdin) instead of pasting a huge string inline — avoids hitting the shell's command-line length limit. The file is a JSON dictionary of field name/id → value; any string value may be `@path/to/file` to pull that field's content from a file instead. Run `pncli <service> schema` (e.g. `pncli jira schema`) to see the exact shape and a runnable example. Individual CLI flags still override matching keys from the file, and the override is reported. See `jira.md` / `ado.md` for details.
 
 ## Available services
 
-For detailed setup of any service, read the included file for that service.
+Each service has its own file in this skill with the config keys and example values for it.
 
 | Service | File | Commands unlocked |
 |---------|------|-------------------|
@@ -52,7 +100,7 @@ For detailed setup of any service, read the included file for that service.
 | Jenkins | `jenkins.md` | Builds, job status |
 | Artifactory | `artifactory.md` | Packages, repos |
 | ServiceNow | `servicenow.md` | Change requests, incidents |
-| Contrast IAST | `contrast.md` | Runtime vulnerability findings |
+| Contrast IAST | `contrast.md` | Runtime vulnerability findings, libraries |
 | Sonatype IQ | `sonatypeiq.md` | Dependency policy enforcement |
 | OpenShift / Kubernetes | `openshift.md` | Pod health, events, logs, metrics |
 | Dynatrace | `dynatrace.md` | Services, entities, problems, traces, Kubernetes workloads |
@@ -61,6 +109,14 @@ For detailed setup of any service, read the included file for that service.
 | Figma | `figma.md` | Design files, comments, version history |
 | Skills Marketplace | `marketplace.md` | Install org-internal skills |
 
+## Installing skills
+
+The skills bundled with pncli install into a repo with `pncli skills install` (default target `.agents/skills/`, which GitHub Copilot and Codex both read; add `--agent claude-code` for `.claude/skills`, or `--all-agents` to cover every agent host in one run). Add `--scope user` to install them globally instead.
+
+Installed skills are a copy — after upgrading pncli, re-run `pncli skills install` to refresh them. `skills list` and `skills status` warn when the installed copy came from a different pncli version.
+
+Org-internal skills come from a git-hosted marketplace: `pncli skills marketplace setup <git-clone-url>` registers one, and `pncli skills marketplace sync` keeps everything installed from it current. `pncli skills status` and `pncli skills locations` show what is installed and where. The full workflow is in the `marketplace.md` file that ships inside the installed skill.
+
 ## Setup walkthrough
 
 **Step 1 — Identity**
@@ -102,3 +158,11 @@ Review results. If any service shows `ok: false`, help troubleshoot the URL or c
 ```
 pncli config show
 ```
+
+**Troubleshooting** — when any command fails unexpectedly, run:
+
+```
+pncli doctor
+```
+
+It reports config-file health, credential validity per service, and skill install state (including stale skills) in one JSON envelope, with a `problems` array listing suggested fixes. Add `--offline` to skip the network checks.

package/skills/pncli/contrast.md

@@ -1,6 +1,6 @@
 # Contrast Security IAST
 
-Enables: `pncli contrast apps`, `pncli contrast findings` — list applications and runtime vulnerability findings from Contrast Security.
+Enables: `pncli contrast apps`, `pncli contrast findings`, `pncli contrast libraries` — list applications, runtime vulnerability findings, and software composition (library) data from Contrast Security.
 
 ## Required config
 

package/skills/pncli/dynatrace.md

@@ -4,6 +4,8 @@ pncli uses Dynatrace's REST APIs directly; no Dynatrace CLI is required.
 
 ## Configuration
 
+### Single environment (legacy)
+
 | Key | Environment variable | Purpose |
 |---|---|---|
 | `dynatrace.baseUrl` | `PNCLI_DYNATRACE_BASE_URL` | Classic environment URL, such as `https://abc12345.live.dynatrace.com` |
@@ -27,8 +29,48 @@ pncli config test
 When platform credentials are present, `config test` and `config check` also run a minimal Grail
 spans query and report it separately as `dynatrace_platform`.
 
+### Multiple named environments
+
+Dynatrace is commonly deployed per-environment (e.g. QA and PROD), each with its own base URL and
+API token. pncli supports named environment profiles so you can switch between them with a flag rather
+than rewriting `dynatrace.baseUrl` and `dynatrace.apiToken` before every command.
+
+```bash
+# Set up named environments
+pncli config set dynatrace.environments.qa.baseUrl https://abc11111.live.dynatrace.com
+pncli config set dynatrace.environments.qa.apiToken dt0c01...
+pncli config set dynatrace.environments.prod.baseUrl https://abc22222.live.dynatrace.com
+pncli config set dynatrace.environments.prod.apiToken dt0c01...
+
+# Optional: include Grail platform credentials per environment
+pncli config set dynatrace.environments.prod.platformUrl https://abc22222.apps.dynatrace.com
+pncli config set dynatrace.environments.prod.platformToken dt0s16...
+
+# Optional: set a default named environment (used when --env is omitted)
+pncli config set dynatrace.defaultEnvironment prod
+```
+
+`config test` and `config check` report the connectivity status of each named environment
+separately as `dynatrace.<name>` (and `dynatrace.<name>_platform` when platform credentials are set).
+
+Environment variables (`PNCLI_DYNATRACE_BASE_URL`, etc.) continue to apply to the legacy flat config
+and take precedence over stored values, but do not override named environments.
+
 ## Commands
 
+```bash
+# Using the default (legacy flat config or defaultEnvironment)
+pncli dynatrace services --from now-2h
+
+# Targeting a named environment
+pncli dynatrace --env qa services --from now-2h
+pncli dynatrace --env prod problems list --from now-24h
+
+# Compare QA and PROD in one session
+pncli dynatrace --env qa entities list --selector 'type("SERVICE")'
+pncli dynatrace --env prod entities list --selector 'type("SERVICE")'
+```
+
 ```bash
 pncli dynatrace services --from now-2h
 pncli dynatrace workloads --from now-2h
@@ -44,3 +86,7 @@ pncli dynatrace trace --id 0123456789abcdef0123456789abcdef
 
 Entity and problem list commands automatically follow Dynatrace pagination. Use Dynatrace selector
 syntax for advanced filtering.
+
+The `--env <name>` option is available on the `dynatrace` parent command and applies to all
+subcommands: `entities list`, `entities get`, `services`, `workloads`, `problems list`,
+`problems get`, and `trace`.

package/skills/pncli/jira.md

@@ -55,5 +55,9 @@ pncli jira create-issue --input-file issue.json --priority Low   # --priority wi
 
 ## Notes
 
-- Jira Cloud and Jira Data Center both work; token format differs (API token vs PAT)
+- Targets **Jira Data Center / Server** (`/rest/api/2`). Jira Cloud is not supported: pncli
+  identifies users by username in the `name` field, where Cloud requires `accountId`. Use
+  Atlassian's own MCP server for Cloud.
+- `--assignee` on `create-issue`, `update-issue`, and `assign` takes a **username**, as does
+  any `user`-typed custom field passed via `--field`
 - Custom fields discovered with `pncli jira fields --discover`

package/skills/pncli/marketplace.md

@@ -26,11 +26,11 @@ pncli skills marketplace list
 pncli skills marketplace plugins <name>
 ```
 
-`list` shows every registered marketplace. `plugins` shows the plugins available inside one of them, without installing anything.
+`list` shows every registered marketplace, including `upstreamRemote` — the `origin` fetch URL read from the local clone, with any injected token scrubbed. It is `null` when the clone is missing or has no `origin`, which is the quickest way to spot a marketplace whose local path has drifted from the URL it was registered with. `plugins` shows the plugins available inside one of them, without installing anything.
 
 ## Sync (pull + install)
 
-Install to `~/.agents/skills` (GitHub Copilot / Codex):
+Install to `~/.agents/skills` (Codex / GitHub Copilot — the default):
 ```
 pncli skills marketplace sync
 ```
@@ -64,6 +64,16 @@ pncli skills marketplace sync --marketplace all
 
 `sync` skips reinstalling when a marketplace has no new upstream changes (single-plugin and `all` installs alike). Pass `--force` to reinstall anyway.
 
+### Update what you already have, without picking up new plugins
+
+By default an `all` sync installs every plugin the marketplace offers, including ones added upstream since you last synced. Pass `--installed-only` to update just the plugins already on disk:
+
+```
+pncli skills marketplace sync --marketplace all --installed-only
+```
+
+Plugins are matched by the marketplace name recorded at install time, falling back to the clone URL — so a marketplace you have since renamed still resolves. Disabled plugins count as installed and are refreshed in place, staying disabled. If a marketplace has no installed plugins at all, it is reported as `skipped` with `installedOnly: true` rather than silently installing everything.
+
 ## Enable / disable installed plugins
 
 Temporarily switch a plugin's skills off without deleting them (no re-download needed to switch back on):
@@ -93,6 +103,47 @@ It loops through a menu until you're done:
 
 Everything the session changed is emitted as one JSON summary at the end. Agents should use the scriptable equivalents instead: `enable`, `disable`, `add`, `remove`.
 
+## Where skills are installed
+
+Every command that installs or reads skills takes `--agent` and `--scope`. Those resolve to:
+
+| `--agent` | `--scope project` | `--scope user` |
+|---|---|---|
+| `codex` (default) | `.agents/skills` | `~/.agents/skills` |
+| `github-copilot` | `.github/skills` | `~/.copilot/skills` |
+| `claude-code` | `.claude/skills` | `~/.claude/skills` |
+
+`.agents/skills` is the cross-tool convention — both Codex and GitHub Copilot read it — which is why it is the default. Use `--agent github-copilot` only when you specifically want Copilot's own directories, and `--agent claude-code` (or the `--claude` shorthand) for Claude Code.
+
+Project-scope paths resolve against the repository root, so you get the same directory whichever subdirectory you run from. Outside a git repository they fall back to the current working directory.
+
+`--target <dir>` overrides all of this and installs wherever you point it. `skills install --target` records the directory in your global config so it still shows up in the commands below; `pncli skills forget-target <dir>` stops tracking it (it deletes nothing).
+
+### List the install paths
+
+```
+pncli skills locations
+```
+
+Reports every path pncli knows about — each agent host at both scopes, plus any recorded custom targets — with whether the directory exists and how many skills are in it. The `marketplaceSkills`, `bundledSkills`, and `untrackedSkills` counts are mutually exclusive and always add up to `totalSkills`; anything in `untrackedSkills` was dropped in by hand or installed before pncli recorded provenance.
+
+`disabledStashMissing` names disabled skills whose stashed copy has been deleted out from under pncli — those cannot be re-enabled and need a fresh `sync`.
+
+### Trace a skill back to its repository
+
+```
+pncli skills status
+```
+
+Walks every known location and emits one record per installed skill joining it to the plugin, marketplace, clone URL, and the live `origin` remote of the local clone. This is the command to reach for when you need to know where a skill actually came from rather than just where it sits.
+
+Narrow it with `--marketplace <name-or-url>`, `--plugin <name>`, `--source marketplace|bundled|untracked`, `--agent`, or `--scope`:
+
+```
+pncli skills status --source untracked
+pncli skills status --marketplace internal-ai
+```
+
 ## Remove a marketplace
 
 ```

package/skills/pncli/openshift.md

@@ -3,13 +3,54 @@
 pncli connects to the OpenShift / Kubernetes REST API using a service account bearer token.
 No `kubectl` or `oc` CLI is required.
 
-## Required config keys
+## Configuration
+
+pncli supports two configuration models for OpenShift clusters, which can be used together:
+
+### Legacy flat config (single cluster)
 
 | Key | Env var | Description |
 |-----|---------|-------------|
 | `openshift.baseUrl` | `PNCLI_OPENSHIFT_BASE_URL` | API server URL, e.g. `https://api.cluster.imagile.dev:6443` |
 | `openshift.token` | `PNCLI_OPENSHIFT_TOKEN` | Service account bearer token |
 
+### Named two-level config (multiple environments and instances)
+
+| Key | Description |
+|-----|-------------|
+| `openshift.environments.<env>.instances.<instance>.baseUrl` | API server URL for this cluster |
+| `openshift.environments.<env>.instances.<instance>.token` | Bearer token for this cluster |
+| `openshift.defaultEnvironment` | Default environment name (used when `--env` is omitted) |
+| `openshift.defaultInstance` | Default instance name (used when `--instance` is omitted) |
+
+Example:
+
+```bash
+pncli config set openshift.environments.non-prod.instances.us-east.baseUrl https://api.np-us-east.imagile.dev:6443
+pncli config set openshift.environments.non-prod.instances.us-east.token eyJhbGciOiJSUzI1NiI...
+pncli config set openshift.environments.non-prod.instances.eu-west.baseUrl https://api.np-eu-west.imagile.dev:6443
+pncli config set openshift.environments.non-prod.instances.eu-west.token eyJhbGciOiJSUzI1NiI...
+pncli config set openshift.environments.prod-us.instances.primary.baseUrl https://api.prod-us.imagile.dev:6443
+pncli config set openshift.environments.prod-us.instances.primary.token eyJhbGciOiJSUzI1NiI...
+
+# Set defaults so --env / --instance can be omitted
+pncli config set openshift.defaultEnvironment non-prod
+pncli config set openshift.defaultInstance us-east
+```
+
+## Selecting a target cluster
+
+All `pncli openshift` subcommands accept `--env` and `--instance` to choose a named cluster:
+
+```bash
+pncli openshift --env non-prod --instance us-east pods --namespace my-namespace
+pncli openshift --env prod-us --instance primary events --namespace my-namespace
+```
+
+If `--env`/`--instance` are omitted, pncli resolves the cluster in this order:
+1. `openshift.defaultEnvironment` + `openshift.defaultInstance`
+2. Legacy flat `openshift.baseUrl` / `openshift.token`
+
 ## Getting your service account token
 
 **Inside a pod** (recommended for CI):
@@ -46,11 +87,21 @@ pncli config init
 
 ## Commands
 
+### List configured clusters
+
+```bash
+pncli openshift cluster list
+```
+
+Returns all configured environments/instances and the flat legacy cluster (if set), plus the
+configured defaults.
+
 ### List pod health summary
 
 ```bash
 pncli openshift pods --namespace my-namespace
 pncli openshift pods --namespace my-namespace --label-selector app=my-app
+pncli openshift --env non-prod --instance us-east pods --namespace my-namespace
 ```
 
 Returns a pre-processed summary with phase counts (running/pending/failed), restart counts,
@@ -62,6 +113,7 @@ CrashLoopBackOff/OOMKilled/ImagePullBackOff indicators, and per-pod container st
 pncli openshift events --namespace my-namespace
 pncli openshift events --namespace my-namespace --field-selector involvedObject.name=my-pod
 pncli openshift events --namespace my-namespace --all   # include Normal events
+pncli openshift --env prod-us --instance primary events --namespace my-namespace
 ```
 
 Returns Warning events sorted by count (highest-frequency first), filtered to surface problems.
@@ -109,9 +161,12 @@ Requires the metrics-server (`GET /apis/metrics.k8s.io/v1beta1/...`) — same as
 ## Test connectivity
 
 ```bash
-pncli config test
+pncli config test    # tests flat config + all named clusters
+pncli config check   # structured status per cluster
 ```
 
+Named clusters appear in `config check` output with keys like `openshift:non-prod/us-east`.
+
 ## Minimum RBAC permissions
 
 The service account needs read access to pods, events, logs, and metrics in the target namespace.