108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
|
# 🛠️ Development Overview
|
||
|
|
|
||
|
|
This document provides a comprehensive overview of the development process for Grokkit, including build instructions, project structure, and the standard TODO workflow.
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# All tests pass without XAI_API_KEY (unit tests only)
|
||
|
|
|
||
|
|
# Run tests
|
||
|
|
make test
|
||
|
|
|
||
|
|
# Agent-specific tests
|
||
|
|
make test-agent
|
||
|
|
|
||
|
|
# Run tests with coverage report
|
||
|
|
make test-cover
|
||
|
|
open build/coverage.html
|
||
|
|
|
||
|
|
# Linting (matches CI, uses .golangci.yml config)
|
||
|
|
make lint
|
||
|
|
# Install golangci-lint if needed:
|
||
|
|
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
||
|
|
|
||
|
|
# Run specific tests
|
||
|
|
go test -run TestEditCommand ./cmd -v
|
||
|
|
|
||
|
|
# Build binary
|
||
|
|
make build
|
||
|
|
|
||
|
|
# Install locally
|
||
|
|
make install
|
||
|
|
|
||
|
|
# Clean build artifacts
|
||
|
|
make clean
|
||
|
|
```
|
||
|
|
|
||
|
|
### Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
grokkit/
|
||
|
|
├── cmd/ # CLI commands (Cobra)
|
||
|
|
│ ├── docs.go # grokkit docs — AI documentation generation
|
||
|
|
│ ├── lint.go # grokkit lint — AI-powered linting
|
||
|
|
│ ├── recipe.go # grokkit recipe — transactional recipe runner
|
||
|
|
│ ├── scaffold.go # grokkit scaffold — project-aware file generation
|
||
|
|
│ └── ... # chat, edit, commit, review, history, pr-describe, agent
|
||
|
|
├── config/ # Viper configuration
|
||
|
|
├── docs/ # Documentation
|
||
|
|
├── .grokkit/ # Project-local Grokkit data
|
||
|
|
│ └── recipes/ # Custom AI workflows (recipes)
|
||
|
|
├── todo/ # TODO tracking: queued/ (pending) and completed/ (historical record)
|
||
|
|
│ ├── queued/ # Pending TODO items
|
||
|
|
│ └── completed/ # Completed TODO items with history
|
||
|
|
├── internal/
|
||
|
|
│ ├── errors/ # Custom error types
|
||
|
|
│ ├── git/ # Git operations
|
||
|
|
│ ├── grok/ # xAI Grok API client
|
||
|
|
│ ├── linter/ # Multi-language linting
|
||
|
|
│ ├── logger/ # Structured slog logging
|
||
|
|
│ ├── recipe/ # Recipe loading and execution engine
|
||
|
|
│ └── version/ # Build/version info
|
||
|
|
├── main.go # Application entrypoint
|
||
|
|
├── go.mod # Dependencies
|
||
|
|
├── Makefile # Build automation
|
||
|
|
├── .golangci.yml # Golangci-lint configuration
|
||
|
|
└── scripts/ # Install scripts
|
||
|
|
```
|
||
|
|
|
||
|
|
## TODO Workflow
|
||
|
|
|
||
|
|
**Policy:**
|
||
|
|
From now on, the only thing to be committed directly to the `master` branch will be to-do items (.md files in `todo/queued/`).
|
||
|
|
|
||
|
|
**Process:**
|
||
|
|
1. When deciding to work on a to-do item: create a branch, implement on the branch, submit PR to `master`.
|
||
|
|
2. After PR merge: move the item to `todo/completed/`.
|
||
|
|
|
||
|
|
**Example workflow:**
|
||
|
|
```bash
|
||
|
|
git checkout -b feature/some-todo
|
||
|
|
# Implement changes, test with make test lint
|
||
|
|
git add .
|
||
|
|
git commit -m "feat: implement some-todo"
|
||
|
|
git push -u origin feature/some-todo
|
||
|
|
# Create and merge PR to master
|
||
|
|
|
||
|
|
# Post-merge:
|
||
|
|
git checkout master
|
||
|
|
git pull
|
||
|
|
mv "todo/queued/SOME_TODO.md" "todo/completed/SOME_TODO.md"
|
||
|
|
git add todo/
|
||
|
|
git commit -m "chore: complete some-todo"
|
||
|
|
git push origin master
|
||
|
|
```
|
||
|
|
|
||
|
|
### Gitea Actions Automation *(automates post-merge above)*
|
||
|
|
|
||
|
|
[`.gitea/workflows/auto-complete-todo.yml`](../../.gitea/workflows/auto-complete-todo.yml) triggers on PR `opened`/`synchronize`:
|
||
|
|
|
||
|
|
- Branches `feature/some-todo`: moves `todo/queued/some-todo.md` → `completed/`.
|
||
|
|
|
||
|
|
**One-time setup** (Gitea → Repo → Settings → Secrets & Variables → Actions):
|
||
|
|
- New Secret: `PAT_TOKEN` = [Personal Access Token](https://gitea.example.com/user/settings/tokens) (scope: `repo`).
|
||
|
|
- Optional: Branch protection → Require "Auto-complete TODO" status check.
|
||
|
|
|
||
|
|
**Result**: No manual post-merge steps needed!
|