Re-syncing the package-facts

The JSON files in this folder are generated from cv-crm by sync.py. Don't hand-edit them — re-run the sync. Doc versions mirror the package version they document (ADR-0008, source ref revised by ADR-0009).

What it reads

Package	Version	Ref	Layout
ClientVerse Core	1.1.10	6077cbd29 (the 1.1.10-2 build commit)	packages/unlocked-core/force-app/main/default (monorepo)
ClientVerse Modules	0.8.0	v0.8.0-1-modules	packages/modules/force-app (monorepo)

Each package is pinned to the exact source its released build was made from: the release tag, or the build commit when the tag doesn't match (ADR-0009's intent, "what a customer can install"). main and develop both move past the documented release, so neither is pinned.

Core 1.1.10 is pinned to its build commit, not its tag. v1.1.10-2-core sits nine commits past the commit the 1.1.10-2 package was built from, and those commits include the Legal Executive Assistant persona, which isn't in the installed package. Synced from the tag, the facts showed 7 apps, 76 permission sets and 10 groups, where the installed package has 6, 74 and 9. The build commit comes from the range line in cv-crm docs/releases/<version>/internal.md. Check it after every bump_pins.py run, because that script derives tags.

Re-sync on each release cut, not on each merge to develop. Anything on develop but not main is coming, not available, and belongs in release notes rather than the guides.

The script reads metadata with git ls-tree / git grep against those refs — it never checks out the branches, never touches the cv-crm working tree, and never copies SFDX source into this repo.

How this runs

Normally: automatically, on release. cv-crm's Release → trigger docs refresh workflow fires when a package version lands on main, and this repo's refresh-package-facts.yml re-syncs and opens a PR with a drift report. Requires the repo secret CV_CRM_READ_TOKEN (read access to clientverse/cv-crm); without it the run fails fast rather than opening a wrong PR.

Run it by hand from the Actions tab to check drift without waiting for a release — it opens no PR if nothing changed.

How to run it locally

# 1. Make sure the refs are fetched in your local cv-crm clone:
CV=~/local-projects/clientverse/cv-project-dev/packages/cv-crm
git -C "$CV" fetch origin main --tags

# 2. Regenerate the facts (run from this directory):
python3 sync.py --cv-repo "$CV" --date $(date +%Y-%m-%d)

# To cross-check what is coming (develop) WITHOUT publishing it — write elsewhere:
#   python3 sync.py --cv-repo "$CV" --core-ref origin/develop --mod-ref origin/develop \
#     --out /tmp/facts-develop --date $(date +%Y-%m-%d)

Outputs (all overwritten): clientverse-core-<version>.json, clientverse-modules-<version>.json, catalog.json, sync-report.md, annotation-backlog.md.

When to re-run

• A new Core/Modules version is released → run bump_pins.py, then re-run the sync (below).
• Objects/fields/permission sets/apps are added or removed.
• You want a fresh annotation-coverage snapshot.

Bumping to a new version

Use bump_pins.py; do not edit the constants by hand.

python3 bump_pins.py --cv-repo "$CV" --core 1.1.10 --modules 0.8.0
python3 sync.py --cv-repo "$CV" --date $(date +%Y-%m-%d)

sync.py pins six values that must move as one: each package's release tag and versionName, the ClientVerse Core Unlocked@X-N and ClientVerse Modules@Y-N aliases, the Core 04t ID, and the Core version Modules depends on. bump_pins.py derives every one from cv-crm — the highest build tagged for each version, and sfdx-project.json at that tag — rewrites them in place, and prints old → new. It changes nothing and exits non-zero if any value cannot be derived. assert_ref_version in sync.py then refuses to run if a tag and its label still disagree.

*_VER mirrors each package's versionName (ADR-0008 — the doc version is the package version), never versionNumber, which carries a .NEXT suffix.

Keep the superseded JSON pair. Guides cite the facts file for the version they were verified against (clientverse-core-1.1.7.json and so on); when a guide is re-verified against the new release, its citations move to the new file. Deleting the old pair breaks every citation in a guide nobody has re-verified yet.