@salesforce/afv-skills 1.46.0 → 1.48.0

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

@@ -0,0 +1,295 @@
+# DevOps Center Project CLI Commands Reference
+
+Complete reference for `sf devops project` CLI commands with JSON output schemas and common patterns.
+
+## Command Summary
+
+| Command | Purpose | Required Flags | Optional Flags |
+|---------|---------|---------------|----------------|
+| `sf devops project list` | List all DevOps Center projects | `--target-org` (`-o`) | `--api-version` |
+| `sf devops project create` | Create a new project | `--target-org` (`-o`), `--name` (`-n`) | `--description` (`-d`), `--api-version` |
+| `sf devops project update` | Update project name, description, or active status | `--target-org` (`-o`), `--project-id` (`-i`), plus at least one of: `--name` (`-n`), `--description` (`-d`), `--is-active` | `--api-version` |
+
+All commands require `--target-org <alias>` (`-o`) unless the `target-org` config var is set, and support `--json` for structured output. `--flags-dir <value>` imports flag values from a directory.
+
+**Org Authentication:**
+Before running any DevOps Center commands, verify org authentication:
+```bash
+sf org display --json
+```
+
+If no default org is set or the user wants to target a specific org, add `--target-org <alias>` to all commands.
+
+---
+
+## List Projects
+
+### Basic Usage
+
+```bash
+sf devops project list --target-org my-devops-org --json
+```
+
+Queries the `DevopsProject` standard object and returns the Id, Name, and Description for each project.
+
+### Example
+
+```bash
+# List projects using an org's username
+sf devops project list --target-org devops-center@example.com --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "projects": [
+      {
+        "Id": "1Qg000000000001",
+        "Name": "Project Alpha",
+        "Description": "Core platform release pipeline"
+      },
+      {
+        "Id": "1Qg000000000002",
+        "Name": "Project Beta",
+        "Description": null
+      }
+    ]
+  }
+}
+```
+
+The project records live under `.result.projects[]` (not a bare `.result[]` array) — every `jq` filter in this skill and its scripts reads that path.
+
+### Key Fields
+
+- `Id`: Salesforce record ID for the project (use with `--project-id` in update and downstream skills)
+- `Name`: Human-readable project name
+- `Description`: Detailed description (may be null/blank)
+
+---
+
+## Create Project
+
+### Required Fields
+
+```bash
+sf devops project create \
+  --target-org my-devops-org \
+  --name "MyApp Release" \
+  --json
+```
+
+### With Optional Description
+
+```bash
+sf devops project create \
+  --target-org my-devops-org \
+  --name "Platform Update" \
+  --description "Platform services update" \
+  --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "Id": "1Qg000000000003",
+    "Name": "Platform Update",
+    "Description": "Platform services update"
+  }
+}
+```
+
+> **Note:** The `create`/`update` single-record `result` shape is representative. The authoritative, verified envelope is `list` (`.result.projects[]` with capitalized `Id`/`Name`/`Description`). To obtain a created/updated project's ID reliably, re-read the list and filter by name rather than depending on the mutation command's own output shape — this is what `scripts/create-project.sh` does.
+
+---
+
+## Update Project
+
+At least one of `--name`, `--description`, or `--is-active` must be provided.
+
+### Update Name
+
+```bash
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --name "MyApp Release v2" \
+  --json
+```
+
+### Update Description
+
+```bash
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --description "Updated release description" \
+  --json
+```
+
+### Activate / Deactivate
+
+```bash
+# Deactivate a project
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --no-is-active \
+  --json
+
+# Activate a project
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --is-active \
+  --json
+```
+
+> **Note:** `--is-active` is a boolean flag. Use `--is-active` to activate or `--no-is-active` to deactivate — never pass a value like `--is-active true`.
+
+### Update Multiple Fields at Once
+
+```bash
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --name "Archived App" \
+  --description "Archived" \
+  --no-is-active \
+  --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "Id": "1Qg000000000001",
+    "Name": "MyApp Release v2",
+    "Description": "Updated release description",
+    "IsActive": true
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Common Error Scenarios
+
+**Project not found (update):**
+```json
+{
+  "status": 1,
+  "name": "NOT_FOUND",
+  "message": "Project with ID 1Qg000000000999 does not exist or is not accessible",
+  "exitCode": 1
+}
+```
+
+**Missing required field (create):**
+```json
+{
+  "status": 1,
+  "name": "RequiredFlagsError",
+  "message": "Missing required flag --name",
+  "exitCode": 1
+}
+```
+
+**Missing update field:**
+```json
+{
+  "status": 1,
+  "name": "RequiredFlagsError",
+  "message": "At least one of --name, --description, or --is-active must be provided",
+  "exitCode": 1
+}
+```
+
+**DevOps Center not enabled / no projects accessible:**
+```json
+{
+  "status": 1,
+  "name": "DEVOPS_NOT_ENABLED",
+  "message": "DevOps Center is not enabled for this org",
+  "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
+}
+```
+
+---
+
+## Parsing JSON Output
+
+Every filter reads the authoritative `.result.projects[]` envelope. To resolve a name to an ID or read back a created project's ID, filter the list by name (see the Idempotent Create Pattern below and `scripts/list-projects.sh --resolve`).
+
+### Check for Empty List
+
+```bash
+COUNT=$(sf devops project list --target-org my-devops-org --json | jq '.result.projects | length')
+
+if [ "$COUNT" -eq 0 ]; then
+  echo "No projects found — create one before setting up work items"
+else
+  echo "Found $COUNT projects"
+fi
+```
+
+### List Project IDs and Names
+
+```bash
+sf devops project list --target-org my-devops-org --json | \
+  jq -r '.result.projects[] | "\(.Id): \(.Name)"'
+
+# Output:
+# 1Qg000000000001: Project Alpha
+# 1Qg000000000002: Project Beta
+```
+
+---
+
+## Idempotent Create Pattern
+
+To avoid duplicate projects, check for an existing project with the same name before creating:
+
+```bash
+NAME="MyApp Release"
+
+# Check if a project with this name exists
+EXISTING_ID=$(sf devops project list --target-org my-devops-org --json | \
+  jq -r ".result.projects[] | select(.Name == \"$NAME\") | .Id" | head -n1)
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Project already exists: $EXISTING_ID"
+else
+  # Create new project, then read the ID back from the list
+  sf devops project create --target-org my-devops-org --name "$NAME" --json >/dev/null
+  NEW_ID=$(sf devops project list --target-org my-devops-org --json | \
+    jq -r ".result.projects[] | select(.Name == \"$NAME\") | .Id" | head -n1)
+  echo "Created new project: $NEW_ID"
+fi
+```
+
+---
+
+## Authentication Requirements
+
+All `sf devops project` commands require an authenticated org (`sf org login web` or JWT), DevOps Center enabled (DOCe provisioned), and permission to manage projects. Verify with `sf org display --target-org <alias> --json`; if auth fails, run `sf org login web --set-default --alias <alias>`.

package/skills/dx-devops-project-manage/scripts/create-project.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Deterministically create a DevOps Center project, idempotently: if a project
+# with the same name already exists, return its ID instead of creating a
+# duplicate. Verifies success by re-reading the project list, so it never
+# depends on the create command's own output envelope.
+# Usage:
+#   scripts/create-project.sh <name> [description] [target-org]
+# Prints "EXISTING <id>" or "CREATED <id>" on success; exits 2 on error.
+
+set -euo pipefail
+
+NAME="${1:?Usage: create-project.sh <name> [description] [target-org]}"
+DESC="${2:-}"
+ORG="${3:-}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Idempotency preflight. list-projects.sh --resolve exits 0 (found), 3 (no such
+# project), or 2 (auth / CLI / JSON failure). Only a clean "not found" (3) is
+# safe to proceed on — any other failure means the list could not be read, so we
+# must abort rather than risk a duplicate or writing to an unreadable org.
+err=$(mktemp); rc=0
+EXISTING=$("$HERE/list-projects.sh" --resolve "$NAME" "$ORG" 2>"$err") || rc=$?
+if [ "$rc" -eq 0 ]; then
+  rm -f "$err"; echo "EXISTING $EXISTING"; exit 0
+elif [ "$rc" -ne 3 ]; then
+  echo "ERROR: idempotency preflight failed (exit $rc); aborting create to avoid a duplicate or writing to an org whose project list could not be read: $(tr '\n' ' ' <"$err")" >&2
+  rm -f "$err"; exit "$rc"
+fi
+rm -f "$err"
+# rc == 3: no existing project with this name — safe to create.
+
+flag=(); [ -n "$ORG" ] && flag=(--target-org "$ORG")
+dflag=(); [ -n "$DESC" ] && dflag=(--description "$DESC")
+
+err=$(mktemp); rc=0
+sf devops project create --name "$NAME" "${dflag[@]+"${dflag[@]}"}" "${flag[@]+"${flag[@]}"}" --json >/dev/null 2>"$err" || rc=$?
+if [ "$rc" -ne 0 ]; then
+  echo "ERROR: project create failed (sf exited $rc): $(tr '\n' ' ' <"$err")" >&2
+  rm -f "$err"; exit 2
+fi
+rm -f "$err"
+
+# Verify by re-reading the list (authoritative .result.projects[] envelope).
+if ID=$("$HERE/list-projects.sh" --resolve "$NAME" "$ORG"); then
+  echo "CREATED $ID"; exit 0
+fi
+echo "ERROR: create reported success but project '$NAME' is not in the project list" >&2
+exit 2

package/skills/dx-devops-project-manage/scripts/list-projects.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Deterministically list DevOps Center projects, or resolve a single project
+# name to its ID. Handles the empty-list case explicitly.
+# Usage:
+#   scripts/list-projects.sh [target-org]
+#       -> print "Id<TAB>Name<TAB>Description" for every project (one per line);
+#          prints "NO_PROJECTS" to stdout and exits 0 when none exist
+#   scripts/list-projects.sh --resolve <project-name> [target-org]
+#       -> print the matching project's Id on stdout; exits 3 if not found
+# Exits 2 on any CLI read / JSON error.
+#
+# project list returns SObject records under .result.projects[] with capitalized
+# fields (Id, Name, Description).
+
+set -euo pipefail
+
+read_projects() {
+  local org="$1" flag=() err rc json st
+  [ -n "$org" ] && flag=(--target-org "$org")
+  err=$(mktemp); rc=0
+  json=$(sf devops project list "${flag[@]+"${flag[@]}"}" --json 2>"$err") || rc=$?
+  if [ "$rc" -ne 0 ]; then
+    echo "ERROR: could not list projects (sf exited $rc): $(tr '\n' ' ' <"$err")" >&2
+    rm -f "$err"; exit 2
+  fi
+  rm -f "$err"
+  st=$(echo "$json" | jq -r '.status // 1' 2>/dev/null || echo 1)
+  if [ "$st" != "0" ]; then
+    local msg; msg=$(echo "$json" | jq -r '.message // "unknown error"' 2>/dev/null || echo "unparseable response")
+    echo "ERROR: 'project list' returned status $st — $msg" >&2; exit 2
+  fi
+  printf '%s' "$json"
+}
+
+if [ "${1:-}" = "--resolve" ]; then
+  NAME="${2:?--resolve needs a project name}"; ORG="${3:-}"
+  JSON=$(read_projects "$ORG")
+  ID=$(echo "$JSON" | jq -r --arg n "$NAME" '.result.projects[]? | select(.Name == $n) | .Id' | head -n1)
+  if [ -z "$ID" ] || [ "$ID" = "null" ]; then
+    echo "ERROR: no project named '$NAME' found" >&2; exit 3
+  fi
+  echo "$ID"; exit 0
+fi
+
+ORG="${1:-}"
+JSON=$(read_projects "$ORG")
+COUNT=$(echo "$JSON" | jq '.result.projects | length')
+if [ "$COUNT" -eq 0 ]; then
+  echo "NO_PROJECTS"; exit 0
+fi
+echo "$JSON" | jq -r '.result.projects[] | "\(.Id)\t\(.Name)\t\(.Description // "")"'

package/skills/dx-devops-project-manage/scripts/update-project.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Deterministically update a DevOps Center project's name, description, and/or
+# active status. Accepts a project ID or a project name (resolved via the list).
+# At least one of --name / --description / --is-active|--no-is-active is required.
+# Usage:
+#   scripts/update-project.sh --project (<id>|name:<name>) \
+#     [--name <new-name>] [--description <new-desc>] \
+#     [--is-active|--no-is-active] [--target-org <alias>]
+# Prints "UPDATED <id>" on success; exits 2 on CLI error, 3 if the name cannot
+# be resolved, 1 on usage error.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT="" NEW_NAME="" NEW_DESC="" ACTIVE="" ORG=""
+have_name=0 have_desc=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) PROJECT="${2:?}"; shift 2 ;;
+    --name) NEW_NAME="${2:?}"; have_name=1; shift 2 ;;
+    --description) NEW_DESC="${2:?}"; have_desc=1; shift 2 ;;
+    --is-active) ACTIVE="true"; shift ;;
+    --no-is-active) ACTIVE="false"; shift ;;
+    --target-org) ORG="${2:?}"; shift 2 ;;
+    *) echo "ERROR: unknown arg '$1'" >&2; exit 1 ;;
+  esac
+done
+
+[ -n "$PROJECT" ] || { echo "ERROR: --project (<id>|name:<name>) is required" >&2; exit 1; }
+if [ "$have_name" -eq 0 ] && [ "$have_desc" -eq 0 ] && [ -z "$ACTIVE" ]; then
+  echo "ERROR: at least one of --name, --description, or --is-active/--no-is-active is required" >&2; exit 1
+fi
+
+# Resolve name:<name> to an ID; otherwise treat as a literal ID. list-projects.sh
+# --resolve exits 3 (no such project) or 2 (auth / CLI / JSON failure); propagate
+# the real code so a failed read is never masked as a clean "not found".
+case "$PROJECT" in
+  name:*)
+    rrc=0
+    PID=$("$HERE/list-projects.sh" --resolve "${PROJECT#name:}" "$ORG") || rrc=$?
+    [ "$rrc" -eq 0 ] || exit "$rrc"
+    ;;
+  *) PID="$PROJECT" ;;
+esac
+
+flag=(); [ -n "$ORG" ] && flag=(--target-org "$ORG")
+args=(--project-id "$PID")
+[ "$have_name" -eq 1 ] && args+=(--name "$NEW_NAME")
+[ "$have_desc" -eq 1 ] && args+=(--description "$NEW_DESC")
+[ "$ACTIVE" = "true" ] && args+=(--is-active)
+[ "$ACTIVE" = "false" ] && args+=(--no-is-active)
+
+err=$(mktemp); rc=0
+sf devops project update "${args[@]}" "${flag[@]+"${flag[@]}"}" --json >/dev/null 2>"$err" || rc=$?
+if [ "$rc" -ne 0 ]; then
+  echo "ERROR: project update failed (sf exited $rc): $(tr '\n' ' ' <"$err")" >&2
+  rm -f "$err"; exit 2
+fi
+rm -f "$err"
+
+# Verify persistence: re-read the project from the authoritative
+# .result.projects[] list envelope and assert each requested field took effect.
+# Never trust the update command's own exit code / output shape alone.
+verr=$(mktemp); vrc=0
+LIST=$(sf devops project list "${flag[@]+"${flag[@]}"}" --json 2>"$verr") || vrc=$?
+if [ "$vrc" -ne 0 ]; then
+  echo "ERROR: update succeeded but the verification re-read failed (sf exited $vrc): $(tr '\n' ' ' <"$verr")" >&2
+  rm -f "$verr"; exit 2
+fi
+rm -f "$verr"
+
+REC=$(echo "$LIST" | jq -c --arg id "$PID" '.result.projects[]? | select(.Id == $id)')
+if [ -z "$REC" ]; then
+  echo "ERROR: update reported success but project '$PID' is not in the project list" >&2; exit 2
+fi
+
+if [ "$have_name" -eq 1 ]; then
+  GOT=$(echo "$REC" | jq -r '.Name')
+  [ "$GOT" = "$NEW_NAME" ] || { echo "ERROR: name not persisted (expected '$NEW_NAME', got '$GOT')" >&2; exit 2; }
+fi
+if [ "$have_desc" -eq 1 ]; then
+  GOT=$(echo "$REC" | jq -r '.Description // ""')
+  [ "$GOT" = "$NEW_DESC" ] || { echo "ERROR: description not persisted (expected '$NEW_DESC', got '$GOT')" >&2; exit 2; }
+fi
+if [ -n "$ACTIVE" ]; then
+  # The list envelope exposes IsActive only on some API versions. Assert it when
+  # present; when absent (null), the field is not verifiable from the list, so we
+  # fall back to the update command's success (already confirmed above) for it.
+  GOT=$(echo "$REC" | jq -r '.IsActive // "absent"')
+  if [ "$GOT" != "absent" ] && [ "$GOT" != "$ACTIVE" ]; then
+    echo "ERROR: active status not persisted (expected '$ACTIVE', got '$GOT')" >&2; exit 2
+  fi
+fi
+
+echo "UPDATED $PID"; exit 0