fix: restore the prototype and establish regression coverage

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: pip install -r requirements-dev.txt
+      - run: ruff check .
+      - run: pytest -q

.gitignore

@@ -0,0 +1,16 @@
+.env
+.venv/
+venv/
+env/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.vscode/
+.idea/
+.DS_Store

README.md

@@ -1,12 +1,29 @@
-# Git SMS 📲 
+# Git SMS 📲
 
 Idea: Enabling GitHub collaboration, automation, and AI interaction via SMS text messages.
 
 > **DISCLAIMER:** Proof-of-concept, insecure by design, do not use in production, not a GitHub product. **As-Is, At Your Own Risk.**
 
+## Current implementation
+
+The executable proof of concept supports `help`, repository summaries, latest-issue summaries, numbered-issue summaries, optional natural-language interpretation of that read-only set, and TwiML replies for a Twilio webhook.
+
+Repository and issue creation remain intentionally disabled. The application imports and starts without credentials; AI-dependent commands return a useful configuration message until GitHub Models or OpenAI is configured.
+
+## Security model
+
+The current implementation does not yet provide Twilio signature verification, sender authorization, replay protection, idempotency, rate limiting, durable auditing, GitHub App authentication, or SMS-triggered Actions. These controls must exist before enabling writes or workflow dispatch.
+
+## Roadmap
+
+1. Authenticate and constrain inbound SMS requests.
+2. Add idempotency, rate limits, and audit records.
+3. Introduce a least-privilege GitHub App.
+4. Demonstrate one allowlisted `workflow_dispatch` command with run tracking.
+
 ## What It Is
 
-Git SMS is an open source project that shows a proof of concept to enable users to interact with GitHub and AI via SMS. Simply by texting a number you could summarize issues, pull requests, repos, and receive updates, and more.
+Git SMS is an open source project that shows a proof of concept to enable users to interact with GitHub and AI via SMS. Simply by texting a number you could summarize issues, pull requests, repos, receive updates, and more.
 
 This workflow brings the power of open source and AI to people who may not have consistent access to laptops, smartphones, or high-speed internet.
 
@@ -16,66 +33,66 @@ This workflow brings the power of open source and AI to people who may not have
 
 Fewer than 65% have reliable internet or a smartphone.
 
-Everyone should be able to participate in global innovation, contribute to the open source community, learn from others and interact 
-with AI.
+Everyone should be able to participate in global innovation, contribute to the open source community, learn from others, and interact with AI.
 
 This system enables:
-* Participation in open source and AI regardless of location or hardware
-* Communication over SMS network
-* Interaction with GitHub through a plain text interface
+
+- Participation in open source and AI regardless of location or hardware
+- Communication over the SMS network
+- Interaction with GitHub through a plain-text interface
 
 ## Use Cases
 
 This project can be adapted for a wide variety of scenarios, from individual developer productivity to large-scale community initiatives.
 
-*Bridging the Digital Divide & Empowering Communities*
+### Bridging the Digital Divide & Empowering Communities
 
 - **Offline First Contribution:** Allow individuals in areas with limited, expensive, or unreliable internet to contribute to open source projects by opening issues, commenting, and receiving updates via SMS.
-- **Bug Reporting from the Field:** Enable users of open source software in remote locations (e.g., agricultural tech, water management systems) to report bugs and provide feedback directly from their location using any mobile phone.
-- **Community Polling & Governance:** Use SMS to allow community members to vote on project features, governance decisions, or new initiatives, ensuring everyone has a voice regardless of their internet access.
-- **Educational Access:** Facilitate coding education by allowing students to interact with repositories, submit assignments as issues, and get feedback from instructors, all without requiring a computer or broadband.
-- **Citizen Journalism & Data Collection:** Empower individuals to submit reports, news tips, or data (e.g., local election monitoring, environmental observations) to a centralized repository as structured issues via SMS.
+- **Bug Reporting from the Field:** Enable users of open source software in remote locations to report bugs and provide feedback directly from their location using any mobile phone.
+- **Community Polling & Governance:** Use SMS to allow community members to vote on project features, governance decisions, or new initiatives.
+- **Educational Access:** Facilitate coding education without requiring a computer or broadband.
+- **Citizen Journalism & Data Collection:** Empower individuals to submit reports, news tips, or structured data to a centralized repository.
 
-*Developer & Project Manager Productivity*
+### Developer & Project Manager Productivity
 
-- **On the Go Issue Management:** Quickly create an issue to capture a bug or idea right when it occurs to you, whether you're commuting, in a meeting, or away from your desk.
-- **Emergency Code Review & Merge:** In critical situations, a project maintainer could receive an urgent pull request notification and approve a merge for a hotfix directly from their phone.
-- **Quick Status Checks:** Get a quick list of open issues, recent commits, or the status of pull requests for a repository while on the move without needing to open a laptop.
-- **Simple Project Scaffolding:** Create a new repository from a predefined template with a single SMS command, streamlining the start of new projects.
-- **Team Status Updates:** Allow team members to provide quick end-of-day status updates by commenting on a designated "daily stand-up" issue via text message.
+- **On the Go Issue Management:** Capture a bug or idea while away from a desk.
+- **Emergency Code Review & Merge:** Support carefully controlled emergency workflows from a phone.
+- **Quick Status Checks:** Get repository, issue, or pull-request status without opening a laptop.
+- **Simple Project Scaffolding:** Start predefined project workflows with a concise SMS command.
+- **Team Status Updates:** Submit lightweight status updates by text.
 
-*DevOps & Automation*
+### DevOps & Automation
 
-- **Triggering CI/CD Pipelines:** Initiate a build, test, or deployment process through a GitHub Actions workflow triggered by a specific SMS command (e.g., `DEPLOY <app> to staging`).
-- **Infrastructure Status & Control:** Create workflows where you can request the status of production systems (`STATUS <service>`) or trigger a restart of a service (`RESTART <service>`) via SMS.
-- **Incident Response & Management:** In the event of a production outage, receive an automated SMS alert and be able to create an incident issue, notify the team, and post updates from your phone.
-- **Release Management:** Trigger a release workflow that tags a new version, generates release notes from recent commits, and publishes the release, all initiated by an SMS command.
-- **Automated Reporting:** Schedule a GitHub Action to send a summary of weekly repository activity (e.g., new issues, closed PRs) to a list of stakeholders via SMS.
+- **Triggering CI/CD Pipelines:** Initiate a build, test, or deployment process through a tightly controlled GitHub Actions workflow.
+- **Infrastructure Status & Control:** Request status or invoke predefined operational workflows.
+- **Incident Response & Management:** Receive alerts and submit incident updates from a phone.
+- **Release Management:** Trigger an allowlisted release workflow.
+- **Automated Reporting:** Receive scheduled summaries of repository activity.
 
-*AI-Powered & Natural Language Interaction*
+### AI-Powered & Natural Language Interaction
 
-- **Code & Project Summarization:** Get a high-level summary of a complex pull request, a lengthy issue discussion, or even the purpose of an entire repository by sending a simple question like, "Summarize the latest PR in owner/repo."
-- **Natural Language Bug Reports:** Allow non-technical users to report issues in plain language (e.g., "The app crashes when I click the blue button"). An LLM backend can parse this, add appropriate labels, and create a well-formatted GitHub issue.
-- **Code Generation & Scaffolding:** Request simple code snippets or file creation via natural language (e.g., "Create a new Python file in repo with a function to calculate factorial").
-- **Knowledge Base Queries:** Use SMS to ask questions about a project's documentation. The AI could search the repository's markdown files and return a concise answer.
-- **AI-Assisted Task Management:** Tell the system, "Remind me to review the auth PR tomorrow," and have it create a new issue assigned to you with a due date.
+- **Code & Project Summarization:** Get a concise summary of a repository or issue discussion.
+- **Natural Language Bug Reports:** Convert plain-language reports into structured issue drafts.
+- **Code Generation & Scaffolding:** Request bounded code-generation workflows.
+- **Knowledge Base Queries:** Ask questions about project documentation.
+- **AI-Assisted Task Management:** Turn natural-language requests into carefully constrained tasks.
 
-*Beyond Software Development*
+### Beyond Software Development
 
-- **Field Service & Maintenance Reporting:** Technicians in the field can report equipment status, log maintenance tasks, or request parts by sending an SMS that creates an issue in a project repository.
-- **Disaster Response & Coordination:** Enable first responders to report incidents, request resources, and provide status updates via SMS, which would populate a centralized dashboard or issue tracker for coordination.
-- **Scientific Research & Citizen Science:** Allow researchers and volunteers in the field without internet to submit data points, observations, or findings to a project repository via text message.
-- **Inventory & Asset Management:** Use SMS to log the status or location of physical assets, creating a commit or issue in a repository that serves as a lightweight asset tracking system.
+- **Field Service & Maintenance Reporting:** Report equipment status or maintenance tasks by SMS.
+- **Disaster Response & Coordination:** Submit incidents, resource requests, and updates over low-bandwidth networks.
+- **Scientific Research & Citizen Science:** Submit observations or findings from the field.
+- **Inventory & Asset Management:** Log status or location changes through controlled workflows.
 
-## Demo 
+## Demo
 
 [Prototype Simulation](https://gh.io/git-sms-simulation)
 
 ## Setup
 
-[Step-by-step Proof of Concept](https://github.com/github/git-sms/blob/main/SETUP.md)
+[Step-by-step Proof of Concept](SETUP.md)
 
 ## Maintainers
 
-* [Ashley Wolf](https://github.com/ashleywolf)
-* [Dan Velton](https://github.com/dvelton)
+- [Ashley Wolf](https://github.com/ashleywolf)
+- [Dan Velton](https://github.com/dvelton)

SETUP.md

@@ -1,83 +1,46 @@
-## 🚀 Setup Instructions
+## Setup Instructions
 
-This project lets you interact with GitHub (summarize repos, issues, PRs, etc.) via SMS using Twilio and OpenAI.
+Git SMS is a read-only proof of concept for summarizing public GitHub repositories and issues through an SMS webhook. Write operations remain intentionally disabled.
 
----
-
-### 1. Clone the Repo
+### Install
 
 ```bash
 git clone https://github.com/your-username/git-sms.git
 cd git-sms
-```
-
-### 2. Set Up Python Environment
-
-```bash
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-### 3. Create a `.env` File
-
-Create a file named `.env` in the project root and add your credentials:
+Tested on Python 3.10, 3.11, and 3.12.
 
-```env
+### Optional credentials
 
-# OpenAI
-OPENAI_API_KEY=your_openai_api_key
+Create `.env` when you want AI summaries:
 
-# GitHub authentication (optional, read-only)
-# Only public read-only access is supported; write operations are disabled.
+```env
+GITHUB_OPENAI_API_KEY=your_github_models_token
+# OPENAI_API_KEY=your_openai_api_key
+# GITHUB_TOKEN=your_optional_read_only_token
 ```
 
----
+The application imports and starts without credentials. AI-dependent commands return a clear SMS response until a provider key is configured.
 
-### 4. Run the Server
+### Run
 
 ```bash
 uvicorn main:app --reload
 ```
 
-Your server will be available at: [http://127.0.0.1:8000](http://127.0.0.1:8000)
-
----
-
-### 5. Expose with ngrok
-
-In a separate terminal window:
-
-```bash
-ngrok http 8000
-```
-
-Copy the HTTPS URL it provides (e.g., `https://abc123.ngrok.io`).
-
----
-
-### 6. Configure Twilio Webhook
-
-1. Go to your [Twilio Console](https://console.twilio.com/)
-2. Navigate to your **Phone Number > Messaging > Webhook**
-3. Set the webhook URL to:
-
-```
-https://abc123.ngrok.io/webhook
-```
-
-4. Set the method to `POST`
-
----
+Expose port 8000 and configure a Twilio incoming-message webhook to POST to `/webhook`.
 
-### ✅ Done
+> This proof of concept does not validate Twilio signatures or authorize senders. Do not deploy it in production.
 
-Try texting your Twilio number with:
+### Commands
 
 ```text
 help
-summarize github/github
+summarize github/git-sms
+summarize owner/repo issue
 summarize owner/repo issue 123
 ```
-
-Let the bots do the rest.

commands.py

@@ -1,17 +1,47 @@
-# commands.py
+"""GitHub command utilities and intentionally disabled write operations."""
+
+from __future__ import annotations
 
 import os
+from dataclasses import dataclass
+
 import requests
 
-def get_headers():
-    # Only read-only access with no authentication token
-    return {
-        "Accept": "application/vnd.github+json"
-    }
+GITHUB_API = "https://api.github.com"
+REQUEST_TIMEOUT = 10
+
+
+@dataclass(frozen=True)
+class CommandOutcome:
+    enabled: bool
+    message: str
+
+
+def get_headers() -> dict[str, str]:
+    headers = {"Accept": "application/vnd.github+json"}
+    token = os.getenv("GITHUB_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
 
-def get_authenticated_username():
-    user_url = "https://api.github.com/user"
-    user_res = requests.get(user_url, headers=get_headers())
-    if not user_res.ok:
+
+def get_authenticated_username() -> str | None:
+    if not os.getenv("GITHUB_TOKEN"):
+        return None
+    try:
+        response = requests.get(f"{GITHUB_API}/user", headers=get_headers(), timeout=REQUEST_TIMEOUT)
+        if not response.ok:
+            return None
+        payload = response.json()
+    except (requests.RequestException, ValueError):
         return None
-    return user_res.json().get("login")
+    login = payload.get("login") if isinstance(payload, dict) else None
+    return str(login) if login else None
+
+
+def create_repo(name: str) -> CommandOutcome:  # noqa: ARG001
+    return CommandOutcome(False, "Repository creation is disabled in this proof of concept.")
+
+
+def create_issue(repo: str, title: str, body: str) -> CommandOutcome:  # noqa: ARG001
+    return CommandOutcome(False, "Issue creation is disabled in this proof of concept.")

llm_client.py

@@ -0,0 +1,56 @@
+"""Lazy LLM provider selection for Git SMS."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+class LLMNotConfiguredError(RuntimeError):
+    """Raised when no supported LLM credential is configured."""
+
+
+def get_llm_client() -> tuple[str, Any]:
+    github_models_key = os.getenv("GITHUB_OPENAI_API_KEY")
+    if github_models_key:
+        from azure.ai.inference import ChatCompletionsClient
+        from azure.core.credentials import AzureKeyCredential
+
+        return "github-models", ChatCompletionsClient(
+            endpoint="https://models.github.ai/inference",
+            credential=AzureKeyCredential(github_models_key),
+        )
+
+    openai_key = os.getenv("OPENAI_API_KEY")
+    if openai_key:
+        from openai import OpenAI
+
+        return "openai", OpenAI(api_key=openai_key)
+
+    raise LLMNotConfiguredError("Set GITHUB_OPENAI_API_KEY or OPENAI_API_KEY to enable AI features.")
+
+
+def complete_text(*, system_prompt: str, user_prompt: str, temperature: float, max_tokens: int) -> str:
+    provider, client = get_llm_client()
+    if provider == "github-models":
+        from azure.ai.inference.models import SystemMessage, UserMessage
+
+        response = client.complete(
+            model=os.getenv("GITHUB_MODELS_MODEL", "openai/gpt-4o"),
+            messages=[SystemMessage(content=system_prompt), UserMessage(content=user_prompt)],
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+    else:
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o"),
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+    if not response or not response.choices or not response.choices[0].message.content:
+        raise RuntimeError("The configured LLM returned no content.")
+    return str(response.choices[0].message.content).strip()