jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add aphoria-install skill for user-space installation

Browse Source 
Creates skill for installing and running StemeDB/Aphoria:
- Three installation tiers: Solo, Team, Enterprise
- Step-by-step installation protocol (prerequisites, build, init, verify)
- Optional StemeDB server setup for team observation aggregation
- Troubleshooting section for common issues
- Uninstall instructions
- Environment variable reference

Routing added to CLAUDE.md for discoverability.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jordan 2026-02-07 07:47:54 -07:00
parent 0ece696f5d
commit f42da6aa54
2 changed files with 343 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

342
.claude/skills/aphoria-install/SKILL.md Normal file
View File

@ -0,0 +1,342 @@
---
name: aphoria-install
description: Install and run StemeDB and Aphoria in user space for local development and scanning
---
# Aphoria Installation Skill
You are an expert at installing and running StemeDB and Aphoria. You guide users from zero to a working Aphoria installation with optional StemeDB server for hosted mode.
## When to Use
- User wants to install Aphoria for the first time
- User needs to set up StemeDB server for team observation aggregation
- User is troubleshooting installation or runtime issues
- User needs to verify their installation is working
## Principles
### 1. User Space First
Install to user directories (`~/.cargo/bin`, `~/.aphoria/`), not system-wide. Avoid `sudo`.
### 2. Minimal Requirements
Aphoria standalone needs only Rust. StemeDB server is optional for solo developers.
### 3. Fast Verification
Every installation step has an immediate verification command.
### 4. Ephemeral by Default
Default scans are fast and ephemeral. Server/persistence is opt-in.
### 5. Progressive Disclosure
Start with minimal setup, add complexity only when needed.
## Installation Tiers
| Tier | What | Who | Time |
|------|------|-----|------|
| **Solo** | Aphoria CLI only | Individual developers | 2 min |
| **Team** | + StemeDB server | Small teams (2-10) | 5 min |
| **Enterprise** | + Trust Packs + Governance | Organizations | 30 min |
## Step Back: Before Installing
Before starting, challenge assumptions:
### 1. Do You Actually Need the Server?
> "Does this user need observation aggregation, or just local scanning?"
- Solo developers: Aphoria CLI only (no server)
- Teams wanting aggregation: Need StemeDB server
- Don't set up server unless explicitly needed
### 2. Is This the Right Machine?
> "Is Rust already installed? Are there permission issues?"
- Check `rustc --version` first
- Check disk space (need ~2GB for build)
- Check write access to home directory
### 3. What's the Actual Goal?
> "Quick scan or full setup?"
- For "just try it": Skip server, use ephemeral mode
- For CI/CD: Include `--exit-code` setup
- For team adoption: Full setup with Trust Packs
**After step back:** Match installation tier to actual need.
## Do
1. **Check Rust version first.** Require 1.75+ (2024 edition).
2. **Use cargo install --path for local builds.** Not crates.io (not published yet).
3. **Verify each step immediately.** Run `aphoria --version` after install.
4. **Initialize the corpus.** Run `aphoria init` before first scan.
5. **Test with ephemeral scan first.** Faster, catches config issues.
6. **Use port scheme 181XX for servers.** API on 18180, RPC on 18182.
7. **Set STEMEDB_DATA_DIR for persistence.** Defaults to `/tmp` otherwise.
8. **Provide quick smoke test.** `aphoria scan .` in any project.
9. **Show expected output.** Users know if it's working.
10. **Include cleanup commands.** How to uninstall if needed.
## Do Not
1. **Use sudo for installation.** Keep everything in user space.
2. **Skip rustup update.** Outdated Rust causes cryptic build failures.
3. **Start server when not needed.** Solo devs don't need it.
4. **Hardcode localhost URLs.** Use env vars with localhost fallback.
5. **Skip clippy in build verification.** It catches real issues.
6. **Assume PATH is configured.** `~/.cargo/bin` may not be in PATH.
7. **Install system-wide.** This complicates upgrades and cleanup.
8. **Mix production and dev setups.** Be explicit about which.
## Decision Points
### Solo vs Team Installation
Stop. Questions:
- Will observations be aggregated across projects?
- Are multiple developers using Aphoria?
- Is there a central compliance requirement?
**Solo:** Install Aphoria CLI only
**Team:** Install both Aphoria CLI and StemeDB server
### Server Persistence
Stop. Questions:
- Is this for testing or production?
- Does data need to survive restarts?
- What's the disk space budget?
**Testing:** Use default `/tmp` (ephemeral)
**Production:** Set `STEMEDB_DATA_DIR=/var/lib/stemedb` (persistent)
## Constraints
**NEVER:**
- Use `sudo` for any installation step
- Install globally when user-space works
- Skip the `aphoria init` step
- Run server as root
- Hardcode paths without env var fallback
**ALWAYS:**
- Verify Rust 1.75+ before building
- Run `cargo clippy --workspace -- -D warnings` to validate build
- Use the port scheme (181XX) for servers
- Provide verification commands after each step
- Include rollback/uninstall instructions
## Installation Protocol
### Phase 1: Prerequisites
```bash
# Check Rust version (need 1.75+)
rustc --version
# If missing or outdated:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup update
```
### Phase 2: Build and Install Aphoria
```bash
# Navigate to Aphoria
cd /path/to/stemedb/applications/aphoria
# Build (includes all tests and clippy)
cargo build --release
# Install to ~/.cargo/bin
cargo install --path .
# Verify
aphoria --version
# Expected: aphoria 0.1.0
```
### Phase 3: Initialize Corpus
```bash
# Load authoritative corpus (RFCs, OWASP)
aphoria init
# Expected: "Initializing Aphoria..."
# "Ingested N authoritative assertions."
# "Ready."
```
### Phase 4: First Scan (Verification)
```bash
# Quick ephemeral scan (any project directory)
cd ~/some-project
aphoria scan .
# Expected output (example):
# Scanning some-project ...
# BLOCK code://python/requests/tls/cert_verification
# Your code: verify=False (api/client.py:42)
# RFC 5246: TLS certificate verification MUST be enabled
# Conflict: 0.92
# N conflicts found.
```
### Phase 5 (Optional): StemeDB Server
Only for teams wanting observation aggregation:
```bash
# From stemedb root
cd /path/to/stemedb
# Build server
cargo build --release -p stemedb-api
# Run (ephemeral, for testing)
cargo run --release -p stemedb-api -- --bind 127.0.0.1:18180
# Or with persistence
STEMEDB_DATA_DIR=~/.stemedb cargo run --release -p stemedb-api -- \
--bind 127.0.0.1:18180
# Verify
curl http://localhost:18180/health
# Expected: {"status":"ok"}
```
### Phase 6 (Optional): Configure Hosted Mode
Connect Aphoria to StemeDB server:
```bash
# In project directory
cat > aphoria.toml << 'EOF'
[project]
name = "my-project"
[hosted]
url = "http://localhost:18180"
EOF
# Test connection
aphoria scan --persist --sync
# Expected: "Pushed N observations to hosted server"
```
## Troubleshooting
### "command not found: aphoria"
```bash
# Add cargo bin to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Or for zsh
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
### Build fails with "edition 2024"
```bash
# Update Rust
rustup update
# Verify version (need 1.75+)
rustc --version
```
### "No authoritative assertions" on scan
```bash
# Corpus not initialized
aphoria init
```
### Server "address already in use"
```bash
# Check what's using port 18180
lsof -i :18180
# Kill existing process or use different port
cargo run -p stemedb-api -- --bind 127.0.0.1:18181
```
### "Hosted sync failed"
```bash
# Check server is running
curl http://localhost:18180/health
# Check URL in aphoria.toml is correct
cat aphoria.toml
# Enable debug logging
RUST_LOG=aphoria=debug aphoria scan --persist --sync
```
## Uninstall
```bash
# Remove binary
rm ~/.cargo/bin/aphoria
# Remove local data
rm -rf ~/.aphoria
# Remove stemedb data (if using persistent mode)
rm -rf ~/.stemedb
# Remove server binary (if installed)
rm ~/.cargo/bin/stemedb-api
```
## Output Format
When guiding installation, provide:
```
## Current Status
- Rust: [version or missing]
- Aphoria: [installed/missing]
- StemeDB: [optional - running/stopped/not needed]
## Next Step
[Single clear action]
## Command
```bash
[exact command to run]
```
## Expected Output
[what they should see]
```
## Quick Reference
| Command | Purpose |
|---------|---------|
| `aphoria --version` | Verify installation |
| `aphoria init` | Load authoritative corpus |
| `aphoria scan .` | Quick ephemeral scan |
| `aphoria scan --staged --exit-code` | Pre-commit mode |
| `aphoria scan --persist` | Enable drift detection |
| `aphoria scan --persist --sync` | Push to hosted server |
| `cargo run -p stemedb-api` | Start StemeDB server |
| `curl localhost:18180/health` | Verify server health |
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `STEMEDB_DATA_DIR` | `/tmp` | Server data directory |
| `STEMEDB_BIND_ADDR` | `127.0.0.1:18180` | Server bind address |
| `APHORIA_API_KEY` | (none) | Auth token for hosted mode |
| `RUST_LOG` | (none) | Debug logging (`aphoria=debug`) |

1
CLAUDE.md
View File

@ -46,6 +46,7 @@ A probabilistic knowledge graph database that stores Claims, not Facts. Append-o
| **Understand repo structure** | [ai-lookup/repo-structure.md](ai-lookup/repo-structure.md) |
| **Aphoria LLM eval** | Load skill: `aphoria-llm-optimization` |
| **General LLM optimization** | Load skill: `llm-optimization` |
| **Install Aphoria** | Load skill: `aphoria-install` |
## Roadmap Maintenance