[FEATURE] Distribution & packaging overhaul — PyPI + Docker + Homebrew + binary + signing

[Wolfvin]

Summary

CodeLens is currently installable only via git clone + setup.sh. Replace with 6 distribution channels (PyPI, Docker, Homebrew, Scoop, Nix, self-contained binary) + release signing (minisign + Cosign) + auto-update command. Critical for adoption — install barrier = user drop-off.

Worker consensus (7 reports — strongest convergence in the analysis)

Worker	Source	Contribution
OpenTaint	update!/CodeLens_vs_OpenTaint_Upgrade_Analysis.md D2	Python package entry point & pipx support — refactor scripts/ → codelens/ package, pyproject.toml entry point, pip install codelens / pipx install codelens. 1-2 weeks.
OpenTaint	same file D1	Multi-channel installer: curl install.sh, install.ps1, Homebrew cask, npm wrapper, npx zero-install, pipx, Docker. 2 weeks, depends on D2.
UBS	update!/CodeLens_UBS_Upgrade_Analysis.md #11	6 channels: Homebrew tap, Scoop bucket, Nix flake, Docker/OCI, curl install, PyPI. GitHub Releases with 5 platform binaries + SHA256SUMS + SBOM + SLSA.
UBS	same file #12	Release signing: minisign (offline key) + Cosign keyless (OIDC) for OCI image, sign by digest, Rekor transparency log, SBOM (SPDX) + SLSA provenance.
UBS	same file #23	Docker/OCI image + GitHub Container Registry — python:3.11-slim base, multi-arch amd64+arm64, <200MB compressed, GHCR publish, Cosign sign.
CodeGraph	update!/CodeLens_CodeGraph_Upgrade_Analysis.md #22	Self-contained binary via PyInstaller — 6 platform targets (linux-x64/arm64, darwin-x64/arm64, win32-x64/arm64), bundle Python runtime + tree-sitter + grammars, <80MB, cold start <500ms.
Opengrep	update!/CodeLens_Opengrep_Upgrade_Analysis.md #43	Self-contained binary via PyInstaller (simpler than Nuitka) — 5 platforms, <50MB, GitHub Actions release workflow, Cosign signing, Homebrew tap (v2), Docker image.
Repomix	update!/CodeLens_vs_Repomix_Upgrade_Analysis.md R12	Docker image (python:3.11-slim + setup.sh) + flake.nix for NixOS. GHCR multi-arch.
Serena	update!/CodeLens_vs_Serena_Upgrade_Analysis.md S16	2 Docker images: minimal (core only) + maximal (all LSP servers pre-installed) + compose.yaml.
CodeGraph	same file #21	Tree-sitter WASM runtime — eliminates native C compile requirement, enables Alpine/slim Docker. Bundles 24 .wasm grammar files.

Proposed phased scope

Phase 1 — Python package + PyPI (P1, 1-2 weeks, foundational)

• Refactor scripts/ → codelens/ package with __init__.py
• Convert sys.path-based imports to absolute imports
• pyproject.toml entry point: [project.scripts] codelens = "codelens.cli:main"
• pip install codelens / pipx install codelens
• Backward compat: python3 scripts/codelens.py still works (legacy mode + deprecation warning)
• GitHub Actions publish-pypi.yaml on tag push

Phase 2 — Docker image (P1, 1 week)

• Dockerfile (minimal: python:3.11-slim + core)
• Dockerfile.maximal (all LSP servers pre-installed) — depends on native LSP server issue
• Multi-arch linux/amd64 + linux/arm64 via docker buildx
• GHCR publish: ghcr.io/wolfvin/codelens:latest, :v8.x.y, :maximal-latest
• Run as non-root codelens user
• HEALTHCHECK CMD codelens --version

Phase 3 — Self-contained binary (P1, 2-3 weeks)

• PyInstaller (simpler than Nuitka)
• 5 platform targets: linux-x64, darwin-x64, darwin-arm64, win32-x64, win32-arm64
• Bundle: Python runtime + tree-sitter (native .so/.dll via --add-binary) + all grammars + PyYAML + watchdog
• Binary size <80MB compressed, cold start <500ms
• install.sh (Linux/macOS) + install.ps1 (Windows) downloaders
• GitHub Actions matrix build, upload to Releases

Phase 4 — Homebrew + Scoop + Nix (P2, 1 week)

• Homebrew tap: Wolfvin/homebrew-tap, brew install wolfvin/tap/codelens
• Scoop bucket: Wolfvin/scoop-bucket
• Nix flake: flake.nix with packages.default, devShells.default, nixosModules.codelens

Phase 5 — Release signing (P1, 1 week)

• minisign for installer + SHA256SUMS (offline private key as GitHub Secret base64)
• Cosign keyless (OIDC) for OCI image — sign by digest, Rekor transparency log
• SBOM (SPDX) via syft or cyclonedx-bom
• SLSA provenance via slsa-framework/slsa-github-generator
• Verification guide at docs/security.md

Phase 6 — Auto-update command (P2, 1 week, optional)

• codelens upgrade [version] detects install method (pip, homebrew, source, binary) and updates accordingly
• --check flag compares current vs latest GitHub Release
• Windows wrinkle: spawn DETACHED helper that waits for current process exit

Acceptance criteria

• pip install codelens works on Python 3.8+
• docker run --rm -v $(pwd):/workspace ghcr.io/wolfvin/codelens scan /workspace works
• Self-contained binary <80MB, cold start <500ms on all 5 platforms
• brew install wolfvin/tap/codelens works
• All releases signed with minisign + Cosign
• SBOM + SLSA provenance attached to every release

License / IP note

No external code copy — all distribution code is original. ast-grep binary (if used for rule accelerator) is MIT-licensed and can be redistributed.

Related

• Depends on OpenTaint D3 / existing issue [BUG-03] Version drift across 6 files — pyproject=7.2.0, utils.py=8.0.0, README=v8.2, SKILL.md=v8.1 #37 (version source of truth) — package metadata must be consistent before PyPI publish
• Depends on existing issue [BUG-04] Command count is inconsistent across 7 sources — actual=60, docs say 45/56/57/41 #38 (command count) — skill.json must be auto-generated before PyPI publish