Skip to content

Commit ad96946

Browse files
nomenarktnomenarkt
authored
Merge pull request #2 from nomenarkt/docs-and-cleanup
Cleanup: Update docs, remove render.yaml, and clean pycache files
2 parents cc4e3cd + 35fff6d commit ad96946

File tree

10 files changed

+59
-27
lines changed

10 files changed

+59
-27
lines changed

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,19 @@ venv/
1111

1212
# System
1313
.DS_Store
14+
15+
.env
16+
17+
# Editor files
18+
*.swp
19+
*.swo
20+
*.bak
21+
*~
22+
.idea/
23+
.vscode/
24+
25+
# Test output
26+
htmlcov/
27+
.coverage
28+
.tox/
29+
.pytest_cache/

‎PRD.md‎

650 Bytes

🧰 Features (Functional Scope)

Feature Description
Recursive File Tree Scan Read and list all files under a folder (depth N).
Read File Contents Base64-decode and return raw content of any file.
Write File Contents Update or create a file in a specified branch.
Detect Module Boundaries Identify domain modules from paths.
Track Missing Interfaces Compare usecase interfaces to existing implementations.
Scan for Project Health Report dead code, stubs, TODOs, broken layers.
Enable GPT Planning GPTs generate next features/tasks directly from structure.
Feature Description Status
Recursive File Tree Scan Read and list all files under a folder (depth N). ✅ Shipped
Read File Contents Base64-decode and return raw content of any file. ✅ Shipped
Write File Contents Update or create a file in a specified branch. ✅ Shipped
Plugin Manifest & OpenAPI Provides ai-plugin.json and openapi.yaml for GPT Actions ✅ Shipped
Planned: Detect Module Boundaries Identify domain modules from paths. 🚧 Planned
Planned: Track Missing Interfaces Compare usecase interfaces to existing implementations. 🚧 Planned
Planned: Scan for Project Health Report dead code, stubs, TODOs, broken layers. 🚧 Planned
Planned: Enable GPT Planning GPTs generate next features/tasks directly from structure. 🚧 Planned

Features marked Planned are for future versions.

‎README.md‎

Lines changed: 43 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
Here’s an updated `README.md` reflecting your **Linode** deployment, with all `render.com` references removed and a generic deployment section added.
2+
This version also clarifies your actual endpoints and gives practical info for Linode/self-hosting.
3+
4+
---
5+
6+
````markdown
17
# GPT Gateway
28

39
**Bridge GPTs and GitHub Repositories**
@@ -7,7 +13,7 @@ This FastAPI service enables GPT Actions or external agents to **list, read, wri
713

814
## 🌐 Live Endpoint
915

10-
> **Base URL**: [https://gpt-gateway-cigu.onrender.com](https://gpt-gateway-cigu.onrender.com)
16+
> **Base URL**: [https://nomena-gpt.xyz](https://nomena-gpt.xyz)
1117
1218
---
1319

@@ -24,8 +30,8 @@ This FastAPI service enables GPT Actions or external agents to **list, read, wri
2430

2531
## 📁 API Reference
2632

27-
- OpenAPI: [`/openapi.yaml`](https://gpt-gateway-cigu.onrender.com/openapi.yaml)
28-
- Plugin Manifest: [`/.well-known/ai-plugin.json`](https://gpt-gateway-cigu.onrender.com/.well-known/ai-plugin.json)
33+
- OpenAPI: [`/openapi.yaml`](https://nomena-gpt.xyz/openapi.yaml)
34+
- Plugin Manifest: [`/.well-known/ai-plugin.json`](https://nomena-gpt.xyz/.well-known/ai-plugin.json)
2935

3036
---
3137

@@ -41,7 +47,7 @@ To function properly, your GitHub token must have the following scopes:
4147
| `Pull requests` | ✅ Optional |
4248
| `Discussions` | ✅ Optional |
4349

44-
Set your token as an environment variable:
50+
Set your token as an environment variable (e.g., in `.env`):
4551

4652
```bash
4753
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx
@@ -56,6 +62,8 @@ We use `pytest` to test API endpoints with FastAPI's built-in `TestClient`.
5662
1. Install dependencies:
5763
5864
```bash
65+
python3 -m venv venv
66+
source venv/bin/activate
5967
pip install -r requirements.txt
6068
pip install pytest
6169
```
@@ -72,23 +80,44 @@ pytest
7280
7381
```
7482
.
75-
├── actions/ # FastAPI route modules
76-
├── services/ # GitHub API logic
77-
├── .well-known/ # ai-plugin.json for GPT integration
78-
├── openapi.yaml # OpenAPI schema (GPT Action schema)
79-
├── main.py # App entrypoint
80-
└── test_main.py # API test suite
83+
├── actions/ # FastAPI route modules
84+
├── services/ # GitHub API logic
85+
├── .well-known/ # ai-plugin.json for GPT integration
86+
├── openapi.yaml # OpenAPI schema (GPT Action schema)
87+
├── main.py # App entrypoint
88+
└── test_main.py # API test suite
8189
```
8290
8391
---
8492
85-
## 🛠️ Deployment (Render)
93+
## 🛠️ Deployment (Linode, or Any VPS)
94+
95+
1. **Clone this repository:**
96+
97+
```bash
98+
git clone https://github.com/nomenarkt/gpt-gateway.git
99+
cd gpt-gateway
100+
```
101+
102+
2. **Set up environment:**
103+
104+
* Place your `.env` with `GITHUB_TOKEN` in the root directory.
105+
106+
3. **Start the FastAPI server:**
107+
108+
```bash
109+
python3 -m venv venv
110+
source venv/bin/activate
111+
pip install -r requirements.txt
112+
uvicorn main:app --host 127.0.0.1 --port 8000
113+
```
114+
115+
4. **(Optional) Use `systemd` or Supervisor for production hosting.**
86116
87-
Configured via `render.yaml`.
88-
Ensure `.well-known/`, `openapi.yaml`, and `main.py` are in the root of your GitHub repo.
117+
5. **Configure Nginx as a reverse proxy (see `/etc/nginx/sites-available/default`).**
89118
90119
---
91120
92121
## 📫 Contact
93122
94-
For feedback or support, email: [nomenaarison@gmail.com](mailto:nomenaarison@gmail.com)
123+
For feedback or support, email: [nomenaarison@gmail.com](mailto:nomenaarison@gmail.com)

‎TECH_SPEC.md‎

1.09 KB

⚙️ TECHNICAL SPECIFICATION (TECH_SPEC)

🏗 Architecture Overview

A custom FastAPI middleware acts as a bridge between:

  • GPT Agents (via tool calls)
  • GitHub’s REST API (via personal token)

🔌 Endpoints (Backend Middleware API)

Endpoint Method Description
/list-files GET List all files in a given GitHub path.
/read-file GET Read and decode a single file.
/scan-repo POST Recursively fetch structure + basic summaries.
/write-file PUT Create or update a file in the repo (in a specific branch).
/find-dead-code POST (Phase 2) Detect unused or incomplete layers.

📁 Folder Structure

gpt-gateway/
│
├── main.py                  # FastAPI app entrypoint
├── actions/
│   ├── list_files.py
│   ├── read_file.py
│   ├── scan_repo.py
│   ├── write_file.py
├── services/
│   ├── github_api.py        # Low-level GitHub API wrapper
├── utils/
│   ├── decoder.py           # For base64 decoding
├── .env                     # GITHUB_TOKEN
└── README.md

🔐 Security

  • GitHub PAT is stored securely in .env, never exposed externally.
  • Only specific non-protected branches (e.g., gpt-agent/*) can be written to.
  • GPTs must supply commit messages and optionally a commit template (enforced by schema).
  • Logging can be enabled for all write actions for audit purposes.

🧪 Testing Strategy

Component Test Type Tool
list-files Unit Pytest
read-file Integration Test with real GitHub repo
scan-repo Load test Check performance with large trees
write-file Integration Ensure new files/branches behave
Security Manual Ensure token and write access is scoped

🧠 GPT Integration Strategy

You define GPT tools like:

{
  "name": "write_file",
  "description": "Create or update a file in the GitHub repo",
  "parameters": {
    "owner": "nomenarkt",
    "repo": "lamina",
    "branch": "gpt-agent/user-module",
    "path": "backend/repository/user_repository.go",
    "content": "<base64_encoded_code>",
    "message": "gpt-write: create user repository scaffold"
  }
}

⚙️ TECH_SPEC.md (Updated)

## ⚙️ TECHNICAL SPECIFICATION (TECH_SPEC)

### 🏗 Architecture Overview

A custom **FastAPI** middleware acts as a bridge between:

* GPT Agents (via tool calls)
* GitHub’s REST API (via personal token)
* External clients, with OpenAPI/ai-plugin.json for GPT compatibility

Hosted on **Linode** (see README for latest base URL).

---

### 🔌 Endpoints (Backend Middleware API)

| Endpoint          | Method | Description                                                 | Status          |
| ----------------- | ------ | ----------------------------------------------------------- | --------------- |
| `/list-files`     | GET    | List all files in a given GitHub path.                      | ✅ Shipped      |
| `/read-file`      | GET    | Read and decode a single file.                              | ✅ Shipped      |
| `/scan-repo`      | POST   | Recursively fetch structure + basic summaries.              | ✅ Shipped      |
| `/write-file`     | PUT    | Create or update a file in the repo (in a specific branch). | ✅ Shipped      |
| `/find-dead-code` | POST   | Detect unused/incomplete layers. *(Phase 2 – Planned)*      | 🚧 Planned      |

---

### 📁 Folder Structure

gpt-gateway/ │ ├── main.py # FastAPI app entrypoint ├── actions/ │ ├── list_files.py │ ├── read_file.py │ ├── scan_repo.py │ ├── write_file.py ├── services/ │ ├── github_api.py # Low-level GitHub API wrapper ├── .well-known/ # ai-plugin.json for GPT integration ├── openapi.yaml # OpenAPI schema (GPT Action schema) ├── .env # GITHUB_TOKEN (not in version control) ├── README.md └── test_main.py # API test suite


---

### 🔐 Security

* GitHub PAT is stored securely in `.env`, never exposed externally.
* Only specific non-protected branches (e.g., `gpt-agent/*`) can be written to.
* GPTs must supply commit messages and optionally a commit template (enforced by schema).
* Logging can be enabled for all write actions for audit purposes.

---

### 🧪 Testing Strategy

| Component    | Test Type   | Tool                                    |
| ------------ | ----------- | --------------------------------------- |
| `list-files` | Unit        | Pytest                                  |
| `read-file`  | Integration | Test with real GitHub repo              |
| `scan-repo`  | Load test   | Check performance with large trees      |
| `write-file` | Integration | Ensure new files/branches behave        |
| Security     | Manual      | Ensure token and write access is scoped |

---

### 🧠 GPT Integration Strategy

Example tool (OpenAPI) definition:

```json
{
  "name": "write_file",
  "description": "Create or update a file in the GitHub repo",
  "parameters": {
    "owner": "nomenarkt",
    "repo": "lamina",
    "branch": "gpt-agent/user-module",
    "path": "backend/repository/user_repository.go",
    "content": "<base64_encoded_code>",
    "message": "gpt-write: create user repository scaffold"
  }
}

Each GPT can:

✅ Deliverables

  • main.py with FastAPI app and endpoint routing
  • Core actions including /write-file
  • GitHub service module with read/write API integration
  • GPT tool schemas with write enforcement
  • Example GPT usage for architecture gap-filling

Phase 2 features like dead code detection will be tracked separately as planned enhancements.

‎actions/__pycache__/list_files.cpython-312.pyc‎

-1.25 KB
Binary file not shown.

‎actions/__pycache__/read_file.cpython-312.pyc‎

-1.22 KB
Binary file not shown.

‎actions/__pycache__/scan_repo.cpython-312.pyc‎

-1.49 KB
Binary file not shown.

‎actions/__pycache__/write_file.cpython-312.pyc‎

-2.17 KB
Binary file not shown.

‎render.yaml‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎services/__pycache__/github_api.cpython-312.pyc‎

-7.7 KB
Binary file not shown.

0 commit comments

Comments
 (0)