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.
The frontend lives in the `frontend/` directory.
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.
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
# 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
# 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
`rust-embed`. No Rust toolchain, Node.js, or extra libraries are required on the target machine.
### macOS
For a static Linux binary (musl, zero dynamic deps):
```bash
# Native build – no extra tools required beyond Rust + npm
make build-macos
# Output: target/release/storkit
# Verify only system frameworks are linked (Security.framework, libSystem.B.dylib, etc.)
otool -L target/release/storkit
cross build --release --target x86_64-unknown-linux-musl
```
### Linux (static x86_64, zero dynamic deps)
The Linux build uses the `x86_64-unknown-linux-musl` target to produce a fully static binary.
**Prerequisites:**
Docker:
```bash
# Install cross – a Rust cross-compilation tool backed by Docker
cargo install cross
# Ensure Docker Desktop (or Docker Engine) is running
docker compose -f docker/docker-compose.yml build
```
**Build:**
## Running in development
```bash
make build-linux
# Output: target/x86_64-unknown-linux-musl/release/storkit
# Run tests
script/test
# Verify the binary is statically linked
file target/x86_64-unknown-linux-musl/release/storkit
# Expected: ELF 64-bit LSB executable, x86-64, statically linked
# Run the server
cargo run -- --port 3000
ldd target/x86_64-unknown-linux-musl/release/storkit
# Expected: not a dynamic executable
# In another terminal, run the frontend dev server
cd frontend && npm install && npm run dev
```
**Running on any Linux x86_64 machine:**
```bash
# No Rust, Node, glibc, or any other library needed – just copy and run
./storkit
```
Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example` for transport setup.
## Releasing
Builds both macOS and Linux binaries locally, tags the repo, and publishes a Gitea release with a changelog.
**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:**
Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).
```bash
make release V=0.2.0
script/release 0.6.1
```
This will:
- 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
```
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.