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.6	origin/main	packages/core/force-app/main/default (monorepo)
ClientVerse Modules	0.3.0	origin/main	packages/modules/force-app (monorepo)

Both packages track main — the branch package versions are cut from, and so the only ref that describes what a customer can install (ADR-0009, superseding ADR-0008's use of develop).

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 → update the *_REF / *_VER constants at the top of sync.py, then re-run (and rename the JSON files to the new version).
• Objects/fields/permission sets/apps are added or removed.
• You want a fresh annotation-coverage snapshot.

Bumping to a new version

Edit the constants near the top of sync.py:

CORE_REF, CORE_BASE, CORE_VER = "origin/develop", "packages/core/force-app/main/default", "1.1.6"
MOD_REF,  MOD_BASE,  MOD_VER  = "origin/develop", "packages/modules/force-app", "0.3.0"

*_VER must mirror each package's versionName in cv-crm's sfdx-project.json (ADR-0008 — the doc version is the package version), not versionNumber (which carries a .NEXT suffix).

Note the layout can differ by branch — confirm the *_BASE path matches the branch's structure (legacy force-app/... vs monorepo packages/.../force-app) before running. Rename the output JSON to the new version and git rm the superseded one.

Also re-check the Modules→Core dependency hardcoded in sync.py's depends_on block: read dependencies for the Modules packageDirectory in sfdx-project.json and resolve the package version ID through packageAliases. It moved from Core 1.1.2-1 to Core 1.1.4-9 at Modules 0.3.0.