feat(cli): wheels packages CLI — registry-backed install (#2270 Phase 3)#2276
Merged
feat(cli): wheels packages CLI — registry-backed install (#2270 Phase 3)#2276
Conversation
…2270 Phase 3) Phase 3 of #2243. Adds `wheels packages list|search|show|install|update|remove` plus `wheels packages registry refresh|info` over the wheels-packages registry. - Registry client with 24h FS cache keyed at ~/.wheels/cache/packages/ - Installer: HTTPS download, SHA-256 verify against manifest, tar -xzf into vendor/<name>/. Hard-aborts on checksum mismatch; refuses overwrite without --force. - VersionResolver reuses vendor/wheels/SemVer.cfc (shipped in #2231) so the CLI and PackageLoader agree on wheelsVersion satisfaction. - Explicit-only updates: `update <name>` and `update --all` require --yes. `update --all` continues on per-package failures and throws at the end so the shell exit code reflects partial failure. - WHEELS_PACKAGES_REGISTRY env var overrides the default registry repo. - Docs: web/sites/guides/.../command-line-tools/commands/packages/ and CLAUDE.md Package System section updated. - 22 new specs under cli/lucli/tests/specs/packages/, network-free via FakeHttpClient + a fixture tarball.
…X build MDX parses bare `<2.0.0` as a JSX tag (`Unexpected character `2` before name`). Wrap the compatible-with range in backticks so the MDX rollup plugin treats it as code.
4 tasks
bpamiri
added a commit
that referenced
this pull request
Apr 24, 2026
* docs(docs): update packages guide for accuracy and 4.1 reality Closes #2244. The packages.mdx guide was shipped before several key pieces landed: the `wheels packages` CLI, the wheels-i18n and wheels-seo-suite conversions to 4.0 format, and before the `view` mixin-target claim was noticed as unsupported. This refresh brings the guide into sync with reality. Substantive changes to `packages.mdx`: - Remove `view` and `service` from the `provides.mixins` target list — neither is in PackageLoader's allowlist (application,dispatch,controller,mapper,model,base,sqlserver,mysql, postgresql,h2,test plus the specials global/none). Explain that `controller` already covers views since Wheels views run in the controller's variables scope. - Replace the per-method override example's `mixin="view"` with realistic `mixin="model"` and `mixin="none"` examples. - Replace "Until Wheels 4.1 lands / gh repo clone as interim" with the real `wheels packages install|list|search|show|update|remove|registry` CLI that shipped in #2276. - Update first-party package list: drop "wheels-i18n is planned for conversion" (shipped as v2.0.0) and add both wheels-i18n and wheels-seo-suite to the list of shipped packages. - Add dedicated sections: Service providers (register/boot lifecycle with ServiceProviderInterface) and Lazy loading (the `lazy: true` manifest flag for service-only packages). - Rewrite the testing section: replace the broken `directory=vendor.*` URL-param pattern (tracked by #2280) with a BDD spec example and a caution box pointing at the issue, plus guidance to rely on per-package CI. - Rewrite the publishing section with the actual registry submission checklist and flow (public repo, v<version> tag, file-type allowlist, 10 MB cap, PR title, mirror workflow bot-commits tarball+sha256). - Add a `lazy` field entry and mention `dependencies` ordering more explicitly in the manifest reference. Smaller fixes: - `glossary.mdx`: "Mixin target" entry no longer lists the non-existent `view` target. - `upgrading/3x-to-4x.mdx`: update `mixin="view"` annotation example to `mixin="model"` / `mixin="none"`. - `CLAUDE.md`: add a cross-link to the public packages guide and to wheels-packages/CONTRIBUTING.md, and refresh the first-party package list to include wheels-i18n and wheels-seo-suite. No code changes — docs and instructions only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(docs): refresh packages-index visual baseline The /packages landing page now renders wheels-i18n and wheels-seo-suite tiles alongside the original four first-party packages (shipped earlier today via wheels-dev/wheels-packages#3 and #4, closes #2268 and #2267). The existing baseline predates those registry entries, so visual-regression reports 34,529 pixels differ. Diff reviewed — only the two new package tiles; layout, typography, header, and existing tiles unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 3 of #2243 — ships the consumer CLI for the wheels-packages registry that Phase 1 (#2266) and Phase 2 set up. Users can now
wheels packages install wheels-sentryand have it appear undervendor/with the tarball sha256 verified against the registry's manifest, no ForgeBox or CommandBox involved.What's new
Eight verbs under
wheels packages:WHEELS_PACKAGES_REGISTRY=<org>/<repo>env var overrides the default registry — useful for forks, mirrors, and test registries.Architecture
Six components in
cli/lucli/services/packages/, each independently testable:HttpClient.cfcManifestCache.cfc~/.wheels/cache/packages/Registry.cfcVersionResolver.cfcvendor/wheels/SemVer.cfc(from #2231)Installer.cfctar -xzfintovendor/<name>/PackagesMainCli.cfc/PackagesRegistryCli.cfcDesign decisions locked in
--skip-checksumflag. This is the whole point of the registry-hosted-tarball design (defeats Attack A — force-push / tag rewrite).update <name>andupdate --allrequire--yes. No auto-pull on reload (Attack B defense).vendor/<name>/must not exist;--forceto overwrite.update --allcontinues on failure. Aggregates per-package results, exits non-zero if any failed (matchesdnf update/apt upgrade/npm update).tar. All target platforms ship it (macOS, Linux, Windows 10+). If Windows Server compat ever matters, swap the$extract()body for a Commons Compress JAR without changing theInstallerinterface.Tests
22 new specs under
cli/lucli/tests/specs/packages/. All network-free — they use aFakeHttpClientstub and a committed fixture tarball (wheels-fake-1.0.0.tar.gz) atcli/lucli/tests/_fixtures/packages/.VersionResolverSpec— 7 cases covering pin + wheelsVersion filtering, highest-wins, empty-versions, compatibleVersions ordering.ManifestCacheSpec— 6 cases covering round-trip read/write, TTL expiry, refresh, info.RegistrySpec— 7 cases covering list, cache reuse, manifest fetch, 404, 500, info, env fallback.InstallerSpec— 8 cases covering happy path, checksum mismatch, force overwrite, missing tarball, uninstall safety.PackagesMainCliSpec+PackagesRegistryCliSpec— 13 cases covering every CLI verb end-to-end against the fake stack.Docs
web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/packages/— 8 mdx files (index + per-verb).CLAUDE.md— Package System section updated to point at the new CLI instead of thegh repo cloneinterim.Out of scope
PackageLoader.cfc(design spec P9 — separate issue).tar.exeships on Windows 10+ so it should work; I didn't test it.Test plan
bash tools/test-cli-local.sh— 429 pass, 0 fail, 0 errorbash tools/test-local.sh— 3319 core framework tests passnpm run buildinweb/sites/guides/)wheels packages listagainst real registry once next LuCLI snapshot is builtFollow-ups
index.jsonsolistis one HTTP round-trip instead of N+1 (Phase 3.5, registry-side).wheels.dev/packages+ in-app/wheels/packages.PackageLoader.cfcnow that distribution-layer sha256 is authoritative.