@salesforce/afv-skills 1.59.0 → 1.61.0

package/skills/agentforce-d360-analyze/scripts/dc.py

@@ -8,17 +8,22 @@ Two responsibilities:
    column names — those live in the .sql files.
 
 2. **Transport.** `resolve_org(alias)` shells out to `sf org display`
-   for the instance URL + access token. `post(sql, instance_url, token)`
+   for the instance URL and `sf org auth show-access-token` for the
+   access token. `post(sql, instance_url, token)`
    POSTs the SQL to the Data Cloud Query API and returns parsed rows.
    Errors route through `DCQueryError` with the full response body + SQL
    context so callers can surface a useful message.
+   `default_target_org()` reads the sf CLI default target org for entry
+   points invoked without `--org`. Both it and `resolve_org` run the
+   `show-access-token` capability preflight as their first sf call, so on
+   either path a too-old CLI fails with the upgrade message first.
 
 Persistence lives in `storage.save`.
 """
 from __future__ import annotations
 
 import json
-import os
+import re
 import subprocess
 import sys
 import urllib.error
@@ -71,51 +76,206 @@ wording has shifted across sf CLI builds while the subcommand has been
 stable since forcedotcom/cli#3560 landed."""
 
 
-def _run_sf_json(argv: list[str], env: dict | None = None) -> dict:
+# Token-redaction patterns, vendored from agentforce-architecture-analyze's
+# rest_client (this skill is self-contained and must not import across
+# skills). sf CLI failure output can echo the access token — e.g. a
+# `show-access-token --json` run that exits non-zero with the payload on
+# stdout — so every stderr/stdout string is scrubbed before it reaches a
+# SystemExit message. Deliberately permissive: over-redact, never leak.
+_AUTH_HEADER_RE = re.compile(r"(Authorization\s*:\s*Bearer\s+)\S+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
+_BEARER_RE = re.compile(r"(\bBearer\s+)[^\s\"']+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
+_ACCESS_TOKEN_QS_RE = re.compile(r"(access[_]?token\s*=\s*)[^&\s\"']+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
+_ACCESS_TOKEN_JSON_RE = re.compile(r"(\"access[_]?token\"\s*:\s*\")[^\"]*", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
+
+
+def _redact_text(text: str | None) -> str:
+    """Scrub bearer tokens and accessToken values from sf CLI output."""
+    if not text:
+        return ""
+    text = _AUTH_HEADER_RE.sub(r"\1<redacted>", text)
+    text = _BEARER_RE.sub(r"\1<redacted>", text)
+    text = _ACCESS_TOKEN_QS_RE.sub(r"\1<redacted>", text)
+    text = _ACCESS_TOKEN_JSON_RE.sub(r"\1<redacted>", text)
+    return text
+
+
+def _run_sf_json(argv: list[str]) -> dict:
     """Shell out + parse JSON. SystemExits on FileNotFoundError /
-    CalledProcessError so callers get a clean message instead of a stack."""
+    CalledProcessError so callers get a clean message instead of a stack.
+    Failure output is redacted before it is surfaced."""
     try:
-        r = subprocess.run(
-            argv, capture_output=True, text=True, check=True, env=env,
-        )
+        r = subprocess.run(argv, capture_output=True, text=True, check=True)
     except FileNotFoundError:
         raise SystemExit("sf CLI not found on PATH — install Salesforce CLI first")
     except subprocess.CalledProcessError as e:
+        detail = _redact_text((e.stderr or "").strip() or (e.stdout or "").strip())
+        raise SystemExit(f"{' '.join(argv[:4])}... failed:\n{detail}") from None
+    return json.loads(r.stdout)
+
+
+_show_access_token_capability_ok = False
+"""Set once the preflight succeeds; the check then never reruns in this
+process. Failures are NOT cached, so a fixed PATH/upgrade is picked up on
+the next call."""
+
+_SHOW_ACCESS_TOKEN_HELP_SIGNATURE_RE = re.compile(
+    r"\$\s*sf\s+org\s+auth\s+show-access-token\b"
+)
+"""USAGE-line form that real `--help` output always contains
+(`$ sf org auth show-access-token -o <value> ...`). The bare command name is
+not enough: unknown-command notices echo it too
+(`Command org:auth:show-access-token not found`,
+`show-access-token is not a sf command`). A zero-exit probe whose output
+lacks the USAGE form is treated as a failed check."""
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+
+
+def _assert_show_access_token_capability() -> None:
+    """Fail fast if the installed sf CLI lacks `sf org auth show-access-token`.
+
+    That command is the only supported token-retrieval path
+    (forcedotcom/cli#3560). Probing `--help` needs no org auth and turns a
+    confusing downstream failure into an actionable upgrade message.
+    `default_target_org` and `resolve_org` each call this first, ahead of
+    every other sf call they make. A successful probe is cached for the
+    process lifetime, so the second call costs nothing.
+
+    Exit status alone is not trusted: a CLI build that answers an unknown
+    command with exit 0 (e.g. printing top-level help or a "not found"
+    notice) would otherwise pass. The probe therefore also requires the
+    command's USAGE line (`$ sf org auth show-access-token`) in the
+    ANSI-stripped stdout+stderr; if it is absent the check fails and is not
+    cached.
+    """
+    global _show_access_token_capability_ok
+    if _show_access_token_capability_ok:
+        return
+    try:
+        proc = subprocess.run(
+            ["sf", "org", "auth", "show-access-token", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=True,
+        )
+    except FileNotFoundError as exc:
         raise SystemExit(
-            f"{' '.join(argv[:4])}... failed:\n{e.stderr.strip() or e.stdout.strip()}"
+            "sf CLI not found on PATH — install Salesforce CLI first"
+        ) from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (
+            _redact_text((exc.stderr or "").strip() or (exc.stdout or "").strip())
+            or "unknown error"
         )
-    return json.loads(r.stdout)
+        raise SystemExit(
+            "sf CLI is missing required command "
+            "'sf org auth show-access-token'. Upgrade/reinstall Salesforce CLI "
+            "to a build that provides this command, then retry.\n"
+            f"Preflight detail: {detail}"
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise SystemExit(
+            "sf CLI capability preflight for 'sf org auth show-access-token' "
+            "timed out after 30s"
+        ) from exc
+    help_text = _ANSI_ESCAPE_RE.sub(
+        "", f"{proc.stdout or ''}\n{proc.stderr or ''}",
+    )
+    if not _SHOW_ACCESS_TOKEN_HELP_SIGNATURE_RE.search(help_text):
+        # Zero exit without the command's help signature — the CLI did not
+        # recognise the command. Fail (uncached) like a non-zero exit.
+        # Redact before truncating so a token can never be split past the regex.
+        detail = (
+            _redact_text(help_text.strip())[:500]
+            or "help output lacked the command signature"
+        )
+        raise SystemExit(
+            "sf CLI is missing required command "
+            "'sf org auth show-access-token'. Upgrade/reinstall Salesforce CLI "
+            "to a build that provides this command, then retry.\n"
+            f"Preflight detail: {detail}"
+        )
+    _show_access_token_capability_ok = True
 
 
-def resolve_org(alias: str) -> tuple[str, str]:
-    """Resolve instanceUrl + accessToken for the sf org alias.
+NO_DEFAULT_ORG_MSG = (
+    "no --org given and no default target org set — run "
+    "`sf config set target-org <alias>` or pass --org <alias>"
+)
+
+
+def default_target_org() -> str:
+    """Return the sf CLI default target org alias/username.
 
-    Two-path strategy per forcedotcom/cli#3560 (effective 2026-05-27):
+    Used by entry points when ``--org`` is omitted ("my org" means the CLI
+    default). Reads ``.result[0].value`` from
+    ``sf config get target-org --json``. Raises SystemExit with a clear,
+    redacted message when the CLI is missing, fails, times out, returns
+    non-JSON, or has no default set.
 
-      1. **Primary** — `sf org display --json --verbose` for instanceUrl,
-         then `sf org auth show-access-token --json --no-prompt` for the
-         access token. This is the upstream long-term path; the
-         `SF_TEMP_SHOW_SECRETS=true` workaround is decommissioned in
-         summer 2026.
-      2. **Fallback** — if `sf org auth show-access-token` is unknown
-         (older sf CLI) OR returns an empty/redacted value, fall back
-         to the accessToken from the org_display call which uses
-         `SF_TEMP_SHOW_SECRETS=true` env var to bypass the redaction.
+    The show-access-token capability preflight runs first, before
+    ``sf config get``. A CLI too old to fetch a token then fails with the
+    upgrade/reinstall message, not a misleading "no default org" message.
+    The preflight is cached per process, so the later ``resolve_org`` call
+    does not probe again.
+    """
+    _assert_show_access_token_capability()
+    argv = ["sf", "config", "get", "target-org", "--json"]
+    try:
+        proc = subprocess.run(
+            argv, capture_output=True, text=True, timeout=30, check=True,
+        )
+    except FileNotFoundError:
+        raise SystemExit(
+            "sf CLI not found on PATH — install Salesforce CLI first"
+        ) from None
+    except subprocess.CalledProcessError as exc:
+        detail = (
+            _redact_text((exc.stderr or "").strip() or (exc.stdout or "").strip())
+            or "unknown error"
+        )
+        raise SystemExit(
+            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org` failed: {detail}"
+        ) from None
+    except subprocess.TimeoutExpired:
+        raise SystemExit(
+            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org` timed out after 30s"
+        ) from None
+    try:
+        payload = json.loads(proc.stdout or "")
+    except json.JSONDecodeError:
+        raise SystemExit(
+            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org --json` returned "
+            f"non-JSON output: {_redact_text(proc.stdout.strip())[:200]}"
+        ) from None
+    result = payload.get("result") if isinstance(payload, dict) else None
+    first = result[0] if isinstance(result, list) and result else {}
+    value = first.get("value") if isinstance(first, dict) else None
+    if not isinstance(value, str) or not value.strip():
+        raise SystemExit(NO_DEFAULT_ORG_MSG)
+    return value.strip()
 
-    `--verbose` is required on the org_display call: without it, sf CLI
-    v2 omits `accessToken` from the JSON entirely (so the fallback
-    path needs both `--verbose` and the env var to work).
+
+def resolve_org(alias: str) -> tuple[str, str]:
+    """Resolve instanceUrl + accessToken for the sf org alias.
+
+    Token retrieval is fail-fast (forcedotcom/cli#3560): the access token
+    comes ONLY from `sf org auth show-access-token --json --no-prompt`.
+    `sf org display --json --verbose` is used for non-secret metadata
+    (instanceUrl); any `accessToken` it carries is ignored.
 
     Raises SystemExit on CLI failure — this is the one thing every
     downstream operation depends on, so a clean early exit is friendlier
     than a stack trace.
     """
-    # Step 1: org_display gives us instanceUrl always; accessToken is
-    # the legacy fallback path (redacted unless SF_TEMP_SHOW_SECRETS=true).
-    env = {**os.environ, "SF_TEMP_SHOW_SECRETS": "true"}
+    # Step 1: capability preflight first, so a missing sf binary or missing
+    # command yields the actionable preflight error (cached once it passes).
+    _assert_show_access_token_capability()
+
+    # Step 2: org_display for instanceUrl (non-secret metadata only).
     display = _run_sf_json(
         ["sf", "org", "display", "--target-org", alias, "--json", "--verbose"],
-        env=env,
     )["result"]
     instance_url = display.get("instanceUrl") or ""
     if not instance_url:
@@ -123,37 +283,27 @@ def resolve_org(alias: str) -> tuple[str, str]:
             f"sf org display returned no instanceUrl for alias {alias!r}"
         )
 
-    # Step 2: prefer the dedicated command. Older sf CLI versions emit
-    # "is not a sf command" with returncode 0 (warning, not error), so
-    # we detect by parsing JSON shape. If the command is unknown the
-    # output isn't JSON; we let the json parse error trigger the fallback.
-    access_token = ""
+    # Step 3: dedicated command is the only token source.
     try:
         token_payload = _run_sf_json(
             ["sf", "org", "auth", "show-access-token",
              "--target-org", alias, "--json", "--no-prompt"],
         )
-    except (SystemExit, json.JSONDecodeError):
-        # Unknown command on older sf CLI → JSON parse fails OR
-        # CalledProcessError → SystemExit; either way, fall through.
-        pass
-    else:
-        token_result = token_payload.get("result") or {}
-        access_token = token_result.get("accessToken") or ""
-
-    # Fallback: if the dedicated command didn't yield a usable token,
-    # try the legacy SF_TEMP_SHOW_SECRETS path via the org_display
-    # payload we already have.
-    if not access_token or _REDACTION_MARKER_FRAGMENT in access_token:
-        legacy = display.get("accessToken") or ""
-        if legacy and _REDACTION_MARKER_FRAGMENT not in legacy:
-            access_token = legacy
+    except (SystemExit, json.JSONDecodeError) as exc:
+        raise SystemExit(
+            f"could not retrieve access token for alias {alias!r} via "
+            "sf org auth show-access-token; ensure the org is authenticated "
+            f"(sf org login web --alias {alias}).\nDetail: {exc}"
+        ) from exc
+
+    token_result = token_payload.get("result") or {}
+    access_token = token_result.get("accessToken") or ""
 
     if not access_token or _REDACTION_MARKER_FRAGMENT in access_token:
         raise SystemExit(
             f"could not retrieve a usable access token for alias {alias!r} "
-            f"via sf org auth show-access-token (primary) or sf org display "
-            f"(fallback). Ensure sf CLI is logged in for this org."
+            "via sf org auth show-access-token. Ensure sf CLI is logged in "
+            "for this org and the command returned a real token."
         )
 
     return instance_url, access_token

package/skills/agentforce-d360-analyze/scripts/discover_sessions.py

@@ -9,9 +9,11 @@ DC-only by design (no OTel path).
 
 ## CLI
 
-    python3 scripts/discover_sessions.py --org <alias> [options]
+    python3 scripts/discover_sessions.py [--org <alias>] [options]
 
-Options (all optional except --org):
+Options (all optional):
+  --org <alias>     sf CLI org alias. Default: the sf CLI default target org
+                    (`sf config get target-org`).
   --since <expr>    "last 2 hours" | "last 10" | "today" | "yesterday"
                     | "YYYY-MM-DD" | "YYYY-MM-DD to YYYY-MM-DD"
                     | explicit UTC/TZ datetime (RFC 3339). Default: last 24 hours.
@@ -55,7 +57,7 @@ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 sys.path.insert(0, str(Path(__file__).parent))
 
-from dc import DCQueryError, load_sql, post, resolve_org
+from dc import DCQueryError, default_target_org, load_sql, post, resolve_org
 from _shared.sql import _escape_sql_literal
 
 
@@ -477,7 +479,8 @@ def main() -> int:
         description="Find candidate Agentforce sessions via Data Cloud. "
                     "Prints a numbered picker; no artifacts written.",
     )
-    ap.add_argument("--org", required=True, help="sf CLI org alias (the one you configured via `sf org login`)")
+    ap.add_argument("--org", help="sf CLI org alias (the one you configured via `sf org login`). "
+                                  "Default: the sf CLI default target org")
     ap.add_argument("--since", help='time range: "last 2 hours" | "today" | "yesterday" | '
                                     '"YYYY-MM-DD" | "YYYY-MM-DD to YYYY-MM-DD" | ISO datetime. '
                                     'Default: last 24 hours.')
@@ -519,7 +522,8 @@ def main() -> int:
         limit=args.limit,
     )
 
-    instance_url, token = resolve_org(args.org)
+    org = args.org or default_target_org()
+    instance_url, token = resolve_org(org)
     try:
         rows = post(sql, instance_url, token, "discover_sessions")
     except DCQueryError as e:
@@ -544,7 +548,7 @@ def main() -> int:
     print(render_picker(
         rows=rows,
         agent_by_sid=agent_by_sid,
-        org=args.org,
+        org=org,
         tr=tr,
         filters=filters,
         composed_sql=sql,

package/skills/agentforce-d360-analyze/scripts/fetch_dc.py

@@ -23,7 +23,9 @@ Design contract:
   - Rerunning the same session overwrites prior artifacts.
 
 Invocation:
-    python3 scripts/fetch_dc.py --session <uuid> --org <alias> [--verbose]
+    python3 scripts/fetch_dc.py --session <uuid> [--org <alias>] [--verbose]
+
+`--org` defaults to the sf CLI default target org (`sf config get target-org`).
 
 After the waterfall finishes, the fetcher chains two downstream steps:
   1. assemble_dc.main_for_session → dc._session_tree.json
@@ -66,7 +68,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from config import DATA_ROOT, paths, sql as _sql_mod
-from dc import SQL_DIR, DCQueryError, load_sql, post, resolve_org
+from dc import SQL_DIR, DCQueryError, default_target_org, load_sql, post, resolve_org
 from storage import save
 
 
@@ -357,7 +359,7 @@ def main() -> int:
                     help="AI-agent session UUID, OR a Salesforce MessagingSession id "
                          "(0Mw... prefix). Messaging ids are resolved to the UUID "
                          "via a one-row DC lookup before the waterfall starts.")
-    ap.add_argument("--org", required=True, help="sf org alias")
+    ap.add_argument("--org", help="sf org alias (default: the sf CLI default target org)")
     ap.add_argument("--verbose", action="store_true", help="dump each SQL before POST")
     ap.add_argument("--no-assemble", action="store_true",
                     help="skip tree assembly after fetch")
@@ -371,6 +373,20 @@ def main() -> int:
 
     _preflight_templates()
 
+    # No --org means the sf CLI default target org. If none is set, surface
+    # it through the DC-access-denied contract (reason "no_org", exit 10
+    # headless) — the same path an unresolvable alias takes.
+    org = args.org
+    if not org:
+        try:
+            org = default_target_org()
+        except SystemExit as e:
+            return _handle_dc_access_denied(
+                DcAccessDenied("no_org", str(e)),
+                session_id=args.session,
+                is_tty=sys.stdin.isatty(),
+            )
+
     # Accept either a UUID or a MessagingSession id (0Mw...). The resolver
     # passes UUIDs through unchanged; on messaging ids it tries disk first
     # (any prior fetch left dc.sessions.json behind under DATA_ROOT), and
@@ -380,7 +396,7 @@ def main() -> int:
     # On multi-match or zero-match the resolver exits with a diagnostic.
     from resolve_session import is_messaging_id, resolve_disk_or_live
     input_id = args.session
-    session_id = resolve_disk_or_live(input_id, org=args.org)
+    session_id = resolve_disk_or_live(input_id, org=org)
     if is_messaging_id(input_id):
         _log(f"resolved messaging id {input_id} → AiAgentSession {session_id}")
 
@@ -390,7 +406,7 @@ def main() -> int:
     # emits either an interactive prompt or a JSON preamble depending on
     # tty presence, then exits with EXIT_DC_ACCESS_DENIED (10).
     try:
-        instance_url, token = preflight_dc_access(session_id, args.org)
+        instance_url, token = preflight_dc_access(session_id, org)
     except DcAccessDenied as exc:
         return _handle_dc_access_denied(
             exc,
@@ -402,7 +418,7 @@ def main() -> int:
 
     ctx = {
         "session_id": session_id,
-        "org_alias": args.org,
+        "org_alias": org,
         "instance_url": instance_url,
         "token": token,
         "verbose": args.verbose,

package/skills/agentforce-d360-analyze/scripts/resolve_session.py

@@ -21,7 +21,8 @@ specific UUID.
 
 ## Two resolution modes
 
-1. **Live** — query DC. Requires `--org`. Used by `fetch_dc.py` at the
+1. **Live** — query DC against `--org` (CLI: defaults to the sf CLI default
+   target org). Used by `fetch_dc.py` at the
    top of the pipeline (before any artifacts exist on disk).
 2. **Disk-first** — scan `DATA_ROOT/*/dc.sessions.json` for a row whose
    `ssot__RelatedMessagingSessionId__c` matches. No DC call, no `--org`
@@ -31,7 +32,7 @@ specific UUID.
 
 ## CLI
 
-    python3 scripts/resolve_session.py --id <uuid|msg_id> --org <alias>
+    python3 scripts/resolve_session.py --id <uuid|msg_id> [--org <alias>]
 
 Prints the resolved UUID to stdout on single-match (or pass-through).
 Non-zero exit with diagnostics on zero-match and multi-match.
@@ -47,7 +48,7 @@ from typing import List, Optional
 sys.path.insert(0, str(Path(__file__).parent))
 
 from config import DATA_ROOT
-from dc import load_sql, post, resolve_org
+from dc import default_target_org, load_sql, post, resolve_org
 
 
 # NOT_SET sentinel set. Matches fetch_dc.py:41; keep in sync.
@@ -224,7 +225,8 @@ def main() -> int:
     )
     ap.add_argument("--id", required=True,
                     help="Either the AI-agent session UUID or the MessagingSession id (0Mw...)")
-    ap.add_argument("--org", help="sf org alias (required for live DC lookup when input is 0Mw...)")
+    ap.add_argument("--org", help="sf org alias for the live DC lookup when input is 0Mw... "
+                                  "(default: the sf CLI default target org)")
     ap.add_argument("--disk-only", action="store_true",
                     help="Only scan DATA_ROOT/*/dc.sessions.json; no DC query")
     # Runtime-agnostic path overrides; default to ~/.vibe/...
@@ -243,19 +245,25 @@ def main() -> int:
             return 1
         print(found)
         return 0
-    if not args.org:
-        # Try disk first as a convenience; only error if that also misses.
+    org = args.org
+    if not org:
+        # Try disk first as a convenience; on a miss, fall back to the sf CLI
+        # default target org for the live lookup, and only error if that
+        # is unset too.
         disk = resolve_from_disk(args.id)
         if disk is not None:
             print(disk)
             return 0
-        print(
-            f"resolve_session: {args.id!r} not found on disk; --org <alias> required "
-            f"for a live DC lookup",
-            file=sys.stderr,
-        )
-        return 2
-    uuid = resolve(args.id, org=args.org)
+        try:
+            org = default_target_org()
+        except SystemExit as e:
+            print(
+                f"resolve_session: {args.id!r} not found on disk; --org <alias> required "
+                f"for a live DC lookup ({e})",
+                file=sys.stderr,
+            )
+            return 2
+    uuid = resolve(args.id, org=org)
     print(uuid)
     return 0