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
|
|||
|
|
```
|