LuCLI: module distribution (lucli modules install wheels) Issue #1947

[bpamiri]

The Wheels LuCLI module (`cli/lucli/`) needs to be installable via:

```bash
lucli modules install wheels --url https://github.com/wheels-dev/wheels
```

LuCLI's module installer extracts from Git archives. Need to verify it can install from a subdirectory (`cli/lucli/`) of the monorepo.

Fallback: Dedicated `wheels-dev/wheels-cli-lucli` repo with just the module files, auto-published from the monorepo via GitHub Actions.

Part of #1942

[bpamiri]

Analysis

Synopsis

The Wheels LuCLI module (cli/lucli/) needs to be installable via lucli modules install wheels. The core challenge is that the module lives in a subdirectory of the monorepo, not a standalone repository, and LuCLI's installer expects to clone/extract a full Git repo.

Merit Assessment

Recommendation: Proceed

• This is a hard prerequisite for Phase 3 (Homebrew/Chocolatey formula updates in LuCLI: update Homebrew formula for LuCLI Issue #1945 #1945/LuCLI: update Chocolatey package for LuCLI Issue #1946 #1946) — nothing ships without a working install path.
• LuCLI installs modules to ~/.lucli/modules/<name>/ and expects Module.cfc + module.json at the repo root. The monorepo layout (cli/lucli/Module.cfc) won't work out of the box.
• The fallback plan (auto-publish to wheels-dev/wheels-cli-lucli via GitHub Actions) is the pragmatically correct approach, since modifying LuCLI's installer for subdirectory support adds upstream complexity.

Implementation Plan

1. Verify LuCLI's archive extraction — Confirm that lucli modules install --url=<git-url> always expects Module.cfc at archive root. Check ModulesInstallCommandImpl.java in cybersonic/LuCLI. If it supports a --path or subdirectory option, use that (unlikely based on current docs).

2. Create wheels-dev/wheels-cli-lucli repo — Minimal repo containing only the module files:

   • Module.cfc (from cli/lucli/Module.cfc)
   • module.json (from cli/lucli/module.json)
   • services/ (from cli/lucli/services/)

3. GitHub Actions sync workflow — In the main wheels-dev/wheels repo, add a workflow that:

   • Triggers on push to develop when cli/lucli/** changes
   • Copies cli/lucli/* to a checkout of wheels-dev/wheels-cli-lucli
   • Commits and pushes (or creates a release tag matching the module version in module.json)

4. Template resolution — The Templates.cfc service (cli/lucli/services/Templates.cfc, line 156-171) resolves templates by walking up from cli/lucli/ to cli/src/templates/. When installed standalone to ~/.lucli/modules/wheels/, this path won't exist. Two options:

   • Option A: Bundle cli/src/templates/ into the distribution repo (adds ~20 files, ~15KB). Simple, self-contained.
   • Option B: Read templates from the project's vendor/wheels/cli/src/templates/ at runtime (already the fallback at line 168). This works only if the user's project has Wheels vendored.
   • Recommendation: Do both — bundle templates for standalone use, fall back to project vendor for overrides.

5. Update Homebrew/Chocolatey formulas (LuCLI: update Homebrew formula for LuCLI Issue #1945 #1945/LuCLI: update Chocolatey package for LuCLI Issue #1946 #1946) to point at the distribution repo URL.

6. Test the install flow:

   lucli modules install wheels --url https://github.com/wheels-dev/wheels-cli-lucli
   lucli wheels generate model User name email

Estimated complexity: Medium. ~1 day for the sync workflow, ~half day for template bundling, ~half day for testing.

Dependencies & Risks

• Upstream dependency: If LuCLI adds subdirectory support (unlikely near-term), the distribution repo becomes unnecessary. Keep it anyway for simplicity.
• Template drift: The sync workflow must stay reliable — if cli/src/templates/ changes without triggering the sync, installed modules will generate stale code. Mitigate by including cli/src/templates/** in the workflow trigger glob.
• Blocks: LuCLI: update Homebrew formula for LuCLI Issue #1945 #1945 (Homebrew), LuCLI: update Chocolatey package for LuCLI Issue #1946 #1946 (Chocolatey), LuCLI: end-to-end testing against real project #1949 (E2E testing)
• Related: LuCLI: tracking issue for Phases 2-4 Issue #1942 #1942 (tracking), LuCLI: wheels new myapp — full project scaffolding #1943 (wheels new needs templates), PLAN.md Phase 3

---

Automated analysis by @claude — review and adjust as needed.