devist 0.1.1

# 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 projects list` | List registered projects (active marked) |
| `devist projects 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 |

### Code comprehension (Phase 4)

| Command | Purpose |
|---|---|
| `devist brief <name>` | Markdown brief: scan + git state + recent activity |
| `devist brief <name> --json` | Same data as JSON |
| `devist scan <name>` | Codebase metadata (languages, top files) |
| `devist scan <name> --tree` | Directory tree |
| `devist scan <name> --json` | JSON output for piping into other tools |
| `devist explain <name> <path>` | File or directory walkthrough with content |
| `devist explain <name> <path> --max-lines 500` | More content |
| `devist watch <name>` | Live file change feed (debounced) |

The `brief` and `scan` outputs are designed to be piped into AI tools:

```bash
devist brief my-app | claude "summarize what changed this week"
devist scan my-app --json > scan.json
devist explain my-app src/main.rs > main-walkthrough.md
```

## Layout

```
~/.devist/
├── config.toml       Your settings
├── registry.toml     Projects you've created
├── state.toml        Currently active backend
├── templates/        Cloned template repos
└── 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