From 44de903ccd9605026c67262b409fad5c5c445141 Mon Sep 17 00:00:00 2001 From: Developer Date: Sun, 6 Apr 2025 02:59:51 +0000 Subject: [PATCH] Initial commit: Add DESIGN.md, PROGRESS.md and .gitignore --- .gitignore | 25 +++++++++ DESIGN.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++ PROGRESS.md | 67 +++++++++++++++++++++++++ 3 files changed, 234 insertions(+) create mode 100644 .gitignore create mode 100644 DESIGN.md create mode 100644 PROGRESS.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c3d9848 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..db9cc5c --- /dev/null +++ b/DESIGN.md @@ -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. diff --git a/PROGRESS.md b/PROGRESS.md new file mode 100644 index 0000000..8e3135a --- /dev/null +++ b/PROGRESS.md @@ -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