Initial commit: Add DESIGN.md, PROGRESS.md and .gitignore
Developer
commit
44de903ccd
|
|
@ -0,0 +1,25 @@
|
||||||
|
# Generated by Cargo
|
||||||
|
/target/
|
||||||
|
|
||||||
|
# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
|
||||||
|
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
|
||||||
|
Cargo.lock
|
||||||
|
|
||||||
|
# These are backup files generated by rustfmt
|
||||||
|
**/*.rs.bk
|
||||||
|
|
||||||
|
# MSVC Windows builds of rustc generate these, which store debugging information
|
||||||
|
*.pdb
|
||||||
|
|
||||||
|
# SQLite database files
|
||||||
|
*.sqlite
|
||||||
|
*.sqlite-journal
|
||||||
|
|
||||||
|
# Editor files
|
||||||
|
.vscode/
|
||||||
|
.idea/
|
||||||
|
*.swp
|
||||||
|
*~
|
||||||
|
|
||||||
|
# Environment variables
|
||||||
|
.env
|
||||||
|
|
@ -0,0 +1,142 @@
|
||||||
|
# Cypraea
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Cypraea is a Bash-compatible shell implemented as a client-server architecture with a focus on persistent sessions, robust command execution, and extensive logging. It is designed not only as a shell but as an observability and behavioral insight tool for terminal usage.
|
||||||
|
|
||||||
|
The goal is to provide infrastructure for:
|
||||||
|
|
||||||
|
1. Persistent, resumable shell sessions.
|
||||||
|
2. Detailed logging of all commands, including timing, results, and output.
|
||||||
|
3. Analysis of command behavior for ML systems, diagnostics, and real-time assistance.
|
||||||
|
|
||||||
|
Cypraea draws architectural inspiration from tmux and semantic goals from observability and telemetry systems.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
- Bash-compatible command behavior
|
||||||
|
- Client-server architecture
|
||||||
|
- Session-based shell state management
|
||||||
|
- Commands persist through disconnects (like SSH dropouts)
|
||||||
|
- Real-time command streaming and output
|
||||||
|
- Comprehensive, always-on command logging
|
||||||
|
- Future capability for behavioral analysis and assistance
|
||||||
|
|
||||||
|
## Core Architecture
|
||||||
|
|
||||||
|
Cypraea consists of:
|
||||||
|
|
||||||
|
- A **daemon process** (`cypraeadd`) running per user, managing all sessions.
|
||||||
|
- A **client frontend** (`cypraea`) that connects to the daemon and attaches to a session.
|
||||||
|
- Communication over a **Unix domain socket** using **line-delimited JSON**.
|
||||||
|
|
||||||
|
The daemon is responsible for:
|
||||||
|
|
||||||
|
- Managing named shell sessions
|
||||||
|
- Executing commands
|
||||||
|
- Capturing and streaming stdout/stderr
|
||||||
|
- Logging metadata and command output
|
||||||
|
- Retaining session state (cwd, env, aliases, etc.)
|
||||||
|
|
||||||
|
## Sessions
|
||||||
|
|
||||||
|
- Sessions are per-user but **multiple per user** (like tmux).
|
||||||
|
- Each session is identified by a numeric or later symbolic name.
|
||||||
|
- Sessions contain their own state:
|
||||||
|
- Current working directory
|
||||||
|
- Environment variables
|
||||||
|
- Aliases and other shell-local information
|
||||||
|
- Sessions are created automatically when referenced.
|
||||||
|
- Clients attach to sessions and may disconnect without terminating them.
|
||||||
|
|
||||||
|
## Client-Server Communication
|
||||||
|
|
||||||
|
- Communication happens over a Unix domain socket, at `$XDG_RUNTIME_DIR/cypraea.sock`.
|
||||||
|
- Only accessible by the user, controlled via file permissions.
|
||||||
|
- Messages are newline-delimited JSON, encoded in UTF-8.
|
||||||
|
|
||||||
|
Example Request (client → server):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "type": "run_command", "session": "1", "cmd": "ls -la", "cwd": "/tmp", "env": { "FOO": "bar" } }
|
||||||
|
```
|
||||||
|
|
||||||
|
Example Response (server → client):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "type": "stdout", "data": "file1.txt\n" }
|
||||||
|
{ "type": "stderr", "data": "warning: something\n" }
|
||||||
|
{ "type": "exit", "code": 0 }
|
||||||
|
```
|
||||||
|
|
||||||
|
- Output is streamed in real time.
|
||||||
|
- Messages may be chunked arbitrarily.
|
||||||
|
|
||||||
|
## Command Execution
|
||||||
|
|
||||||
|
- Commands are run using `tokio::process::Command`.
|
||||||
|
- stdout and stderr are piped back to the client in real time.
|
||||||
|
- Command output is also captured for logging.
|
||||||
|
- Execution occurs within the context of the session (cwd, env, etc.).
|
||||||
|
- Support for concurrent execution of commands across sessions and clients.
|
||||||
|
|
||||||
|
## Logging System
|
||||||
|
|
||||||
|
- Logs are stored in a SQLite database at `$XDG_DATA_HOME/cypraea/log.sqlite`.
|
||||||
|
- Every command execution is logged, including:
|
||||||
|
- Timestamps (start/end)
|
||||||
|
- Duration
|
||||||
|
- Command text
|
||||||
|
- Working directory
|
||||||
|
- Environment (optional, partial)
|
||||||
|
- Exit code
|
||||||
|
- stdout and stderr output
|
||||||
|
|
||||||
|
Example table schema:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE commands (
|
||||||
|
id INTEGER PRIMARY KEY,
|
||||||
|
session TEXT,
|
||||||
|
timestamp_start DATETIME,
|
||||||
|
timestamp_end DATETIME,
|
||||||
|
duration_ms INTEGER,
|
||||||
|
cmd TEXT,
|
||||||
|
cwd TEXT,
|
||||||
|
exit_code INTEGER,
|
||||||
|
stdout TEXT,
|
||||||
|
stderr TEXT
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
- Logging is always on.
|
||||||
|
- Output size may be truncated or compressed in future versions.
|
||||||
|
- No retention or cleanup policy yet (by design).
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
- Access to the daemon is limited to the user by standard Unix file permissions.
|
||||||
|
- No multi-user access is allowed or supported.
|
||||||
|
- Future: socket authentication and encryption can be explored.
|
||||||
|
|
||||||
|
## Implementation Stack
|
||||||
|
|
||||||
|
- Language: Rust
|
||||||
|
- Async Runtime: Tokio
|
||||||
|
- IPC: Unix domain sockets via `tokio::net::UnixStream`
|
||||||
|
- Message Serialization: `serde_json`
|
||||||
|
- Command Parsing: `shell-words`
|
||||||
|
- Logging: SQLite using `rusqlite`
|
||||||
|
|
||||||
|
## Future Ideas
|
||||||
|
|
||||||
|
- Terminal emulator integration or attach/detach model
|
||||||
|
- Web dashboard or analytics viewer
|
||||||
|
- Error recognition and command recommendations
|
||||||
|
- LSP integration for intelligent shell completions
|
||||||
|
- Integration with OpenTelemetry or observability pipelines
|
||||||
|
- Plugin system and event hooks
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Cypraea is a shell for users and systems that want to *learn* from what happens at the command line. With real-time execution, logging, and stateful sessions, it serves as a durable, intelligent layer between user behavior and system insight.
|
||||||
|
|
@ -0,0 +1,67 @@
|
||||||
|
# Cypraea Project Progress
|
||||||
|
|
||||||
|
## Phase 1: MVP
|
||||||
|
|
||||||
|
### Daemon Implementation
|
||||||
|
- [ ] Set up project structure
|
||||||
|
- [ ] Implement Unix domain socket server
|
||||||
|
- [ ] Define JSON message protocol
|
||||||
|
- [ ] Create session management system
|
||||||
|
- [ ] Implement asynchronous command execution
|
||||||
|
- [ ] Set up output streaming to clients
|
||||||
|
- [ ] Implement SQLite logging infrastructure
|
||||||
|
- [ ] Add command metadata collection
|
||||||
|
|
||||||
|
### Client Implementation
|
||||||
|
- [ ] Set up client project structure
|
||||||
|
- [ ] Implement Unix socket connection
|
||||||
|
- [ ] Create command input handling
|
||||||
|
- [ ] Build output display system
|
||||||
|
- [ ] Add session connection/disconnection logic
|
||||||
|
- [ ] Implement basic REPL (Read-Eval-Print Loop)
|
||||||
|
|
||||||
|
## Phase 2: Shell Features
|
||||||
|
|
||||||
|
### Session State Management
|
||||||
|
- [ ] Implement persistent working directory tracking
|
||||||
|
- [ ] Add environment variable persistence
|
||||||
|
- [ ] Create alias system
|
||||||
|
- [ ] Implement session recovery on reconnect
|
||||||
|
|
||||||
|
### Built-in Commands
|
||||||
|
- [ ] Implement `cd` command
|
||||||
|
- [ ] Implement `export` for environment variables
|
||||||
|
- [ ] Implement `alias` command
|
||||||
|
- [ ] Add session management commands (create, list, switch)
|
||||||
|
|
||||||
|
## Phase 3: Stability
|
||||||
|
|
||||||
|
### Tools and Utilities
|
||||||
|
- [ ] Develop session introspection tools
|
||||||
|
- [ ] Create CLI tools for log access and analysis
|
||||||
|
- [ ] Implement crash recovery mechanisms
|
||||||
|
- [ ] Add socket reinitialization for reliability
|
||||||
|
|
||||||
|
### Log Management
|
||||||
|
- [ ] Implement log rotation
|
||||||
|
- [ ] Add configurable log retention policies
|
||||||
|
- [ ] Create log compression for large outputs
|
||||||
|
- [ ] Add log export functionality
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
### User Experience
|
||||||
|
- [ ] Terminal emulator integration
|
||||||
|
- [ ] Web dashboard for session and log management
|
||||||
|
- [ ] Command history search and analysis
|
||||||
|
|
||||||
|
### Intelligence Features
|
||||||
|
- [ ] Error recognition system
|
||||||
|
- [ ] Command recommendations based on history
|
||||||
|
- [ ] LSP integration for shell completions
|
||||||
|
- [ ] OpenTelemetry integration
|
||||||
|
|
||||||
|
### Extensibility
|
||||||
|
- [ ] Design plugin system architecture
|
||||||
|
- [ ] Implement event hooks
|
||||||
|
- [ ] Create API for external tools integration
|
||||||
Loading…
Reference in New Issue