@salesforce/afv-skills 1.33.0 → 1.35.0

package/skills/dx-devops-pipeline-manage/references/cli-commands.md

@@ -0,0 +1,298 @@
+# DevOps Center Pipeline CLI Commands Reference
+
+Command reference for `sf devops pipeline` and `sf devops stage` — flags and JSON output schemas. For jq parsing snippets, error handling, the idempotent check-before-create pattern, and auth setup, see `references/parsing-patterns.md`.
+
+## Command Summary
+
+| Command | Purpose | Required Flags |
+|---------|---------|---------------|
+| `sf devops pipeline list` | List all pipelines in the org | `--target-org` |
+| `sf devops pipeline get` | Get one pipeline's stages, repos, and connected projects | `--target-org`, `--pipeline-id` |
+| `sf devops pipeline create` | Create a pipeline linked to a Git repo | `--target-org`, `--name`, `--repo` |
+| `sf devops pipeline update` | Activate / deactivate / rename a pipeline | `--target-org`, `--pipeline-id` |
+| `sf devops pipeline stage add` | Insert an empty stage before another stage | `--target-org`, `--pipeline-id`, `--name`, `--next-stage-id` |
+| `sf devops pipeline stage update` | Rename a stage | `--target-org`, `--pipeline-id`, `--stage-id`, `--name` |
+| `sf devops pipeline stage delete` | Delete a stage (auto-relinks neighbors) | `--target-org`, `--pipeline-id`, `--stage-id` |
+| `sf devops pipeline project add` | Attach a project to a pipeline | `--target-org`, `--pipeline-id`, `--project-id` |
+| `sf devops pipeline project delete` | Detach a project from a pipeline | `--target-org`, `--pipeline-id`, `--project-id` |
+| `sf devops stage environment add` | Add a Salesforce environment to a stage | `--target-org`, `--pipeline-id`, `--stage-id`, `--environment-name`, `--org-type` |
+| `sf devops stage environment delete` | Remove an environment (inactive pipeline only) | `--target-org`, `--pipeline-id`, `--environment-id` |
+
+All commands support `--json` for structured output and `--api-version <value>` to override the API version. `--target-org` is not required if the `target-org` config variable is already set.
+
+---
+
+## List Pipelines
+
+```bash
+sf devops pipeline list --target-org my-devops-org --json
+```
+
+Returns all pipelines in the org as **SObject records** under `.result.pipelines[]`, with capitalized fields (`Id`, `Name`, `Description`, `IsActive`). This summary view does **not** include stages or connected projects — use `pipeline get` for those.
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "pipelines": [
+      {
+        "attributes": { "type": "DevopsPipeline", "url": "/services/data/v67.0/sobjects/DevopsPipeline/1PJWt0000007NsjOAE" },
+        "Id": "1PJWt0000007NsjOAE",
+        "Name": "Release Pipeline",
+        "Description": null,
+        "IsActive": false
+      }
+    ]
+  }
+}
+```
+
+Use `.Id` with `--pipeline-id` in follow-on commands.
+
+---
+
+## Get Pipeline Details
+
+```bash
+sf devops pipeline get --target-org my-devops-org --pipeline-id 0XB000000000001 --json
+```
+
+Returns a single pipeline's full detail — its stages, the repo/branch per stage, and connected projects. **This is how you discover stage IDs** needed by `stage add` (`--next-stage-id`), `stage update`/`stage delete` (`--stage-id`), and `stage environment add` (`--stage-id`). Unlike `pipeline list`, `get` uses lowercase camelCase fields (`id`, `name`, `stages`, `connectedProjects`).
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "1PJWt000000HLUfOAO",
+    "name": "Release Pipeline",
+    "description": null,
+    "isActive": true,
+    "stages": [
+      {
+        "id": "1QVWt000000G3huOAC",
+        "name": "Staging",
+        "nextStageId": "1QVWt000000G3htOAC",
+        "branchName": "staging",
+        "repositoryName": "my-new-rep",
+        "repositoryOwner": "ad-shreya",
+        "environment": { "id": "1QeWt0000000i13KAA", "name": "cli-stage" }
+      },
+      {
+        "id": "1QVWt000000G3htOAC",
+        "name": "Production",
+        "nextStageId": null,
+        "branchName": "main",
+        "repositoryName": "my-new-rep",
+        "repositoryOwner": "ad-shreya",
+        "environment": { "id": "1QeWt0000000jDFKAY", "name": "Prod 2" }
+      }
+    ],
+    "connectedProjects": [ { "id": "1QgWt0000000rabKAA", "name": "Release Project 1" } ],
+    "warnings": []
+  }
+}
+```
+
+### Stage Ordering — Linked List, Not an Array Index
+
+Stages form a **linked list** via `nextStageId`, not a numeric `order` field:
+- Each stage's `nextStageId` points to the stage that follows it in the promotion chain.
+- The **terminal stage** (last, typically Production) has `nextStageId: null`.
+- To insert before a given stage with `stage add`, pass that stage's `id` as `--next-stage-id`.
+
+See `references/parsing-patterns.md` for jq snippets that list stage names/IDs, find the terminal stage, and resolve a stage ID by name.
+
+---
+
+## Create Pipeline
+
+A pipeline must be linked to a Git repository at creation.
+
+```bash
+# Existing repo — pass the full URL, nothing else
+sf devops pipeline create --target-org my-devops-org --name "Release Pipeline" \
+  --repo https://github.com/myorg/myrepo --json
+
+# New GitHub repo — requires --repo-owner
+sf devops pipeline create --target-org my-devops-org --name "Release Pipeline" \
+  --repo my-new-repo --create-repo --repo-type github --repo-owner myorg --json
+```
+
+For a **new Bitbucket repo**, swap the provider flags: `--repo-type bitbucket --bitbucket-workspace myworkspace` (plus optional `--bitbucket-project-key PROJ`) in place of `--repo-type github --repo-owner`. Add `--description "<text>"` to any scenario for a pipeline description.
+
+### Required Flags by Scenario
+
+The correct flag set depends on whether the repo already exists and, for new repos, on the provider. Always required: `--name` and `--repo`. `--description` is optional in every scenario.
+
+| Scenario | Required flags | Must NOT include |
+|----------|---------------|------------------|
+| **Existing repo** (GitHub or Bitbucket) | `--name`, `--repo <url>` | `--create-repo`, `--repo-type`, `--repo-owner`, `--bitbucket-*` |
+| **New GitHub repo** | `--name`, `--repo <name>`, `--create-repo`, `--repo-type github`, `--repo-owner <org-or-user>` | `--bitbucket-workspace`, `--bitbucket-project-key` |
+| **New Bitbucket repo** | `--name`, `--repo <name>`, `--create-repo`, `--repo-type bitbucket`, `--bitbucket-workspace <workspace>` | `--repo-owner` |
+
+Per-flag detail:
+
+| Flag | Applies to | Notes |
+|------|-----------|-------|
+| `--name` / `-n` | all | Pipeline name (required) |
+| `--repo` / `-r` | all | Existing repo URL, or a repo name when used with `--create-repo` (required) |
+| `--description` / `-d` | all | Pipeline description (optional) |
+| `--create-repo` | new repo only | Create the repo if it doesn't exist |
+| `--repo-type` | new repo only | `github` or `bitbucket` (required when creating a repo) |
+| `--repo-owner` | **GitHub** new repo | Organization or user that owns the repo (required for GitHub create) |
+| `--bitbucket-workspace` | **Bitbucket** new repo | Workspace that owns the repo (required for Bitbucket create) |
+| `--bitbucket-project-key` | Bitbucket new repo | Optional Bitbucket project key |
+| `--stage` / `-s` | all | Name of a pipeline stage, in promotion order. Repeat once per stage. Defaults to Integration, UAT, Staging, Production |
+
+> **Provider mismatch fails:** pairing `--repo-owner` with `--repo-type bitbucket`, or `--bitbucket-workspace` with `--repo-type github`, is rejected. Match the provider flag to `--repo-type`.
+
+### Custom Stage Names at Create Time
+
+By default a new pipeline seeds the stage chain **Integration → UAT → Staging → Production**. To seed a different chain, repeat `--stage` once per stage in promotion order:
+
+```bash
+sf devops pipeline create \
+  --target-org my-devops-org \
+  --name "Release Pipeline" \
+  --repo https://github.com/myorg/myrepo \
+  --stage Dev --stage QA --stage Prod \
+  --json
+```
+
+Seeding stages at create time avoids a separate round of `stage add` / `stage update` calls afterward.
+
+After creating, resolve the new pipeline's ID by name from `sf devops pipeline list --json` (see `references/parsing-patterns.md`) — this avoids depending on the exact shape of the create response. A new pipeline always starts with at least one stage (the default chain, or your `--stage` list) — run `sf devops pipeline get` to see the seeded stages, then add or rename stages if you need to adjust the chain.
+
+---
+
+## Update Pipeline (Activate / Deactivate / Rename)
+
+```bash
+# Activate — requires at least one stage
+sf devops pipeline update --pipeline-id 0XB000000000001 --activate --json
+
+# Deactivate
+sf devops pipeline update --pipeline-id 0XB000000000001 --deactivate --json
+
+# Rename
+sf devops pipeline update --pipeline-id 0XB000000000001 --name "My Pipeline" --json
+
+# Deactivate and rename in one step
+sf devops pipeline update --pipeline-id 0XB000000000001 --deactivate --name "My Pipeline" --json
+```
+
+| Flag | Notes |
+|------|-------|
+| `--pipeline-id` | Required — ID of the pipeline to update |
+| `--activate` | Activate the pipeline. Mutually exclusive with `--deactivate` |
+| `--deactivate` | Deactivate the pipeline. Mutually exclusive with `--activate` |
+| `--name` / `-n` | New name for the pipeline. Can be combined with `--deactivate` |
+
+- A pipeline must have **at least one stage** before it can be activated.
+- `--activate` and `--deactivate` cannot be used together; `--deactivate` and `--name` may be combined in one command.
+- **You can't modify pipeline stages after you activate and promote changes through it.** Finish all stage/environment configuration before activating.
+
+---
+
+## Add a Stage
+
+Inserts an **empty** stage (no branch or environment) immediately before `--next-stage-id`. Configure its environment separately afterward.
+
+```bash
+# Add a Development stage before Integration
+sf devops pipeline stage add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --name "Development" \
+  --next-stage-id 0Xc000000000001 \
+  --json
+```
+
+Get the `--next-stage-id` from `sf devops pipeline get`. The new stage is always inserted **immediately before** the anchor stage you pass as `--next-stage-id` — there is no append-to-end flag. To place a stage at a given point in the chain, choose the anchor that should follow it (e.g. anchor to the terminal stage to insert the new stage just before it).
+
+---
+
+## Rename / Delete a Stage
+
+```bash
+# Rename a stage
+sf devops pipeline stage update \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xc000000000002 \
+  --name "QA" \
+  --json
+
+# Delete a stage — the predecessor auto-relinks to the successor so the chain stays intact
+sf devops pipeline stage delete \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xc000000000002 \
+  --json
+```
+
+---
+
+## Add an Environment to a Stage
+
+```bash
+sf devops stage environment add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xp000000000001 \
+  --environment-name Production_Org \
+  --org-type Production \
+  --json
+```
+
+| Flag | Required | Notes |
+|------|----------|-------|
+| `--pipeline-id` | Required | Pipeline containing the stage |
+| `--stage-id` | Required | Target stage (from `pipeline get`) |
+| `--environment-name` / `-e` | Required | Environment name |
+| `--org-type` | Required | Exactly `Production` or `Sandbox` |
+| `--no-browser` | Optional | Don't auto-open a browser for OAuth; prints the redirect URL instead |
+
+> **Headless caveat:** This command triggers an OAuth flow and opens a browser by default. In CI or headless runs, pass `--no-browser` and complete authentication via the printed redirect URL.
+
+---
+
+## Delete an Environment from a Stage
+
+The pipeline must be **inactive** before you can delete an environment.
+
+```bash
+sf devops stage environment delete \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --environment-id 0Xe000000000001 \
+  --json
+```
+
+`--pipeline-id` is used to verify the pipeline is inactive before deleting.
+
+---
+
+## Attach / Detach a Project
+
+A project can be attached to **only one pipeline**.
+
+```bash
+# Attach
+sf devops pipeline project add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --project-id 0Hn000000000001 \
+  --json
+
+# Detach — deletes only the junction record; the project itself is not deleted
+sf devops pipeline project delete \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --project-id 0Hn000000000001 \
+  --json
+```
+
+Resolve a project ID from its name via `sf devops project list --json` — see `references/parsing-patterns.md` for the jq snippet.

package/skills/dx-devops-pipeline-manage/references/parsing-patterns.md

@@ -0,0 +1,134 @@
+# DevOps Center Pipeline — Parsing, Errors & Auth
+
+jq snippets for parsing `sf devops` JSON output, error-handling reference, the idempotent check-before-create pattern, and authentication requirements. For command flags and JSON schemas, see `references/cli-commands.md`.
+
+## Parsing Stage Chains
+
+Stages form a linked list via `nextStageId` (see the schema in `references/cli-commands.md`). Use these snippets against `pipeline get`:
+
+```bash
+# List stage names and IDs with their next pointer
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
+
+# Find the terminal stage ID (nextStageId is null)
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | select(.nextStageId == null) | .id'
+
+# Find a stage ID by name (e.g. to anchor an insert before "Production")
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | select(.name == "Production") | .id'
+```
+
+---
+
+## Resolve a Pipeline ID by Name
+
+`pipeline list` is the reliable way to turn a pipeline name into an ID (note the `.pipelines[]` wrapper and capitalized `Name`/`Id`):
+
+```bash
+PIPELINE_ID=$(sf devops pipeline list --json | \
+  jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
+echo "Pipeline: $PIPELINE_ID"
+```
+
+### List Pipelines (name, ID, active state)
+
+`pipeline list` does not carry stages — to show the stage chain, feed each ID into `pipeline get`:
+
+```bash
+sf devops pipeline list --json | \
+  jq -r '.result.pipelines[] | "\(.Name) [\(.IsActive)] (\(.Id))"'
+# Release Pipeline [true] (1PJWt000000HLUfOAO)
+```
+
+---
+
+## Resolve a Project ID by Name
+
+`project list` returns SObject records under `.result.projects[]` with capitalized fields (`Id`, `Name`):
+
+```bash
+sf devops project list --json | jq -r '.result.projects[] | "\(.Id): \(.Name)"'
+
+# Extract a specific project ID by name
+sf devops project list --json | \
+  jq -r '.result.projects[] | select(.Name == "Release Project 1") | .Id'
+```
+
+---
+
+## Idempotent Create (Check-Before-Create)
+
+The CLI does not dedupe pipelines. Check for an existing pipeline before creating:
+
+```bash
+PIPELINE_NAME="Release Pipeline"
+
+EXISTING_ID=$(sf devops pipeline list --json | \
+  jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Pipeline already exists: $EXISTING_ID"
+else
+  sf devops pipeline create \
+    --name "$PIPELINE_NAME" \
+    --repo https://github.com/myorg/myrepo \
+    --json
+  NEW_ID=$(sf devops pipeline list --json | \
+    jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)
+  echo "Created new pipeline: $NEW_ID"
+fi
+```
+
+---
+
+## Error Handling
+
+**Missing required repo (create):**
+```json
+{ "status": 1, "name": "RequiredFlagsError", "message": "Missing required flag --repo", "exitCode": 1 }
+```
+
+**Pipeline not found:**
+```json
+{ "status": 1, "name": "NOT_FOUND", "message": "Pipeline 0XB000000000999 does not exist or is not accessible", "exitCode": 1 }
+```
+
+**Activation without a stage:**
+```json
+{ "status": 1, "name": "NO_STAGES", "message": "A pipeline must have at least one stage before you can activate it", "exitCode": 1 }
+```
+
+**Environment delete on active pipeline:**
+```json
+{ "status": 1, "name": "PIPELINE_ACTIVE", "message": "The environment must belong to an inactive pipeline", "exitCode": 1 }
+```
+
+**Project already attached:**
+```json
+{ "status": 1, "name": "PROJECT_ALREADY_ATTACHED", "message": "You can attach a project to only one pipeline", "exitCode": 1 }
+```
+
+**Authentication failure:**
+```json
+{ "status": 1, "name": "NoOrgFound", "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.", "exitCode": 1 }
+```
+
+> **Note:** Error `name`/`message` strings are representative — match on the non-zero `status` and the substring of `message`, not exact strings.
+
+---
+
+## Authentication Requirements
+
+All `sf devops pipeline` / `sf devops stage` commands require:
+
+1. **Authenticated org**: `sf org login web` or JWT auth
+2. **DevOps Center enabled**: org must have DOCe provisioned
+3. **Appropriate permissions**: access to the pipeline, its stages, and connected environments
+
+```bash
+sf org display --target-org <alias> --json
+```
+
+If auth fails: `sf org login web --set-default --alias <alias>`.

package/skills/dx-devops-pipeline-manage/scripts/check-activation-ready.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Check the deterministic activation prerequisite: a pipeline must have >=1 stage
+# before `sf devops pipeline update --activate` will succeed.
+# Usage: scripts/check-activation-ready.sh <pipeline-id> [target-org-alias]
+# Exits 0 if the pipeline has at least one stage; otherwise prints an actionable
+# error and exits 1. Exits 2 if the pipeline can't be read.
+
+set -euo pipefail
+
+PIPELINE_ID="${1:?Usage: check-activation-ready.sh <pipeline-id> [target-org-alias]}"
+TARGET_ORG="${2:-}"
+
+ORG_FLAG=()
+[ -n "$TARGET_ORG" ] && ORG_FLAG=(--target-org "$TARGET_ORG")
+
+GET_JSON=$(sf devops pipeline get --pipeline-id "$PIPELINE_ID" "${ORG_FLAG[@]+"${ORG_FLAG[@]}"}" --json 2>/dev/null) || {
+  echo "ERROR: could not read pipeline '$PIPELINE_ID'. Verify the ID with 'sf devops pipeline list --json' and that the org has DevOps Center enabled." >&2
+  exit 2
+}
+
+STATUS=$(echo "$GET_JSON" | jq -r '.status // 1')
+if [ "$STATUS" != "0" ]; then
+  echo "ERROR: 'pipeline get' returned status $STATUS for '$PIPELINE_ID'." >&2
+  exit 2
+fi
+
+STAGE_COUNT=$(echo "$GET_JSON" | jq -r '(.result.stages // []) | length')
+if [ "$STAGE_COUNT" -ge 1 ]; then
+  echo "OK: pipeline '$PIPELINE_ID' has $STAGE_COUNT stage(s) — ready to activate"
+  exit 0
+fi
+
+echo "ERROR: pipeline '$PIPELINE_ID' has no stages. Add at least one stage (sf devops pipeline stage add ...) before --activate." >&2
+exit 1

package/skills/dx-devops-pipeline-manage/scripts/validate-org-type.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Validate a stage-environment --org-type value against the fixed CLI enum.
+# Usage: scripts/validate-org-type.sh <org-type>
+# Exits 0 if the value is exactly "Production" or "Sandbox"; otherwise prints
+# an actionable error and exits 1.
+
+set -euo pipefail
+
+ORG_TYPE="${1:-}"
+
+if [ "$ORG_TYPE" = "Production" ] || [ "$ORG_TYPE" = "Sandbox" ]; then
+  echo "OK: --org-type '$ORG_TYPE' is valid"
+  exit 0
+fi
+
+echo "ERROR: --org-type must be exactly 'Production' or 'Sandbox' (case-sensitive). Got: '${ORG_TYPE}'" >&2
+exit 1

package/skills/dx-devops-pipeline-manage/scripts/verify-operation.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Deterministically verify the result of a pipeline operation by checking the
+# command's JSON status and the relevant post-state fields from `pipeline get`.
+# Usage:
+#   scripts/verify-operation.sh status <json-file-or-'-'>
+#       -> assert the captured CLI JSON has .status == 0
+#   scripts/verify-operation.sh active <pipeline-id> <true|false> [target-org]
+#       -> assert .result.isActive matches the expected boolean
+#   scripts/verify-operation.sh has-stage <pipeline-id> <stage-name> [target-org]
+#       -> assert a stage with that name exists in the chain
+#   scripts/verify-operation.sh has-project <pipeline-id> <project-name> [target-org]
+#       -> assert a connected project with that name exists
+# Exits 0 when the assertion holds; prints an actionable error and exits 1 otherwise.
+
+set -euo pipefail
+
+MODE="${1:?Usage: verify-operation.sh <status|active|has-stage|has-project> ...}"
+
+# Read a pipeline once and hand back validated JSON on stdout. Distinguishes a
+# failed CLI read / non-zero JSON status from a successful read (whose fields the
+# caller then evaluates), so post-state checks never mistake a read failure for a
+# "not found" result. Exits 2 with an actionable message on any read/JSON error.
+GET_JSON=""
+read_pipeline() {
+  local pid="$1" org="$2"
+  local flag=() err rc
+  [ -n "$org" ] && flag=(--target-org "$org")
+  # Capture stdout and stderr separately; do not let pipefail abort silently.
+  err=$(mktemp)
+  rc=0
+  GET_JSON=$(sf devops pipeline get --pipeline-id "$pid" "${flag[@]+"${flag[@]}"}" --json 2>"$err") || rc=$?
+  if [ "$rc" -ne 0 ]; then
+    echo "ERROR: could not read pipeline '$pid' (sf exited $rc): $(tr '\n' ' ' <"$err")" >&2
+    rm -f "$err"; exit 2
+  fi
+  rm -f "$err"
+  local st
+  st=$(echo "$GET_JSON" | jq -r '.status // 1' 2>/dev/null || echo 1)
+  if [ "$st" != "0" ]; then
+    local msg
+    msg=$(echo "$GET_JSON" | jq -r '.message // "unknown error"' 2>/dev/null || echo "unparseable response")
+    echo "ERROR: 'pipeline get' for '$pid' returned status $st — $msg" >&2
+    exit 2
+  fi
+}
+
+case "$MODE" in
+  status)
+    SRC="${2:?status mode needs a JSON file path or '-' for stdin}"
+    JSON=$([ "$SRC" = "-" ] && cat || cat "$SRC")
+    ST=$(echo "$JSON" | jq -r '.status // 1')
+    if [ "$ST" = "0" ]; then echo "OK: command status 0"; exit 0; fi
+    MSG=$(echo "$JSON" | jq -r '.message // "unknown error"')
+    echo "ERROR: command returned status $ST — $MSG" >&2; exit 1
+    ;;
+  active)
+    PID="${2:?}"; WANT="${3:?expected true|false}"; ORG="${4:-}"
+    read_pipeline "$PID" "$ORG"   # exits 2 on read/JSON error before we evaluate fields
+    GOT=$(echo "$GET_JSON" | jq -r '.result.isActive')
+    if [ "$GOT" = "$WANT" ]; then echo "OK: isActive == $WANT"; exit 0; fi
+    echo "ERROR: expected isActive=$WANT but pipeline '$PID' reports isActive=$GOT" >&2; exit 1
+    ;;
+  has-stage)
+    PID="${2:?}"; NAME="${3:?stage name}"; ORG="${4:-}"
+    read_pipeline "$PID" "$ORG"
+    if echo "$GET_JSON" | jq -e --arg n "$NAME" '.result.stages[]? | select(.name == $n)' >/dev/null; then
+      echo "OK: stage '$NAME' present"; exit 0
+    fi
+    echo "ERROR: stage '$NAME' not found in pipeline '$PID'" >&2; exit 1
+    ;;
+  has-project)
+    PID="${2:?}"; NAME="${3:?project name}"; ORG="${4:-}"
+    read_pipeline "$PID" "$ORG"
+    if echo "$GET_JSON" | jq -e --arg n "$NAME" '.result.connectedProjects[]? | select(.name == $n)' >/dev/null; then
+      echo "OK: project '$NAME' connected"; exit 0
+    fi
+    echo "ERROR: project '$NAME' not connected to pipeline '$PID'" >&2; exit 1
+    ;;
+  *)
+    echo "ERROR: unknown mode '$MODE' (expected status|active|has-stage|has-project)" >&2; exit 1
+    ;;
+esac