slave 0.5.0

# slave

A Laravel-inspired Rust framework for **MCP-first applications**.

Every business operation in a slave app is an
[MCP](https://modelcontextprotocol.io) tool served over Streamable HTTP, so AI
agents and your own web apps use the same, single API. The `slave` CLI
scaffolds the backend (users, roles, bearer-token auth, Turso database,
migrations), adds web apps built with Axum or Dioxus, and routes them by domain
or path through a gateway, in the spirit of `laravel new`, `php artisan make:*`
and `Route::domain()`.

```
browser / AI agent
        │
        ▼
gateway (Pingora) ── config/apps.toml: route by domain and/or path
   ├──► MCP backend    /mcp: auth_*, user_*, role_*, your tools …   ← owns the database
   ├──► apps/dashboard  Axum, server-rendered HTML                  ┐ call MCP tools,
   └──► apps/console    Dioxus single-page app (WebAssembly)        ┘ never the database
```

## Why

- **One interface.** No REST layer next to MCP: the tools an AI agent calls are
  the same ones your dashboards call.
- **Batteries included.** Accounts, roles, Argon2id passwords, hashed bearer
  tokens, migrations with rollback, tests that drive `/mcp` end to end.
- **Pick the right UI per app.** Axum for fast server-rendered pages; Dioxus
  for complex, interactive single-page apps. Both reach the backend only
  through MCP; tokens stay in HttpOnly cookies.
- **Laravel ergonomics.** Generators, domain and path routing,
  `route:list`, one `slave serve` for everything.
- **Agent-ready projects.** Every new project ships an `AGENTS.md` (and a
  `CLAUDE.md` that imports it) teaching coding agents the architecture, the
  rules and recipes for adding features.

## Install

```sh
cargo install slave
```

Requirements: Rust 1.85+, [CMake](https://cmake.org) (the gateway's Pingora
dependency compiles zlib-ng: `brew install cmake` / `apt install cmake`), and
for Dioxus apps the Dioxus CLI:
`cargo install dioxus-cli --version ^0.7 --locked`.

## Quick start

```sh
slave new shop && cd shop
slave migrate                                            # users, roles, auth tokens
slave make:app dashboard --domain admin.localhost        # Axum app on a subdomain
slave make:app console --path /console --stack dioxus    # Dioxus SPA on a path
slave serve
```

```
  MCP backend   http://127.0.0.1:3000/mcp
  Gateway       http://127.0.0.1:8000
    http://mcp.localhost:8000            → MCP backend
    http://admin.localhost:8000          → dashboard
    http://localhost:8000/console        → console
```

Register the first account (it becomes `admin`) from any MCP client, for
example Claude Code:

```sh
claude mcp add --transport http shop http://mcp.localhost:8000/mcp
```

then call the `auth_register` tool, or sign in through one of the apps.

## Commands

| Command | Does |
|---|---|
| `slave new <name>` | Create a project: MCP backend, auth, users, roles, migrations, gateway config, `AGENTS.md` |
| `slave serve` | Build the workspace (and Dioxus SPAs with `dx`) and run backend, gateway and apps |
| `slave make:tools <Name>Tools [--module m]` | MCP tools for a module (`src/modules/<m>/tools.rs`) |
| `slave make:model <Name> [--module m]` | A model in `src/modules/<m>/models/` |
| `slave make:migration <name>` | A timestamped migration (`create_*_table` gets a CREATE TABLE template) |
| `slave make:app <name> --domain <host> \| --path </prefix> [--stack axum\|dioxus]` | A web app in `apps/<name>`, routed by the gateway |
| `slave migrate`, `migrate:status`, `migrate:rollback` | Run, inspect and roll back migrations |
| `slave route:list`, `route:match <host>[/path]` | Inspect domain and path routing |

## Routing

`config/apps.toml` maps requests to apps, like Laravel's `Route::domain()` and
`Route::prefix()`:

```toml
[[domain]]
host = "admin.localhost"      # by domain
app = "dashboard"
port = 4000

[[domain]]
host = "{toko}.localhost"     # {toko} reaches the app as X-Slave-Param-Toko
app = "storefront"
port = 4001

[[domain]]
path = "/console"             # by path, on any host (add `host` to restrict)
app = "console"
port = 4002
```

The most specific entry wins regardless of order: the longest path prefix,
then the most specific host. Unknown routes get 404, a down app gets 502, and
spoofed `X-Slave-*` / `X-Forwarded-*` headers are dropped.

## Crates

| Crate | Role |
|---|---|
| [`slave`](https://crates.io/crates/slave) | This CLI and the project templates |
| [`slave-framework`](https://crates.io/crates/slave-framework) | Runtime used by generated apps: server lifecycle, config, logging, Turso database and migrations, password hashing and tokens |
| [`slave-gateway`](https://crates.io/crates/slave-gateway) | The domain/path routing gateway, built on [Pingora](https://github.com/cloudflare/pingora) |

## Repository layout

```
src/          the slave CLI (commands, generators)
templates/    files written by `slave new` and `slave make:*`
framework/    slave-framework
gateway/      slave-gateway
tests/        end-to-end tests of the CLI and generated projects
```

Run the tests with `cargo test --workspace`; `cargo test -p slave --test cli
-- --ignored` also builds a generated project and runs its own test suite.

## License

MIT