fix: ship registry reader with framework so Tools→Packages works in fresh apps (#2543)

* fix: ship registry reader with framework so Tools→Packages works in fresh apps

The debug bar's Tools→Packages link (and the standalone packagelist
page it opens) silently rendered an empty registry list in apps
generated with `wheels new`. Public.$loadRegistryPackages gated on
FileExists("/cli/lucli/services/packages/Registry.cfc") — that path
only exists in the framework dev repo. User apps ship vendor/wheels/
without cli/, so the gate always returned an empty array.

Move the registry reader into the framework at
vendor/wheels/services/packages/{Registry,HttpClient,ManifestCache}.cfc
so it ships with every generated app. Public.cfc now instantiates the
bundled component directly and the file-existence gate is gone.

Keep the registry list scoped to the standalone Tools→Packages page —
the inline Environment > Packages section now shows installed packages
only, so the debug bar stays compact and we don't trigger a registry
walk on every dev-mode page load. The CLI keeps its own copies under
cli/lucli/services/packages/; both contexts have their own classpath
mappings (modules.wheels.* vs wheels.*) and dedup is left for a
follow-up.

Issue #2530.

* fix: validate versions array in Registry.fetchManifest before listAll() reads it

Address PR #2543 reviewer A. listAll() reads
local.m.versions[ArrayLen(local.m.versions)] without first checking
that the .versions key exists, is an array, and is non-empty. The
existing manifest validation only checked for .name. A registry entry
that passed the .name check but lacked .versions would crash with an
Expression-level "element VERSIONS is undefined" error — bypassing
both the per-package RegistryMalformed skip in listAll() and the
three typed catches in Public.$loadRegistryPackages, surfacing as an
unhandled stack trace on the Tools → Packages page.

Validate the .versions invariant in fetchManifest so cached and
fresh manifests share one guard, and the per-package skip
catches a typed throw. Mirrored into the CLI's Registry.cfc to
keep both copies in sync per the in-file note.

New RegistryFetchManifestSpec exercises the framework Registry with
a fake HttpClient — covers missing key, non-array, empty array, and
the listAll() end-to-end skip path. Adds wheels.tests._assets.packages.FakeHttpClient
trimmed to the framework HttpClient surface (no download()).

CHANGELOG entry for #2530 also rewritten to match the final UX
(registry list scoped to the standalone Tools → Packages page only)
and a new entry added for the validation fix.

* fix: validate cached manifests on read so stale on-disk entries can't crash listAll

Address PR #2543 reviewer B follow-up. The previous fix only validated
manifests on the fresh-fetch path before writing to cache. The
cache-hit path in fetchManifest returned the on-disk entry without
revalidating, so a manifest written by an older Registry version that
didn't enforce the versions invariant could still crash listAll() with
an Expression-level error.

Extract the manifest contract assertion into $validateManifest() and
call it from both the cache-hit and fresh-fetch paths. Mirrored into
the CLI's Registry.cfc to keep both copies in sync.

New spec case writes a stale-bad manifest to the cache directly, marks
it fresh, then verifies fetchManifest re-validates on read instead of
returning the stale entry.

Author: bpamiri

CHANGELOG.md

@@ -150,7 +150,8 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Fixed
 
-- Debug bar Packages tab now lists packages available from the `wheels-dev/wheels-packages` registry alongside the installed-packages table, mirroring the existing wire-up in `/wheels/packages`. Previously only the installed-packages table rendered, so developers had to leave the debug bar to discover what else was available. (#2530)
+- Debug bar Tools → Packages page now lists packages available from the `wheels-dev/wheels-packages` registry in fresh apps generated with `wheels new`. The previous gate (`FileExists("/cli/lucli/services/packages/Registry.cfc")`) silently returned an empty list because user apps don't ship the CLI alongside the framework. The registry reader now lives at `vendor/wheels/services/packages/{Registry,HttpClient,ManifestCache}.cfc` and ships with every generated app. The registry list stays scoped to the standalone Tools → Packages page; the inline debug-bar Environment panel shows installed packages only, so the bar stays compact and doesn't trigger a registry walk on every dev-mode page load. (#2530)
+- `Registry.fetchManifest()` now validates that a manifest contains a non-empty `versions` array before returning, throwing `Wheels.Packages.RegistryMalformed` instead of letting a downstream `local.m.versions[ArrayLen(...)]` access crash with an unhandled `Expression` error. The per-package skip-on-malformed catch in `listAll()` now actually catches every malformed shape, so the Tools → Packages page degrades gracefully when the registry serves a partial manifest. Mirrored into the CLI's `cli/lucli/services/packages/Registry.cfc` to keep both copies in sync. (#2530)
 - Snapshot pre-releases on `develop` now publish the full artifact set (`wheels-core-*.zip`, `wheels-base-template-*.zip`, `wheels-cli-*.zip`, `wheels-starter-app-*.zip`) alongside `wheels-module-*`. Previously only the module tarball was attached, which broke Homebrew/Chocolatey distributions that depend on fetching `wheels-core-*.zip` as a companion artifact: users scaffolded a new app and hit "Could not locate the Wheels framework source" at chapter 1 of the tutorial. Snapshots now mirror the main-branch release contents exactly, flagged as pre-release.
 - `wheels doctor` now detects when the installed CLI module has no companion framework source (vendor/wheels/) on disk — catches broken package distributions before they surface as a cryptic scaffold error. Previously `doctor` would report missing project directories and recommend `wheels new`, but `wheels new` would then fail with "Could not locate the Wheels framework source." The new `checkFrameworkSourceBundled` check walks the same search paths as `Module.cfc`'s `resolveFrameworkSource()` and reports a CRITICAL issue when none resolve, replacing the misleading `wheels new` recommendation with guidance to reinstall or set `WHEELS_FRAMEWORK_PATH`.
 - `wheels new` framework-not-found error now links to the real guides page (`/v4-0-0-snapshot/start-here/installing/`) instead of a 404 (`/docs/getting-started`), and mentions Homebrew/Chocolatey packaging explicitly so users can tell the difference between "I'm in the wrong directory" and "my install is incomplete."

cli/lucli/services/packages/Registry.cfc

@@ -15,28 +15,29 @@ component {
 	variables.DEFAULT_REPO = "wheels-dev/wheels-packages";
 	variables.DEFAULT_BRANCH = "main";
 
-	public Registry function init(
-		any httpClient = "",
-		any cache = "",
-		string registryRepo = "",
-		string branch = ""
-	) {
+	public Registry function init(any httpClient = "", any cache = "", string registryRepo = "", string branch = "") {
 		variables.http = IsObject(arguments.httpClient)
-			? arguments.httpClient
-			: new modules.wheels.services.packages.HttpClient();
+		 ? arguments.httpClient
+		 : new modules.wheels.services.packages.HttpClient();
 		variables.cache = IsObject(arguments.cache)
-			? arguments.cache
-			: new modules.wheels.services.packages.ManifestCache();
+		 ? arguments.cache
+		 : new modules.wheels.services.packages.ManifestCache();
 		variables.registryRepo = Len(arguments.registryRepo)
-			? arguments.registryRepo
-			: $resolveRepo();
+		 ? arguments.registryRepo
+		 : $resolveRepo();
 		variables.branch = Len(arguments.branch) ? arguments.branch : variables.DEFAULT_BRANCH;
 		return this;
 	}
 
-	public string function registryRepo() { return variables.registryRepo; }
-	public string function branch()        { return variables.branch; }
-	public any    function cache()         { return variables.cache; }
+	public string function registryRepo() {
+		return variables.registryRepo;
+	}
+	public string function branch() {
+		return variables.branch;
+	}
+	public any function cache() {
+		return variables.cache;
+	}
 
 	/**
 	 * Returns the list of package names in the registry. Serves cached
@@ -56,10 +57,7 @@ component {
 		}
 		local.entries = DeserializeJSON(local.resp.body);
 		if (!IsArray(local.entries)) {
-			Throw(
-				type = "Wheels.Packages.RegistryMalformed",
-				message = "Registry contents endpoint did not return an array."
-			);
+			Throw(type = "Wheels.Packages.RegistryMalformed", message = "Registry contents endpoint did not return an array.");
 		}
 		local.names = [];
 		for (local.entry in local.entries) {
@@ -74,10 +72,18 @@ component {
 
 	/**
 	 * Fetches a package's manifest. Cached 24h per package.
+	 *
+	 * Both the cache-hit and fresh-fetch paths run $validateManifest()
+	 * so a manifest written by an older Registry version that lacks
+	 * the `versions` invariant (or any other required field added later)
+	 * still throws RegistryMalformed instead of crashing listAll() with
+	 * an Expression-level error.
 	 */
 	public struct function fetchManifest(required string name) {
 		if (variables.cache.hasFreshManifest(arguments.name)) {
-			return variables.cache.readManifest(arguments.name);
+			local.cached = variables.cache.readManifest(arguments.name);
+			$validateManifest(arguments.name, local.cached);
+			return local.cached;
 		}
 		local.url = "https://raw.githubusercontent.com/#variables.registryRepo#/#variables.branch#/packages/#arguments.name#/manifest.json";
 		local.resp = variables.http.get(local.url);
@@ -94,14 +100,36 @@ component {
 			);
 		}
 		local.manifest = DeserializeJSON(local.resp.body);
-		if (!IsStruct(local.manifest) || !StructKeyExists(local.manifest, "name")) {
+		$validateManifest(arguments.name, local.manifest);
+		variables.cache.writeManifest(arguments.name, local.manifest);
+		return local.manifest;
+	}
+
+	/**
+	 * Asserts the listAll() consumption contract: must be a struct with
+	 * `name` and a non-empty `versions` array. Throws RegistryMalformed
+	 * on any violation. Called from both the cache-hit and fresh-fetch
+	 * paths in fetchManifest so stale on-disk manifests written by an
+	 * older Registry version surface as a typed throw instead of an
+	 * Expression-level crash deeper in the call chain.
+	 */
+	private void function $validateManifest(required string name, required any manifest) {
+		if (!IsStruct(arguments.manifest) || !StructKeyExists(arguments.manifest, "name")) {
 			Throw(
 				type = "Wheels.Packages.RegistryMalformed",
 				message = "Manifest for '#arguments.name#' is not a valid manifest struct."
 			);
 		}
-		variables.cache.writeManifest(arguments.name, local.manifest);
-		return local.manifest;
+		if (
+			!StructKeyExists(arguments.manifest, "versions")
+			|| !IsArray(arguments.manifest.versions)
+			|| !ArrayLen(arguments.manifest.versions)
+		) {
+			Throw(
+				type = "Wheels.Packages.RegistryMalformed",
+				message = "Manifest for '#arguments.name#' is missing a non-empty versions array."
+			);
+		}
 	}
 
 	/**
@@ -120,24 +148,27 @@ component {
 				continue;
 			}
 			local.latest = local.m.versions[ArrayLen(local.m.versions)];
-			ArrayAppend(local.out, {
-				name:          local.m.name,
-				description:   local.m.description ?: "",
-				tags:          IsArray(local.m.tags ?: "") ? local.m.tags : [],
-				homepage:      local.m.homepage ?: "",
-				latestVersion: local.latest.version
-			});
+			ArrayAppend(
+				local.out,
+				{
+					name = local.m.name,
+					description = local.m.description ?: "",
+					tags = IsArray(local.m.tags ?: "") ? local.m.tags : [],
+					homepage = local.m.homepage ?: "",
+					latestVersion = local.latest.version
+				}
+			);
 		}
 		return local.out;
 	}
 
 	public struct function info() {
 		local.cacheInfo = variables.cache.info();
 		return {
-			registryRepo: variables.registryRepo,
-			branch: variables.branch,
-			indexUrl: "https://github.com/#variables.registryRepo#/tree/#variables.branch#/packages",
-			cache: local.cacheInfo
+			registryRepo = variables.registryRepo,
+			branch = variables.branch,
+			indexUrl = "https://github.com/#variables.registryRepo#/tree/#variables.branch#/packages",
+			cache = local.cacheInfo
 		};
 	}
 
@@ -154,4 +185,5 @@ component {
 		}
 		return variables.DEFAULT_REPO;
 	}
+
 }