lgtmaybe 0.0.1__tar.gz

lgtmaybe-0.0.1/.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv --version)",
+      "Bash(uv sync *)",
+      "Bash(uv run *)",
+      "Bash(git check-ignore *)",
+      "Bash(gh auth *)",
+      "Bash(git ls-remote *)",
+      "Bash(gh repo *)",
+      "Bash(git ls-tree *)",
+      "Bash(git checkout *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(gh pr create --base main --head foundation --title 'foundation: freeze contracts, fakes, structured logging, CI' --body ' *)",
+      "Bash(gh pr *)",
+      "Bash(echo \"--- exit: $? ---\")",
+      "Bash(git pull *)",
+      "Bash(env)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/lgtmaybe/json)",
+      "Bash(uv build *)",
+      "Bash(uvx twine *)"
+    ]
+  }
+}

lgtmaybe-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync (with dev deps)
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Types
+        run: uv run mypy
+
+      - name: Tests
+        run: uv run pytest -q

lgtmaybe-0.0.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

lgtmaybe-0.0.1/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+Guidance for agents working in **lgtmaybe** — a provider-agnostic PR reviewer.
+Read this before writing code. It encodes decisions that are **made, not options**.
+
+## What this is
+
+A PR reviewer that posts inline review comments + a summary. The user picks the
+LLM backend with a `--provider` flag, drops a key into GitHub secrets (or wires
+OIDC/WIF for cloud providers), and gets a review. One core, two distribution
+variants:
+
+- **PyPI CLI** — `pip install lgtmaybe`
+- **GitHub Action** — Docker container action pulling a GHCR image
+
+**The wedge:** first-class **Bedrock + Vertex with keyless OIDC/WIF**. Five
+providers, one flag, no keys in secrets for cloud. We do not try to out-feature
+pr-agent; we win on auth + simplicity. Reuse its proven mechanics, don't clone
+its surface.
+
+## Non-negotiables
+
+- **TDD, always: red → green → refactor.** Write the acceptance test from a
+  task's stated in/out *first*, watch it fail, write the minimum code to pass,
+  then refactor. CI rejects a PR whose diff adds code without a test.
+- **Structured output only.** The model returns JSON (`severity`, `file`,
+  `line`, `body`, `suggestion`). Never parse prose.
+- **Fork safety.** Trigger on `pull_request_target` so the review has secrets,
+  but **never check out or execute PR code** — fetch the diff via API only.
+  Treat all diff content as untrusted input.
+- **No static cloud keys.** Bedrock uses ambient AWS creds; Vertex uses ambient
+  GCP creds. Never accept or require a service-account JSON or static AWS key.
+
+## Key decisions (do not relitigate)
+
+- **Language:** Python.
+- **Provider spine:** [litellm] — normalises openai, openrouter, anthropic,
+  bedrock, vertex, ollama to one `completion()` call. A thin wrapper on top adds
+  retries / fallback / cost.
+- **License:** MIT (already in `LICENSE`).
+- **Posting:** REST review API — batched inline comments + one summary.
+  Idempotent updates via a hidden marker comment.
+
+### Auth model — resolved by provider (chain of responsibility)
+
+| Provider               | Auth                                                              |
+|------------------------|------------------------------------------------------------------|
+| openai / openrouter / anthropic | API key from `secrets.*` / env / `--api-key`            |
+| bedrock                | ambient AWS creds (GitHub OIDC role, or local `~/.aws`); IAM `bedrock:InvokeModel*` only |
+| vertex                 | ambient GCP creds (WIF, or local ADC)                            |
+| ollama                 | none — just an `api_base` (localhost, host.docker.internal, tailscale host); fully local, zero cost |
+
+Resolver order: chosen provider → try ambient cloud creds if that's its native
+mode → else API key → ollama needs neither → else **fail with a clear "how to
+auth this provider" message**.
+
+## Architecture — ports & adapters (hexagonal)
+
+This is what lets tracks build in parallel against frozen contracts.
+
+- `core/ports.py` — the ports (interfaces). **Frozen in the foundation step.**
+- litellm / github classes — the adapters.
+- **Engine is a pipeline:** `fetch → compress → prompt → parse → post`, as
+  composable stages.
+- **Provider choice:** strategy + factory. The `--provider` flag selects a
+  strategy; a small factory builds the `ProviderClient` (litellm keeps it tiny).
+- **Credential resolution:** chain of responsibility (see auth table).
+- **Dependency injection:** inject ports into the engine — this is what makes
+  fakes + dry-run drop in.
+
+**Deliberately skipped** (don't add without a written reason): repository
+pattern, event bus, plugin framework.
+
+## Parallel build structure
+
+1. **Foundation (sequential, first):** freeze the contracts in `core/ports.py`,
+   plus structured logging for CI debugging. Everything downstream codes against
+   these frozen ports.
+2. **Parallel tracks**, each against frozen contracts:
+   - **Track A** — provider/litellm wrapper: retries, fallback, **cost reporting**.
+   - **Track B** — github adapter + diff handling; **skip generated/binary files**
+     (lockfiles, minified, vendored).
+   - **Track C** — hardening: **prompt-injection defense** (PR text trying to
+     steer the reviewer), **secret redaction in diffs before they leave for the
+     LLM**, fork-PR exposure (already handled by `pull_request_target` + no checkout).
+   - **CLI track** — PyPI packaging, `--dry-run` for local dev.
+3. **Integration (sequential, last):** wire stages; surface errors (**a failed
+   review posts a comment, never fails silently**); fold cost into the summary.
+
+Every task carries its inputs/outputs and an acceptance test so an agent can
+self-verify without asking. The acceptance test *is* the red step — start there.
+
+## Conventions
+
+- **Docs:** `manual-steps.md` holds the human-only setup (cloud roles,
+  registries, marketplace).
+- Treat diff content as untrusted everywhere it flows.
+- Errors surface to the user; never swallow them.
+
+[litellm]: https://github.com/BerriAI/litellm

lgtmaybe-0.0.1/Dockerfile

@@ -0,0 +1,13 @@
+# Container action image (published to GHCR). The CLI track wires the real
+# entrypoint; this builds the skeleton into a runnable image today.
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:0.10.6 /uv /uvx /bin/
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN uv sync --no-dev
+
+ENTRYPOINT ["uv", "run", "python", "-m", "lgtmaybe"]

lgtmaybe-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Coles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lgtmaybe-0.0.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: lgtmaybe
+Version: 0.0.1
+Summary: Provider-agnostic PR reviewer — five providers, one flag, no keys in secrets for cloud.
+Project-URL: Homepage, https://github.com/lgtmaybe/lgtmaybe
+Author: Matt Coles
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# lgtmaybe
+
+Provider-agnostic PR reviewer. Five providers, one flag, no keys in secrets for
+cloud. Posts inline review comments + a summary.
+
+> Status: under construction. See `CLAUDE.md` for the build plan and
+> `manual-steps.md` for the human-only setup.
+
+## Providers
+
+`openai` · `openrouter` · `anthropic` · `bedrock` (keyless OIDC) ·
+`vertex` (keyless WIF) · `ollama` (local, zero cost)
+
+## Distribution
+
+- **CLI** — `pip install lgtmaybe`
+- **GitHub Action** — Docker container action from GHCR
+
+## License
+
+MIT — see `LICENSE`.

lgtmaybe-0.0.1/README.md

@@ -0,0 +1,21 @@
+# lgtmaybe
+
+Provider-agnostic PR reviewer. Five providers, one flag, no keys in secrets for
+cloud. Posts inline review comments + a summary.
+
+> Status: under construction. See `CLAUDE.md` for the build plan and
+> `manual-steps.md` for the human-only setup.
+
+## Providers
+
+`openai` · `openrouter` · `anthropic` · `bedrock` (keyless OIDC) ·
+`vertex` (keyless WIF) · `ollama` (local, zero cost)
+
+## Distribution
+
+- **CLI** — `pip install lgtmaybe`
+- **GitHub Action** — Docker container action from GHCR
+
+## License
+
+MIT — see `LICENSE`.

lgtmaybe-0.0.1/manual-steps.md

@@ -0,0 +1,53 @@
+# lgtmaybe — manual steps
+
+things an agent cant do for you. work top to bottom; each block says *when* in the build it's needed.
+
+---
+
+## A. before any code (day one)
+- [ ] create github org/repo `lgtmaybe` (confirm `lgtm-ai` isnt yours — it's a different project).
+- [ ] `pip install build twine` and push a `0.0.1` placeholder to pypi to hold the name. real release comes later.
+- [ ] enable branch protection on `main`: require CI green, require a PR.
+
+## B. provider credentials (needed to run a real review)
+pick whichever providers you'll actually demo. you do **not** need all five.
+
+### key-based (openai / openrouter / anthropic)
+- [ ] generate an api key in that provider's console.
+- [ ] add it as a github **repo secret** (e.g. `OPENAI_KEY`, `ANTHROPIC_KEY`, `OPENROUTER_KEY`).
+
+### bedrock (keyless, via OIDC) — the wedge, worth doing
+- [ ] in AWS, create an IAM **OIDC identity provider** for `token.actions.githubusercontent.com`.
+- [ ] create an IAM **role** with a trust policy scoped to your repo (`repo:<org>/lgtmaybe:*`).
+- [ ] attach a least-privilege policy: `bedrock:InvokeModel` + `bedrock:InvokeModelWithResponseStream` on the specific model ARNs only.
+- [ ] note the **role ARN** — it becomes the `aws_role_arn` action input. no static key is ever stored.
+- [ ] confirm the models you want are enabled in the target region (model access request in the Bedrock console).
+
+### vertex (keyless, via workload identity federation)
+- [ ] create a GCP **workload identity pool** + a github provider in it.
+- [ ] create a service account with `roles/aiplatform.user` (or narrower).
+- [ ] grant the github principal permission to impersonate that SA, scoped to your repo.
+- [ ] note the **WIF provider resource name** — it becomes `gcp_wif_provider`.
+
+## C. repo permissions for the action
+- [ ] the workflow needs `permissions: id-token: write` (for OIDC) and `pull-requests: write` (to post comments).
+- [ ] decide the trigger: `pull_request_target` (so secrets are available) — and confirm the action never checks out PR code, only reads the diff.
+
+## D. publishing (step 4 of the plan)
+
+### pypi CLI via trusted publishing (no token in secrets)
+- [ ] on pypi, add a **trusted publisher** for the repo + the release workflow name + environment.
+- [ ] no `PYPI_TOKEN` secret needed — the release workflow authenticates via OIDC.
+
+### GHCR image
+- [ ] confirm `packages: write` permission in the release workflow; GHCR uses the built-in `GITHUB_TOKEN`, nothing manual beyond that.
+
+### marketplace listing
+- [ ] add an `action.yml` with `name`, `description`, `branding` (icon + colour).
+- [ ] tag a release (`v1.0.0`) and a floating `v1`.
+- [ ] from the release page, tick **"Publish this Action to the GitHub Marketplace"**, accept terms, pick categories (`code-review`, `continuous-integration`).
+
+## E. before you announce / blog it
+- [ ] run lgtmaybe on its own repo (dogfood) so the README screenshot is real.
+- [ ] write the data/privacy statement: which provider sees the diff, and that cloud variants send no static keys.
+- [ ] sanity-check the least-privilege IAM/WIF scopes one more time before the repo goes public.

lgtmaybe-0.0.1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "lgtmaybe"
+version = "0.0.1"
+description = "Provider-agnostic PR reviewer — five providers, one flag, no keys in secrets for cloud."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "Matt Coles" }]
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/lgtmaybe/lgtmaybe"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lgtmaybe"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.12"
+packages = ["lgtmaybe"]
+mypy_path = "src"
+strict = true

lgtmaybe-0.0.1/src/lgtmaybe/__init__.py

@@ -0,0 +1,3 @@
+"""lgtmaybe — provider-agnostic PR reviewer."""
+
+__version__ = "0.0.1"

lgtmaybe-0.0.1/src/lgtmaybe/__main__.py

@@ -0,0 +1,20 @@
+"""Module entrypoint placeholder.
+
+The real CLI is wired in the CLI track. For now this keeps `python -m lgtmaybe`
+(and the Docker ENTRYPOINT) runnable on the skeleton.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    print(f"lgtmaybe {__version__} — CLI not wired yet (see CLAUDE.md)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

lgtmaybe-0.0.1/src/lgtmaybe/cli/__init__.py

@@ -0,0 +1 @@
+"""cli — populated by its track (see CLAUDE.md)."""

lgtmaybe-0.0.1/src/lgtmaybe/config/__init__.py

@@ -0,0 +1 @@
+"""config — populated by its track (see CLAUDE.md)."""

lgtmaybe-0.0.1/src/lgtmaybe/core/__init__.py

@@ -0,0 +1 @@
+"""Core: frozen data contracts and boundary interfaces (ports)."""