@salesforce/afv-skills 1.62.0 → 1.64.0

package/skills/dx-lifecycle-center/references/error-handling.md

@@ -0,0 +1,21 @@
+# Simple Deploy Error Handling
+
+Connect errors arrive as `CODE:message`. Read the code, explain the cause in plain language, state the fix, and stop. Never retry in a loop and never fabricate a `requestId` or result.
+
+| Code / symptom | Cause | Fix |
+|---|---|---|
+| 403 / no access | User lacks `userHasDevopsSimpleDeployApiAccess`. | Ask an admin for DX Inspector deploy access. |
+| `TARGET_ORG_NAMED_CREDENTIAL_NOT_AUTHENTICATED` | Named credential exists but OAuth was never completed. | Complete the OAuth flow for the environment (`connect-org.md`), then retry. |
+| `TARGET_ORG_SESSION_EXPIRED` | Credential returned 401 or 403. | Reconnect the target org (`connect-org.md`), then retry. |
+| `DEPLOY_TARGET_ORG_CONNECTION_FAILED` with `Bad_OAuth_Token` | The environment's stored OAuth token is stale or revoked (seen live). | Reconnect that environment (`connect-org.md`); try another environment only if the user asks. |
+| `DEPLOY_TARGET_ORG_CONNECTION_FAILED` with an HTML error page | The target org is gone or unreachable (for example an expired scratch org; seen live). The message carries a full HTML page. | Say the target org is unreachable or expired. Do not paste the HTML. |
+| `DEPLOY_TARGET_ORG_CONNECTION_FAILED` | Credential service or target unreachable, or "Target environment does not match the named credential". | Re-resolve the pair from the same `DevopsEnvironment` row (`list-orgs.md`). |
+| `VALIDATION_REQUIRES_METADATA` | Validate run with no `changes`. | Add at least one metadata component. |
+| `QUICK_DEPLOY_NOT_AVAILABLE` / `QUICK_DEPLOY_NOT_DEPLOYABLE` | No successful, still-valid validation for this target. | Re-run validate, then quick deploy the new `0Af` id. |
+| `QUICK_DEPLOY_ALREADY_DONE` / `QUICK_DEPLOY_ALREADY_IN_PROGRESS` | The validation was already used or is running. | Check status of the earlier request instead. |
+| `QUICK_DEPLOY_VALIDATE_ONLY_MUTUALLY_EXCLUSIVE` | Both `isCheckDeploy` and `isQuickDeploy` set. | Send only one. |
+| `VALIDATE_QUICK_DEPLOY_FEATURE_NOT_ENABLED` | Validate/quick deploy kill switch is closed. | Use a plain deploy, or ask the platform team. |
+| 400 with a Zod message | cliaas schema rule (see `request-body.md`): blank `fullName`/`type`/`operation`, bad `testOptions`, `changes` with quick deploy, bad `0Af` id. | Fix the named field and resubmit once. |
+| `DEPLOY_UNKNOWN_ERROR` | Unexpected server error. | Report the message; do not retry blindly. |
+| Status `FAILED` (or `DevopsRequestInfo` `ERROR`) | Deploy ran and failed. | Show the failed `step` and the reason: `errorDetail` (component and test failures, coverage shortfall) when present, else `activityMessage`. Details in `deploy.md`, Step 7. |
+| Status `NOT_FOUND` | Unknown id, or older than ~2 days. | Confirm the id; resubmit only if the user asks. |

package/skills/dx-lifecycle-center/references/hub-org.md

@@ -0,0 +1,37 @@
+# Lifecycle Center org (Operation C)
+
+The **Lifecycle Center org** is the Lifecycle Center hub that DX Inspector connects to. Its credential is named exactly `ALMDevOpsCenterHub` (case-sensitive). It is a separate connection from the deploy targets.
+
+Three rules always hold:
+
+1. It is **never a deploy target**.
+2. It **never appears in a list** and is not mentioned while listing, whether or not it is connected. It is discussed only when the user asks about it by name.
+3. Its credential is **never used to deploy**.
+
+## Hub names
+
+Make two normalized forms of the request, both lowercase. The **word form** turns hyphens, underscores, and other punctuation into single spaces and splits camel case ("LifecycleCenter" becomes "lifecycle center"). The **compact form** also drops every space. Then "Lifecycle Center org", "lifecycle-center", "lifecycle_center", "LifecycleCenter org", and "lifecyclecenter" all read the same. Work through these in order:
+
+1. **Never a hub name:** "Dev Hub" in any form (including "Dev Hub org"; it is the Salesforce Dev Hub), and plural or general phrases such as "DevOps Center orgs", "DevOps Center environments", or "orgs connected to DevOps Center". These are ordinary requests: route them by rules 2 to 5 in `SKILL.md`.
+2. **Certain:** the compact form contains `lifecyclecenter`, `lifecyclecentre`, `almdevopscenterhub`, or `devopscenterhub`, and the name is used as an org: it stands alone or is followed by "org", "hub", "connection", "credential", or "status". This covers "connect to lifecycle center", "is lifecyclecenter org connected", "Lifecycle Center hub", "life cycle center", and `ALMDevOpsCenterHub`. Treat the request as Operation C with no clarifying question, even with extra words around it. If the name is followed by another word that makes it a longer name ("LifecycleCenterService", "lifecycle center controller"), it is a component name, not the org.
+3. **Ambiguous:** the word form contains, as whole words, "hub org", "the hub", "doce hub", or "devops center org" (not followed by "s", "list", or letters that make a longer word, so "organizations" is not a match), or a standalone word "hub" that is not part of "dev hub", or any longer word that ends in "hub". Treat the request as Operation C only after the user confirms (see the first row below).
+
+Run this check **before** the other routing rules.
+
+## What to do
+
+| The request | Do |
+|---|---|
+| Connect, reconnect, repair, log in to, or authorize the Lifecycle Center org | 1. If the name is in the ambiguous group, ask: "Do you mean the Lifecycle Center org (the Lifecycle Center hub)?" On no, ask which org they mean and treat it as a normal org (Operation B). 2. On yes, or for a certain name, check the credential (`connect-org.md`, Step 0, hub mode). 3. **Configured:** reply only "The Lifecycle Center org is already configured." and stop. No reconnect offer, org details, or login link. 4. **Not configured, or half-created:** run `connect-org.md` Steps 1 to 5 in hub mode, using its sign-in layout (Step 2) and connected layout (Step 5). |
+| Ask whether the Lifecycle Center org is connected or configured | Check the credential the same way. Configured: reply only "The Lifecycle Center org is already configured." Not configured: reply "The Lifecycle Center org is not configured. Want me to connect it?" |
+| Deploy, validate, or quick deploy to the Lifecycle Center org | Make no API call. Ask: "Do you mean the Lifecycle Center org, or a different org?" A different org: ask which and continue at `deploy.md`, Step 2. The Lifecycle Center org: say a deploy cannot go there because it is the Lifecycle Center hub, not a deploy target, and offer to connect that org, or another one, as a regular deploy target (Operation B). Never deploy with the hub credential. |
+| List connected orgs or environments | Never mention the Lifecycle Center org. Follow `list-orgs.md`. |
+| Show the Lifecycle Center org in the list, or asks why it is not listed | Say it is the Lifecycle Center hub, kept separate from deploy targets, and is never part of the deploy list. If they want its status, check the credential and answer as above. |
+| Remove or disconnect it | Say to use **Remove DevOps Center Connection** in DX Inspector. |
+
+## Notes for the connect flow
+
+- Hub mode has no `DevopsEnvironment` row: it uses `setupNamedCredential` with the fixed name `ALMDevOpsCenterHub`.
+- The user must sign in as someone with the **DevOps Center User** permission set in the Lifecycle Center org.
+- A failed finish step clears the user's saved DX Inspector selections. Say so before a repair, and again if the finish fails.
+- Never rename `ALMDevOpsCenterHub`. DX Inspector finds the credential by that exact name.

package/skills/dx-lifecycle-center/references/list-orgs.md

@@ -0,0 +1,99 @@
+# List connected orgs (Operation A)
+
+Shows the orgs that can receive a deploy: the **DX Inspector environments** stored in the source org. The same lookup resolves a target the user names (alias, URL, org id, or name) for Deploy and Connect.
+
+The targets are the DX Inspector environments, **not** the orgs authorized on this machine. Never build the list from `sf org list` or local aliases: an org can be authorized locally yet not connected, and the reverse.
+
+## 1. Run the resolver
+
+```bash
+bash scripts/resolve-environment.sh <source-org-alias> [identifier]
+```
+
+`<source-org-alias>` is the alias the user named, else the default org from `sf org display --json`. Pass `identifier` exactly as the user gave it. It accepts:
+
+| The user gives | Example |
+|---|---|
+| Environment name | `MySandbox` |
+| Local `sf` alias | `my-sandbox` |
+| Org URL (My Domain, setup, or lightning host) | `https://mydomain--mysandbox.sandbox.my.salesforce.com` |
+| Org id (15 or 18 characters) | `00D5g000001AbCd` |
+
+The script runs `SELECT Id, Name, NamedCredential, OrgType, IsExpired, OrgUrl, OrgIdentifier FROM DevopsEnvironment ORDER BY Name` and prints one JSON document:
+
+- `source`: `alias`, `username`, `orgId`, `instanceUrl` of the source org.
+- `environments[]`: each row with `state` of `selectable`, `expired`, or `unauthenticated`.
+- With an identifier: `matchStatus`, `matches[]`, `match`, and `sourceMatched`.
+
+The Lifecycle Center org's own row is never returned (see `hub-org.md`).
+
+## 2. If the script fails
+
+It exits `1` and prints one reason on stderr. Say only what the reason supports:
+
+| Script says | Tell the user | Then |
+|---|---|---|
+| `DevOps Center not enabled or no access` | "DX Inspector isn't enabled for this org or user, so there are no environments to list or deploy to. An admin needs to enable it." | Stop. Do not run another query, do not fall back to `sf org list`, and do not offer a deploy. |
+| `query failed, not an enablement problem` | The error in plain words (often an expired session). | Tell them to reconnect the source org (in Builder Central use the Reconnect prompt; running the CLI locally, `sf org login web --alias <alias>`), then try again. Never say DX Inspector is disabled. |
+| `unexpected query result` | The environment lookup returned something unreadable. | Report that and stop. Do not guess a list. |
+| `cannot read source org` | The source org is not authorized on this machine. | Ask which org they build in. If it is not authorized, reconnect it the same way as above, then start again. |
+| `jq required` | `jq` is missing from the environment. | Report it and stop. |
+
+## 3. Read the match (only when an identifier was passed)
+
+**First check `sourceMatched`.** If it is `true`, the identifier is the source org (this also covers a row with `isSource: true`): say it cannot be its own deploy target and ask for a different org. Ignore `matchStatus` in that case.
+
+| `matchStatus` | Do |
+|---|---|
+| `matched` and `state` is `selectable` | Use that row. Confirm it back with name, URL, and org id. |
+| `matched` and `state` is `unauthenticated` | Connect never finished. Offer to finish it (`connect-org.md`, repair path). |
+| `matched` and `state` is `expired` | Retired or replaced by an environment swap. Not deployable and not repairable: pick another or connect a new one. |
+| `ambiguous` | Show `matches` and ask which one. |
+| `not-connected` | Not in DX Inspector. Offer to connect it (`connect-org.md`). If the identifier was an alias, URL, or org id, carry it into the connect flow so only the missing inputs are asked. |
+| `none-requested` | No target named: show the list (section 4). |
+
+When the identifier is an alias that is not connected, `sf org display --target-org <alias> --json` gives its URL, which sets the `orgType` by the host table in `connect-org.md`. Use the alias as the suggested environment name (letters only) and still ask the user to confirm the type if the host does not decide it.
+
+## 4. Show the list
+
+A numbered table with the columns `#`, `Name`, `Type`, `URL`, `Org id`, `Status`:
+
+- One row per entry in `environments[]`, then the **source org** as the last row. A row with `isSource: true` is the source org: show it once, as that last row, never as a selectable environment.
+- Always include the `Org id` column. Write `—` for any empty cell.
+- The source org's `Type` is always `—`: `source` carries no org type, so never infer one.
+- Never show row ids or credential names.
+- If several rows share a name, tell them apart by URL.
+
+| Row | Status column |
+|---|---|
+| `state = selectable` | Selectable |
+| `state = expired` | Retired or replaced |
+| `state = unauthenticated` | Not authenticated |
+| The source org | `<alias> (current org, source)`. It is the source, so it is **not** a deploy target. If the user picks it, explain that and ask for another. |
+
+Example:
+
+| # | Name | Type | URL | Org id | Status |
+|---|---|---|---|---|---|
+| 1 | MySandbox | Sandbox | mydomain--mysandbox.sandbox.my.salesforce.com | 00D5g000001AbCd | Selectable |
+| 2 | OldSandbox | Sandbox | mydomain--old.sandbox.my.salesforce.com | — | Retired or replaced |
+| 3 | my-alias *(current org, source)* | — | mydomain.my.salesforce.com | 00D5g000001XyZw | — |
+
+End the list with exactly this sentence and nothing after it:
+
+> Want to deploy to an org that isn't listed? I can help you connect a new one.
+
+Do not add any other offer, summary, or follow-up.
+
+| Situation | Reply instead of the table |
+|---|---|
+| No environments | "No environments are connected to DX Inspector in `<source-org-alias>` yet." Then the closing sentence. |
+| Every environment is expired or unauthenticated | "None of the connected environments can accept a deploy right now: <names and reasons>." Then the closing sentence. |
+
+## 5. Current-org details
+
+When the user asks about the current org itself, answer from `source`: alias, username, URL, and org id. Add nothing else.
+
+## Carrying a chosen row forward
+
+For Deploy, take `id` → `targetEnvironmentId` and `namedCredential` → `namedCredential` from the **same** row. The API rejects a mismatched pair. Never deploy to a row whose `state` is not `selectable`.

package/skills/dx-lifecycle-center/references/request-body.md

@@ -0,0 +1,75 @@
+# Simple Deploy Request Body
+
+> **Scope:** the skill sends metadata only. `datachanges` is documented here for reference but is deferred; do not send it from this skill yet.
+
+Source of truth: `ISimpleDeployResource` / `SimpleDeployInputRepresentation` (Connect) and the cliaas `validator/schema.ts`. Connect forwards `requestBody` to cliaas unchanged, so cliaas validation errors surface as a 400.
+
+## Envelope (Connect input)
+
+| Field | Type | Notes |
+|---|---|---|
+| `namedCredential` | string | `DevopsEnvironment.NamedCredential`. Must be bound to `targetEnvironmentId`. |
+| `targetEnvironmentId` | string | `DevopsEnvironment.Id`. Scopes validate and quick-deploy tracking. |
+| `requestBody` | object | The deploy payload below. |
+| `headerTargetInstanceURL`, `headerTargetAccessToken` | string | Raw-token alternative to `namedCredential`. **Do not use from this skill.** |
+| `components` | array | Deprecated and ignored. Do not send. |
+
+## `requestBody`
+
+| Field | Type | Notes |
+|---|---|---|
+| `changes[]` | `{fullName, type, operation}` | All three required and non-blank. `operation` is `add`, `modify`, or `delete`. Map anything else (dependency, manual, manifest) to `modify`. |
+| `datachanges` | object (deferred) | `{ "objectsList": { "<ObjectApiName>": { "fields": [{"name": "..."}], ... } } }`. Each object needs at least one field. |
+| `isCheckDeploy` | boolean | `true` = validate only (alias `checkOnly`). Default `false`. |
+| `testOptions` | `{level, tests[]}` | `level`: `NoTestRun`, `RunSpecifiedTests`, `RunLocalTests` (default), `RunAllTestsInOrg`. `tests` must list the tests for `RunSpecifiedTests`; send an empty array otherwise. Legacy `testLevel` + `tests` also accepted. |
+| `isQuickDeploy` | boolean | `true` = deploy a prior validation. Default `false`. |
+| `checkDeployIdentifier` | string | `0Af` id (15 or 18 chars). Required with `isQuickDeploy`. |
+| `metadataLookups` | map<string,string> | Optional. |
+
+### `datachanges.objectsList.<Object>` entry
+
+`fields[]` (required, `{name, ...}`), plus optional `relatedObjects`, `duplicateCheck` (field names for dedupe), `recordIds`, `filters`, `formats`, `numRecords`, `externalIdField` (upsert/match key, for example `External_Account_Id__c`). Unknown keys pass through. Remove duplicate fields by `name` before sending.
+
+## Mode matrix
+
+| Mode | `changes` | `datachanges` | `testOptions` | Other |
+|---|---|---|---|---|
+| deploy | required (this skill) | deferred | optional | The API itself allows data-only; this skill sends metadata. |
+| validate | **required** | ignored (stripped, remembered for quick deploy) | optional | `isCheckDeploy: true`. |
+| quickDeploy | **forbidden** | forbidden | **forbidden** | `isQuickDeploy: true` + `checkDeployIdentifier`. |
+
+Test level default: Production targets need tests to complete a deploy, so use `RunLocalTests`; sandbox and scratch-like targets use `NoTestRun`. An explicit user choice always wins.
+
+## Examples
+
+Metadata deploy:
+
+```json
+{
+  "namedCredential": "QA_Sandbox_1PJSB...",
+  "targetEnvironmentId": "1QeSB0000004T3R0AU",
+  "requestBody": {
+    "changes": [
+      {"fullName": "AccountService", "type": "ApexClass", "operation": "modify"},
+      {"fullName": "Account.Tier__c", "type": "CustomField", "operation": "add"}
+    ],
+    "testOptions": {"level": "NoTestRun", "tests": []}
+  }
+}
+```
+
+Validate only:
+
+```json
+{ "namedCredential": "Prod", "targetEnvironmentId": "1Qe...",
+  "requestBody": { "isCheckDeploy": true,
+    "changes": [{"fullName": "AccountService", "type": "ApexClass", "operation": "modify"}],
+    "testOptions": {"level": "RunLocalTests", "tests": []} } }
+```
+
+Quick deploy:
+
+```json
+{ "namedCredential": "Prod", "targetEnvironmentId": "1Qe...",
+  "requestBody": { "isQuickDeploy": true, "checkDeployIdentifier": "0AfXXXXXXXXXXXXXXX" } }
+```

package/skills/dx-lifecycle-center/references/troubleshooting.md

@@ -0,0 +1,31 @@
+# Troubleshooting: DX Inspector org connection
+
+Explain each problem to the user in plain language. Never echo raw JSON or tokens. Do not retry a failing call in a loop.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Deploy POST returns `TARGET_ORG_ENVIRONMENT_CREATION_FAILED:Invalid org type` | `orgType` is not valid | Use `PRODUCTION`, `SANDBOX`, or `ORGFARM`. `envName` must contain at least one letter. |
+| Hub POST returns `400 namedCredentialType is not supported.` | Typo or wrong case in the type | Use one of `ORG_TO_ORG`, `ORG_TO_SANDBOX_ORG`, `ORG_TO_ORGFARM_ORG`. |
+| POST returns 403 or "insufficient access" | User lacks DevOps API access in the dev org | Assign the DevOps Center permissions in the dev org. The user needs *Customize Application*. |
+| POST succeeds but `redirectUrl` is empty | Setup or URL generation failed on the server; the errors were swallowed | **Hub:** check status; if the EC or NC exists, re-POST once. **Deploy:** the row already exists, so do not POST again (it would insert a second row). Get a fresh link with `GET /connect/devops/environment/<id>`, or delete the row (below) and start over. If it is still empty, tell the user setup failed server-side and stop. |
+| Login page is `login.salesforce.com` but the target is a sandbox, or the reverse | Wrong `namedCredentialType` | **Deploy:** `DELETE /connect/devops/environment/<id>` (removes the NC, EC and row), then POST again with the correct `orgType`. **Hub:** delete the NC and EC in Setup, then re-run with the correct type. |
+| OAuth page shows an error or loops back | The browser has no dev-org session, or the user denied access | Ask the user to sign in to the dev org in that browser, then give a fresh link (deploy: `GET /connect/devops/environment/<id>`; hub: re-run Step 1). Do not run `sf org open`. |
+| EC principal still `NotConfigured` after the user says they're done | The login didn't finish, or a different Salesforce user completed it | The token is per user, so the same dev-org user must do the login. Give a fresh link (deploy: `GET /connect/devops/environment/<id>`; hub: re-run Step 1). |
+| User can't use the credential | Missing **Access DevOps Center Named Credentials** (`AccessDevOpsCenterNamedCredentials`) | Assign that permission set to the user in the dev org. |
+| Hub PATCH returns `404 Named credential does not exist` | POST never created the NC, or the name differs | Re-check the exact name (case-sensitive) and re-run Step 1. |
+| Hub PATCH returns `DOCE_CONNECTION_UPDATE_FAILED` | The `userinfo` callout failed, usually because the OAuth token is missing or expired | Confirm the principal is `Configured`, then re-run Steps 1–4. The user's saved DX Inspector selections were cleared, so they must pick them again. |
+| Deploy environment PATCH returns `TARGET_ORG_AUTHENTICATION_STATUS_CHECK_FAILED` (401/403), `TARGET_ORG_AUTHENTICATION_TIMEOUT` (408/504), or `TARGET_ORG_UNKNOWN_ERROR` (includes "Environment record not found" and "does not have a named credential") | The login is missing or expired, the callout timed out, or the id is wrong | Confirm the principal is `Configured` and the `id` is the POST's. Give a fresh link and PATCH once. Do not loop. |
+| PATCH `calloutUrl` or `orgUrl` is still a login host | Unexpected `userinfo` response | Stop and report. Do not hand the NC to deploy. |
+| Hub mode: `doceConnectionType` fails | The hub user lacks **DevOps Center User** | Assign the permission set in the Lifecycle Center org, then re-run the check. |
+| Deploy: `TARGET_ORG_SESSION_EXPIRED` or `Bad_OAuth_Token` | The target refresh token was revoked or expired. A stale token is not visible in the environment list; it only shows at deploy time | Repair: fresh link from `GET /connect/devops/environment/<id>`, user logs in, PATCH once. |
+| Environment shows `unauthenticated` (empty `OrgUrl` or `OrgIdentifier`) | The connect never finished: POST ran but login or PATCH did not | Same repair: fresh link, login, PATCH once. Do not POST again. |
+| `Doce Hub Environment` row is missing from the environment list | By design: the resolver drops the hub row (credential `ALMDevOpsCenterHub`, empty `OrgUrl`) because it is the Lifecycle Center hub, not a deploy target | Nothing to repair. To deploy to that org, connect it as a deploy target with the Environment API. |
+| Environment shows `expired` | `IsExpired` is set when an environment is retired or replaced by a swap; it is not an OAuth expiry | Do not repair it. Pick another environment or connect a new one. |
+
+## Starting over
+
+**Deploy target:** `DELETE /connect/devops/environment/<id>` (confirm with the user first). It removes the Named Credential, External Credential, and the `DevopsEnvironment` row. Do not delete credentials in Setup: that leaves an orphaned row that still looks selectable.
+
+**Hub:** delete both the **Named Credential** and the **External Credential** named `ALMDevOpsCenterHub` in Setup → Named Credentials (and the External Credentials tab), and run the skill again.
+
+For the hub, the **Remove DevOps Center Connection** option in DX Inspector does the same teardown.

package/skills/dx-lifecycle-center/scripts/poll-deploy-status.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# Poll a Simple Deploy request until it reaches a terminal state, or check once.
+# Read-only: issues only GET calls and SOQL queries.
+#
+# Two sources are read on every check, and a terminal state from EITHER one ends the poll:
+#   1. the Simple Deploy status endpoint (live `step`, `metadata.deployId`)
+#   2. DevopsRequestInfo, queried by RequestToken (the same record commit polling uses;
+#      Status is SUCCESS or ERROR, with Message / ErrorDetails / RequestCompletionDate)
+#
+# Usage:
+#   poll-deploy-status.sh --once <requestId> <source-org-alias>
+#   poll-deploy-status.sh <requestId> <source-org-alias> [interval-seconds] [timeout-seconds]
+# Env: DETAIL_WAIT=<seconds> how long to wait for the failure detail (default 20; 4 with --once)
+#
+# On failure the component-level errors are read from the DEPLOYMENT_COMPLETED
+# DevopsActivityLog row of the request. Core's DeployDetailFetchHandler fills it in
+# asynchronously (it calls the target org's Metadata API through the deploy's named
+# credential), so no login to the target org is needed here. The script waits briefly
+# for it, and stops waiting early if Core marks it errorDetailUnavailable.
+#
+# Prints one JSON object on stdout when the check ends:
+#   outcome (SUCCEEDED|FAILED|NOT_FOUND|IN_PROGRESS|TIMEOUT), status, step, deployId, message,
+#   errorMessage, errorDetails, deployJobLogURL, completedAt, decidedBy,
+#   activityMessage, errorDetail (null when unavailable), errorDetailUnavailable, response
+# Progress lines go to stderr.
+#
+# NOT_FOUND from the endpoint is tolerated for the first few polls: right after submit
+# the status cache entry may not exist yet. A DevopsRequestInfo row overrides it.
+#
+# Exit codes:
+#   0  deploy succeeded
+#   1  usage error, missing dependency, or both status calls failed
+#   2  deploy failed, or NOT_FOUND after the grace polls
+#   3  timeout reached before a terminal state (poll mode); outcome TIMEOUT carries requestId,
+#      step and deployId (when known) so the user can be told what to check
+#   4  still processing (--once mode only)
+set -euo pipefail
+
+ONCE=0
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --once) ONCE=1; shift ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+
+REQUEST_ID="${ARGS[0]:-}"
+SOURCE_ORG="${ARGS[1]:-}"
+INTERVAL="${ARGS[2]:-10}"
+TIMEOUT="${ARGS[3]:-100}"
+API_VERSION="${SF_API_VERSION:-v67.0}"
+API_VERSION="v${API_VERSION#v}"  # accept 67.0 or v67.0
+NOT_FOUND_GRACE=3
+DETAIL_WAIT="${DETAIL_WAIT:-20}"
+[ "$ONCE" -eq 1 ] && DETAIL_WAIT="${DETAIL_WAIT_ONCE:-4}"
+
+usage() {
+  echo "Usage: poll-deploy-status.sh [--once] <requestId> <source-org-alias> [interval-seconds] [timeout-seconds]" >&2
+  exit 1
+}
+
+[ -n "$REQUEST_ID" ] && [ -n "$SOURCE_ORG" ] || usage
+case "$REQUEST_ID" in *[!A-Za-z0-9-]*) echo "requestId may only contain letters, digits and hyphens" >&2; exit 1 ;; esac
+case "$INTERVAL$TIMEOUT" in *[!0-9]*) echo "interval and timeout must be whole numbers" >&2; exit 1 ;; esac
+[ "$INTERVAL" -ge 1 ] || { echo "interval must be >= 1" >&2; exit 1; }
+for dep in sf jq; do
+  command -v "$dep" >/dev/null 2>&1 || { echo "Missing dependency: $dep" >&2; exit 1; }
+done
+
+PATH_URL="/services/data/${API_VERSION}/connect/devops/simple-deploy/deploy?requestID=${REQUEST_ID}"
+SOQL="SELECT Id, Status, Message, ErrorDetails, RequestCompletionDate FROM DevopsRequestInfo WHERE RequestToken = '${REQUEST_ID}'"
+START=$(date +%s)
+NOT_FOUND_COUNT=0
+POLLS=0
+
+sfq() { env FORCE_COLOR=0 SF_CLI_DISABLE_AUTOUPDATE=true "$@"; }
+
+# Failure detail from Core: DEPLOYMENT_COMPLETED DevopsActivityLog.Description (JSON) holds the flat
+# errorMessage plus, once Core's async handler has run, errorDetail {componentFailures, testFailures,
+# errorMessage, ...} or errorDetailUnavailable. Waits up to DETAIL_WAIT seconds for either marker.
+ACT_MSG=""; ACT_DETAIL=null; ACT_UNAVAIL=false
+fetch_failure_detail() {
+  [ -n "$DRI_ID" ] || return 0
+  local waited=0 q desc
+  # No target-org deploy job (failed before the target, e.g. RETRIEVE_METADATA): Core will never add
+  # errorDetail, and the flat message already says why, so do not wait.
+  [ -n "$DEPLOY_ID" ] || DETAIL_WAIT=0
+  while true; do
+    q=$(sfq sf data query --target-org "$SOURCE_ORG" --json -q \
+      "SELECT Description FROM DevopsActivityLog WHERE ActivityType = 'DEPLOYMENT_COMPLETED' AND DevopsRequestInfoId = '${DRI_ID}' LIMIT 1" 2>/dev/null) || q=""
+    desc=$(printf '%s' "$q" | jq -r '.result.records[0].Description // empty' 2>/dev/null || true)
+    if [ -n "$desc" ] && printf '%s' "$desc" | jq -e . >/dev/null 2>&1; then
+      ACT_MSG=$(printf '%s' "$desc" | jq -r '.errorMessage // empty')
+      ACT_DETAIL=$(printf '%s' "$desc" | jq -c '.errorDetail // null')
+      ACT_UNAVAIL=$(printf '%s' "$desc" | jq -r 'if .errorDetailUnavailable then "true" else "false" end')
+      if [ "$ACT_DETAIL" != "null" ] || [ "$ACT_UNAVAIL" = "true" ]; then return 0; fi
+    fi
+    [ "$waited" -ge "$DETAIL_WAIT" ] && return 0
+    echo "waiting for Core to attach the failure detail (${waited}s/${DETAIL_WAIT}s)" >&2
+    sleep 2; waited=$((waited + 2))
+  done
+}
+
+# Emit the final JSON and exit. $1 outcome, $2 exit code, $3 decidedBy.
+finish() {
+  [ "$1" = "FAILED" ] && fetch_failure_detail
+  jq -n \
+    --arg outcome "$1" --arg decidedBy "$3" --arg requestId "$REQUEST_ID" \
+    --arg status "$STATUS" --arg step "$STEP" --arg deployId "$DEPLOY_ID" \
+    --arg errorMessage "$ERR_MSG" --arg logUrl "$LOG_URL" \
+    --arg message "$DRI_MSG" --arg errorDetails "$DRI_ERR" --arg completedAt "$DRI_DONE" \
+    --arg activityMessage "$ACT_MSG" --argjson errorDetail "$ACT_DETAIL" --argjson unavailable "$ACT_UNAVAIL" \
+    --argjson response "${RESP_JSON:-null}" \
+    '{requestId:$requestId, outcome:$outcome, status:$status, step:$step, deployId:$deployId,
+      message:$message, errorMessage:$errorMessage, errorDetails:$errorDetails,
+      activityMessage:$activityMessage, errorDetail:$errorDetail, errorDetailUnavailable:$unavailable,
+      deployJobLogURL:$logUrl, completedAt:$completedAt, decidedBy:$decidedBy, response:$response}'
+  exit "$2"
+}
+
+while true; do
+  # --- source 1: Simple Deploy status endpoint
+  EP_OK=1; RESP_JSON=null
+  ERRF=$(mktemp)
+  if OUT=$(sfq sf api request rest "$PATH_URL" --method GET --target-org "$SOURCE_ORG" 2>"$ERRF"); then
+    RESP_JSON=$(printf '%s' "$OUT" | jq -c '.response // null' 2>/dev/null || echo null)
+  else
+    EP_OK=0
+    echo "Status endpoint call failed: $(printf '%s%s' "$OUT" "$(cat "$ERRF")" | head -c 300)" >&2
+  fi
+  rm -f "$ERRF"
+
+  jqr() { printf '%s' "$RESP_JSON" | jq -r "$1" 2>/dev/null || true; }
+  STATUS=$(jqr '(.status // empty) | ascii_upcase')
+  STEP=$(jqr '.step // empty')
+  DEPLOY_ID=$(jqr '.metadata.deployId // empty')
+  ERR_MSG=$(jqr '.errorMessage // empty')
+  LOG_URL=$(jqr '.metadata.deployJobLogURL // empty')
+  LOG_URL="${LOG_URL//\{version\}/${API_VERSION#v}}"  # the API returns a literal v{version}
+  META=$(jqr '(.metadata.status // empty) | ascii_upcase')
+
+  # --- source 2: DevopsRequestInfo (same record commit polling reads)
+  DRI_ID=""; DRI_STATUS=""; DRI_MSG=""; DRI_ERR=""; DRI_DONE=""
+  if DRI=$(sfq sf data query --target-org "$SOURCE_ORG" --json -q "$SOQL" 2>/dev/null); then
+    DRI_ID=$(printf '%s' "$DRI" | jq -r '.result.records[0].Id // empty' 2>/dev/null || true)
+    DRI_STATUS=$(printf '%s' "$DRI" | jq -r '(.result.records[0].Status // empty) | ascii_upcase' 2>/dev/null || true)
+    DRI_MSG=$(printf '%s' "$DRI" | jq -r '.result.records[0].Message // empty' 2>/dev/null || true)
+    DRI_ERR=$(printf '%s' "$DRI" | jq -r '.result.records[0].ErrorDetails // empty' 2>/dev/null || true)
+    DRI_DONE=$(printf '%s' "$DRI" | jq -r '.result.records[0].RequestCompletionDate // empty' 2>/dev/null || true)
+  fi
+
+  if [ "$EP_OK" -eq 0 ] && [ -z "$DRI_STATUS" ]; then
+    echo "Both status sources failed for requestId=${REQUEST_ID}" >&2
+    exit 1
+  fi
+
+  # --- decide: a terminal state from either source wins
+  case "$DRI_STATUS" in
+    SUCCESS) STATUS=SUCCEEDED; finish SUCCEEDED 0 request-info ;;
+    ERROR)   STATUS=FAILED; finish FAILED 2 request-info ;;
+  esac
+  case "$META" in
+    SUCCEEDED|SUCCEEDEDPARTIAL|SUCCESS) [ "$STATUS" = "FAILED" ] || STATUS=SUCCEEDED ;;
+    FAILED|CANCELED|CANCELLED) STATUS=FAILED ;;
+  esac
+  case "$STATUS" in
+    SUCCEEDED|COMPLETED|SUCCESS|SUCCEEDED_PARTIAL) finish SUCCEEDED 0 endpoint ;;
+    FAILED|ERROR|CANCELED|CANCELLED) finish FAILED 2 endpoint ;;
+    NOT_FOUND)
+      NOT_FOUND_COUNT=$((NOT_FOUND_COUNT + 1))
+      if [ "$ONCE" -eq 1 ] || [ "$NOT_FOUND_COUNT" -gt "$NOT_FOUND_GRACE" ]; then
+        finish NOT_FOUND 2 endpoint
+      fi ;;
+    QUEUED|STARTED|IN_PROGRESS|INPROGRESS|PENDING|CANCELING|"") ;;
+    *)
+      echo "Unexpected status '${STATUS}': ${RESP_JSON}" | head -c 500 >&2; echo >&2
+      exit 1 ;;
+  esac
+
+  if [ "$ONCE" -eq 1 ]; then
+    finish IN_PROGRESS 4 endpoint
+  fi
+
+  ELAPSED=$(( $(date +%s) - START ))
+  if [ "$ELAPSED" -ge "$TIMEOUT" ]; then
+    echo "Timed out after ${TIMEOUT}s. requestId=${REQUEST_ID} status=${STATUS:-unknown} step=${STEP:-n/a}" >&2
+    finish TIMEOUT 3 none
+  fi
+  REMAINING=$(( TIMEOUT - ELAPSED ))
+  POLLS=$((POLLS + 1))
+  # Quick early checks (fast deploys finish in seconds), then settle to INTERVAL.
+  STEP_SLEEP=$INTERVAL
+  if [ "$POLLS" -le 3 ] && [ "$INTERVAL" -gt 3 ]; then STEP_SLEEP=3
+  elif [ "$POLLS" -le 6 ] && [ "$INTERVAL" -gt 5 ]; then STEP_SLEEP=5
+  fi
+  SLEEP=$(( STEP_SLEEP < REMAINING ? STEP_SLEEP : REMAINING ))
+  echo "status=${STATUS:-pending} step=${STEP:-n/a} request-info=${DRI_STATUS:-none}; next check in ${SLEEP}s" >&2
+  sleep "$SLEEP"
+done

package/skills/dx-lifecycle-center/scripts/resolve-environment.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Lists the DevOps Center environments of a source org and resolves an optional
+# identifier (alias, username, My Domain URL, 15/18-char org id, or environment name)
+# to one of them. Read-only. Prints one JSON document on stdout.
+#
+# Usage: resolve-environment.sh <source-org-alias> [identifier] [--rows-file <file>]
+#   --rows-file  read the DevopsEnvironment query result JSON from a file (tests)
+#
+# Exit codes: 0 ok (check .match / .matchStatus), 1 usage or call error.
+set -uo pipefail
+
+command -v jq >/dev/null || { echo "jq required" >&2; exit 1; }
+SRC="${1:-}"
+[ -n "$SRC" ] || { echo "usage: resolve-environment.sh <source-org-alias> [identifier] [--rows-file <file>]" >&2; exit 1; }
+shift
+IDENT=""; ROWS_FILE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --rows-file) [ $# -ge 2 ] || { echo "--rows-file needs a value" >&2; exit 1; }; ROWS_FILE="$2"; shift 2 ;;
+    *) IDENT="$1"; shift ;;
+  esac
+done
+
+sfj() { env FORCE_COLOR=0 SF_CLI_DISABLE_AUTOUPDATE=true "$@" 2>/dev/null; }
+
+# Source org (the org the user built in).
+src_json=$(sfj sf org display --target-org "$SRC" --json) \
+  || { echo "cannot read source org '$SRC'" >&2; exit 1; }
+source_obj=$(printf '%s' "$src_json" | jq -c --arg a "$SRC" \
+  '{alias:$a, username:.result.username, orgId:.result.id, instanceUrl:.result.instanceUrl}')
+
+# DevopsEnvironment rows.
+if [ -n "$ROWS_FILE" ]; then
+  rows_json=$(cat "$ROWS_FILE")
+else
+  rows_json=$(sfj sf data query --target-org "$SRC" --json --query \
+    "SELECT Id, Name, NamedCredential, OrgType, IsExpired, OrgUrl, OrgIdentifier FROM DevopsEnvironment ORDER BY Name") \
+    || {
+      # sf prints its JSON error on stdout; tell "not enabled" apart from an expired session or other failure.
+      qmsg=$(printf '%s' "$rows_json" | jq -r '[.name, .message] | map(select(. != null)) | join(": ")' 2>/dev/null)
+      case "$qmsg" in
+        *INVALID_TYPE*|*"sObject type"*|*"not supported"*|*INSUFFICIENT_ACCESS*)
+          echo "DevOps Center not enabled or no access: DevopsEnvironment is unavailable ($qmsg)" >&2 ;;
+        *) echo "DevopsEnvironment query failed, not an enablement problem: ${qmsg:-unknown error}" >&2 ;;
+      esac
+      exit 1
+    }
+fi
+printf '%s' "$rows_json" | jq -e '.result.records' >/dev/null 2>&1 \
+  || { echo "unexpected query result" >&2; exit 1; }
+
+# Identifier -> comparable keys: org id (first 15), host, and a lowercase name.
+# Local alias or username: expand through `sf org display` to its org id and host.
+id15=""; host=""; name=""
+if [ -n "$IDENT" ]; then
+  if printf '%s' "$IDENT" | grep -Eq '^00D[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$'; then
+    id15="${IDENT:0:15}"
+  elif printf '%s' "$IDENT" | grep -Eiq '^https?://' \
+       || printf '%s' "$IDENT" | grep -Eiq '^[A-Za-z0-9.-]+\.(salesforce\.com|salesforce-setup\.com|force\.com|pc-rnd\.salesforce\.com)(/.*)?$'; then
+    host=$(printf '%s' "$IDENT" | sed -E 's#^[Hh][Tt][Tt][Pp][Ss]?://##; s#[/?].*$##' | tr 'A-Z' 'a-z')
+  else
+    # Environment name, alias, or username. An authorized alias also yields an org id and host.
+    name=$(printf '%s' "$IDENT" | tr 'A-Z' 'a-z')
+    exp=$(sfj sf org display --target-org "$IDENT" --json) && {
+      id15=$(printf '%s' "$exp" | jq -r '.result.id // empty | .[0:15]')
+      host=$(printf '%s' "$exp" | jq -r '.result.instanceUrl // empty' | sed -E 's#^https?://##')
+      # A resolved org is matched by identity only: an environment that merely shares its name is another org.
+      [ -n "$id15" ] && name=""
+    }
+  fi
+fi
+
+jq -n \
+  --argjson source "$source_obj" \
+  --argjson rows "$rows_json" \
+  --arg ident "$IDENT" --arg id15 "$id15" --arg host "$host" --arg name "$name" '
+  # setup and lightning hosts point at the same org as the My Domain host
+  def norm: ascii_downcase | sub("^https?://"; "") | sub("[/?].*$"; "")
+            | sub("\\.salesforce-setup\\.com$"; ".salesforce.com")
+            | sub("\\.lightning\\.force\\.com$"; ".my.salesforce.com");
+  # expired = retired or replaced by an environment swap (not an OAuth expiry).
+  # unauthenticated = connect never finished: the PATCH fills OrgUrl and OrgIdentifier.
+  # The DevOps Center hub row is created with only the fixed hub NC (no OrgUrl) and is the control
+  # plane, not a deploy target, so it is dropped before listing or matching (also by its fixed
+  # name while it has no OrgUrl, in case its credential was removed).
+  # NamedCredential is plain text in the API; strip an <a> wrapper in case a UI layer added one.
+  def ncname: ((.NamedCredential // "") | gsub("<[^>]*>"; "") | gsub("^\\s+|\\s+$"; ""));
+  def state: if (.IsExpired == true) then "expired"
+             elif ((ncname == "") or (.OrgUrl // "") == "" or (.OrgIdentifier // "") == "") then "unauthenticated"
+             else "selectable" end;
+  [ ($rows.result.records // [])[] | select(ncname != "ALMDevOpsCenterHub" and ((.Name // "") != "Doce Hub Environment" or (.OrgUrl // "") != "")) ] as $recs
+  | ($host | if . == "" then "" else norm end) as $h
+  | [ $recs[] | {
+        id: .Id, name: .Name, orgType: .OrgType,
+        orgUrl: (.OrgUrl // null),
+        orgId: (.OrgIdentifier // null),
+        namedCredential: (ncname | if . == "" then null else . end),
+        state: state,
+        isSource: ((.OrgIdentifier // "")[0:15] == ($source.orgId // "")[0:15] and (.OrgIdentifier // "") != "")
+    } ] as $envs
+  | ( if $ident == "" then []
+      else [ $envs[] | select(
+               ($id15 != "" and ((.orgId // "")[0:15] == $id15))
+            or ($h != "" and ((.orgUrl // "") != "") and ((.orgUrl | norm) == $h))
+            or ($name != "" and ((.name | ascii_downcase) == $name))) ]
+      end ) as $m
+  | { source: $source,
+      environments: $envs,
+      identifier: $ident,
+      matchStatus: ( if $ident == "" then "none-requested"
+                     elif ($m | length) == 0 then "not-connected"
+                     elif ($m | length) > 1 then "ambiguous"
+                     else "matched" end ),
+      matches: $m,
+      match: (if ($m | length) == 1 then $m[0] else null end),
+      sourceMatched: ( $ident != "" and
+        ( ($id15 != "" and $id15 == ($source.orgId // "")[0:15])
+       or ($h != "" and (($source.instanceUrl // "") | norm) == $h)
+       or ($name != "" and $name == ($source.alias | ascii_downcase))
+       or (($m | length) == 1 and $m[0].isSource) ) ) }'

package/skills/dx-org-devhub-configure/SKILL.md

@@ -16,9 +16,7 @@ metadata:
   # could falsely gate an admin holding only one. Declare the canonical
   # System-Administrator perm; the OR alternative stays documented in the
   # description and body.
-  accessCheck:
-    - type: "userPerm"
-      value: "ModifyAllData"
+  accessCheck: "UserPermissions.ModifyAllData"
   cliTools:
     - tool: ["jq"]
       semver: ">=1.6.0"

package/skills/dx-org-shape-manage/SKILL.md

@@ -10,11 +10,7 @@ metadata:
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
-  accessCheck:
-    - type: "orgPref"
-      value: "ScratchOrgManagementPref"
-    - type: "orgPref"
-      value: "ShapeExportPref"
+  accessCheck: "(OrgPreferences.ScratchOrgManagementPref) && (OrgPreferences.ShapeExportPref)"
 ---
 
 # dx-org-shape-manage

package/skills/dx-org-snapshot-manage/SKILL.md

@@ -13,9 +13,7 @@ metadata:
       semver: ">=2.0.0"
     - tool: ["jq"]
       semver: ">=1.6"
-  accessCheck:
-    - type: "orgPref"
-      value: "ScratchOrgSnapshotPref"
+  accessCheck: "OrgPreferences.ScratchOrgSnapshotPref"
 ---
 
 # dx-org-snapshot-manage