@salesforce/afv-skills 1.63.0 → 1.65.0

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

@@ -0,0 +1,153 @@
+# Deploy, validate, or quick deploy (Operation D)
+
+Deploys metadata that already exists in the **source org** (the org the user built in) to a **target environment** connected in DX Inspector. It calls `POST /connect/devops/simple-deploy/deploy`, then polls `GET` until the request reaches a final status.
+
+Metadata only. Data (record) deploys are not supported. Needs Salesforce API **v67.0** or later.
+
+| Mode | When | Request body |
+|---|---|---|
+| `deploy` (default) | The user wants the components in the target | `references/request-body.md` |
+| `validate` | The user asks for a check only. For a Production target, recommend it first (Step 3), but never switch the mode without their agreement | `isCheckDeploy: true` |
+| `quickDeploy` | The user has a successful validation id (`0Af…`) to deploy | `isQuickDeploy: true` + `checkDeployIdentifier` |
+
+## Before Step 1
+
+1. Source org: the alias the user named, else the default org from `sf org display --json`. If it cannot be read, ask which org they build in.
+2. Read `result.apiVersion` from that output. If it is below `67.0`, stop and say the org's API version is too old for this skill.
+3. One target per run. If the user names several, deploy to the first, finish, and ask before starting the next. Each target gets its own confirmation (Step 4).
+
+## Step 1: Components
+
+Skip this step for `quickDeploy`: it sends no `changes`.
+
+Ask: "Which components do you want to deploy? Give the name and type of each (for example `AccountService` ApexClass, `Account.Tier__c` CustomField), and tell me whether each is **new**, **changed**, or **removed**."
+
+Map the answer to the wire `operation`: new → `add`, changed → `modify`, removed → `delete`. Anything unclear → `modify`.
+
+Build `changes[]` as `{fullName, type, operation}`. All three are required and non-blank. Types are Metadata API type names (`ApexClass`, `CustomObject`, `CustomField`, `Flow`, `LightningComponentBundle`, …). If the user gives a name without a type, ask; do not guess.
+
+## Step 2: Target environment
+
+Follow `references/list-orgs.md` with the identifier the user gave (sections 1 to 3). Then:
+
+| Outcome | Do |
+|---|---|
+| Target is `matched` and `selectable` | Carry `id` and `namedCredential` from that row. Go to Step 3. |
+| No target named yet | Ask which target. Show the list (`list-orgs.md`, section 4) if they want to choose. |
+| `not-connected` | Offer to connect it. If the user agrees, run `references/connect-org.md` (deploy-target mode), then **continue as below**. |
+| `unauthenticated` | Offer to finish connecting it (repair path), then continue as below. |
+| `expired` | Not deployable. Ask for another target or offer to connect a new one. |
+
+**Continuing after a connect.** When the connect flow finishes and the environment shows as `selectable`, tell the user in one sentence that `<name>` is now connected, and that you will continue the deploy of `<components>` to it. Then go straight to Step 3 and Step 4. The Step 4 message is the confirmation they give before anything is deployed; connecting an org never deploys by itself.
+
+If the user connected the org but gave no components yet, ask for them (Step 1) after the connect.
+
+## Step 3: Build the request
+
+Write the POST body to a temp file (`BODY=$(mktemp)`; this avoids shell-quoting nested JSON):
+
+```json
+{
+  "namedCredential": "<NamedCredential>",
+  "targetEnvironmentId": "<DevopsEnvironment Id>",
+  "requestBody": {
+    "changes": [{"fullName": "AccountService", "type": "ApexClass", "operation": "modify"}],
+    "testOptions": {"level": "NoTestRun", "tests": []}
+  }
+}
+```
+
+Mode variants and test-level rules: `references/request-body.md`.
+
+- **Production target:** recommend a `validate` run first unless the user already has a successful one, and default the test level to `RunLocalTests`. An explicit user choice of test level always wins.
+- **Quick deploy:** the validation id comes from the user or from an earlier `validate` in this conversation (`metadata.deployId`). If you have neither, ask for it. Never invent one. Send only `isQuickDeploy` and `checkDeployIdentifier`, never `changes` or `testOptions`.
+
+## Step 4: Confirmation gate
+
+**This call changes the target org (except `validate`). Do not proceed without an explicit yes.** Show:
+
+> "I'm about to **<deploy | validate | quick deploy>** from `<source-org-alias>` to `<environment Name>` (<OrgType>):
+> - Components: <n> (<first few, with new/changed/removed>)
+> - Test level: <level>
+>
+> Shall I proceed?"
+
+For **quick deploy**, replace the components and test-level lines with `- Validation id: <0Af…>`, and use the same target environment the validation ran against. If the user gives only the id, ask which target it was validated against.
+
+Call out any `delete` and any Production target explicitly. `validate` does not change the target, so it needs no confirmation, but still state what you are about to validate.
+
+## Step 5: Submit
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/simple-deploy/deploy" \
+  --method POST \
+  --body @"$BODY" \
+  --target-org <source-org-alias>
+```
+
+Read `response.requestId`. If it is absent, the call failed: use `references/error-handling.md`. Make **one** attempt. Never retry in a loop, never resubmit after a timeout, and never invent a `requestId`.
+
+## Step 6: Poll to completion
+
+Polling is automatic and read-only. Every check reads **two sources**, and a terminal state from **either** one ends it: the Simple Deploy status endpoint (live `step`, `metadata.deployId`) and the `DevopsRequestInfo` record for the `requestId` (`Status` is `SUCCESS` or `ERROR`; it is the same record commit polling uses).
+
+```bash
+bash scripts/poll-deploy-status.sh <requestId> <source-org-alias> 10 100
+```
+
+Checks come at 3 s, then 5 s, then every 10 s, for at most **100 seconds**, about 2 minutes in all. Set the shell tool timeout to at least 180 seconds so the run is not killed before it exits. Progress lines (`status=… step=… request-info=…`) go to stderr; relay the current step to the user while waiting. Never say the deploy is "still waiting" after the script has printed a result.
+
+On a failed deploy the script also reads the failure detail that Core attaches to the request (the `DEPLOYMENT_COMPLETED` `DevopsActivityLog` row). Core fills it in a few seconds after the failure by calling the target org's Metadata API through the deploy's named credential, so **no login to the target org is needed**. The script waits up to 20 s for it (`DETAIL_WAIT`), and skips the wait when the deploy failed before reaching the target org.
+
+The script prints one JSON object when it ends:
+
+| Field | Meaning |
+|---|---|
+| `outcome` | `SUCCEEDED`, `FAILED`, `NOT_FOUND`, `TIMEOUT` (poll ran out of time), or `IN_PROGRESS` (`--once` only) |
+| `step`, `status` | Last phase seen (`RETRIEVE_METADATA`, `DEPLOY_METADATA`, `VALIDATE_METADATA`, …) and its status |
+| `deployId` | The target org's deploy id (`0Af…`). For a successful `validate` this is the id for a quick deploy |
+| `message`, `errorDetails`, `activityMessage` | Failure text. For a failure before the target org (retrieve or validation) this already names the problem; for a failed target deploy it is generic ("Metadata deployment failed with status: Failed"). Prefer these over `errorMessage`, which can be HTML-escaped (`&#39;`) |
+| `deployJobLogURL` | Per-component detail, in the target org |
+| `errorDetail` | Core's detail for a failed target deploy: `numberComponentErrors`, `componentFailures[]` (`componentType`, `fileName`, `problem`, `problemType`, `lineNumber`, `columnNumber`), `testFailures[]` (`name`, `methodName`, `message`, `stackTrace`), `errorMessage` (for example a code-coverage shortfall), `truncated` (only the first 5 of each are kept). `null` when none |
+| `errorDetailUnavailable` | `true` when Core recorded that no detail will come |
+| `decidedBy` | `endpoint` or `request-info`: which source reported the final state |
+| `response` | The raw endpoint response |
+
+Exit codes: `0` succeeded, `2` failed or not found, `3` timeout, `1` usage error or both sources failed, `4` still processing (`--once` only). `outcome` tells `FAILED` from `NOT_FOUND`.
+
+`NOT_FOUND` right after a submit can be transient (the script allows a short grace period, and a `DevopsRequestInfo` row overrides it). If it persists, the id is unknown or older than about 2 days.
+
+On timeout (exit `3`, `outcome` `TIMEOUT`, about 2 minutes), stop polling and tell the user, in plain words, that the deploy has not reported a final status yet but may still be running. Give them what they need to check it later:
+
+- **Request token (`requestId`)**: "Send me this id and I'll check its status."
+- **Deployment id (`deployId`, starts `0Af`)**, only if the result has one: it is the deploy job in the target org. They can find it in the target org under Setup → Deployment Status, or at `deployJobLogURL`.
+- The `step` it had reached.
+- That the deploy also shows in DX Inspector's activity history for this org.
+
+Example: "Your deploy to `<target>` hasn't reported a final status after 2 minutes. It was at `DEPLOY_METADATA` and may still be running. Request token: `<requestId>`. Deployment id: `<deployId>`. Send me the request token any time and I'll check it, or look up the deployment id in `<target>` under Setup → Deployment Status." Never resubmit, and do not keep polling.
+
+For a one-off check, put `--once` **first**: `bash scripts/poll-deploy-status.sh --once <requestId> <source-org-alias>`. It exits `4` while the request is still processing: report the current `step` and do not poll again unless the user asks. With `--once` there is no grace period, so `NOT_FOUND` right after a submit may be transient: say the request is not visible yet and check again shortly, not that it failed.
+
+If the user gives a `requestId` to check (also when they come back with the id from a timeout), skip Steps 1 to 5 and check it once with `--once`, using the source org alias. If the user asks for the status without an id, use the `requestId` from earlier in this conversation; if there is none, ask for it. Then report as in Step 7.
+
+## Step 7: Report
+
+Summarize in plain language: what was deployed, from where, to where, and the outcome. No raw JSON.
+
+- **Succeeded:** say so, with the completion time (`completedAt`). After a successful `validate`, give `deployId` as the validation id and offer a quick deploy with it.
+- **Failed:** always show the error, never just "failed".
+  1. Say which `step` failed. If `errorDetail` is present, use it: list each `errorDetail.componentFailures` entry as `<fileName> (<componentType>), line <lineNumber>: <problem>`, each `testFailures` entry as `<name>.<methodName>: <message>`, and always include `errorDetail.errorMessage` when set (a code-coverage shortfall appears only there, with `numberComponentErrors` at 0). If `truncated` is true, say only the first few are shown and give `deployJobLogURL`.
+  2. If `errorDetail` is `null`, quote `activityMessage` (else `errorDetails`, else `message`). A failure at `RETRIEVE_METADATA` or validation, such as "Entity of type 'CustomField' named 'Book__c.Author__c' cannot be found", is complete as is: the component is missing from the source org.
+  3. If `errorDetail` is `null` and the message is only the generic "Metadata deployment failed with status: Failed", the detail was not attached in time (or `errorDetailUnavailable` is `true`). Say so, give `deployJobLogURL` (also Setup → Deployment Status in the target org), and offer to check again shortly with `--once`.
+  4. Map the error with `references/error-handling.md`, and ask before retrying. Never resubmit on your own.
+
+## Gotchas
+
+| Gotcha | What to do |
+|---|---|
+| Component not in the source org | The deploy retrieves from the source org. Confirm the name and type exist there before submitting. |
+| Quick deploy with `changes` | Forbidden. Send only `isQuickDeploy` and `checkDeployIdentifier`. |
+| Target equals the source org | Not allowed. Ask for a different target. |
+| An id starting `0Af` | It is a validation id, not a `requestId`. Never poll it. If the user gives one alone, ask whether to quick deploy it, and to which target. |
+| Stale target login | Shows only at deploy time (`Bad_OAuth_Token`, `TARGET_ORG_SESSION_EXPIRED`). Reconnect that environment (`connect-org.md`, repair path), then ask before retrying. |

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