@salesforce/afv-skills 1.67.0 → 1.68.0

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

@@ -1,16 +1,15 @@
 ---
 name: dx-org-devhub-configure
-description: "Enable Dev Hub on a Salesforce org and view its scratch org allocation, using the Salesforce CLI (sf). Use when someone wants to turn on or enable Dev Hub, set up an org to create scratch orgs or second-generation (2GP) and unlocked packages, check whether Dev Hub is already enabled, see how many scratch orgs they can create (Active and Daily scratch org limits, remaining allocation), configure Dev Hub preferences such as packaging, org shape export, or scratch org snapshots, or list the active scratch orgs created from a Dev Hub. Enabling deploys the enableScratchOrgManagementPref setting, is irreversible, needs a System Administrator (ModifyAllData or ModifyMetadata), and does not work in sandboxes. DO NOT TRIGGER for creating or deleting individual scratch orgs, for switching the default org (use dx-org-switch), or for trial or org expiration dates (use dx-org-trial-expiration-check)."
-allowed-tools: Read, Bash(bash), Bash(sf api request rest), Bash(sf data query), Bash(sf org list), Bash(sf org login web), Bash(sf org login device), Bash(sf project deploy), Bash(sf config get), Bash(sf org display), Bash(sf org open), Bash(jq)
+description: "Enable Dev Hub on a Salesforce org, view its status and scratch org allocation, or read its current DevHubSettings preferences, using the Salesforce CLI (sf). Use when someone wants to turn on or enable Dev Hub, set up an org for scratch orgs or 2GP/unlocked packages, check whether Dev Hub is already enabled, see scratch org allocation (Active/Daily limits, remaining, and a pre-flight warning near the limit), see which Dev Hub preferences (packaging, org shape export, scratch org snapshots) are on or off, configure those preferences, list active scratch orgs, or list authenticated orgs when none is specified. Enabling deploys enableScratchOrgManagementPref, is irreversible, needs a System Administrator (ModifyAllData or ModifyMetadata), and does not work in sandboxes. DO NOT TRIGGER for creating or deleting individual scratch orgs."
+allowed-tools: Read, Bash(bash), Bash(sf api request rest), Bash(sf data query), Bash(sf org list), Bash(sf project deploy), Bash(sf config get), Bash(sf org display), Bash(sf org open), Bash(jq)
 metadata:
-  version: "1.0"
+  version: "1.1"
   domains: ["Developer Experience"]
   # DevHubSettings metadata + the Tooling API DevHubSettings endpoint require
-  # API 47.0 or later (see scripts/devhub.sh SETTINGS_API_VERSION).
-  minApiVersion: "47.0"
-  relatedSkills:
-    - "dx-org-switch"
-    - "dx-org-trial-expiration-check"
+  # DevHubSettings base fields need API 47.0+, but enableShapeExportPref needs
+  # 55.0+ and enableScratchOrgSnapshotPref needs 61.0+, so the script reads and
+  # deploys at 62.0 (see scripts/devhub.sh SETTINGS_API_VERSION).
+  minApiVersion: "62.0"
   # Enabling needs ModifyAllData OR ModifyMetadata (either suffices). accessCheck
   # is a flat array with no OR operator, so declaring both would read as AND and
   # could falsely gate an admin holding only one. Declare the canonical
@@ -27,10 +26,12 @@ metadata:
 # Enable Dev Hub & View Scratch Org Allocation
 
 Enable **Dev Hub** on a Salesforce org, verify whether it is already on, and see
-the org's **scratch org allocation** (Active and Daily limits and how many
-remain) — for the default org or a named org. The skill can also configure Dev
-Hub sub-preferences (packaging, org shape export, scratch org snapshots) and
-list the active scratch orgs created from a Dev Hub.
+the org's **scratch org allocation** (Active and Daily limits, how many
+remain, and a pre-flight warning when close to the limit) — for the default
+org or a named org. The skill can also read the org's current **DevHubSettings
+preferences**, configure Dev Hub sub-preferences (packaging, org shape export,
+scratch org snapshots), list the active scratch orgs created from a Dev Hub,
+and list which orgs are authenticated when none is specified.
 
 Dev Hub is the org feature that lets you **create and manage scratch orgs** and
 **second-generation (2GP) / unlocked packages**.
@@ -45,7 +46,9 @@ Trigger on requests like:
   limit?" / "How many scratch orgs do I have left?"
 - "Turn on packaging / 2GP / unlocked packages" / "Enable org shape export" /
   "Enable scratch org snapshots" (Dev Hub sub-preferences).
+- "Which Dev Hub preferences are turned on?" / "Show my current DevHubSettings."
 - "List the scratch orgs on my Dev Hub."
+- "What orgs do I have authenticated?" / "I didn't pass an org — what's available?"
 
 ## When NOT to use
 
@@ -55,9 +58,6 @@ Do **not** trigger this skill for:
   `sf org create scratch` / `sf org delete scratch`, a different workflow. This
   skill enables the *Dev Hub feature* and reports *allocation*; it does not
   create scratch orgs.
-- **Switching the default/active org** — use `dx-org-switch`.
-- **Trial or org expiration dates** ("when does my org expire") — use
-  `dx-org-trial-expiration-check`.
 
 ## How Dev Hub enablement is determined
 
@@ -80,9 +80,12 @@ ScratchOrgInfo` means Dev Hub is **ON**; an `INVALID_TYPE` error means it is
 - **Requires** a user with **ModifyAllData** or **ModifyMetadata** (a **System
   Administrator** has these). A user without them gets `INSUFFICIENT_ACCESS`.
 - **Cannot** be enabled in a **sandbox**, or in an org that has a **registered
-  namespace**.
+  namespace**. The script checks the org's edition/sandbox facts before an
+  `--enable --apply` and refuses (no deploy attempted) if the target is a
+  sandbox; there's no reliable CLI signal for a registered namespace, so that
+  stays a documented caveat rather than an enforced check.
 - Available in **Developer, Enterprise, Performance, Unlimited**, and **trial**
-  editions.
+  editions — `status` and `--allocation` show the org's edition when known.
 
 ## Steps
 
@@ -96,36 +99,45 @@ ScratchOrgInfo` means Dev Hub is **ON**; an `INVALID_TYPE` error means it is
    containing this SKILL.md).
 
    ```bash
-   bash "<skill_dir>/scripts/devhub.sh" <alias-or-username>            # status: on? + allocation
+   bash "<skill_dir>/scripts/devhub.sh" <alias-or-username>            # status: on? + edition + allocation
    bash "<skill_dir>/scripts/devhub.sh"                               # default org (target-org)
-   bash "<skill_dir>/scripts/devhub.sh" <org> --allocation           # allocation only
+   bash "<skill_dir>/scripts/devhub.sh" <org> --allocation           # allocation + pre-flight warnings
+   bash "<skill_dir>/scripts/devhub.sh" <org> --show-settings        # current DevHubSettings preferences
+   bash "<skill_dir>/scripts/devhub.sh" --list-orgs                  # authenticated orgs (no org needed)
    bash "<skill_dir>/scripts/devhub.sh" <org> --enable               # validate enabling (dry run)
    bash "<skill_dir>/scripts/devhub.sh" <org> --enable --apply       # actually enable (irreversible)
    bash "<skill_dir>/scripts/devhub.sh" <org> --list-scratch         # list active scratch orgs
-   bash "<skill_dir>/scripts/devhub.sh" <alias> --instance-url <url> --enable --apply  # log in first, then enable
-   bash "<skill_dir>/scripts/devhub.sh" <url>                        # bare instance URL: log in to it
    ```
 
-   When the user supplies an instance URL (their My Domain, sandbox, or
-   pre-release/scratch login URL — e.g.
-   `https://my-domain.my.salesforce.com`), pass that exact URL with
-   `--instance-url <url>` — the script accepts Salesforce-owned hostnames and logs in with
-   `sf org login web --instance-url <url>` and then continues. A bare URL
-   positional is accepted as shorthand for the same thing.
-
    `<skill_dir>` is the absolute path to the directory containing this SKILL.md.
 
 2. **For enablement, default to a dry run first.** Run `--enable` (no `--apply`)
    to validate the deploy, then relay the result. Because enabling is
    **irreversible**, only run `--enable --apply` when the user has clearly asked
    to actually enable Dev Hub. Applied operations require an explicit org alias
-   or username; the script refuses to mutate an implicit default org. If the
-   deploy is rejected for permissions, surface the Setup-UI fallback it prints.
-
-3. Relay the script output. When an org can't be queried, surface the
-   `sf org login web` command the script prints so the user can authenticate.
-   Pick optional flags based on the request (see below): `--allocation` for
-   limits only, `--list-scratch` to enumerate scratch orgs, `--packaging` /
+   or username; the script refuses to mutate an implicit default org. The
+   script also refuses to enable on a **sandbox** — it checks the org's edition
+   facts first and returns an eligibility explanation instead of deploying, and
+   `status` on a sandbox reports the same ineligibility. When the target is
+   ineligible (a sandbox, or an org with a registered namespace), **declining to
+   enable is the correct, complete outcome even if the user explicitly asked to
+   apply it** — do not deploy. Give a full answer that (1) states Dev Hub
+   **cannot** be enabled on this org, (2) says **why** (a sandbox cannot host a
+   Dev Hub; a registered namespace also blocks it), and (3) gives the
+   **alternative** — enable Dev Hub on the source **production** org, or a
+   **Developer Edition / trial** org, with a **System Administrator**, and use
+   that as the Dev Hub. Do not report a scratch-org allocation for an ineligible
+   org. If the deploy is rejected for permissions, surface the Setup-UI fallback
+   it prints.
+
+3. Relay the script output. When an org can't be authenticated, the script
+   never logs in on its own — it prints the exact `sf org login web` command as
+   guidance; surface that command to the user so they can run it themselves,
+   then re-run the skill. When no org and no default are configured, it also
+   lists the authenticated orgs it found so the user can pick one. Pick
+   optional flags based on the request (see below): `--allocation` for limits
+   only, `--show-settings` for current preference values, `--list-orgs` for
+   discovery, `--list-scratch` to enumerate scratch orgs, `--packaging` /
    `--snapshots` / `--shape` to turn on sub-preferences, `--json` for automation.
 
 ## Before you finish
@@ -134,15 +146,18 @@ Verify these before returning your answer:
 
 - [ ] **CRITICAL:** Invoked the helper via its **absolute path** (`bash "<skill_dir>/scripts/devhub.sh" …`), never `./scripts/` (the script rejects a non-absolute `$0`).
 - [ ] Did **not** run `--apply` unless the user clearly asked to actually enable Dev Hub or deploy a preference — enabling is **irreversible**.
-- [ ] Relayed the script's own output (status/allocation or the login/Setup-UI guidance it printed), rather than substituting a hand-written answer.
+- [ ] Did **not** attempt to log in on the user's behalf — if the org isn't authenticated, relayed the `sf org login web` guidance the script printed instead of running it.
+- [ ] Relayed the script's own output (status/allocation/settings, the pre-flight warnings, the discovered orgs, the sandbox-eligibility refusal, or the login/Setup-UI guidance it printed), rather than substituting a hand-written answer.
 
 ## Options
 
 | Flag | Purpose |
 |------|---------|
-| `--allocation`, `-A` | Show only the scratch org allocation (Active/Daily). |
+| `--allocation`, `-A` | Show only the scratch org allocation (Active/Daily), including pre-flight `WARN`/`NOTE` lines when close to the limit. |
+| `--show-settings`, `-s` | Show the org's current `DevHubSettings` preference values (packaging, snapshots, shape, etc.), ON/OFF. Requires Dev Hub to already be enabled. |
+| `--list-orgs` | List authenticated orgs (alias, username, connected status, default marker). No target org required. |
 | `--list-scratch`, `-l` | List active scratch orgs created from this Dev Hub. |
-| `--enable`, `-e` | Enable Dev Hub (deploys `enableScratchOrgManagementPref=true`). Dry run unless `--apply`. |
+| `--enable`, `-e` | Enable Dev Hub (deploys `enableScratchOrgManagementPref=true`). Dry run unless `--apply`; refuses on a sandbox. |
 | `--configure`, `-c` | Configure sub-preferences without (re)enabling the master switch. Pair with a pref flag. |
 | `--packaging` | `enablePackaging2=true` (Unlocked + 2GP packages). |
 | `--snapshots` | `enableScratchOrgSnapshotPref=true`. |
@@ -150,8 +165,6 @@ Verify these before returning your answer:
 | `--scratch-management` | `enableScratchOrgManagementPref=true` (the Dev Hub switch). |
 | `--pref KEY=VALUE` | Any `DevHubSettings` sub-pref (KEY starts with `enable`, VALUE `true`/`false`). Repeatable. |
 | `--apply` | Actually deploy to the explicit org argument. Default for `--enable`/`--configure` is a validate-only dry run. |
-| `--login` | Authenticate an org first via `sf org login web` (opens a browser), then run the action. |
-| `--instance-url <url>` | Log in to a specific instance (My Domain, sandbox, or pre-release/scratch instance) with `sf org login web --instance-url <url>`. Implies `--login`. |
 | `--json` | Emit machine-readable JSON. |
 | `--fail-if-disabled` | Exit `3` if Dev Hub is not enabled (CI/cron gate). |
 | `--help`, `-h` | Show usage. |
@@ -171,8 +184,12 @@ keep this workflow lean.
 ## Structured output for automation (`--json`)
 
 Use `--json` in any mode for machine-readable output (no prose). Status returns
-`devHubEnabled`, `status`, and an `allocation` object; enablement returns
-`success`, `applied`, and `devHubVerifiedState`. Deterministic, no LLM needed.
+`devHubEnabled`, `status`, `edition`, `isSandbox`, and an `allocation` object
+(with `usedPct` per limit and a `warnings` array); `--show-settings` returns
+`org` and a `settings` map of preference key → boolean; `--list-orgs` returns
+a normalized array of `{alias, username, connectedStatus, isDefault}`;
+enablement returns `success`, `applied`, and `devHubVerifiedState`.
+Deterministic, no LLM needed.
 
 ```bash
 bash "<skill_dir>/scripts/devhub.sh" my-devhub --json
@@ -189,59 +206,41 @@ Hub is not enabled, so a scheduled job can gate on it.
 - `2` bad usage or a missing dependency (`sf` or `jq`)
 - `3` Dev Hub is not enabled (only when `--fail-if-disabled` is set)
 
-## Authentication
+## Authentication (guidance only)
 
-If the org isn't authenticated yet, the skill can log in for you with
-`--login` (or `--instance-url <url>`), then continue with the requested action
-in the same run — this is the preferred path when the user provides an instance
-URL:
-
-Substitute the user's actual instance URL for `<url>` (shown here as the generic
-`https://my-domain.my.salesforce.com` placeholder):
-
-```bash
-# Log in to a specific instance (My Domain / pre-release / sandbox), then enable:
-bash "<skill_dir>/scripts/devhub.sh" my-alias \
-  --instance-url https://my-domain.my.salesforce.com --enable --apply
-
-# Bare instance URL as shorthand — logs in to it, then reports status:
-bash "<skill_dir>/scripts/devhub.sh" https://my-domain.my.salesforce.com
-
-# Just authenticate an org (no other action):
-bash "<skill_dir>/scripts/devhub.sh" my-alias --login
-```
-
-`sf org login web` opens a browser for the OAuth flow; complete it promptly (the
-session times out). A supplied positional (`my-alias`) becomes the CLI alias; a
-positional that looks like a URL (contains `://`) is taken as the
-`--instance-url` to log in to. The script accepts only HTTPS Salesforce-owned
-hostnames for this option. Omit `--instance-url` for standard
-production/DE/trial logins (`login.salesforce.com`). If the browser flow keeps
-timing out, the script prints the `sf org login device` fallback for a
-code-based login.
-
-If an org isn't authenticated and no login flag was passed, the script instead
-prints the exact command to log in and re-run — using the instance URL you
-supplied when there is one:
+This skill **never runs an interactive login itself** — it has no `--login` or
+`--instance-url` flag, and it never invokes `sf org login web` or
+`sf org login device`. If the target org can't be queried (not authenticated,
+expired session, wrong instance), the script prints the exact login command as
+copy-paste **guidance** and stops; relay that command to the user and let them
+run it, then re-run the skill:
 
 ```text
   my-org                         could not query org (...)
 
-  To authenticate against https://my-domain.my.salesforce.com, run:
-    sf org login web --instance-url "https://my-domain.my.salesforce.com" --alias "my-org"
-  Or let this script log you in and continue in one step:
-    devhub.sh "my-org" --instance-url "https://my-domain.my.salesforce.com" --login
-  Then re-run. List existing logins with:  sf org list
+  This org is not authenticated (or the session expired). Authentication is
+  a precondition for this skill — run one of these yourself, then re-run:
+    sf org login web --alias 'my-org'                                             # prod / DE / trial
+    sf org login web --alias <my-alias> --instance-url https://MYDOMAIN.my.salesforce.com   # sandbox / My Domain
+  List existing logins with:  sf org list
 ```
 
+When no org and no default is configured at all, the script also runs org
+discovery (`--list-orgs`) and lists the authenticated orgs it found, so the
+user can pick one instead of guessing an alias.
+
 ## Manual fallback (if the script is unavailable)
 
 ```bash
 # Detect Dev Hub (INVALID_TYPE error means OFF; a count means ON):
 sf data query --query "SELECT COUNT() FROM ScratchOrgInfo" --target-org <org> --json
 
+# Read current DevHubSettings preferences (requires Dev Hub already ON):
+sf api request rest "/services/data/v62.0/tooling/sobjects/DevHubSettings/DevHub" \
+  --target-org <org> --json
+
 # Enable Dev Hub via the Tooling API (what the Setup toggle does; irreversible):
-sf api request rest "/services/data/v47.0/tooling/sobjects/DevHubSettings/DevHub" \
+sf api request rest "/services/data/v62.0/tooling/sobjects/DevHubSettings/DevHub" \
   --method PATCH \
   --body '{"FullName":"DevHub","Metadata":{"enableScratchOrgManagementPref":true}}' \
   --target-org <org>
@@ -250,12 +249,16 @@ sf api request rest "/services/data/v47.0/tooling/sobjects/DevHubSettings/DevHub
 
 # View scratch org allocation:
 sf org list limits --target-org <org> --json | jq '.result[] | select(.name|test("ScratchOrg"))'
+
+# List authenticated orgs:
+sf org list --json
 ```
 
 ## Notes
 
 - Requires the Salesforce CLI (`sf`) and `jq` on the PATH, plus at least one
-  authenticated org (`sf org login web`).
+  authenticated org. This skill only ever prints the `sf org login web`
+  command as guidance — it never runs it.
 - After enabling, set the org as your default Dev Hub:
   `sf config set target-dev-hub <org>`.
 - Enabling **packaging** (`enablePackaging2`) requires Dev Hub to be on first —
@@ -263,5 +266,3 @@ sf org list limits --target-org <org> --json | jq '.result[] | select(.name|test
 - Non-admin users still need object access (Read/Create on `ScratchOrgInfo` and
   `ActiveScratchOrg`) to create/view scratch orgs, and the "Create and Update
   Second-Generation Packages" permission to build 2GP/unlocked packages.
-- To *switch* the default org use `dx-org-switch`; to check *expiration* use
-  `dx-org-trial-expiration-check`.

package/skills/dx-org-devhub-configure/examples/status-output.md

@@ -5,26 +5,49 @@ These are reference only — the script prints the authoritative output at runti
 
 ## Dev Hub is ON (status + allocation)
 
+`status` mode prints the enablement line, the org edition, the signup-record
+count, a one-line summary of which preferences are on, and the allocation table.
+
 ```text
 Dev Hub status for 'MyDevHub':
   Dev Hub: ENABLED  (ScratchOrgInfo is queryable)
+  Edition: Developer Edition
   Scratch org signup records: 3
+  Enabled preferences: enableScratchOrgManagementPref enableScratchOrgSnapshotPref
 
 Scratch org allocation for 'MyDevHub':
   Limit                        Used  Remaining        Max
-  Active scratch orgs             0          3          3
-  Daily scratch orgs              0          6          6
+  Active scratch orgs             2          1          3
+  Daily scratch orgs              5          1          6
+  WARN: only 1 active scratch org(s) remaining.
+  NOTE: Daily scratch org usage at 83% (5/6).
 
   Active = orgs alive right now; Daily = successful creations in a rolling 24h window.
   Allocation is set by the Dev Hub's edition (e.g. Developer/trial 3 & 6;
   Enterprise 40 & 80; Unlimited/Performance 100 & 200) plus any purchased add-on.
 ```
 
+## Current preferences (`--show-settings`)
+
+`--show-settings` prints every `DevHubSettings` preference with an explicit
+ON/OFF, one per line (requires Dev Hub to already be enabled).
+
+```text
+DevHub preferences for 'MyDevHub':
+  enableScratchOrgManagementPref     ON
+  enablePackaging2                   OFF
+  enableScratchOrgSnapshotPref       ON
+  enableShapeExportPref              OFF
+```
+
 ## Dev Hub is OFF (prints how to enable it)
 
 ```text
 Dev Hub status for 'my-org':
   Dev Hub: NOT ENABLED
+  Detection: ScratchOrgInfo is queryable only when Dev Hub is on. A successful count means ENABLED. An INVALID_TYPE error means NOT ENABLED. Scratch org limits are not used, because they are reported even when Dev Hub is off.
+
+  Scratch org allocation, Dev Hub preferences, and the scratch org list are not available until Dev Hub is enabled. An empty allocation or a failed exit from those modes means Dev Hub is off, not that the org is unauthenticated.
 
   Enable it (deploys enableScratchOrgManagementPref=true; irreversible):
     devhub.sh "my-org" --enable            # validate first (dry run)