Greg Gauthier
cd47686679
- Simplified README.md by moving detailed command docs, workflows, and development info to dedicated user-guide/ and developer-guide/ directories. - Created index.md files for both guides to improve navigation. - Extracted individual command guides (e.g., chat.md, edit.md) into user-guide/ for focused, maintainable documentation. - Moved architecture, configuration, and troubleshooting to developer-guide/. - Updated README links to point to the new docs structure.
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!
|