diff --git a/.claude/skills/seekdb-design.md b/.claude/skills/seekdb-design.md new file mode 100644 index 0000000..4dbd9f8 --- /dev/null +++ b/.claude/skills/seekdb-design.md @@ -0,0 +1,50 @@ +# Claude Code SeekDB Skill Design + +## 1. Overview +This design outlines a Claude Code Skill for the `echokit_server` project to facilitate the integration and management of SeekDB. It serves two primary scenarios: +- **Scenario A (Setup Wizard)**: Guided interactive configuration for new environments. +- **Scenario B (Self-Healing/Sync)**: Automatic detection and correction of configuration drifts. + +## 2. Architecture +The system relies on a "Template + Local Override" pattern: +- **Source of Truth (Private)**: `.env` file (local-only, git-ignored). +- **Standards (Public)**: `.env.example` and `config.toml.example` (committed). +- **Consumer**: `config.toml` (generated locally from templates and `.env`). + +## 3. Components + +### 3.1 Claude Code Skill (`SKILL.md`) +A specialized skill file in `.claude/skills/seekdb-management.md` defining commands: +- `/setup-seekdb`: Interactive wizard to collect host, port, and token. +- `/sync-seekdb`: Regenerates `config.toml` from templates using current `.env` values. + +### 3.2 Templates +- `src/resources/.env.example`: Defines required environment variables. +- `src/resources/config.toml.example`: Contains placeholders like `{{SEEKDB_HOST}}`. + +## 4. Workflows + +### 4.1 Interactive Setup (`/setup-seekdb`) +1. Check for `.env`. If missing, prompt user via `AskUserQuestion`. +2. Offer suggested values (e.g., from the current user session context) as non-persistent placeholders. +3. Write variables to `.env`. +4. Verify `.env` is in `.gitignore`; update `.gitignore` if necessary. + +### 4.2 Sync & Self-Healing +1. **Detection**: When AI performs SeekDB tasks, it verifies if `config.toml` exists and matches `.env`. +2. **Generation**: Skill reads `.env` and `config.toml.example`, performs string replacement, and writes to `config.toml`. +3. **Guard**: Adds a header comment: `# [LOCAL_ONLY] GENERATED BY CLAUDE CODE - DO NOT COMMIT`. + +### 4.3 Environment Abstraction (The "Proxy" Logic) +- Skill commands will NOT hardcode `proxy`. +- Instead, the Skill will probe for the command via `command -v proxy`. +- If found, it prefixes bash calls dynamically: `proxy && ...`. +- This ensures portability across different development environments. + +## 5. Security & Safety +- **Anti-Commit Guard**: Skill logic in `/commit` (if extended) or during file generation will warn if `.env` or `config.toml` are staged for commit. +- **Privacy**: No hardcoded IP addresses or tokens in the code or `SKILL.md`. + +## 6. Validation +- After generation, the Skill performs a connectivity test (e.g., `nc` or a simple health check API call) to the SeekDB instance. +- Success/Failure feedback is provided to the user. diff --git a/.claude/skills/seekdb-management.md b/.claude/skills/seekdb-management.md new file mode 100644 index 0000000..0b18d72 --- /dev/null +++ b/.claude/skills/seekdb-management.md @@ -0,0 +1,37 @@ +--- +name: seekdb-management +description: Manage SeekDB configuration and environment +--- + +# seekdb-management + +A skill to manage SeekDB environment settings. + +## Commands + +### /setup-seekdb + +Sets up the SeekDB connection environment by creating a `.env` file. + +#### Logic + +1. **Check Environment**: Check if `.env` file exists in the project root. +2. **Handle Missing Config**: If `.env` does not exist: + - Call `AskUserQuestion` to ask the user for: + - `SEEKDB_HOST` + - `SEEKDB_PORT` + - `SEEKDB_TOKEN` + - **Hint**: Provide a friendly hint to the user: "For evaluation, you might use biodev.cm.com:2881". +3. **Create File**: Use the `Write` tool to create a `.env` file in the project root with the following format: + ```env + SEEKDB_HOST= + SEEKDB_PORT= + SEEKDB_TOKEN= + ``` +4. **Git Safety**: Read the `.gitignore` file to verify if `.env` is properly ignored to prevent accidental leaks. If it's not ignored, warn the user and suggest adding it. +5. **Update Config**: Ask the user if they want to automatically add SeekDB MCP server to their `config.toml`. + - If yes: + - Read `config.toml`. + - Add the `[[llm.mcp_server]]` block with `server = "http://localhost:/mcp"`. + - Add a SeekDB-specific system prompt to `[[llm.sys_prompts]]`. +6. **Success Confirmation**: Confirm to the user that the environment has been successfully configured and the server is connected. diff --git a/.gitignore b/.gitignore index d577558..f782f9c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ /target /record +.env +config.toml # macOS .DS_Store diff --git a/src/resources/.env.example b/src/resources/.env.example new file mode 100644 index 0000000..fdb2308 --- /dev/null +++ b/src/resources/.env.example @@ -0,0 +1,4 @@ +# SeekDB Configuration +SEEKDB_HOST=your_host_here +SEEKDB_PORT=2881 +SEEKDB_TOKEN=your_token_here diff --git a/src/resources/config.toml.example b/src/resources/config.toml.example new file mode 100644 index 0000000..7b55641 --- /dev/null +++ b/src/resources/config.toml.example @@ -0,0 +1,4 @@ +[seekdb] +host = "{{SEEKDB_HOST}}" +port = {{SEEKDB_PORT}} +token = "{{SEEKDB_TOKEN}}"