Skip to content

Commit 3a98f02

Browse files
wow-mileywow-miley
authored
Add CLI watch command (#15)
1 parent 181b1a6 commit 3a98f02

8 files changed

Lines changed: 717 additions & 60 deletions

File tree

‎ampere-cli/WATCH_COMMAND_USAGE.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Watch Command Usage Guide
2+
3+
The `ampere watch` command connects to the event stream and displays events in real-time with color coding and formatting.
4+
5+
## Prerequisites
6+
7+
- **Java 21** or higher is required to run the CLI
8+
- Check your Java version: `java -version`
9+
- If you have multiple Java versions, you can list them: `/usr/libexec/java_home -V`
10+
11+
## Building the CLI
12+
13+
```bash
14+
./gradlew :ampere-cli:installJvmDist
15+
```
16+
17+
The executable will be located at:
18+
```
19+
ampere-cli/build/install/ampere-cli-jvm/bin/ampere-cli
20+
```
21+
22+
## Running with Java 21
23+
24+
### Option 1: Use the wrapper script (recommended)
25+
26+
A wrapper script is provided that automatically uses Java 21:
27+
28+
```bash
29+
./ampere-cli/ampere watch
30+
```
31+
32+
### Option 2: Set JAVA_HOME manually
33+
34+
If your default Java version is not 21+, set JAVA_HOME before running:
35+
36+
```bash
37+
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
38+
ampere-cli/build/install/ampere-cli-jvm/bin/ampere-cli watch
39+
```
40+
41+
Or inline:
42+
43+
```bash
44+
JAVA_HOME=$(/usr/libexec/java_home -v 21) ampere-cli/build/install/ampere-cli-jvm/bin/ampere-cli watch
45+
```
46+
47+
## Basic Usage
48+
49+
### Watch all events
50+
```bash
51+
./ampere-cli/ampere watch
52+
```
53+
54+
This will display all events from the event bus in real-time.
55+
56+
### Filter by event type
57+
```bash
58+
# Watch only TaskCreated events
59+
./ampere-cli/ampere watch --filter TaskCreated
60+
61+
# Watch multiple event types
62+
./ampere-cli/ampere watch --filter TaskCreated --filter QuestionRaised
63+
```
64+
65+
### Filter by agent
66+
```bash
67+
# Watch events from a specific agent
68+
./ampere-cli/ampere watch --agent agent-pm
69+
70+
# Watch events from multiple agents
71+
./ampere-cli/ampere watch --agent agent-pm --agent agent-dev
72+
```
73+
74+
### Combine filters
75+
```bash
76+
# Watch TaskCreated events from agent-pm
77+
./ampere-cli/ampere watch \
78+
--filter TaskCreated \
79+
--agent agent-pm
80+
```
81+
82+
### Short option names
83+
```bash
84+
# Use -f for --filter and -a for --agent
85+
./ampere-cli/ampere watch -f TaskCreated -a agent-pm
86+
```
87+
88+
## Available Event Types
89+
90+
The following event types can be used with `--filter`:
91+
92+
### Base Events
93+
- `TaskCreated`
94+
- `QuestionRaised`
95+
- `CodeSubmitted`
96+
97+
### Meeting Events
98+
- `MeetingScheduled`
99+
- `MeetingStarted`
100+
- `AgendaItemStarted`
101+
- `AgendaItemCompleted`
102+
- `MeetingCompleted`
103+
- `MeetingCanceled`
104+
105+
### Ticket Events
106+
- `TicketCreated`
107+
- `TicketStatusChanged`
108+
- `TicketAssigned`
109+
- `TicketBlocked`
110+
- `TicketCompleted`
111+
- `TicketMeetingScheduled`
112+
113+
### Message Events
114+
- `ThreadCreated`
115+
- `MessagePosted`
116+
- `ThreadStatusChanged`
117+
- `EscalationRequested`
118+
119+
### Notification Events
120+
- `NotificationToAgent`
121+
- `NotificationToHuman`
122+
123+
Event type names are **case-insensitive** (e.g., `taskcreated`, `TaskCreated`, `TASKCREATED` all work).
124+
125+
## Output Format
126+
127+
Events are displayed in the following format:
128+
```
129+
[timestamp] [icon] [event type] [summary]
130+
```
131+
132+
For example:
133+
```
134+
14:32:18 📋 TaskCreated Task #123: Implement authentication (assigned to: agent-auth) [HIGH] from agent-pm
135+
14:32:25 ❓ QuestionRaised "How should we handle this error?" - Context: During database migration [MEDIUM] from agent-dev
136+
14:33:01 💻 CodeSubmitted src/main/Auth.kt - Add OAuth support (review required) for agent-reviewer [LOW] from agent-dev
137+
```
138+
139+
### Color Coding
140+
141+
#### Event Types
142+
- **Green** (📋🎫): Tasks and tickets (actionable items)
143+
- **Magenta** (❓📅): Questions and meetings (need attention)
144+
- **Cyan** (💻): Code submissions (technical)
145+
- **Blue** (💬): Messages (communication)
146+
- **White** (🔔): Notifications (informational)
147+
148+
#### Urgency Levels
149+
- **Red** [HIGH]: Needs immediate attention
150+
- **Yellow** [MEDIUM]: Should be addressed soon
151+
- **Gray** [LOW]: Can wait
152+
153+
#### Other
154+
- **Gray**: Timestamps and sources
155+
156+
## Integration Testing
157+
158+
To test the watch command with actual events, you'll need to:
159+
160+
1. **Start the watch command**:
161+
```bash
162+
./ampere-cli/ampere watch
163+
```
164+
165+
2. **Publish events from another process** (using the event publishing API):
166+
```kotlin
167+
import link.socket.ampere.agents.events.bus.EventSerialBus
168+
import link.socket.ampere.agents.events.Event
169+
import kotlinx.coroutines.runBlocking
170+
171+
runBlocking {
172+
val eventBus = EventSerialBus(scope)
173+
eventBus.publish(Event.TaskCreated(...))
174+
}
175+
```
176+
177+
The events should appear in the watch command output immediately.
178+
179+
## Troubleshooting
180+
181+
### No events appearing
182+
- Make sure events are being published to the EventBus
183+
- Check that your filters match the events being published
184+
- Verify the event types are spelled correctly (use `--help` for examples)
185+
186+
### Invalid event type warning
187+
If you see a warning about invalid event types, check the spelling and refer to the list of available event types above.
188+
189+
## Help
190+
191+
For full command help:
192+
```bash
193+
./ampere-cli/ampere watch --help
194+
```

‎ampere-cli/ampere‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/bin/bash
2+
# Wrapper script for ampere CLI that ensures Java 21+ is used
3+
4+
# Find Java 21 or higher
5+
JAVA_21=$(/usr/libexec/java_home -v 21 2>/dev/null)
6+
JAVA_24=$(/usr/libexec/java_home -v 24 2>/dev/null)
7+
8+
if [ -n "$JAVA_24" ]; then
9+
export JAVA_HOME="$JAVA_24"
10+
elif [ -n "$JAVA_21" ]; then
11+
export JAVA_HOME="$JAVA_21"
12+
else
13+
echo "Error: Java 21 or higher is required to run ampere CLI"
14+
echo "Please install Java 21+ from:"
15+
echo " - https://www.oracle.com/java/technologies/downloads/"
16+
echo " - https://adoptium.net/"
17+
exit 1
18+
fi
19+
20+
# Get the directory where this script is located
21+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
22+
23+
# Execute the ampere CLI
24+
exec "$SCRIPT_DIR/build/install/ampere-cli-jvm/bin/ampere-cli" "$@"

‎ampere-cli/build.gradle.kts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
@file:OptIn(ExperimentalKotlinGradlePluginApi::class)
22

3+
import org.gradle.jvm.application.tasks.CreateStartScripts
34
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
45
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
56

@@ -45,6 +46,9 @@ kotlin {
4546

4647
// DateTime
4748
implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
49+
50+
// SLF4J no-op implementation to suppress warnings
51+
implementation("org.slf4j:slf4j-nop:2.0.16")
4852
}
4953
}
5054

@@ -53,6 +57,7 @@ kotlin {
5357
implementation(kotlin("test"))
5458
implementation("org.junit.jupiter:junit-jupiter:5.10.2")
5559
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
60+
implementation("com.github.ajalt.clikt:clikt:4.4.0")
5661
}
5762
}
5863
}
@@ -61,3 +66,8 @@ kotlin {
6166
tasks.named<Test>("jvmTest") {
6267
useJUnitPlatform()
6368
}
69+
70+
// Configure JVM arguments for the start scripts to suppress JNA warnings
71+
tasks.named<CreateStartScripts>("startScriptsForJvm") {
72+
defaultJvmOpts = listOf("--enable-native-access=ALL-UNNAMED")
73+
}

0 commit comments

Comments
 (0)