42 lines
4.0 KiB
Markdown
42 lines
4.0 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This repository contains a small Go HTTP wrapper for running AI CLI prompts on a Debian host. The active service entry point is `main.go`; it exposes `POST /run`, `POST /runCodex`, and `POST /runGemini`. `/run` is a backward-compatible alias for `/runCodex`. `daiapi.service` is the systemd unit, and `go.mod` defines the local module. `old-python/` contains the previous Python implementation for reference only.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `gofmt -w main.go`: format Go source before committing.
|
|
- `go test ./...`: run all Go tests.
|
|
- `go build ./...`: verify the module builds.
|
|
- `go build -o daiapi .`: build the service binary used by `daiapi.service`.
|
|
- `PORT=8000 ./daiapi`: run locally on port 8000.
|
|
- `curl -X POST localhost:8000/runCodex -H 'Content-Type: application/json' -d '{"prompt":"Say hello"}'`: smoke-test Codex.
|
|
- `curl -X POST localhost:8000/runGemini -H 'Content-Type: application/json' -d '{"prompt":"Say hello"}'`: smoke-test Gemini.
|
|
|
|
## API Behavior
|
|
|
|
Codex endpoints accept `{"prompt":"..."}` and return the original response shape: `success`, `answer`, `usage`, and `stderr`. Keep `/run` and `/runCodex` behavior identical. Gemini uses the same request body and returns `success`, `answer`, `usage`, `stdout`, `stderr`, `exitCode`, and optional `error`. Use `exec.Command` or `exec.CommandContext` with argument slices; never pass prompts through shell strings.
|
|
|
|
## Request Logging
|
|
|
|
All execution endpoints are wrapped by request logging middleware. Each request creates a separate log file under `/var/log/daiapi/YYYY/MM/DD/HH-MM-SS.<hash>.log`, where the hash is derived from the receive timestamp, request path, body, and an atomic process-local counter. The middleware must restore `r.Body` after reading it and must capture responses through a `http.ResponseWriter` wrapper so normal handler behavior is preserved.
|
|
|
|
Log files include request timestamp, method, path, query, selected headers, request body, response timestamp, HTTP status code, response body, and error text when applicable. Logging must never block request processing: directory creation uses `os.MkdirAll()`, file creation uses exclusive create semantics, and failures are written to the service logger only. Redact sensitive headers such as `Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key`, and `X-Auth-Token`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use standard Go formatting and idioms. Keep imports, indentation, and struct tags managed by `gofmt`. Use short lower-camel-case names for handlers and locals, such as `runCodexHandler`, `runGeminiHandler`, and `finalText`. Keep helpers unexported unless there is a concrete external need.
|
|
|
|
## Testing Guidelines
|
|
|
|
Add Go tests beside the code as `*_test.go` files, using `testing` and `net/http/httptest`. Prefer handler-level tests for request validation, status codes, JSON response shape, request logging, and CLI error handling. Isolate external command invocation so tests do not require real Codex or Gemini credentials. For request logging tests, override the log root to `t.TempDir()` rather than writing to `/var/log/daiapi`.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
The current history uses short initial-commit messages only, so use concise imperative subjects, for example `Add Gemini endpoint tests`. Pull requests should explain API behavior changes, list manual verification commands, and call out deployment impact such as changes to `daiapi.service`, environment variables, PATH requirements, ports, or CLI arguments.
|
|
|
|
## Security & Configuration Notes
|
|
|
|
The service executes prompts through local CLI tools. Codex runs with `--full-auto` and access to `/tmp`; Gemini must be available in the service `PATH`. Keep `PORT` and secrets in `/etc/daiapi/daiapi.env`, and do not commit host-specific credentials or expanded environment files. Ensure the service user can create and write `/var/log/daiapi`; request logs contain prompt and response bodies, so treat them as sensitive operational data and do not commit copied logs.
|