This commit is contained in:
@@ -0,0 +1,500 @@
|
||||
---
|
||||
phase: 01-core-infrastructure
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on:
|
||||
- 01-03
|
||||
files_modified:
|
||||
- src/gsd_openclaw/cli.py
|
||||
- src/gsd_openclaw/tmux_session.py
|
||||
- tests/test_cli.py
|
||||
- pyproject.toml
|
||||
autonomous: true
|
||||
requirements:
|
||||
- SESS-05
|
||||
user_setup: []
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can resume an interrupted session with context restoration"
|
||||
- "User can invoke create/list/destroy/resume from command line"
|
||||
- "Orphan sessions are detected and can be cleaned up"
|
||||
- "State is validated before session resumption"
|
||||
artifacts:
|
||||
- path: "src/gsd_openclaw/cli.py"
|
||||
provides: "CLI entry point for session management"
|
||||
exports: ["main", "cli"]
|
||||
min_lines: 100
|
||||
- path: "tests/test_cli.py"
|
||||
provides: "Test coverage for CLI commands"
|
||||
contains: "test_cli_create"
|
||||
key_links:
|
||||
- from: "src/gsd_openclaw/cli.py"
|
||||
to: "tmux_session.TmuxSessionManager"
|
||||
via: "CLI invokes session operations"
|
||||
pattern: "TmuxSessionManager"
|
||||
- from: "cli resume"
|
||||
to: "state_manager.load"
|
||||
via: "State validation before resumption"
|
||||
pattern: "load_state"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Implement CLI entry point with session recovery and orphan cleanup.
|
||||
|
||||
Purpose: Provides the user-facing interface for session management. Includes resume functionality that restores context from persisted state and cleanup for orphan sessions.
|
||||
|
||||
Output: Working CLI with create/list/destroy/resume/cleanup commands.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/01-core-infrastructure/01-CONTEXT.md
|
||||
@.planning/phases/01-core-infrastructure/01-RESEARCH.md
|
||||
</context>
|
||||
|
||||
<interfaces>
|
||||
<!-- From Plan 01-03 (Tmux Session) -->
|
||||
|
||||
**TmuxSessionManager:**
|
||||
```python
|
||||
class TmuxSessionManager:
|
||||
def create_session(self, project_name: str, ...) -> TmuxSession: ...
|
||||
def destroy_session(self, project_name: str, cleanup_workspace: bool) -> bool: ...
|
||||
def list_gsd_sessions(self) -> List[SessionInfo]: ...
|
||||
```
|
||||
|
||||
**SessionInfo:**
|
||||
```python
|
||||
@dataclass
|
||||
class SessionInfo:
|
||||
tmux_name: str
|
||||
project_name: str
|
||||
session_id: str
|
||||
created_at: str
|
||||
last_active_at: str
|
||||
command_count: int
|
||||
display_name: Optional[str]
|
||||
is_orphan: bool
|
||||
```
|
||||
|
||||
<!-- From Plan 01-01 (State Manager) -->
|
||||
|
||||
**StateManager:**
|
||||
```python
|
||||
class StateManager:
|
||||
def save(self, state: SessionState) -> None: ...
|
||||
def load(self) -> Optional[SessionState]: ...
|
||||
```
|
||||
</interfaces>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Implement session resume with state validation</name>
|
||||
<files>src/gsd_openclaw/tmux_session.py, tests/test_tmux_session.py</files>
|
||||
<behavior>
|
||||
- Test 1: resume_session returns existing session if state valid and tmux exists
|
||||
- Test 2: resume_session recreates tmux session if state exists but tmux missing
|
||||
- Test 3: resume_session raises error if no state file exists
|
||||
- Test 4: resume_session validates schema version before resuming
|
||||
</behavior>
|
||||
<action>
|
||||
Add resume_session and get_session methods to TmuxSessionManager:
|
||||
|
||||
```python
|
||||
class TmuxSessionError(Exception):
|
||||
"""Errors related to tmux session management."""
|
||||
pass
|
||||
|
||||
|
||||
class TmuxSessionManager:
|
||||
# ... existing code ...
|
||||
|
||||
def get_session(self, project_name: str) -> Optional[TmuxSession]:
|
||||
"""Get existing session without creating new one."""
|
||||
state_manager = StateManager(project_name)
|
||||
state = state_manager.load()
|
||||
|
||||
if state is None:
|
||||
return None
|
||||
|
||||
# Find tmux session
|
||||
try:
|
||||
tmux_session = self.server.sessions.get(
|
||||
session_name=state.tmux_session_name
|
||||
)
|
||||
except libtmux.exc.LibTmuxException:
|
||||
tmux_session = None
|
||||
|
||||
return TmuxSession(
|
||||
session_id=state.session_id,
|
||||
project_name=project_name,
|
||||
tmux_session_name=state.tmux_session_name,
|
||||
tmux_session=tmux_session
|
||||
)
|
||||
|
||||
def resume_session(self, project_name: str) -> TmuxSession:
|
||||
"""Resume an existing session, recreating tmux if needed."""
|
||||
state_manager = StateManager(project_name)
|
||||
state = state_manager.load()
|
||||
|
||||
if state is None:
|
||||
raise TmuxSessionError(f"No session found for project: {project_name}")
|
||||
|
||||
# Validate state
|
||||
if state.schema_version != "1.0":
|
||||
raise TmuxSessionError(
|
||||
f"Unsupported state version: {state.schema_version}"
|
||||
)
|
||||
|
||||
# Check if tmux session exists
|
||||
try:
|
||||
tmux_session = self.server.sessions.get(
|
||||
session_name=state.tmux_session_name
|
||||
)
|
||||
except libtmux.exc.LibTmuxException:
|
||||
tmux_session = None
|
||||
|
||||
# Recreate tmux session if missing
|
||||
if tmux_session is None:
|
||||
workspace_manager = WorkspaceManager(project_name)
|
||||
if not workspace_manager.exists():
|
||||
raise TmuxSessionError(
|
||||
f"Workspace missing for project: {project_name}"
|
||||
)
|
||||
# Create new tmux session with same name
|
||||
tmux_session = self.server.new_session(
|
||||
session_name=state.tmux_session_name,
|
||||
attach=False,
|
||||
window_name='main',
|
||||
start_directory=str(workspace_manager.get_workspace().root)
|
||||
)
|
||||
# Update pane ID in state
|
||||
state.tmux_pane_id = tmux_session.active_pane.pane_id
|
||||
state.last_active_at = datetime.now().isoformat()
|
||||
state_manager.save(state)
|
||||
|
||||
return TmuxSession(
|
||||
session_id=state.session_id,
|
||||
project_name=project_name,
|
||||
tmux_session_name=state.tmux_session_name,
|
||||
tmux_session=tmux_session
|
||||
)
|
||||
```
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_tmux_session.py::test_resume_session -x</automated>
|
||||
<automated>pytest tests/test_tmux_session.py::test_resume_recreates_tmux -x</automated>
|
||||
</verify>
|
||||
<done>resume_session validates state, recreates tmux if needed, raises clear errors</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Implement orphan session cleanup</name>
|
||||
<files>src/gsd_openclaw/tmux_session.py, tests/test_tmux_session.py</files>
|
||||
<behavior>
|
||||
- Test 1: cleanup_orphans kills tmux sessions without state files
|
||||
- Test 2: cleanup_orphans returns list of cleaned session names
|
||||
- Test 3: cleanup_orphans handles sessions with corrupted state files
|
||||
</behavior>
|
||||
<action>
|
||||
Add cleanup_orphans method:
|
||||
|
||||
```python
|
||||
from typing import List
|
||||
|
||||
@dataclass
|
||||
class CleanupResult:
|
||||
"""Result of orphan cleanup."""
|
||||
cleaned_sessions: List[str]
|
||||
errors: List[str]
|
||||
|
||||
|
||||
class TmuxSessionManager:
|
||||
# ... existing code ...
|
||||
|
||||
def cleanup_orphans(self) -> CleanupResult:
|
||||
"""Remove tmux sessions without corresponding state files."""
|
||||
cleaned = []
|
||||
errors = []
|
||||
|
||||
# Get all gsd-* tmux sessions
|
||||
tmux_sessions = self.list_sessions()
|
||||
|
||||
for tmux_session in tmux_sessions:
|
||||
tmux_name = tmux_session.name
|
||||
project_name = self._extract_project_name(tmux_name)
|
||||
|
||||
# Check for state file
|
||||
state_manager = StateManager(project_name)
|
||||
state = state_manager.load()
|
||||
|
||||
should_clean = False
|
||||
|
||||
if state is None:
|
||||
# No state file - orphan
|
||||
should_clean = True
|
||||
elif state.tmux_session_name != tmux_name:
|
||||
# State exists but references different tmux session
|
||||
# This could be a collision case, treat as orphan
|
||||
should_clean = True
|
||||
|
||||
if should_clean:
|
||||
try:
|
||||
tmux_session.kill()
|
||||
cleaned.append(tmux_name)
|
||||
except libtmux.exc.LibTmuxException as e:
|
||||
errors.append(f"Failed to kill {tmux_name}: {e}")
|
||||
|
||||
return CleanupResult(cleaned_sessions=cleaned, errors=errors)
|
||||
```
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_tmux_session.py::test_cleanup_orphans -x</automated>
|
||||
</verify>
|
||||
<done>cleanup_orphans removes tmux sessions without state files, reports results</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Implement CLI with argparse</name>
|
||||
<files>src/gsd_openclaw/cli.py, tests/test_cli.py</files>
|
||||
<behavior>
|
||||
- Test 1: `gsd-ocl create <project>` creates session
|
||||
- Test 2: `gsd-ocl list` shows sessions
|
||||
- Test 3: `gsd-ocl destroy <project>` removes session
|
||||
- Test 4: `gsd-ocl resume <project>` resumes session
|
||||
- Test 5: `gsd-ocl cleanup` removes orphans
|
||||
- Test 6: CLI exits with code 1 on error
|
||||
</behavior>
|
||||
<action>
|
||||
Create CLI using argparse following dev-workflow pattern:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""CLI for gsd-openclaw session management."""
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
from datetime import datetime
|
||||
|
||||
from gsd_openclaw.tmux_session import (
|
||||
TmuxSessionManager,
|
||||
TmuxSessionError,
|
||||
CleanupResult,
|
||||
)
|
||||
|
||||
|
||||
def cmd_create(args):
|
||||
"""Create a new session for a project."""
|
||||
manager = TmuxSessionManager()
|
||||
try:
|
||||
session = manager.create_session(
|
||||
project_name=args.project,
|
||||
display_name=args.display_name
|
||||
)
|
||||
print(f"Created session: {session.tmux_session_name}")
|
||||
print(f"Session ID: {session.session_id}")
|
||||
print(f"Project: {session.project_name}")
|
||||
except Exception as e:
|
||||
print(f"Error: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def cmd_list(args):
|
||||
"""List all gsd sessions."""
|
||||
manager = TmuxSessionManager()
|
||||
sessions = manager.list_gsd_sessions()
|
||||
|
||||
if not sessions:
|
||||
print("No active sessions.")
|
||||
return
|
||||
|
||||
print(f"{'Project':<20} {'Session ID':<10} {'Last Active':<20} {'Status'}")
|
||||
print("-" * 70)
|
||||
for s in sessions:
|
||||
status = "ORPHAN" if s.is_orphan else "active"
|
||||
display = s.display_name or s.project_name
|
||||
print(f"{display:<20} {s.session_id:<10} {s.last_active_at:<20} {status}")
|
||||
|
||||
|
||||
def cmd_destroy(args):
|
||||
"""Destroy a session."""
|
||||
manager = TmuxSessionManager()
|
||||
result = manager.destroy_session(
|
||||
project_name=args.project,
|
||||
cleanup_workspace=args.cleanup
|
||||
)
|
||||
if result:
|
||||
print(f"Destroyed session for: {args.project}")
|
||||
else:
|
||||
print(f"No session found for: {args.project}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def cmd_resume(args):
|
||||
"""Resume an existing session."""
|
||||
manager = TmuxSessionManager()
|
||||
try:
|
||||
session = manager.resume_session(project_name=args.project)
|
||||
print(f"Resumed session: {session.tmux_session_name}")
|
||||
print(f"Session ID: {session.session_id}")
|
||||
print(f"Project: {session.project_name}")
|
||||
except TmuxSessionError as e:
|
||||
print(f"Error: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def cmd_cleanup(args):
|
||||
"""Clean up orphan sessions."""
|
||||
manager = TmuxSessionManager()
|
||||
result = manager.cleanup_orphans()
|
||||
|
||||
if result.cleaned_sessions:
|
||||
print(f"Cleaned {len(result.cleaned_sessions)} orphan session(s):")
|
||||
for name in result.cleaned_sessions:
|
||||
print(f" - {name}")
|
||||
|
||||
if result.errors:
|
||||
print(f"Errors ({len(result.errors)}):")
|
||||
for err in result.errors:
|
||||
print(f" - {err}")
|
||||
|
||||
if not result.cleaned_sessions and not result.errors:
|
||||
print("No orphan sessions found.")
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="gsd-ocl",
|
||||
description="GSD-OpenClaw session management"
|
||||
)
|
||||
subparsers = parser.add_subparsers(dest="command", required=True)
|
||||
|
||||
# create
|
||||
p_create = subparsers.add_parser("create", help="Create a new session")
|
||||
p_create.add_argument("project", help="Project name")
|
||||
p_create.add_argument("--display-name", "-d", help="Friendly display name")
|
||||
p_create.set_defaults(func=cmd_create)
|
||||
|
||||
# list
|
||||
p_list = subparsers.add_parser("list", help="List all sessions")
|
||||
p_list.set_defaults(func=cmd_list)
|
||||
|
||||
# destroy
|
||||
p_destroy = subparsers.add_parser("destroy", help="Destroy a session")
|
||||
p_destroy.add_argument("project", help="Project name")
|
||||
p_destroy.add_argument("--cleanup", "-c", action="store_true",
|
||||
help="Also remove workspace directory")
|
||||
p_destroy.set_defaults(func=cmd_destroy)
|
||||
|
||||
# resume
|
||||
p_resume = subparsers.add_parser("resume", help="Resume a session")
|
||||
p_resume.add_argument("project", help="Project name")
|
||||
p_resume.set_defaults(func=cmd_resume)
|
||||
|
||||
# cleanup
|
||||
p_cleanup = subparsers.add_parser("cleanup", help="Clean up orphan sessions")
|
||||
p_cleanup.set_defaults(func=cmd_cleanup)
|
||||
|
||||
args = parser.parse_args()
|
||||
args.func(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_cli.py -x</automated>
|
||||
</verify>
|
||||
<done>CLI provides create/list/destroy/resume/cleanup commands via argparse</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Configure pyproject.toml with CLI entry point</name>
|
||||
<files>pyproject.toml</files>
|
||||
<action>
|
||||
Create or update pyproject.toml with package configuration:
|
||||
|
||||
```toml
|
||||
[build-system]
|
||||
requires = ["setuptools>=61.0"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "gsd-openclaw"
|
||||
version = "0.1.0"
|
||||
description = "GSD to OpenClaw bridge skill"
|
||||
requires-python = ">=3.9"
|
||||
dependencies = [
|
||||
"libtmux>=0.53.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
"pytest>=8.0",
|
||||
"pytest-cov>=4.0",
|
||||
]
|
||||
|
||||
[project.scripts]
|
||||
gsd-ocl = "gsd_openclaw.cli:main"
|
||||
|
||||
[tool.setuptools.packages.find]
|
||||
where = ["src"]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
python_files = ["test_*.py"]
|
||||
python_classes = ["Test*"]
|
||||
python_functions = ["test_*"]
|
||||
addopts = "-v --tb=short"
|
||||
```
|
||||
|
||||
This makes the CLI installable via `pip install -e .` and accessible as `gsd-ocl`.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pip install -e . && gsd-ocl --help</automated>
|
||||
</verify>
|
||||
<done>Package installable, gsd-ocl command available in PATH</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Run full test suite:
|
||||
```bash
|
||||
pytest tests/ -v
|
||||
```
|
||||
|
||||
Test CLI end-to-end:
|
||||
```bash
|
||||
pip install -e .
|
||||
gsd-ocl create test-project
|
||||
gsd-ocl list
|
||||
gsd-ocl resume test-project
|
||||
gsd-ocl destroy test-project
|
||||
gsd-ocl cleanup
|
||||
```
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- resume_session validates state and recreates tmux if needed
|
||||
- cleanup_orphans removes orphan tmux sessions
|
||||
- CLI provides all session management commands
|
||||
- CLI exits with appropriate error codes
|
||||
- Package installable via pip
|
||||
- gsd-ocl command available in PATH
|
||||
- All tests pass: `pytest tests/ -v`
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/01-core-infrastructure/01-04-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user