crashlabs/huskies
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 26 Wiki Activity

docs: rewrite README for 0.6.1

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
dave
2026-03-28 10:56:36 +00:00
parent 40575924b5
commit 7fc788baea
1 changed files with 25 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -152
View File
@@ -1,182 +1,55 @@
# Story Kit # Storkit
This app runs as a single Rust web server binary that serves the Vite/React frontend and exposes APIs. A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend. Communicates via Matrix, WhatsApp, and Slack bot transports, and exposes MCP tools for programmatic access.
The frontend lives in the `frontend/` directory.
You can also run the frontend and backend separately in development (Vite dev server + Rust API). ## Prerequisites
## Running it in development - Rust (2024 edition)
- Node.js and npm
- Docker (for Linux cross-compilation and container deployment)
- `cross` (`cargo install cross`) for Linux static builds
## Building for production
```bash ```bash
# Build the frontend
cd frontend
npm install
npm run dev
# In another terminal - run the server (serves embedded frontend/dist/)
cargo run
```
## Production
```bash
# Build the release binary (also builds the frontend via build.rs)
cargo build --release cargo build --release
# Run the server (serves embedded frontend/dist/)
./target/release/storkit
``` ```
## Cross-Platform Distribution The release binary embeds the frontend via `rust-embed`. Output: `target/release/storkit`.
Story Kit ships as a **single self-contained binary** with the React frontend embedded via For a static Linux binary (musl, zero dynamic deps):
`rust-embed`. No Rust toolchain, Node.js, or extra libraries are required on the target machine.
### macOS
```bash ```bash
# Native build – no extra tools required beyond Rust + npm cross build --release --target x86_64-unknown-linux-musl
make build-macos
# Output: target/release/storkit
# Verify only system frameworks are linked (Security.framework, libSystem.B.dylib, etc.)
otool -L target/release/storkit
``` ```
### Linux (static x86_64, zero dynamic deps) Docker:
The Linux build uses the `x86_64-unknown-linux-musl` target to produce a fully static binary.
**Prerequisites:**
```bash ```bash
# Install cross – a Rust cross-compilation tool backed by Docker docker compose -f docker/docker-compose.yml build
cargo install cross
# Ensure Docker Desktop (or Docker Engine) is running
``` ```
**Build:** ## Running in development
```bash ```bash
make build-linux # Run tests
# Output: target/x86_64-unknown-linux-musl/release/storkit script/test
# Verify the binary is statically linked # Run the server
file target/x86_64-unknown-linux-musl/release/storkit cargo run -- --port 3000
# Expected: ELF 64-bit LSB executable, x86-64, statically linked
ldd target/x86_64-unknown-linux-musl/release/storkit # In another terminal, run the frontend dev server
# Expected: not a dynamic executable cd frontend && npm install && npm run dev
``` ```
**Running on any Linux x86_64 machine:** Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example` for transport setup.
```bash
# No Rust, Node, glibc, or any other library needed – just copy and run
./storkit
```
## Releasing ## Releasing
Builds both macOS and Linux binaries locally, tags the repo, and publishes a Gitea release with a changelog. Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).
**One-time setup:**
1. Create a Gitea API token at `https://code.crashlabs.io/user/settings/applications` (needs repository read/write)
2. Add it to `.env` (gitignored): `GITEA_TOKEN=your_token`
3. Ensure `cross` is installed (`cargo install cross`) and Docker is running
**To release:**
```bash ```bash
make release V=0.2.0 script/release 0.6.1
``` ```
This will: This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.
- Build macOS arm64 (native) and Linux amd64 (static musl via cross/Docker)
- Generate a changelog from commits since the last tag
- Tag the repo as `v0.2.0` and push the tag
- Create a Gitea release with both binaries and the changelog attached
## Testing
### Frontend Tests
The frontend uses **Vitest** for unit tests and **Playwright** for end-to-end tests.
```bash
cd frontend
# Run unit tests
npm test
# Run end-to-end tests
npm run test:e2e
```
### Backend Tests
This project uses **nextest** for running tests and **cargo-llvm-cov** for code coverage.
### Install Tools
```bash
cargo install cargo-nextest cargo-llvm-cov
```
### Run Tests
```bash
# Run all tests
cargo nextest run
# Run specific module
cargo nextest run search_files
# Run with verbose output
cargo nextest run --no-capture
```
### Generate Coverage
```bash
# HTML report (opens in browser)
cargo llvm-cov nextest --html --open
# Terminal output
cargo llvm-cov nextest
# LCOV format (for CI)
cargo llvm-cov nextest --lcov --output-path lcov.info
# Clean coverage data
cargo llvm-cov clean
```
### Configuration
- **Nextest config**: `.config/nextest.toml`
- **Coverage output**: `target/llvm-cov/html/index.html`
## Current Coverage (search_files module)
```
Module: commands/search.rs
├── Region Coverage: 75.36%
├── Function Coverage: 69.05%
└── Line Coverage: 72.55%
```
### Available Test Profiles
```bash
# Development (default)
cargo nextest run
# CI with retries
cargo nextest run --profile ci
# Coverage optimized
cargo nextest run --profile coverage
```