devist 0.3.0

# devist

[![CI](https://github.com/WebchemistCorp/devist/actions/workflows/ci.yml/badge.svg)](https://github.com/WebchemistCorp/devist/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Project bootstrap CLI for AI-assisted development.

A Rust CLI that lets you scaffold new projects from templates, run multiple
project backends without overloading your machine, and stay on top of what's
in your codebase — even when most of the code was written by AI.

Built by [Webchemist](https://github.com/WebchemistCorp).

> **Status:** v0.1.0 beta. APIs and template manifest schema may change
> before v1.0.

## Why

Two pains modern dev workflows hit hard:

1. **Backend stack overload.** One Supabase or Postgres docker stack per
   project melts your laptop. devist runs at most one backend at a time —
   switching projects auto-stops the previous one.
2. **AI-assisted code blindness.** When AI writes most of the code, you stop
   knowing how the system fits together. devist gives you `brief`, `scan`,
   `explain`, and `watch` to keep your mental model intact.

## Install

### From source (any platform)

```bash
git clone https://github.com/WebchemistCorp/devist
cd devist
cargo install --path .
```

### One-liner (macOS / Linux, prebuilt binary)

```bash
curl -fsSL https://raw.githubusercontent.com/WebchemistCorp/devist/main/scripts/install.sh | sh
```

### Specific version

```bash
curl -fsSL https://raw.githubusercontent.com/WebchemistCorp/devist/main/scripts/install.sh | DEVIST_VERSION=v0.1.0 sh
```

### Manual binary download

Grab the archive for your platform from the
[Releases page](https://github.com/WebchemistCorp/devist/releases) and
extract `devist` somewhere on your `PATH`.

> Homebrew tap (`brew install WebchemistCorp/devist/devist`) and crates.io
> publish are planned for v1.0.

## Quick Start

```bash
devist setup
devist template add https://github.com/WebchemistCorp/devist-templates
devist init my-app --template=react-supabase
devist start my-app --dev
```

## Command Reference

### Project lifecycle

| Command | Purpose |
|---|---|
| `devist setup` | Initialize `~/.devist/` workspace |
| `devist doctor` | Check required CLIs (git, docker, node, pnpm, supabase) |
| `devist init <name> --template=<t>` | Create a new project |
| `devist init <name> -t <t> --var key=value` | Override template variables |
| `devist start <name>` | Start the project's backend (lazy: stops others) |
| `devist start <name> --dev` | Backend + dev server |
| `devist stop [name]` | Stop active backend (or specific one) |
| `devist project list` | List registered projects (active marked) |
| `devist project forget <name>` | Remove from registry (files untouched) |

### Templates

| Command | Purpose |
|---|---|
| `devist template list` | List installed templates |
| `devist template add <git-url>` | Clone a template repo |
| `devist template sync` | `git pull` all templates |
| `devist template remove <name>` | Delete a template directory |

### Worker (background observer)

A long-running daemon watches a parent folder of projects, records every
file event into a local SQLite store, and (in future phases) pushes them
to the devist Supabase for web-based inspection.

| Command | Purpose |
|---|---|
| `devist worker start` | Start the daemon (prompts for monitor folder on first run) |
| `devist worker stop` | Stop the daemon |
| `devist worker status` | Show PID, monitor folder, event/sync counts |
| `devist worker watch` | Tail recent events live in the terminal |
| `devist worker config show` | Print current config |
| `devist worker config get <key>` | Read a single value |
| `devist worker config set <key> <value>` | Update a value (e.g. `monitor_dir`, `supabase_url`) |
| `devist worker config path` | Print config file path |

State lives in `~/.devist/worker/`:

```
worker.db    SQLite event log (L1 store)
config.toml  Worker config
worker.pid   Daemon PID
worker.log   Daemon stdout/stderr
```

## Layout

```
~/.devist/
├── config.toml       Your settings
├── registry.toml     Projects you've created
├── state.toml        Currently active backend
├── templates/        Cloned template repos
├── worker/           Background worker state (db, pid, log, config)
└── cache/            Reserved
```

## Templates

A template is a directory with a `devist.toml` manifest plus any project files.
Files ending in `.tmpl` get variable substitution; everything else is copied
as-is (binary-safe).

Minimal `devist.toml`:

```toml
[meta]
name = "my-stack"
version = "0.1.0"
description = "Short description"
author = "You"
tags = ["fullstack"]

[variables]
project_name = { default = "{{folder_name}}" }
description = { default = "A new project" }

[stack]
type = "supabase"   # or "docker-compose", "none"

[commands]
install = "pnpm install"
dev = "pnpm dev"
backend_start = "supabase start"
backend_stop = "supabase stop"
test = "pnpm test"
```

Variables are substituted in `*.tmpl` files with `{{ name }}` syntax.
Auto-provided: `project_name`, `folder_name`. Override with `--var key=value`.

A single git repo can host multiple templates as subdirectories. The official
`WebchemistCorp/devist-templates` repo is structured this way.

## Development

```bash
cargo build
cargo test
cargo run -- --help
```

Required: Rust 1.70+, git. For most templates: docker, node, pnpm, supabase
CLI.

## Status

Active development. Phases:

| Version | Phase | Contents |
|---|---|---|
| 0.1 | Phase 1 | Core CLI, react-supabase + wordpress |
| 0.2 | Phase 2 | + fastapi-postgres, react-native-supabase |
| 0.3 | Phase 3 | + flutter-supabase, nestjs-postgres, rust-axum |
| 0.4 | Phase 4 | + brief, scan, explain, watch |
| 1.0 | Phase 5 | Public release (Homebrew, crates.io) |

Currently at end of Phase 4.

## License

MIT