Skip to content

Commit 9e8d6db

Browse files
yanmxayanmxa
authored
Merge pull request #4 from yanmxa/refactor/architecture-analysis
Refactor/architecture analysis
2 parents e33a8da + b619ea7 commit 9e8d6db

43 files changed

Lines changed: 6594 additions & 407 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/architecture.md‎

Lines changed: 377 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/features/1-cli-startup.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Feature 1: CLI Entry & Startup Modes
2+
3+
## Overview
4+
5+
`gen` supports several startup modes controlled by flags. The TUI is only launched in interactive mode; other modes produce plain stdout output.
6+
7+
| Flag | Behavior |
8+
|------|----------|
9+
| `gen` | Launch interactive TUI |
10+
| `gen -p "prompt"` | Non-interactive: print response to stdout, no TUI |
11+
| `gen --plan "task"` | Start in plan mode (read-only) |
12+
| `gen -c` | Resume the most recent session |
13+
| `gen -r` | Pick a session from a list |
14+
| `gen -c --fork` | Fork the most recent session |
15+
| `gen -r <id> --fork` | Fork a specific session |
16+
| `gen --plugin-dir PATH` | Load plugins from a directory |
17+
| `gen version` | Print version string |
18+
| `gen help` | Print help |
19+
20+
## UI Interactions
21+
22+
- **Interactive mode**: full TUI with input box, streaming output, and status bar.
23+
- **Print mode (`-p`)**: no TUI; response is written to stdout line by line.
24+
- **Plan mode**: status bar shows `[PLAN MODE]`; write tools are blocked.
25+
- **Session resume (`-r`)**: a scrollable session picker is shown before the TUI starts.
26+
27+
## Automated Tests
28+
29+
```bash
30+
go test ./tests/integration/session/... -v
31+
32+
# Smoke test: non-interactive mode
33+
echo "say hello" | gen -p 2>&1 | grep -i hello
34+
35+
# No provider needed
36+
gen version
37+
gen help
38+
```
39+
40+
Test cases to add:
41+
42+
```go
43+
func TestNonInteractivePrintMode(t *testing.T) {
44+
// -p must write response to stdout without launching a TUI
45+
}
46+
47+
func TestPlanModeFlag_ToolsAreRestricted(t *testing.T) {
48+
// --plan flag: write tools must be blocked
49+
}
50+
51+
func TestSessionContinue_LoadsHistory(t *testing.T) {
52+
// -c must restore previous session messages
53+
}
54+
55+
func TestSessionFork_IsIndependent(t *testing.T) {
56+
// --fork must create a new session that does not affect the original
57+
}
58+
```
59+
60+
## Interactive Tests (tmux)
61+
62+
```bash
63+
tmux new-session -d -s t_cli -x 200 -y 50
64+
65+
# Test 1: Basic TUI startup
66+
tmux send-keys -t t_cli 'gen' Enter
67+
sleep 2
68+
tmux capture-pane -t t_cli -p
69+
# Expected: TUI appears with input box and status bar
70+
71+
# Test 2: Non-interactive print mode
72+
tmux send-keys -t t_cli 'q' Enter
73+
tmux send-keys -t t_cli 'gen -p "what is 1+1"' Enter
74+
sleep 5
75+
tmux capture-pane -t t_cli -p
76+
# Expected: "2" on stdout; no TUI launched
77+
78+
# Test 3: Plan mode startup
79+
tmux send-keys -t t_cli 'gen --plan "analyze this project"' Enter
80+
sleep 2
81+
tmux capture-pane -t t_cli -p
82+
# Expected: [PLAN MODE] visible in status bar
83+
tmux send-keys -t t_cli 'q' Enter
84+
85+
# Test 4: Session resume picker
86+
tmux send-keys -t t_cli 'gen -r' Enter
87+
sleep 2
88+
tmux capture-pane -t t_cli -p
89+
# Expected: session list sorted by recency; navigate with arrow keys
90+
91+
tmux kill-session -t t_cli
92+
```

‎docs/features/10-agents.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Feature 10: Agents / Subagent System
2+
3+
## Overview
4+
5+
Agents are defined in AGENT.md files. They run their own `core.Loop` with an independent system prompt, tool set, and permission mode. They can be invoked headlessly or spawned from within the TUI via the `Agent` tool.
6+
7+
**AGENT.md frontmatter:**
8+
9+
```yaml
10+
---
11+
name: CodeReviewer
12+
description: Reviews code changes for quality issues
13+
model: inherit # inherit | sonnet | opus | haiku
14+
permission-mode: default
15+
tools:
16+
- Read
17+
- Glob
18+
- Grep
19+
max-turns: 50
20+
mcp-servers: []
21+
---
22+
```
23+
24+
**Permission modes:**
25+
26+
| Mode | Behavior |
27+
|------|----------|
28+
| `default` | Interactive prompts |
29+
| `acceptEdits` | Auto-accept edits |
30+
| `dontAsk` | Convert prompts to denials |
31+
| `plan` | Read-only |
32+
| `bypassPermissions` | Auto-approve all |
33+
| `auto` | Autonomous |
34+
35+
**Headless execution:**
36+
37+
```bash
38+
gen agent run --type AgentName --prompt "task"
39+
```
40+
41+
## UI Interactions
42+
43+
- **`/agents`**: picker to enable/disable agents.
44+
- **Agent tool call**: TUI shows `SubagentStart` notification; progress indicator runs while the agent is active.
45+
- **Agent output**: streamed back to the parent conversation as a tool result.
46+
- **Background agents**: tracked in the task panel (Ctrl+T).
47+
48+
## Automated Tests
49+
50+
```bash
51+
go test ./internal/agent/... -v
52+
go test ./tests/integration/agent/... -v
53+
```
54+
55+
Covered:
56+
57+
```
58+
TestAgent_LazyLoading
59+
TestAgent_Integration_Headless
60+
TestAgent_Integration_MaxTurns_Respected
61+
TestAgent_Integration_ToolRestriction
62+
TestAgent_Integration_ModelOverride
63+
```
64+
65+
Cases to add:
66+
67+
```go
68+
func TestAgent_PlanPermissionMode_BlocksWrites(t *testing.T) {
69+
// Agent with permission-mode: plan must not write files
70+
}
71+
72+
func TestAgent_ProgressCallback_Fires(t *testing.T) {
73+
// Progress callback must fire for each turn
74+
}
75+
76+
func TestAgent_SubagentHooks_Fire(t *testing.T) {
77+
// SubagentStart and SubagentStop hooks must fire
78+
}
79+
```
80+
81+
## Interactive Tests (tmux)
82+
83+
```bash
84+
mkdir -p /tmp/agent_test/.gen/agents
85+
echo "hello from agent test" > /tmp/agent_test/sample.txt
86+
87+
cat > /tmp/agent_test/.gen/agents/FileReader.md << 'EOF'
88+
---
89+
name: FileReader
90+
description: Reads and summarizes text files
91+
model: inherit
92+
permission-mode: default
93+
tools:
94+
- Read
95+
- Glob
96+
max-turns: 10
97+
---
98+
99+
You are a file reading agent. Read the requested file and provide a concise summary.
100+
EOF
101+
102+
# Headless execution
103+
gen agent run --type FileReader --prompt "read /tmp/agent_test/sample.txt and summarize" 2>&1
104+
# Expected: agent reads file, outputs summary, exits cleanly
105+
106+
# Agent invoked from TUI
107+
tmux new-session -d -s t_agent -x 220 -y 60
108+
tmux send-keys -t t_agent 'cd /tmp/agent_test && gen' Enter
109+
sleep 2
110+
tmux send-keys -t t_agent 'use the FileReader agent to read sample.txt' Enter
111+
sleep 15
112+
tmux capture-pane -t t_agent -p
113+
# Expected: SubagentStart shown; agent output in conversation; SubagentStop fires
114+
115+
tmux kill-session -t t_agent
116+
rm -rf /tmp/agent_test
117+
```

‎docs/features/11-mcp.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Feature 11: MCP System
2+
3+
## Overview
4+
5+
MCP (Model Context Protocol) connects gencode to external tool servers over STDIO, HTTP, or SSE transports. MCP tools appear alongside built-in tools in the LLM's tool list.
6+
7+
**Transport types:**
8+
9+
| Type | Config |
10+
|------|--------|
11+
| STDIO | Local subprocess |
12+
| HTTP | REST endpoint |
13+
| SSE | Server-Sent Events |
14+
15+
**Config scopes:**
16+
- `~/.gen/mcp.json` — user-level
17+
- `./.gen/mcp.json` — project-level
18+
- `./.gen/mcp.local.json` — local (git-ignored)
19+
20+
**CLI commands:**
21+
22+
```bash
23+
gen mcp add <name> -- <command> # STDIO
24+
gen mcp add --transport http <name> <url> # HTTP
25+
gen mcp list
26+
gen mcp get <name>
27+
gen mcp edit <name>
28+
gen mcp remove <name>
29+
```
30+
31+
## UI Interactions
32+
33+
- **`/mcp`**: opens the MCP management panel; shows connected servers and their tools.
34+
- **Tool calls**: MCP tools appear in the same permission dialog as built-in tools.
35+
- **Connection errors**: shown inline when a server fails to connect at startup.
36+
37+
## Automated Tests
38+
39+
```bash
40+
go test ./internal/mcp/... -v
41+
go test ./tests/integration/mcp/... -v
42+
```
43+
44+
Covered:
45+
46+
```
47+
TestMCP_ConfigLoad
48+
TestMCP_ScopeMerge
49+
TestMCP_Registry_Connect
50+
TestMCP_Registry_ListTools
51+
TestMCP_STDIO_Transport
52+
TestMCP_STDIO_JsonRPC
53+
TestMCP_Integration_STDIO_Server
54+
TestMCP_Integration_ToolExecution
55+
```
56+
57+
Cases to add:
58+
59+
```go
60+
func TestMCP_HTTP_Transport_Connect(t *testing.T) {
61+
// HTTP transport must connect and list tools correctly
62+
}
63+
64+
func TestMCP_ResourceListing(t *testing.T) {
65+
// ListMcpResourcesTool must return resources from connected server
66+
}
67+
```
68+
69+
## Interactive Tests (tmux)
70+
71+
```bash
72+
# Requires Node.js
73+
tmux new-session -d -s t_mcp -x 220 -y 60
74+
75+
# Add STDIO server
76+
tmux send-keys -t t_mcp 'gen mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp' Enter
77+
sleep 5
78+
tmux capture-pane -t t_mcp -p
79+
# Expected: "filesystem" server added
80+
81+
# List servers
82+
tmux send-keys -t t_mcp 'gen mcp list' Enter
83+
sleep 2
84+
tmux capture-pane -t t_mcp -p
85+
# Expected: "filesystem" listed with STDIO transport
86+
87+
# Use MCP from TUI
88+
tmux send-keys -t t_mcp 'gen' Enter
89+
sleep 2
90+
tmux send-keys -t t_mcp 'list files in /tmp using the filesystem MCP tool' Enter
91+
sleep 12
92+
tmux capture-pane -t t_mcp -p
93+
# Expected: /tmp listing via MCP server
94+
95+
# /mcp command
96+
tmux send-keys -t t_mcp '/mcp' Enter
97+
sleep 2
98+
tmux capture-pane -t t_mcp -p
99+
# Expected: MCP management UI with configured servers
100+
101+
# Cleanup
102+
tmux send-keys -t t_mcp 'q' Enter
103+
tmux send-keys -t t_mcp 'gen mcp remove filesystem' Enter
104+
sleep 2
105+
106+
tmux kill-session -t t_mcp
107+
```

0 commit comments

Comments
 (0)