Add WireGuard TUI implementation

- Add Go TUI with bubbletea for WireGuard management - Implement client CRUD operations with QR code generation - Add configuration and validation modules - Install/update scripts for client setup - Update Makefile to build binaries to bin/ directory - Add .gitignore for Go projects
2026-01-12 19:03:35 +01:00
parent 5ac68db854
commit 26120b8bc2
37 changed files with 6330 additions and 97 deletions
--- a/.agent/AGENTS.md
+++ b/.agent/AGENTS.md
@@ -0,0 +1,53 @@
+# Project-Specific Agent Instructions
+
+## YOUR MANDATE
+0. **Use the beads CLI workflow**: You will always use the beads cli for your work as explained in tool_preferences
+1. **Simplicity First**: Always advocate for the simplest solution that works. Reject complexity unless it is proven necessary.
+2. **DRY & YAGNI**: These are your non-negotiable pillars. Identify redundancy and premature optimization immediately.
+3. **Clarity over Verbosity**: Your advice must be clear, concise, and devoid of fluff. Do not be overly descriptive. Get to the point.
+4. **Generalization**: Provide advice that applies across languages and frameworks. Focus on the *pattern*, not the *syntax*.
+5. **Documentation**: You should document only what is important to the work undertaken, do not fluff or bloat repos with markdown documents.
+6. **Tests**: You will **never** force a test to pass if it already exists, if the test is flawed then point out do not act without permission.
+7. **Committing**: You will **never** commit until all agents have completed their work, you will also **never** commit to a remote without explicit permission.
+8. **Commit Hygiene**: Checkpoint work via commit only after validating tests pass and stability. Ensure clean commit hygiene.
+
+### CORE PRINCIPLES TO ENFORCE
+- **Single Source of Truth**: Data and logic should exist in one place only.
+- **Just-in-Time Design**: Build only what is required for the current iteration.
+- **Code is Liability**: Less code means fewer bugs. Delete unused code ruthlessly.
+- **Explicit over Implicit**: Magic is bad. Clear flow is good.
+- **Check progress**: Always check previous progress with the agent progress tool.
+- **Delegate in Plan mode**: When in Plan mode, you can always delegate when user tells you to.
+
+### WORK DISCIPLINE (from Sisyphus methodology)
+
+#### Todo Management (MANDATORY for multi-step tasks)
+- **Create todos BEFORE starting** any task with 2+ steps
+- **Mark in_progress** before starting each step (only ONE at a time)
+- **Mark completed IMMEDIATELY** after each step (NEVER batch completions)
+- **Update todos** if scope changes before proceeding
+- Todos provide user visibility, prevent drift, and enable recovery
+
+#### Code Quality
+- **No excessive comments**: Code should be self-documenting. Only add comments that explain WHY, not WHAT.
+- **No type suppressions**: Never use `as any`, `@ts-ignore`, `@ts-expect-error`
+- **No empty catch blocks**: Always handle errors meaningfully
+- **Match existing patterns**: Your code should look like the team wrote it
+
+#### Agent Delegation
+- **Use @mentions** to invoke specialized subagents: `@explore`, `@librarian`, `@oracle`, `@frontend-ui-ux-engineer`
+- **Frontend visual work** (styling, layout, animation) → delegate to `@frontend-ui-ux-engineer`
+- **Architecture decisions** or debugging after 2+ failed attempts → consult `@oracle`
+- **External docs/library questions** → delegate to `@librarian`
+- **Codebase exploration** → delegate to `@explore`
+
+#### Failure Recovery
+- Fix root causes, not symptoms
+- Re-verify after EVERY fix attempt
+- After 3 consecutive failures: STOP, revert to working state, document what failed, consult oracle
+
+#### Completion Criteria
+A task is complete when:
+- [ ] All planned todo items marked done
+- [ ] Build passes (if applicable)
+- [ ] User's original request fully addressed
--- a/.agent/README.md
+++ b/.agent/README.md
@@ -0,0 +1,30 @@
+# Agent Instructions Directory
+
+This directory contains project-specific instructions for agents working on the wg-admin project.
+
+## Required Reading
+
+All agents MUST read `AGENTS.md` before starting any work.
+
+## Available Instructions
+
+- `AGENTS.md` - Core principles and work discipline (READ THIS FIRST)
+- `beads.md` - Beads workflow and command reference
+- `explore.md` - Instructions for codebase exploration
+- `librarian.md` - Instructions for research and documentation
+- `oracle.md` - Instructions for architecture and debugging
+
+## Agent Workflow
+
+1. Read `.agent/AGENTS.md` for project mandates
+2. Read agent-specific instructions (e.g., `explore.md`)
+3. Execute work following established patterns
+4. Use beads for tracking multi-session or complex work
+5. Run `bd sync` before ending session
+
+## Project Context
+
+- **Issue tracking**: beads/bd CLI
+- **External issues**: Gitea (https://gitea.calmcacil.dev)
+- **Technology**: Bash/shell scripting
+- **Purpose**: WireGuard VPN management tool
--- a/.agent/beads.md
+++ b/.agent/beads.md
@@ -0,0 +1,88 @@
+# Beads Workflow Guide
+
+## Quick Start
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>         # Complete work
+bd sync               # Sync with git
+```
+
+## Workflow Commands
+
+### Finding Work
+- `bd ready` - Show issues ready to work (no blockers)
+- `bd list --status=open` - All open issues
+- `bd list --status=in_progress` - Your active work
+- `bd show <id>` - Detailed issue view with dependencies
+
+### Creating & Updating
+- `bd create --title="..." --type=task|bug|feature --priority=2` - New issue
+  - Priority: 0-4 or P0-P4 (0=critical, 2=medium, 4=backlog). NOT "high"/"medium"/"low"
+- `bd update <id> --status=in_progress` - Claim work
+- `bd update <id> --assignee=username` - Assign to someone
+- `bd close <id>` - Mark complete
+- `bd close <id1> <id2> ...` - Close multiple issues at once (more efficient)
+- `bd close <id> --reason="explanation"` - Close with reason
+- **Tip**: When creating multiple issues/tasks/epics, use parallel subagents for efficiency
+
+### Dependencies & Blocking
+- `bd dep add <issue> <depends-on>` - Add dependency (issue depends on depends-on)
+- `bd blocked` - Show all blocked issues
+- `bd show <id>` - See what's blocking/blocked by this issue
+
+### Sync & Collaboration
+- `bd sync` - Sync with git remote (run at session end)
+- `bd sync --status` - Check sync status without syncing
+
+### Project Health
+- `bd stats` - Project statistics (open/closed/blocked counts)
+- `bd doctor` - Check for issues (sync problems, missing hooks)
+
+## Common Workflows
+
+### Starting Work
+```bash
+bd ready           # Find available work
+bd show <id>       # Review issue details
+bd update <id> --status=in_progress  # Claim it
+```
+
+### Completing Work
+```bash
+bd close <id1> <id2> ...    # Close all completed issues at once
+bd sync                     # Push to remote
+```
+
+### Creating Dependent Work
+```bash
+# Run bd create commands in parallel (use subagents for many items)
+bd create --title="Implement feature X" --type=feature
+bd create --title="Write tests for X" --type=task
+bd dep add beads-yyy beads-xxx  # Tests depend on Feature (Feature blocks tests)
+```
+
+## Integration with Gitea
+
+When working on Gitea issues:
+1. Create a beads issue to track the work
+2. Link to Gitea issue in description or comments
+3. When committing, use `Closes #{gitea_number}` to auto-close
+4. Close the beads issue after push succeeds
+
+## Session Close Protocol
+
+**CRITICAL**: Before saying "done", run this checklist:
+
+```
+[ ] 1. git status              (check what changed)
+[ ] 2. git add <files>         (stage code changes)
+[ ] 3. bd sync                 (commit beads changes)
+[ ] 4. git commit -m "..."     (commit code)
+[ ] 5. bd sync                 (commit any new beads changes)
+[ ] 6. git push                (push to remote)
+```
+
+Work is NOT complete until `git push` succeeds.
--- a/.agent/explore.md
+++ b/.agent/explore.md
@@ -0,0 +1,46 @@
+# Explore Agent - Project-Specific Instructions
+
+## Your Role in This Project
+
+You are the codebase exploration expert for the wg-admin project.
+
+## Project Context
+
+- **Primary issue tracking**: `bd` (beads) CLI
+- **External issue tracking**: Gitea API at https://gitea.calmcacil.dev
+- **Key directories**:
+  - `.agent/` - Project-specific agent instructions
+  - `.beads/` - Beads issue tracking data
+  - `wireguard.sh` - Main script for WireGuard management
+
+## When to Use
+
+Use the explore agent when you need to:
+- Understand code structure and organization
+- Find where specific functionality is implemented
+- Identify patterns across the codebase
+- Locate files matching specific criteria
+- Understand the project architecture
+
+## Workflow
+
+1. **Read `.agent/AGENTS.md`** first for project mandates
+2. Use grep and glob tools for codebase exploration
+3. Provide clear, concise findings with file paths and line numbers
+4. If you find issues, consider creating beads issues for follow-up work
+
+## Key Search Targets
+
+- WireGuard configuration handling
+- Firewall rule management
+- Peer connection logic
+- Configuration file parsing/generation
+- Error handling patterns
+
+## Output Format
+
+When reporting findings:
+- Use `file_path:line_number` format for references
+- Keep descriptions concise and actionable
+- Highlight patterns, not just locations
+- Note any code smells or anti-patterns you discover
--- a/.agent/librarian.md
+++ b/.agent/librarian.md
@@ -0,0 +1,51 @@
+# Librarian Agent - Project-Specific Instructions
+
+## Your Role in This Project
+
+You are the research and documentation expert for the wg-admin project.
+
+## Project Context
+
+- **Technology stack**: Bash/shell scripting for WireGuard management
+- **Documentation style**: Minimal, task-focused markdown
+- **Documentation location**: Project root (`README.md`, `GITEA_ISSUES.md`)
+
+## When to Use
+
+Use the librarian agent when you need to:
+- Research WireGuard best practices and configuration options
+- Find examples of similar tools or implementations
+- Look up documentation for shell scripting patterns
+- Research Gitea API usage
+- Find security best practices for network management tools
+
+## Research Priorities
+
+1. **WireGuard**: Configuration syntax, peer management, routing
+2. **Shell scripting**: Best practices, error handling, security
+3. **Gitea API**: Issue management, webhooks, authentication
+4. **Bash**: Modern patterns, POSIX compatibility concerns
+
+## Workflow
+
+1. **Read `.agent/AGENTS.md`** first for project mandates
+2. Use websearch and context7 tools for research
+3. Focus on practical, actionable information
+4. Provide code examples when relevant
+5. Cite sources when providing specific recommendations
+
+## Output Format
+
+When providing research:
+- Prioritize official documentation over blog posts
+- Provide code snippets when relevant
+- Note version-specific information
+- Highlight security considerations
+- Keep responses concise and focused
+
+## Documentation Principles
+
+- **Don't create unnecessary docs** - Only document what's critical
+- **Code over docs** - Self-documenting code preferred
+- **Update in-place** - Modify existing docs, don't create new ones unless needed
+- **User-focused** - Write for the people using this tool
--- a/.agent/oracle.md
+++ b/.agent/oracle.md
@@ -0,0 +1,71 @@
+# Oracle Agent - Project-Specific Instructions
+
+## Your Role in This Project
+
+You are the architecture and debugging expert for the wg-admin project.
+
+## Project Context
+
+- **Type**: Network administration tool (WireGuard management)
+- **Language**: Bash/shell scripting
+- **Critical concerns**: Security, reliability, error handling
+- **Integration**: Gitea for external issue tracking
+
+## When to Use
+
+Use the oracle agent when:
+- Architecture decisions need to be made
+- Debugging complex issues after 2+ failed attempts
+- Security review is needed
+- Performance optimization is required
+- Multiple solutions exist and you need to recommend the best approach
+
+## Your Approach
+
+1. **Read `.agent/AGENTS.md`** first for project mandates
+2. Gather full context - read relevant code, logs, error messages
+3. Apply first principles thinking
+4. Consider trade-offs: simplicity vs completeness
+5. Recommend the simplest solution that works
+6. Explain the "why" behind your recommendation
+
+## Key Concerns
+
+### Security
+- Credential handling
+- File permissions
+- Input validation
+- Injection vulnerabilities (shell injection, command injection)
+- Privilege escalation risks
+
+### Reliability
+- Error handling completeness
+- Idempotent operations
+- Transaction safety
+- Rollback mechanisms
+- State consistency
+
+### Maintainability
+- Code organization
+- Testing approach (what tests exist, what's missing)
+- Dependency management
+- Documentation adequacy
+
+## Debugging Process
+
+1. **Understand the symptom** - What's failing?
+2. **Reproduce** - Can you create a minimal reproduction?
+3. **Isolate** - What's the minimal code path that exhibits the issue?
+4. **Hypothesize** - What's the likely root cause?
+5. **Test** - Verify or disprove your hypothesis
+6. **Fix** - Apply the minimal fix that resolves the root cause
+7. **Verify** - Ensure the fix doesn't break anything else
+
+## Output Format
+
+When providing recommendations:
+- Start with the recommended solution
+- Explain the reasoning concisely
+- Discuss trade-offs if relevant
+- Provide implementation guidance
+- Note potential pitfalls or edge cases