storkit/README.md

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