@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/investigating-agentforce-architecture/scripts/finalize.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""Finalize: write DATA_DIR + CACHE_DIR atomically, build manifest.
+
+Replaces old agent Phase 7. Steps:
+  1. Load $WORK_DIR/declared_action_tree.json.
+  2. Compute _partial = !(planner_ok && _pending_fetches empty); strip _visited.
+  3. Stage DATA_DIR at $DATA_DIR.tmp: copy tree as {api}_{ver}_metadata_tree.json.
+  4. rmtree final DATA_DIR; rename .tmp → DATA_DIR.
+  5. Stage CACHE_DIR at $CACHE_DIR.tmp: copy metadata/<wave> dirs + sidecars.
+  6. Write manifest.json.
+  7. rmtree final CACHE_DIR; rename .tmp → CACHE_DIR.
+  8. Seed .gitignore on data_root + cache_root parents.
+  9. Write $WORK_DIR/.built_at.txt (ISO-Z UTC).
+
+the previously-emitted `{api}_{ver}_metadata_tree.summary.md` is
+dropped from the output contract — it was a redundant summary of the tree
+JSON. Consumers should read the JSON directly.
+
+Usage:
+    python3 finalize.py
+
+Inputs (env):
+    WORK_DIR       required
+    CACHE_DIR      required
+    DATA_DIR       required
+    PLANNER_NAME   optional — empty → tree marked partial
+    AGENT_API_NAME, AGENT_VERSION — used for filenames
+
+Outputs:
+    $DATA_DIR/{api}_{ver}_metadata_tree.json
+    $DATA_DIR/last_built_at.txt
+    $CACHE_DIR/manifest.json + metadata/<wave>/... + parsed sidecars
+    $WORK_DIR/.built_at.txt
+    exit 0 success, 1 on any write failure → caller emits STATUS=WRITE_FAILED
+"""
+import datetime
+import json
+import os
+import pathlib
+import shutil
+import sys
+
+
+def sort_tree_in_place(root: dict) -> None:
+    """Sort `root.children` and each TOPIC's children alphabetically.
+
+    Ordering rules (2026-05-05, schema 3.1):
+    - `BOT_DEFINITION.children`: TOPIC nodes first (by `api_name`
+      case-insensitive), then non-topic plannerActions (by kind, then
+      `api_name`). This preserves the "planner-level actions as a
+      distinct trailing group" convention for readers who scan the
+      rendered tree top-down.
+    - Each TOPIC's children: alphabetical by `api_name`
+      case-insensitive.
+    - FLOW children are NOT sorted — flow-actionCall / subflow order
+      is the flow author's execution sequence, not a set.
+    - GEN_AI_FUNCTION / APEX / PROMPT_TEMPLATE / STANDARD_ACTION leaves
+      don't have children that warrant sorting.
+
+    Applied as a final pass after tree assembly and before the
+    authoritative JSON write, so ordering is pinned at the single
+    source of truth — the renderer doesn't re-sort.
+    """
+    if not isinstance(root, dict):
+        return
+    children = root.get("children") or []
+    if not children:
+        return
+
+    def _root_sort_key(node: dict) -> tuple:
+        kind = node.get("kind") or ""
+        api = (node.get("api_name") or "").casefold()
+        # TOPIC first (tier 0), everything else second (tier 1). Within
+        # each tier, stable by kind + api_name case-insensitive.
+        tier = 0 if kind == "TOPIC" else 1
+        return (tier, kind, api)
+
+    root["children"] = sorted(children, key=_root_sort_key)
+
+    for child in root["children"]:
+        if child.get("kind") == "TOPIC":
+            child_children = child.get("children") or []
+            child["children"] = sorted(
+                child_children,
+                key=lambda n: (n.get("api_name") or "").casefold(),
+            )
+
+
+def main() -> int:
+    try:
+        work_dir = pathlib.Path(os.environ["WORK_DIR"])
+        cache_dir = pathlib.Path(os.environ["CACHE_DIR"])
+        data_dir = pathlib.Path(os.environ["DATA_DIR"])
+        agent_api_name = os.environ["AGENT_API_NAME"]
+        agent_version = os.environ["AGENT_VERSION"]
+    except KeyError as e:
+        sys.stderr.write(f"finalize.py: missing env {e}\n")
+        return 1
+
+    planner_name = os.environ.get("PLANNER_NAME", "")
+    tree_path = work_dir / "declared_action_tree.json"
+
+    try:
+        tree = json.loads(tree_path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        sys.stderr.write(f"finalize.py: cannot read {tree_path}: {e}\n")
+        return 1
+
+    # Compute _partial. _pending_fetches drains as wave-B BFS resolves
+    # refs; failures (HTTP 4xx, iteration-cap exhaustion, managed-flow
+    # filter mismatch) move OUT of _pending_fetches and into _unresolved.
+    # If we only check _pending_fetches we'd silently call a run with
+    # _unresolved entries "converged" — STATUS=OK with hidden failures.
+    # Both buckets must be empty for a clean run.
+    planner_ok = bool(planner_name)
+    pending_total = sum(len(v) for v in (tree.get("_pending_fetches") or {}).values())
+    unresolved_count = len(tree.get("_unresolved") or [])
+    waves_converged = pending_total == 0 and unresolved_count == 0
+    tree["_partial"] = not (planner_ok and waves_converged)
+
+    # Bug F fix: parse_wave + main set _partial_reason from
+    # _pending_fetches only (legacy predicate). When _pending is empty
+    # but _unresolved is non-empty, those writers set reason=None. The
+    # promotion above flips _partial=True from the unresolved bucket, so
+    # the reason needs a matching promotion or PARTIAL_REASON= ends up
+    # blank in the RESULT block.
+    if tree["_partial"] and not tree.get("_partial_reason"):
+        if not planner_ok:
+            tree["_partial_reason"] = "no-planner"
+        elif unresolved_count > 0:
+            tree["_partial_reason"] = "unresolved-refs"
+        else:
+            tree["_partial_reason"] = "pending-refs"
+
+    # Strip _visited (internal state — not part of the durable artifact)
+    tree.pop("_visited", None)
+
+    # Pin deterministic child ordering as the last assembly step before
+    # the authoritative write — see `sort_tree_in_place` docstring for
+    # the ordering rules. Downstream readers (render_architecture,
+    # summarize_tree, third-party tooling) therefore see a single
+    # canonical order from disk; they don't re-sort.
+    sort_tree_in_place(tree.get("root") or {})
+
+    # Rewrite the authoritative tree before copying it anywhere else
+    try:
+        tmp = tree_path.with_suffix(tree_path.suffix + ".tmp")
+        tmp.write_text(json.dumps(tree, indent=2))
+        os.replace(tmp, tree_path)
+    except OSError as e:
+        sys.stderr.write(f"finalize.py: cannot rewrite tree: {e}\n")
+        return 1
+
+    built_at = datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    a = tree.get("agent", {}) or {}
+    tree_base = f"{agent_api_name}_{agent_version}_metadata_tree"
+
+    # --- DATA_DIR staging ---
+    # summary.md dropped from the output contract; DATA_DIR now
+    # holds only the tree JSON + last_built_at.txt (+ whatever the caller
+    # writes alongside, e.g. architecture.md from render_architecture).
+    #
+    # The prior pattern was `rmtree(data_dir); data_tmp.rename(data_dir)` —
+    # destructive of any co-tenant content under `<agent>__<ver>/`. We
+    # now iterate staging's children and overwrite each one into data_dir
+    # individually, leaving unrelated siblings intact. See
+    # `main.py:_swap_dir_atomic` for the production path with the same
+    # invariant.
+    data_tmp = data_dir.with_suffix(".tmp")
+    try:
+        if data_tmp.exists():
+            shutil.rmtree(data_tmp)
+        data_tmp.mkdir(parents=True)
+        shutil.copy(tree_path, data_tmp / f"{tree_base}.json")
+
+        (data_tmp / "last_built_at.txt").write_text(built_at + "\n")
+
+        data_dir.mkdir(parents=True, exist_ok=True)
+        for staged in list(data_tmp.iterdir()):
+            target = data_dir / staged.name
+            if target.exists() or target.is_symlink():
+                if target.is_dir() and not target.is_symlink():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            shutil.move(str(staged), str(target))
+        shutil.rmtree(data_tmp, ignore_errors=True)
+    except OSError as e:
+        sys.stderr.write(f"finalize.py: DATA_DIR write failed: {e}\n")
+        try:
+            if data_tmp.exists():
+                shutil.rmtree(data_tmp)
+        except OSError:
+            pass
+        return 1
+
+    # --- CACHE_DIR staging ---
+    cache_tmp = cache_dir.with_suffix(".tmp")
+    try:
+        if cache_tmp.exists():
+            shutil.rmtree(cache_tmp)
+        cache_tmp.mkdir(parents=True)
+
+        # Mirror sf_meta/<wave>/ into metadata/<wave>/ verbatim so cache has:
+        # retrieve.json (sf CLI output — critical for debugging silent
+        # retrieves that produced zero members)
+        # unpackaged/ (parsed XML tree)
+        # unpackaged.zip is intentionally skipped — it's byte-for-byte the
+        # same as unpackaged/ and doubles cache size on every run.
+        meta_dir = cache_tmp / "metadata"
+        meta_dir.mkdir()
+        sf_meta = work_dir / "sf_meta"
+        if sf_meta.exists():
+            for wave_dir in sorted(sf_meta.iterdir()):
+                if not wave_dir.is_dir():
+                    continue
+                dst = meta_dir / wave_dir.name
+                dst.mkdir(parents=True, exist_ok=True)
+                for item in wave_dir.iterdir():
+                    if item.name == "unpackaged.zip":
+                        continue  # redundant with unpackaged/
+                    if item.is_dir():
+                        shutil.copytree(item, dst / item.name, dirs_exist_ok=True)
+                    else:
+                        shutil.copy(item, dst / item.name)
+
+        # Copy every WORK_DIR top-level artifact except:
+        # - .emit_ctx.json (per-run shell state, irrelevant to cache)
+        # - .built_at.txt (recorded in manifest.built_at_utc)
+        # - sf_meta/ (handled above)
+        # This catches declared_action_tree.json, _bundle_parsed.json,
+        # _agent_generation.txt, _bot_definition.json, _bot_versions.json,
+        # and anything future scripts write as top-level sidecars.
+        SKIP_NAMES = {".emit_ctx.json", ".built_at.txt", "sf_meta"}
+        for item in work_dir.iterdir():
+            if item.name in SKIP_NAMES:
+                continue
+            if item.name.endswith(".tmp"):
+                continue  # atomic-write staging from some other script
+            if item.is_dir():
+                shutil.copytree(item, cache_tmp / item.name, dirs_exist_ok=True)
+            elif item.is_file():
+                shutil.copy(item, cache_tmp / item.name)
+
+        manifest = {
+            "built_at_utc": built_at,
+            "schema_version": tree.get("_schema_version", "2.4"),
+            "agent": a,
+            "node_count": tree.get("node_count", 0),
+            "depth": tree.get("depth", 0),
+            "kind_counts": tree.get("_kind_counts", {}),
+            "ttl_days": 7,
+            "data_path": str(data_dir / f"{tree_base}.json"),
+            "partial": tree.get("_partial", False),
+            "unresolved_count": len(tree.get("_unresolved", []) or []),
+        }
+        (cache_tmp / "manifest.json").write_text(json.dumps(manifest, indent=2))
+
+        if cache_dir.exists():
+            shutil.rmtree(cache_dir)
+        cache_tmp.rename(cache_dir)
+    except OSError as e:
+        sys.stderr.write(f"finalize.py: CACHE_DIR write failed: {e}\n")
+        try:
+            if cache_tmp.exists():
+                shutil.rmtree(cache_tmp)
+        except OSError:
+            pass
+        return 1
+
+    # --- .gitignore seeding on parent dirs (data_root + cache_root) ---
+    for root in (cache_dir.parent.parent, data_dir.parent.parent):
+        try:
+            gi = root / ".gitignore"
+            if not gi.exists():
+                root.mkdir(parents=True, exist_ok=True)
+                gi.write_text("*\n")
+        except OSError:
+            pass
+
+    # --- .built_at.txt for emit ctx ---
+    try:
+        (work_dir / ".built_at.txt").write_text(built_at + "\n")
+    except OSError as e:
+        sys.stderr.write(f"finalize.py: .built_at.txt write failed: {e}\n")
+        # Non-fatal — finalize succeeded; emit can recompute
+
+    print(f"[finalize] built_at: {built_at}")
+    print(f"[finalize] data  written: {data_dir}/{tree_base}.json")
+    print(f"[finalize] cache written: {cache_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())