183 lines
3.9 KiB
Markdown
183 lines
3.9 KiB
Markdown
# Story Kit
|
||
|
||
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.
|
||
|
||
You can also run the frontend and backend separately in development (Vite dev server + Rust API).
|
||
|
||
## Running it in development
|
||
|
||
```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
|
||
|
||
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
|
||
|
||
```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
|
||
```
|
||
|
||
### 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:**
|
||
|
||
```bash
|
||
# Install cross – a Rust cross-compilation tool backed by Docker
|
||
cargo install cross
|
||
|
||
# Ensure Docker Desktop (or Docker Engine) is running
|
||
```
|
||
|
||
**Build:**
|
||
|
||
```bash
|
||
make build-linux
|
||
# Output: target/x86_64-unknown-linux-musl/release/storkit
|
||
|
||
# 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
|
||
|
||
ldd target/x86_64-unknown-linux-musl/release/storkit
|
||
# Expected: not a dynamic executable
|
||
```
|
||
|
||
**Running on any Linux x86_64 machine:**
|
||
|
||
```bash
|
||
# No Rust, Node, glibc, or any other library needed – just copy and run
|
||
./storkit
|
||
```
|
||
|
||
## 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:**
|
||
|
||
```bash
|
||
make release V=0.2.0
|
||
```
|
||
|
||
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
|
||
```
|