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