feat(distribution): pip-installable package + PyPI publish workflow (closes #54 phase-1)

[Wolfvin]

Closes #54 (Phase 1 only — Python package + PyPI)

What

Implements Phase 1 of issue #54: makes CodeLens pip-installable and adds a PyPI publish workflow.

Changes

New: codelens/ package

• codelens/__init__.py — thin wrapper that delegates to scripts/codelens.py
• codelens/__main__.py — enables python -m codelens
• Resolves scripts/ dir at runtime (works in source checkout AND installed package)
• main() function loads legacy codelens.py via importlib
• Exports __version__ = "8.2.0" for programmatic access

pyproject.toml

• [project.scripts] codelens = "codelens:main" — console entry point
• [tool.setuptools.packages.find] includes both codelens/ and scripts/ subpackages (commands, formatters, parsers, plugins)
• scripts/codelens.py excluded from auto-discovery (would shadow the package)

setup.py (new)

• Explicitly lists top-level .py modules from scripts/ (excluding codelens.py)
• Prevents setuptools from creating a conflicting codelens module

scripts/codelens.py

• Legacy mode (python3 scripts/codelens.py) now prints a DeprecationWarning pointing to the codelens console command
• Fully backward compatible — legacy mode still works

.github/workflows/publish-pypi.yml (new)

• Triggers on tag push (v*.*.*)
• Builds sdist + wheel via python -m build
• Publishes to PyPI via trusted publishing (OIDC) — no API token needed
• TestPyPI publish on manual workflow_dispatch
• Requires configuring trusted publishing at https://pypi.org/manage/account/publishing/

docs/install.md (new)

• Documents 4 install methods: pip install, pipx install, python -m codelens, from source
• Optional extras table (grammars, rules, watch, lsp, dev, all)
• Troubleshooting section (PATH, Unicode on Windows, grammar not found)

Synced docs

• README.md, SKILL.md, SKILL-QUICK.md, scripts/graph_model.py — command count 68→69, MCP tools 66→67 (from prior PRs, needed for consistent package metadata before PyPI publish)

Verification

All 4 install methods tested and working:

# 1. Console command (after pip install)
$ codelens --command-count
69

# 2. python -m codelens
$ python -m codelens --command-count
69

# 3. import codelens
$ python -c "import codelens; print(codelens.__version__)"
8.2.0

# 4. Legacy mode (with deprecation warning)
$ python3 scripts/codelens.py --command-count
DeprecationWarning: Running codelens via 'python3 scripts/codelens.py' is the legacy mode...
69

End-to-end scan via pip install:

$ codelens init /tmp/test && codelens scan /tmp/test
{"status": "ok", ...}

Test suite: 1347 passed, 76 skipped, 0 failed (no regressions)

Acceptance criteria status

• pip install codelens works on Python 3.8+ (tested 3.12)
• PyPI publish workflow triggers on tag push (will verify after first tag)
• Backward compat: python3 scripts/codelens.py still works (with deprecation warning)
• GitHub Actions publish-pypi.yaml on tag push

Not in this PR (future phases)

• Phase 2: Docker image (docker run ghcr.io/wolfvin/codelens)
• Phase 3: Self-contained binary via PyInstaller
• Phase 4: Homebrew, Scoop, Nix
• Phase 5: Release signing (minisign + Cosign + SBOM + SLSA)
• Phase 6: Auto-update command (codelens upgrade)

Test plan

• codelens console command works after pip install -e .
• python -m codelens works
• import codelens returns correct __version__
• Legacy python3 scripts/codelens.py works with deprecation warning
• codelens init + codelens scan end-to-end works
• Full test suite: 1347 passed, 0 failed
• CI: full test suite passes
• First tag push triggers PyPI publish workflow

Setup required before first PyPI publish

1. Configure trusted publishing at https://pypi.org/manage/project/codelens/publishing/
   • GitHub workflow: Wolfvin/CodeLens
   • Workflow name: Publish to PyPI
   • Environment: pypi
2. Create the pypi environment in GitHub repo settings (Settings → Environments)
3. Tag a release: git tag v8.3.0 && git push --tags

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[Wolfvin]

Closing as duplicate — #145 has more complete implementation (MANIFEST.in, packaging tests, CHANGELOG). Merge #145 instead.