@salesforce/afv-skills 1.67.0 → 1.68.0

package/skills/dx-org-devhub-configure/scripts/test-devhub.sh

@@ -16,13 +16,28 @@ printf '%s\n' "$*" >> "$SF_STUB_LOG"
 
 case "$*" in
   "config get target-org --json")
-    printf '%s\n' '{"status":0,"result":[{"value":"default-org"}]}'
+    if [ "${SF_TEST_NO_DEFAULT:-0}" = "1" ]; then
+      printf '%s\n' '{"status":0,"result":[]}'
+    else
+      printf '%s\n' '{"status":0,"result":[{"value":"default-org"}]}'
+    fi
     ;;
   "config get target-dev-hub --json")
-    printf '%s\n' '{"status":0,"result":[{"value":"default-devhub"}]}'
+    if [ "${SF_TEST_NO_DEFAULT:-0}" = "1" ]; then
+      printf '%s\n' '{"status":0,"result":[]}'
+    else
+      printf '%s\n' '{"status":0,"result":[{"value":"default-devhub"}]}'
+    fi
     ;;
-  org\ login\ web*)
-    printf '%s\n' '{"status":0,"result":{"username":"logged-in@example.com"}}'
+  "org list --json")
+    if [ "${SF_TEST_HANG:-0}" = "1" ]; then
+      sleep 60
+    fi
+    if [ "${SF_TEST_NO_ORGS:-0}" = "1" ]; then
+      printf '%s\n' '{"status":0,"result":{"nonScratchOrgs":[],"scratchOrgs":[]}}'
+    else
+      printf '%s\n' '{"status":0,"result":{"nonScratchOrgs":[{"alias":"my-org","username":"a@b.com","connectedStatus":"Connected","isDefaultUsername":true}],"scratchOrgs":[]}}'
+    fi
     ;;
   "data query --query SELECT COUNT() FROM ScratchOrgInfo"*)
     if [ "${SF_TEST_DEVHUB_ENABLED:-0}" = "1" ]; then
@@ -32,12 +47,18 @@ case "$*" in
       exit 1
     fi
     ;;
+  "data query --query SELECT OrganizationType, IsSandbox FROM Organization"*)
+    printf '%s\n' "{\"status\":0,\"result\":{\"records\":[{\"OrganizationType\":\"Developer Edition\",\"IsSandbox\":${SF_TEST_SANDBOX:-false}}]}}"
+    ;;
+  "api request rest /services/data/"*"/tooling/sobjects/DevHubSettings/DevHub"*)
+    printf '%s\n' '{"Id":"DevHub","FullName":"DevHub","Metadata":{"enableScratchOrgManagementPref":true,"enablePackaging2":false,"enableScratchOrgSnapshotPref":true,"enableShapeExportPref":false}}'
+    ;;
   "org list limits"*)
     if [ "${SF_TEST_LIMITS_FAIL:-0}" = "1" ]; then
       printf '%s\n' '{"status":1,"message":"limits unavailable"}'
       exit 1
     fi
-    printf '%s\n' '{"status":0,"result":[{"name":"ActiveScratchOrgs","remaining":3,"max":3},{"name":"DailyScratchOrgs","remaining":6,"max":6}]}'
+    printf '%s\n' "{\"status\":0,\"result\":[{\"name\":\"ActiveScratchOrgs\",\"remaining\":${SF_TEST_ACTIVE_REM:-3},\"max\":${SF_TEST_ACTIVE_MAX:-3}},{\"name\":\"DailyScratchOrgs\",\"remaining\":${SF_TEST_DAILY_REM:-6},\"max\":${SF_TEST_DAILY_MAX:-6}}]}"
     ;;
   "org display"*)
     printf '%s\n' '{"status":0,"result":{"id":"00D000000000001","username":"admin@example.com","instanceUrl":"https://example.my.salesforce.com"}}'
@@ -79,7 +100,7 @@ check "reject disabling the master switch" 2 "cannot be set to false" \
   "$SCRIPT" explicit-org --pref enableScratchOrgManagementPref=false
 
 check "warn for scratch-management apply" 0 "IRREVERSIBLE" \
-  "$SCRIPT" explicit-org --scratch-management --apply
+  env SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT" explicit-org --scratch-management --apply
 
 check "propagate status allocation failure" 1 "Could not read org limits" \
   env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_LIMITS_FAIL=1 "$SCRIPT" explicit-org
@@ -87,23 +108,87 @@ check "propagate status allocation failure" 1 "Could not read org limits" \
 check "require explicit target for apply" 2 "explicit org" \
   "$SCRIPT" --enable --apply
 
-check "reject non-Salesforce login origin" 2 "Salesforce hostname" \
-  "$SCRIPT" explicit-org --instance-url https://attacker.example --login
+# --- new: read current DevHubSettings preferences ---
+check "show-settings renders master pref ON" 0 "enableScratchOrgManagementPref" \
+  env SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT" explicit-org --show-settings
+check "show-settings renders packaging OFF" 0 "enablePackaging2                   OFF" \
+  env SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT" explicit-org --show-settings
 
-check "login-only exits after authentication" 0 "Authenticated" \
+# --- new: pre-flight allocation thresholds ---
+check "threshold WARN under 2 remaining" 0 "WARN" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_ACTIVE_REM=1 SF_TEST_ACTIVE_MAX=3 "$SCRIPT" explicit-org --allocation
+check "threshold NOTE above 80 percent" 0 "usage at" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_ACTIVE_REM=0 SF_TEST_ACTIVE_MAX=3 "$SCRIPT" explicit-org --allocation
+
+# --- new: sandbox refuses enablement, before any deploy ---
+: > "$LOG_FILE"
+sandbox_out="$(env SF_TEST_DEVHUB_ENABLED=0 SF_TEST_SANDBOX=true "$SCRIPT" explicit-org --scratch-management --apply 2>&1)"
+sandbox_rc=$?
+if [ "$sandbox_rc" -eq 1 ] && printf '%s' "$sandbox_out" | grep -qi "sandbox" && ! grep -Fq "project deploy start" "$LOG_FILE"; then
+  pass=$((pass + 1)); printf 'PASS: sandbox refuses enablement without deploying\n'
+else
+  fail=$((fail + 1)); printf 'FAIL: sandbox refuses enablement (exit %s)\n%s\n' "$sandbox_rc" "$sandbox_out"
+fi
+
+# --- new: org discovery when no default is set ---
+check "org discovery lists authenticated orgs" 2 "my-org" \
+  env SF_TEST_NO_DEFAULT=1 SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT"
+
+check "list-orgs mode lists authenticated orgs" 0 "my-org" \
+  "$SCRIPT" --list-orgs
+
+# --- removed: login flags are now unknown options ---
+check "login flag rejected" 2 "Unknown option" \
   "$SCRIPT" explicit-org --login
-if grep -Fq "data query" "$LOG_FILE"; then
-  fail=$((fail + 1))
-  printf 'FAIL: login-only queried org status\n'
+check "instance-url flag rejected" 2 "Unknown option" \
+  "$SCRIPT" explicit-org --instance-url https://x.my.salesforce.com
+
+# --- new: show-settings refuses when Dev Hub is OFF ---
+check "show-settings refuses when Dev Hub off" 1 "no DevHubSettings to read" \
+  env SF_TEST_DEVHUB_ENABLED=0 "$SCRIPT" explicit-org --show-settings
+
+# --- new: daily-limit NOTE threshold (only active was covered before) ---
+check "threshold NOTE daily above 80 percent" 0 "Daily scratch org usage at" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_DAILY_REM=1 SF_TEST_DAILY_MAX=6 "$SCRIPT" explicit-org --allocation
+
+# --- new: list-orgs with no authenticated orgs ---
+check "list-orgs reports none authenticated" 0 "No orgs are authenticated" \
+  env SF_TEST_NO_ORGS=1 "$SCRIPT" --list-orgs
+
+# A hung CLI must not hold the caller for the full stub sleep.
+hang_start=$(date +%s)
+hang_out="$(env SF_TEST_HANG=1 "$SCRIPT" --list-orgs 2>&1)"
+hang_rc=$?
+hang_elapsed=$(( $(date +%s) - hang_start ))
+if [ "$hang_rc" -eq 1 ] && [ "$hang_elapsed" -lt 35 ] && printf '%s' "$hang_out" | grep -Fq "Could not list authenticated orgs"; then
+  pass=$((pass + 1)); printf 'PASS: list-orgs bounds a hung sf org list (%ss)\n' "$hang_elapsed"
 else
-  pass=$((pass + 1))
-  printf 'PASS: login-only skipped org status\n'
+  fail=$((fail + 1)); printf 'FAIL: list-orgs bounds a hung sf org list (exit %s, %ss)\n%s\n' "$hang_rc" "$hang_elapsed" "$hang_out"
 fi
 
+# --- new: JSON fidelity for the added fields ---
+check "status JSON reports edition" 0 "\"edition\": \"Developer Edition\"" \
+  env SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT" explicit-org --json
+check "status JSON reports isSandbox false (not null) for non-sandbox" 0 "\"isSandbox\": false" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_SANDBOX=false "$SCRIPT" explicit-org --json
+check "status JSON reports isSandbox true for sandbox" 0 "\"isSandbox\": true" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_SANDBOX=true "$SCRIPT" explicit-org --json
+check "allocation JSON emits warnings array near limit" 0 "\"warnings\"" \
+  env SF_TEST_DEVHUB_ENABLED=1 SF_TEST_ACTIVE_REM=1 SF_TEST_ACTIVE_MAX=3 "$SCRIPT" explicit-org --allocation --json
+check "show-settings JSON emits settings map" 0 "enableScratchOrgSnapshotPref" \
+  env SF_TEST_DEVHUB_ENABLED=1 "$SCRIPT" explicit-org --show-settings --json
+check "list-orgs JSON emits normalized array" 0 "\"isDefault\"" \
+  "$SCRIPT" --list-orgs --json
+
+# --- new: a not-enabled sandbox is flagged as ineligible in status ---
+check "status flags sandbox as unable to host Dev Hub" 0 "cannot host Dev Hub" \
+  env SF_TEST_DEVHUB_ENABLED=0 SF_TEST_SANDBOX=true "$SCRIPT" explicit-org
+
+# --- safety: cleanup trap treats TMPDIR content as data ---
 unsafe_tmp="$WORK_DIR/unsafe'; touch $MARKER; #"
 mkdir -p "$unsafe_tmp"
 check "cleanup trap does not execute TMPDIR content" 0 "Dry run passed" \
-  env TMPDIR="$unsafe_tmp" "$SCRIPT" explicit-org --packaging
+  env SF_TEST_DEVHUB_ENABLED=1 TMPDIR="$unsafe_tmp" "$SCRIPT" explicit-org --packaging
 if [ -e "$MARKER" ]; then
   fail=$((fail + 1))
   printf 'FAIL: cleanup trap executed TMPDIR content\n'

package/skills/dx-packaging-move-to-2gp-migrate/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dx-packaging-move-to-2gp-migrate
+description: "Use this skill when users want to finalize the irreversible, one-way Move-to-2GP cutover for a converted 1GP managed package — afterward, new major/minor 1GP versions can NEVER be created. Also use when an ISV admin asks to move a 1GP package to 2GP development. TRIGGER when: the user asks to move, finalize, or complete the move of a converted 1GP managed package to 2GP development, asks how to move a package to 2GP, or asks whether their converted package is eligible to move to 2GP. DO NOT TRIGGER for: converting a 1GP package to 2GP in the first place, creating or promoting 2GP package versions, packaging UI bundles (use experience-ui-bundle-2gp-deploy), enabling Dev Hub (use dx-org-devhub-configure), or post-install configuration (use dx-pkg-post-install-configure)."
+metadata:
+  relatedSkills:
+  - dx-org-devhub-configure
+  - dx-pkg-post-install-configure
+  - experience-ui-bundle-2gp-deploy
+  version: "1.0"
+  accessCheck: "UserPermissions.CreatePackaging"
+  cliTools:
+  - tool:
+    - "sf"
+    semver: ">=2.0.0"
+  domains:
+  - "Developer Experience"
+---
+
+
+# Move to 2GP Development
+
+## When to Use This Skill
+
+Finalize the irreversible, one-way Move-to-2GP cutover for a converted 1GP managed package — afterward, new major/minor 1GP versions can NEVER be created. Use when an ISV admin asks to move a 1GP package to 2GP development. The agent dispatches the finalize directly via the packaging Connect API (POST /connect/packaging/package/{packageId}/finalize-move-to-2gp, shipped 266) after clearing the eligibility + conversion/subscriber-migration-testing gates and obtaining the three explicit affirmations the endpoint requires; it then wire-verifies the result against PackageConversion.EndDate (read-only Tooling exposure, shipped 264).
+
+## Workflow
+
+---
+BACKEND / VERSIONING MECHANICS (relocated from the discover card — describe-only, never shown on the card):
+- FINALIZE DISPATCH (266+): the agent-dispatchable path is the packaging Connect API POST /services/data/v69.0/connect/packaging/package/{packageId}/finalize-move-to-2gp (operationId finalizeMoveTo2gp), which runs against the 1GP DE org. The endpoint enforces the CreatePackaging edit-access gate, requires all three affirmation flags true, and verifies the {packageId} in the URL matches the package the org is currently converting — a mismatch returns 400. On success it finalizes the conversion, after which PackageConversion.EndDate is set (observable via verify-finalize-on-packaging-org). It performs the same finalize action that was previously available only through the Setup UI's Move-to-2GP dialog.
+- PRE-266 HISTORY / FALLBACK: before 266 no public agent-dispatchable API existed — finalize was available only as a Setup-page action the user completed in the browser, with no stable programmatic contract. The fallback delivers the user to the package's Setup detail page at `/udd/AllPackage/viewAllPackage.apexp` (any authenticated browser session to the packaging org reaches it), which hosts the "Move to Second-Generation Managed Packaging" dialog and its Proceed action. This remains the fallback for orgs on a pre-266 release.
+- CANNOT-CREATE BOUNDARY, MECHANICS: after finalize, new major/minor 1GP versions cannot be created — neither via `sf package1 version create` nor via the major/minor upload flow on viewAllPackage.apexp; all new major/minor innovation must use 2GP via `sf package version create`. Customers running on prior 1GP versions are unaffected.
+- PATCH EXCEPTION (surface conversationally only when the user asks e.g. "can I still cut a patch?"): PATCH versions of major.minor versions that existed BEFORE finalize remain permitted, to hotfix 1GP subscribers not yet migrated to 2GP. This exception is intentionally NOT part of the affirmation prompt the user confirms (the Setup dialog uses the same headline framing) — never put it in the affirmation.
+- ELIGIBILITY GATE (3-part proactive pre-check, two-org query): (a) the 1GP package's highest Released major.minor version, queried from the 1GP DE org via MetadataPackageVersion; (b) a corresponding 2GP-converted Package2Version at the same major.minor on DevHub, AND that 2GP version is Released; (c) no native 2GP version exists yet on DevHub (its presence means Move-to-2GP already happened — early exit). Parts (b)/(c) are the DevHub-side pre-check: run them when DevHub is authenticated to give the user a clear up-front answer; if (a) or (b) fails, surface what's missing + the fix (typically promote the converted 2GP version to Released). When DevHub is unavailable, this proactive check is skipped and the finalize endpoint enforces the same eligibility server-side (→ 400 on mismatch). DevHub eligibility queries hit the Package2 / Package2Version 0Ho-prefix entity.
+- PRE-FLIGHT (mandatory): Salesforce docs state "Before you complete your move to 2GP package development, it's critical that you thoroughly test package conversions and subscriber migrations first." Never invoke the manual step without explicit user affirmation that conversion + subscriber-migration testing is complete.
+- RELEASE HISTORY (both milestones shipped): 264 exposed the PackageConversion object read-only via the Tooling API (available when packaging is enabled for the org), lighting up verify-finalize-on-packaging-org as an EndDate-based wire-verify. 266 shipped the Connect API finalize endpoint POST /services/data/v69.0/connect/packaging/package/{packageId}/finalize-move-to-2gp (operationId finalizeMoveTo2gp), driven by the 1GP MetadataPackage Id (033-prefix) with the three affirmation flags in the request body; finalize-move-to-2gp dispatches invocation.kind: rest, is status: implemented, and the skill is now fully agent-driveable end-to-end. The manual browser fallback path is retained only as a pre-266 fallback.
+- WIRE-VERIFICATION (264+): the canonical post-finalize signal is PackageConversion.EndDate (non-null) on the 1GP DE org, queryable via the read-only Tooling exposure shipped in 264. The finalize endpoint's own response also returns finalizedAt + conversionId directly. Move-to-2GP does NOT auto-create a native (non-converted) Package2Version on DevHub — native versions are created later by a separate user-driven `sf package version create`, so their absence immediately post-finalize is expected, not a failure signal (i.e. there is no Package2Version-based wire-verify; EndDate is the reliable signal). verify-finalize-by-user-confirmation remains available as an optional human cross-check but is no longer the only verification surface.
+- ORG REACHABILITY (auth mechanism is agent's choice, not `sf`-specific): only the 1GP DE (packaging) org is genuinely required — it backs the 266 Connect finalize endpoint, the read-only PackageConversion wire-verify (264), the 1GP-side eligibility query (MetadataPackageVersion), and the browser Setup page for the pre-266 fallback. Reachability can come from an `sf` alias OR any valid bearer token for the org (raw REST); the skill is not coupled to the `sf` CLI. The DevHub org (Package2 / Package2Version) is OPTIONAL — it only enables the proactive eligibility pre-check; when it is absent the finalize endpoint still validates eligibility server-side (a not-yet-converted/not-promoted package → 400), so the skill can proceed DevHub-less. This also sidesteps the multi-org-auth burden of skills that hard-require two authenticated orgs.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- REQUIRED: the 1GP DE (packaging) org must be reachable with valid credentials. This is the one org the finalize path needs — an `sf` alias is the convenient way to authenticate, but the skill is NOT coupled to the `sf` CLI: any caller that can present a valid bearer token for this org (e.g. a raw REST call) works equally. The 1GP DE org hosts MetadataPackageVersion (the authoritative highest-Released 1GP version for the eligibility gate), is the org the finalize Connect API endpoint (266) runs against, hosts the read-only PackageConversion Tooling exposure (264) the wire-verify queries, and is the org the pre-266 manual browser fallback opens. (check: `PackagingOrgAuthenticated`)
+- OPTIONAL (recommended): authenticating the DevHub org lets the agent proactively pre-check eligibility before dispatching finalize — the converted 2GP Package2Version at the matching major.minor exists and is Released (Package2 + Package2Version live on DevHub). It is NOT a hard prerequisite: if DevHub is unavailable the skill can still finalize, because the Connect endpoint validates eligibility server-side and returns a 400 with a specific reason (e.g. version mismatch) when the latest released version has not been converted + promoted. Skipping the pre-check trades a clear up-front message for a server-side reject; it does not make the workflow unsafe (the irreversibility is gated by the three affirmations, not by DevHub). (check: `DevHubOrgAuthenticated`)
+- User must have the CreatePackaging user permission (which implies CustomizeApplication) plus dev-org ownership of the package. This is the exact edit-access gate the finalize Connect endpoint enforces server-side — the same edit-access check the package's Setup detail page applies. A caller lacking it gets a 403 from the endpoint before any state is inspected (note: sysadmins do NOT clear this gate — edit access is org-dev scoped, not sysadmin-scoped). (check: `UserPermissions.CreatePackaging`)
+- Package conversion testing must be complete. Per the Salesforce documentation, "Before you complete your move to 2GP package development, it's critical that you thoroughly test package conversions and subscriber migrations first." An agent MUST explicitly confirm this with the user before proceeding to the finalize step. See "Test Converted Packages and Subscriber Migrations" (linked from the workflow doc) for the testing checklist. (check: `ConversionTestingComplete`)
+- Source files for the package's latest converted version should be retrieved before finalize. Per the docs, the user runs `sf package version retrieve --package 04tXXX --output-dir my-folder --target-dev-hub <devhub>` to retrieve, then edits sfdx-project.json's versionName, versionNumber, and ancestorVersion. This is preparatory work for ongoing 2GP development AFTER finalize, but the doc places it in the workflow sequence — the agent should remind the user. (check: `PackageSourceRetrievedAndProjectFileUpdated`)
+
+**Operational rules:**
+
+- AT START — the finalize path needs ONE org: the 1GP DE (packaging) org, reachable with valid credentials. A DevHub org is OPTIONAL-but-recommended, used only to proactively pre-check eligibility. Auth is not coupled to the `sf` CLI: an `sf` alias is convenient, but any valid bearer token for the org works for a raw REST call. Ask the user for the packaging-org alias (and, if they want the eligibility pre-check, the DevHub alias) at the start if not already provided; `sf org list --json` confirms what's authed. If the packaging org is missing, instruct the user to make it reachable (e.g. `sf org login web --alias <name>`) and wait. If only DevHub is missing you may still finalize — skip the DevHub-side eligibility queries and rely on the endpoint's server-side validation (a not-yet-converted/not-promoted package returns a 400 with a specific reason), and tell the user the proactive pre-check was skipped.
+MULTI-ORG DISPATCH (read once, important): this workflow spans two orgs — the 1GP DE (packaging) org and the DevHub org. Each step's `invocation` block carries a `target_org` field naming which org the call must hit (`{packaging_org_alias}` vs `{devhub_alias}`); route each call to the org its `target_org` names rather than assuming a single org for the whole workflow. Route to the DevHub org: discover-package-on-devhub, check-eligibility-2gp-converted-released, and check-already-done. Route to the packaging org: check-eligibility-1gp-released, finalize-move-to-2gp, and verify-finalize-on-packaging-org. If your execution channel can only reach one connected org at a time, run each off-target read-only step against the org named in its `target_org` before dispatching the finalize against the packaging org; a CLI-driven runner can map that routing onto its own tooling. A step sent to the wrong org returns empty or misleading results.
+TWO ROOT INTENTS — pick by user phrasing.
+INTENT A — "tell me how to move my package to 2GP" (planning /
+  education): walk the user through the full sequence —
+  discover-package-on-devhub → check-eligibility-1gp-released →
+  check-eligibility-2gp-converted-released → check-already-done →
+  remind-of-prerequisites (testing, source retrieval) → describe the
+  manual finalize step in Setup. Treat this as a planning
+  conversation, NOT a dispatch action.
+- INTENT B — "do the move-to-2GP step now" (action request):
+  discover-package-on-devhub → check-eligibility-1gp-released →
+  check-eligibility-2gp-converted-released → check-already-done →
+  confirm-affirmations → finalize-move-to-2gp (direct Connect API
+  dispatch) → verify-finalize-on-packaging-org (wire-verify against
+  PackageConversion.EndDate) → verify-finalize-by-user-confirmation
+  (optional cross-check). The finalize step now dispatches the
+  packaging Connect API POST directly against the 1GP DE org — the
+  agent does NOT open a browser tab in the normal path. It MUST
+  still obtain the three explicit affirmations in confirm-affirmations
+  first (the endpoint requires all three flags true and rejects the
+  call otherwise), then POST, then wire-verify EndDate. The manual
+  browser fallback path is retained only as a fallback for orgs on a
+  pre-266 release (see finalize-move-to-2gp.invocation.fallback).
+- HARD STOP CONTRACT: this workflow is irrevocable. Per the documentation's "After you click Proceed, you can no longer create new major or minor versions in the packaging org." An agent MUST NOT instruct the user to click Proceed in Setup until ALL THREE of the following have been explicitly confirmed: (a) conversion testing is done, (b) subscriber migration testing is done, (c) the user understands the irreversibility. Skipping any of these is a contract violation regardless of how the user phrased the original request.
+EARLY EXIT: if check-already-done returns ≥1 row (a Package2Version exists with ConvertedFromVersionId = NULL), the move-to-2GP has ALREADY been completed — or the package was 2GP-native to start with. Report this to the user and stop. Do NOT proceed to affirmations or finalize.
+ELIGIBILITY GATING: if check-eligibility-1gp-released returns no Released 1GP version, OR if check-eligibility-2gp-converted-released returns no matching Released 2GP-converted version at the same major.minor, the user is NOT eligible to Move to 2GP. Surface the specific missing piece and what to do — typically "you need to promote 2GP version X.Y to Released before you can move-to-2GP." If DevHub is not authenticated, skip the proactive 2GP eligibility query and rely on the endpoint's server-side validation instead — the finalize call returns a 400 with a specific reason (e.g. version mismatch) when the latest released version has not been converted + promoted; relay that message to the user.
+RELEASE HISTORY (both milestones now shipped — describe-only, not an ongoing constraint): 264 shipped the read-only PackageConversion Tooling exposure, lighting up verify-finalize-on-packaging-org (EndDate-based wire-verify). 266 shipped the finalize Connect API — finalize-move-to-2gp now dispatches POST /services/data/v69.0/connect/packaging/package/{packageId}/finalize-move-to-2gp against the 1GP DE org (invocation.kind: rest, operationId finalizeMoveTo2gp, MCP-enabled). The endpoint requires the three affirmation flags (acknowledgedIrrevocable / acknowledgedTestingComplete / acknowledgedSourceRetrieved) all true in the request body, mirroring the Setup dialog's checkboxes — this is the load-bearing safety gate, so the confirm-affirmations step remains mandatory. For orgs still on a pre-266 release, the manual browser fallback applies.
+Only the 1GP DE (packaging) org is required for the finalize dispatch + wire-verify. The DevHub org is optional — used only for the proactive eligibility pre-check; the endpoint validates eligibility server-side regardless.
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `finalize-move-to-2gp`: call `verify-finalize-by-user-confirmation`
+- After `verify-finalize-by-user-confirmation`: call `verify-finalize-on-packaging-org`
+
+Read [Operations reference](references/api-operations.md) before executing this workflow. It contains the original operation definitions, dependencies, inputs, and verification instructions.

package/skills/dx-packaging-move-to-2gp-migrate/references/api-operations.md

@@ -0,0 +1,164 @@
+# Move to 2GP Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `discover-package-on-devhub` | read | implemented | `queryPackage2ByConvertedFrom` | — |
+| `check-eligibility-1gp-released` | validate | implemented | `queryHighestReleased1GPVersion` | `discover-package-on-devhub` |
+| `check-eligibility-2gp-converted-released` | validate | implemented | `queryReleased2GPConvertedVersion` | `check-eligibility-1gp-released` |
+| `check-already-done` | validate | implemented | `queryNativePackage2Version` | `check-eligibility-2gp-converted-released` |
+| `confirm-affirmations` | validate | implemented | — | `check-already-done` |
+| `finalize-move-to-2gp` | write | implemented | `finalizeMoveTo2gp` | `confirm-affirmations` |
+| `verify-finalize-by-user-confirmation` | verify | implemented | — | `finalize-move-to-2gp` |
+| `verify-finalize-on-packaging-org` | verify | implemented | `queryPackageConversion` | `verify-finalize-by-user-confirmation` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  discover_package_on_devhub["discover-package-on-devhub (read)"]
+  check_eligibility_1gp_released["check-eligibility-1gp-released (validate)"]
+  check_eligibility_2gp_converted_released["check-eligibility-2gp-converted-released (validate)"]
+  check_already_done["check-already-done (validate)"]
+  confirm_affirmations["confirm-affirmations (validate)"]
+  finalize_move_to_2gp["finalize-move-to-2gp (write)"]
+  verify_finalize_by_user_confirmation["verify-finalize-by-user-confirmation (verify)"]
+  verify_finalize_on_packaging_org["verify-finalize-on-packaging-org (verify)"]
+  discover_package_on_devhub --> check_eligibility_1gp_released
+  check_eligibility_1gp_released --> check_eligibility_2gp_converted_released
+  check_eligibility_2gp_converted_released --> check_already_done
+  check_already_done --> confirm_affirmations
+  confirm_affirmations --> finalize_move_to_2gp
+  finalize_move_to_2gp --> verify_finalize_by_user_confirmation
+  verify_finalize_by_user_confirmation --> verify_finalize_on_packaging_org
+```
+
+### Read operations
+
+#### `discover-package-on-devhub`
+
+Look up the 2GP Package2 record on DevHub for the 1GP package the user wants to move. The user provides the 1GP package by name (the customer-facing label) or by SubscriberPackageId (the 033... key prefix). Returns the Package2 Id (0Ho... key prefix) and namespace prefix, plus the SubscriberPackageId for use in eligibility queries. This is the DevHub-side anchor for the DevHub-side eligibility checks; the 1GP-side eligibility check uses the SubscriberPackageId (which equals the MetadataPackage Id on the 1GP DE org) directly.
+
+**Call:** `queryPackage2ByConvertedFrom`   — status: `implemented`
+
+**Inputs:**
+
+- `devhub_alias` *(`String`)* — Source: user_input. The `sf` alias of the user's DevHub org. Captured at skill start (see agent_guidance "AT START").
+- `subscriber_package_id` *(`String`)* — The 1GP package's SubscriberPackageId (033... key prefix). User provides this directly, or agent obtains it via a MetadataPackage name lookup on the 1GP DE org (see agent_guidance).
+
+### Write operations
+
+#### `finalize-move-to-2gp`
+
+Irrevocably finalize the Move-to-2GP transition by POSTing to the packaging Connect API endpoint `POST /services/data/v69.0/connect/packaging/package/{packageId}/finalize-move-to-2gp` against the 1GP DE (packaging) org. `{packageId}` is the 1GP MetadataPackage Id (033- prefix). The request body carries the three affirmation flags — acknowledgedIrrevocable, acknowledgedTestingComplete, acknowledgedSourceRetrieved — all required and all must be true (these are exactly what the user confirmed in confirm-affirmations). Server-side the endpoint enforces the CreatePackaging edit-access gate, re-validates the three affirmations, confirms the URL packageId matches the org's in-progress conversion, then finalizes it — after which PackageConversion.EndDate is set. Shipped in 266 (operationId finalizeMoveTo2gp, MCP-enabled). On success returns successfullyFinalized, finalizedAt, packageId, and conversionId. For orgs on a pre-266 release, fall back to the manual browser path (invocation.fallback) which delivers the user to viewAllPackage.apexp to click "Move to 2GP" → Proceed.
+
+**Call:** `finalizeMoveTo2gp`   — status: `implemented`
+
+**Inputs:**
+
+- `packaging_org_alias` *(`String`)* — Source - output of confirm-affirmations (transitively from check-eligibility-1gp-released.packaging_org_alias). The `sf` alias of the user's 1GP DE (packaging) org.
+  - **Source:** output of `check-eligibility-1gp-released`
+- `subscriber_package_id` *(`String`)* — Source - output of confirm-affirmations (transitively from discover-package-on-devhub.subscriber_package_id). The 1GP MetadataPackage's SubscriberPackageId / 033- prefix.
+  - **Source:** output of `discover-package-on-devhub`
+- `acknowledged_irrevocable` *(`Boolean`)* — Source - output of confirm-affirmations (acknowledged_irrevocable).
+- `acknowledged_testing_complete` *(`Boolean`)* — Source - output of confirm-affirmations (acknowledged_testing_complete).
+- `acknowledged_source_retrieved` *(`Boolean`)* — Source - output of confirm-affirmations (acknowledged_source_retrieved).
+
+**Depends on:** `confirm-affirmations`
+
+### Verify operations
+
+#### `verify-finalize-by-user-confirmation`
+
+Human cross-check for the pre-266 manual fallback path ONLY: ask the user what the Setup page showed after they clicked Proceed. This step applies only when finalize-move-to-2gp took its manual browser fallback (org on a pre-266 release). In the normal 266 path the agent dispatches the finalize directly and the user never interacts with a browser, so this step is skipped — the endpoint's own response (successfullyFinalized / finalizedAt / conversionId) plus verify-finalize-on-packaging-org's EndDate wire-verify are the authoritative signals. Retained because the fallback still needs a verification surface when no direct-dispatch response exists.
+
+**Status:** `implemented`
+
+**Inputs:**
+
+- `package_name` *(`String`)* — Source - output of finalize-move-to-2gp (transitively from discover-package-on-devhub.package_name).
+  - **Source:** output of `discover-package-on-devhub`
+
+**Depends on:** `finalize-move-to-2gp`
+
+#### `verify-finalize-on-packaging-org`
+
+The canonical wire-verification: re-query the PackageConversion record on the 1GP DE org to confirm EndDate is populated (non-null). EndDate is set by the package-conversion finalization service as part of finalize and is the reliable post-finalize wire signal. Uses the read-only PackageConversion Tooling exposure shipped in 264 (1GP DE org auth is already a hard precondition for this skill, so no auth-state branching needed). This is the canonical wire-verify and supplements (rather than replaces) the optional user attestation in verify-finalize-by-user-confirmation. Note: the finalize step's own 266 response also returns finalizedAt + conversionId directly, so this step is a durable cross-check rather than the sole success signal.
+
+**Call:** `queryPackageConversion`   — status: `implemented`
+
+**Inputs:**
+
+- `packaging_org_alias` *(`String`)* — Source - output of verify-finalize-by-user-confirmation (transitively from check-eligibility-1gp-released.packaging_org_alias).
+  - **Source:** output of `check-eligibility-1gp-released`
+- `subscriber_package_id` *(`String`)* — Source - output of verify-finalize-by-user-confirmation (transitively from discover-package-on-devhub.subscriber_package_id).
+  - **Source:** output of `discover-package-on-devhub`
+
+**Depends on:** `verify-finalize-by-user-confirmation`
+
+**Notes:** 264 shipped the read-only public Tooling exposure of PackageConversion (available when packaging is enabled for the org). The fields queried here — Id, EndDate, FinalizedVersionId (FK → SubscriberPackageVersion), FinalizedVersionNumber, and the WHERE key ConvertedFromPackageId (FK → SubscriberPackage) — are all exposed read-only. EndDate non-null means finalize completed. Move-to-2GP does NOT auto-create native Package2Version records on DevHub (native creation is a separate user-driven step), so there is no Package2Version-based wire-verify; EndDate is the reliable signal.
+
+### Other operations
+
+#### `check-eligibility-1gp-released`
+
+Find the highest Released 1GP major.minor version of the package by querying MetadataPackageVersion on the 1GP DE org. MetadataPackageVersion is the 1GP DE-side view of `all_package_version` joined with `dev_package_version`, with a `ReleaseState` STATICENUM field whose Released picklist value is `"Released"`.
+
+**Call:** `queryHighestReleased1GPVersion`   — status: `implemented`
+
+**Inputs:**
+
+- `packaging_org_alias` *(`String`)* — Source: user_input. The `sf` alias of the user's 1GP DE (packaging) org. Captured at skill start (see agent_guidance "AT START").
+- `subscriber_package_id` *(`String`)* — Source - output of discover-package-on-devhub. Note: the SubscriberPackageId (033... key prefix) on DevHub is the same Id as MetadataPackage on the 1GP DE org — both wrap the same all_package row.
+
+**Depends on:** `discover-package-on-devhub`
+
+#### `check-eligibility-2gp-converted-released`
+
+Confirm a 2GP-converted Package2Version exists at the same major.minor as the highest Released 1GP version, AND that the 2GP version is Released. This is the second half of the eligibility gate — Move-to-2GP requires the highest 1GP major.minor to have a corresponding RELEASED 2GP-converted equivalent. Queries Package2Version on DevHub.
+
+**Call:** `queryReleased2GPConvertedVersion`   — status: `implemented`
+
+**Inputs:**
+
+- `devhub_alias` *(`String`)* — Source - output of check-eligibility-1gp-released (transitively from discover-package-on-devhub.devhub_alias).
+  - **Source:** output of `discover-package-on-devhub`
+- `package2_id` *(`String`)* — Source - output of check-eligibility-1gp-released (transitively from discover-package-on-devhub.package2_id).
+  - **Source:** output of `discover-package-on-devhub`
+- `major` *(`Integer`)* — Source - output of check-eligibility-1gp-released (highest_1gp_major).
+- `minor` *(`Integer`)* — Source - output of check-eligibility-1gp-released (highest_1gp_minor).
+
+**Depends on:** `check-eligibility-1gp-released`
+
+#### `check-already-done`
+
+Detect the early-exit case — if a native (non-converted) Package2Version exists for this Package2, Move-to-2GP has ALREADY happened OR the package was 2GP-native to start with. Native 2GP versions are characterized by ConvertedFromVersionId = NULL. If any such Package2Version exists, the skill exits immediately.
+
+**Call:** `queryNativePackage2Version`   — status: `implemented`
+
+**Inputs:**
+
+- `devhub_alias` *(`String`)* — Source - output of check-eligibility-2gp-converted-released (transitively from discover-package-on-devhub.devhub_alias).
+  - **Source:** output of `discover-package-on-devhub`
+- `package2_id` *(`String`)* — Source - output of check-eligibility-2gp-converted-released (transitively from discover-package-on-devhub.package2_id).
+  - **Source:** output of `discover-package-on-devhub`
+
+**Depends on:** `check-eligibility-2gp-converted-released`
+
+#### `confirm-affirmations`
+
+Present the irrevocability + testing affirmations to the user, mirroring the "Move to Second-Generation Managed Packaging" dialog shown in Setup UI. The user must explicitly confirm each affirmation before the agent proceeds to the (manual) finalize step. This step has no API surface — it's a structured agent-to-user interaction encoded in the SOR for contract consistency between the eventual 266 Connect API (which is expected to require these as request-body fields) and the pre-266 manual flow.
+
+**Status:** `implemented`
+
+**Inputs:**
+
+- `package_name` *(`String`)* — Source - output of check-already-done (transitively from discover-package-on-devhub.package_name).
+  - **Source:** output of `discover-package-on-devhub`
+- `package2_id` *(`String`)* — Source - output of check-already-done (transitively from discover-package-on-devhub.package2_id).
+  - **Source:** output of `discover-package-on-devhub`
+
+**Depends on:** `check-already-done`

package/skills/dx-scratch-def-configure/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: dx-scratch-def-configure
+description: "Drafts a schema-valid Salesforce DX scratch-def from natural language. Preview first (confirmation card, do not write). A later edit — including a write that also changes the draft — is another preview. Write only on consent that this draft is unchanged: invoke this skill and apply via its helper — never hand-write JSON with Write. Writes config/<purpose>-scratch-def.json (default purpose project) under an existing SF DX project that already has config/ (never creates config/). Grounds features on the PUBLIC config-values catalog: put product names (like Revenue Cloud) in features as-is. Use to author/validate a scratch-def or layer features onto a shape or snapshot. Also use for trial, shape-only, snapshot-only, underspecified, missing config/ (ask for the SF DX project path), or batch multi-def asks: invoke this skill, STOP, write report.md on disk (chat is not a substitute; do not skip the skill). Does not create orgs or enable Dev Hub. Not for dx-org-manage, dx-org-devhub-configure, or SKU work."
+allowed-tools: Read, Write, Bash(python3), Bash(python)
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  relatedSkills:
+    - "dx-org-devhub-configure"
+    - "dx-org-manage"
+    - "dx-org-shape-manage"
+    - "dx-org-snapshot-manage"
+    - "platform-trial-org-create"
+  cliTools:
+    - tool: ["python3", "python"]
+      semver: ">=3.8.0"
+---
+
+# Configure Scratch Org Definition File
+
+This skill writes `config/<purpose>-scratch-def.json` (default
+`config/project-scratch-def.json`) from a product ask. It does **not** create
+the org. Never `mkdir config`.
+
+Every turn writes `report.md` on disk. Chat is not a substitute. Then exactly
+one of these happens:
+
+| Mode | When | What the user gets |
+|------|------|--------------------|
+| **Stop** | Trial, shape-only, shape/snapshot + features with no id, missing project, unclear ask, batch, other-user path | The next step, named. No scratch-def file. |
+| **Preview** | First generate (including just-write / skip-preview) or a revision, and the project already has `config/` | A draft + Write file?. Nothing is written yet. |
+| **Write** | They accept this draft **unchanged** (this preview, as drafted). This turn may restate it; no prior chat required. | The file. Name dx-org-manage. |
+
+## CRITICAL first gate (before any helper)
+
+First matching row wins. Copy that recipe into `report.md`.
+
+Never Skill() another skill. Never run `sf`. Name the next skill in `report.md` only.
+
+STOP: write `report.md` on disk. Chat is not a substitute. Skip the helper
+and skip scratch-def JSON.
+
+Consent is accepting this draft, **unchanged** — not a closed list of yes-words.
+Accepting this draft (this preview, as drafted) and asking to write is consent:
+apply; reconstruct if they restate the same draft; do not ask Write file?.
+A first generate is Preview even if they say write or skip preview.
+A different edition, product, or setting is a change: preview.
+
+| If the ask is… | Then |
+|----------------|------|
+| Shape or snapshot **lifecycle alone** (no features to layer), including "use my org shape only" | STOP. Name dx-org-shape-manage or dx-org-snapshot-manage. |
+| Trial / trialforce / "trial org definition" | STOP. Name platform-trial-org-create. Do **not** skip this skill. |
+| Underspecified ("I need a scratch def") — no edition and no products/clouds/features | STOP. Ask the two questions below. If `config/` is also missing, include the Missing-project question. Do not invent an edition. |
+| Another user's laptop / no readable workspace path | STOP. Cannot read another user's machine. Ask for a readable workspace path. |
+| Batch generation (multiple def files in one turn), e.g. "Generate 5 def files for different personas" | STOP. Batch generation is not supported yet — offer to make the first one. |
+| WRITE-eligible (imperative generate with edition and/or products/features, or shape/snapshot **+ features**) but cwd has **no** `config/` | STOP. Ask the Missing-project question (folder that **already** contains `config/`). Do **not** create `config/`. |
+| Shape/snapshot **+ features**, root resolved, user omitted `sourceOrg` or snapshot id/name | STOP. Write `report.md` on disk. Ask for the id. Name dx-org-shape-manage / dx-org-snapshot-manage to list. Resume this skill with the id. |
+| User revises the draft — this turn names a **different** edition, products, settings, or other edits, including a write request that also changes the draft, and root resolved | This turn's wording is the full draft. Preview it. Do not require a prior file or earlier chat. **Do not** apply yet. |
+| User consents that this preview is the draft they want written, **unchanged** (this preview, as drafted), and root resolved | Write it. Reconstruct if this turn restates the same draft. No prior chat required. See **Write**. |
+| Shape/snapshot **+ features**, root resolved, user supplied the id, and this turn is not consent to write | Preview it. **Do not** apply yet. |
+| Imperative generate that names edition and/or products/features (one def), including a first-turn write or skip-preview ask, root resolved, and this turn is not consent to write | Preview it. **Do not** apply yet. |
+
+Underspecified questions: (1) what are you building/demoing? (2) which products/clouds?
+
+Missing-project question: What is the path to your Salesforce DX project (the directory that already contains a config folder)?
+
+## Preview
+
+Show the confirmation card (see `examples/confirm-card.md`, or
+`artifacts/examples/confirm-card.md` when packaged). Put **schema-valid JSON**
+in chat alongside `report.md` (never inside it): the helper `document`. Ask
+Write file? in `report.md`. **Do not** apply yet. Do not name dx-org-manage
+until they consent to write.
+
+## Write
+
+One `apply` only — no preview, no second card, no Write file?. Reconstruct
+if this turn restates the same draft (no in-context copy). `--out config/<purpose>-scratch-def.json`
+(default `config/project-scratch-def.json`). Report the path + a one-line
+summary + the **final written JSON in chat**. Name dx-org-manage
+(dx-org-devhub-configure if Dev Hub is off).
+
+## Outcome report (always)
+
+**Read** `examples/report-recipes.md` (or `artifacts/examples/report-recipes.md`
+when packaged) and copy the matching recipe. First line: `# Scratch Def Report`.
+Plain prose — never the backtick character. Spell next-skill names as plain
+words (dx-org-shape-manage, platform-trial-org-create).
+
+Omit cache date, shipped-snapshot, jsonschema, and dropped-token notes from
+`report.md` unless the helper warned this turn.
+
+## Steps
+
+1. Run the CRITICAL first gate. If it is STOP, write `report.md` and stop here.
+
+2. On WRITE-eligible asks, **resolve the SF DX project root before any helper**:
+   cwd with `config/` is the root; otherwise the Missing-config STOP row.
+
+3. Resolve the helper by absolute path:
+
+   ```bash
+   HELPER="<skill_dir>/scripts/lib_scratch_def.py"
+   [ -f "$HELPER" ] || HELPER="<skill_dir>/artifacts/scripts/lib_scratch_def.py"
+   ```
+
+4. **One helper call per turn** from the SF DX project root. Keep the draft in
+   **chat/tool context**. Pass the draft on stdin with a quoted heredoc
+   (`<<'EOF'`). Invoke `python3` when that binary exists; otherwise `python`.
+   - Preview (generate or a revision of the draft):
+     ```bash
+     python3 "$HELPER" preview <<'EOF'
+     {"edition":"Developer","features":["API"]}
+     EOF
+     ```
+   - After consent that this draft is what they want, unchanged:
+     ```bash
+     python3 "$HELPER" apply --out config/<purpose>-scratch-def.json <<'EOF'
+     …same draft JSON…
+     EOF
+     ```
+     (default `config/project-scratch-def.json`). `--out` writes the scratch-def.
+   If the helper warns `jsonschema not installed`, ask the user to install
+   (`python3 -m pip install jsonschema` or `python -m pip install jsonschema`).
+   On success, retry this same helper call once. If they decline or install fails,
+   keep this result — do **not** block preview/apply.
+   Do **not** Read `references/features.json` or `settings-map.json` into chat.
+   Do not Grep them to pick extra tokens.
+
+5. Put the user's product, cloud, and feature words in the `features` array
+   as-is (for example Revenue Cloud, not a guessed token list). Use lower
+   camelCase settings keys. The helper maps each string to at most one PUBLIC
+   token and enriches required settings. Do not add catalog tokens the user
+   did not name.
+
+6. Write `report.md` on disk. Put chat JSON and the card per Preview / Write.
+
+Unknown token: drop it and warn in report.md.
+
+## Before you finish
+
+- [ ] `report.md` exists on disk and matches a recipe
+- [ ] Preview / revision (including write + change): this turn's wording is the full draft; card + document JSON in chat; asked Write file?; **Do not** apply yet
+- [ ] Consent unchanged (this preview, as drafted; no prior chat required): `apply`; file + final JSON in chat; no Write file?; name dx-org-manage
+- [ ] WRITE turns: root resolved; one helper call; features array is the user's words
+- [ ] report.md mentions cache date, jsonschema, or dropped tokens only when the helper warned this turn
+
+## Notes
+
+Catalog: each helper invocation loads maps into process memory from:
+
+1. Today's `cache/public-config-values-YYYY-MM-DD.json` if usable.
+2. Else GET live PUBLIC config-values markdown; on success write today's cache file.
+3. Else newest usable prior dated file in `cache/`. report.md: that date
+   (only when this fallback fired).
+4. Else shipped snapshot JSON `references/features.json` + `settings-map.json`
+   (`artifacts/references/` when packaged). Backup. report.md: shipped snapshot
+   (only when this fallback fired).
+
+Every helper call (`preview` and `apply`) may write today's cache file under
+`cache/` before the user confirms the scratch-def. Add `cache/` to `.gitignore`.
+Treat cache JSON as generated. Delete is safe: the next call refetches if
+today's file is missing. Feature tokens come from this catalog.