cofactor-create-vigil-app 0.1.0
Scaffolding tool for Vigil projects
License: Apache-2.0
Requires Python: >=3.11
Keywords: reproducible, scaffolding, science, template, vigil

# create-vigil-app

Scaffolding tool for Vigil projects - get from idea to first Receipt in under 5 minutes.

## Installation

```bash
# Via uvx (recommended - no install required)
uvx create-vigil-app my-project

# Via pip install (for frequent use)
pip install create-vigil-app
create-vigil-app my-project
```

## Quick Start

### Interactive Mode (Default)

```bash
$ uvx create-vigil-app

Welcome to Vigil! Let's create your reproducible science project.

? What template do you want to use?
  ❯ imaging-starter     - Microscopy analysis with GPU support
    minimal-starter     - Simplest viable template

? Project name: my-project
? Description: Analysis of microscopy data
? Author name: Jane Doe
? Author email: jane@example.com
? License: Apache-2.0

✓ Created my-project from imaging-starter
✓ Installed dependencies with uv
✓ Generated workspace.spec.json
✓ Initialized git repository

Next steps:
  cd my-project
  vigil dev                # Preview the pipeline
  vigil run --cores 4      # Execute the pipeline
  vigil promote            # Generate a receipt
```

### Non-Interactive Mode

```bash
# Minimal flags
uvx create-vigil-app my-project --template minimal

# All metadata
uvx create-vigil-app my-project \
  --template imaging \
  --description "Analysis of microscopy data" \
  --author "Jane Doe <jane@example.com>" \
  --license Apache-2.0 \
  --skip-install
```

### List Templates

```bash
$ uvx create-vigil-app --list

Available Vigil Templates

┌───────────────────┬────────────────────────────────────────┬──────────────────┐
│ Template          │ Description                            │ Features         │
├───────────────────┼────────────────────────────────────────┼──────────────────┤
│ imaging-starter   │ Microscopy analysis pipeline           │ GPU, MCP, UI     │
│ minimal-starter   │ Simplest viable template               │ CPU only, Simple │
└───────────────────┴────────────────────────────────────────┴──────────────────┘

Usage: create-vigil-app <project-name> --template <template>
```

## CLI Options

### Required

- `<project-name>` - Name of the project directory (positional argument)

### Optional

```bash
--template TEXT              Template to use (required if not interactive)
                             Choices: imaging, minimal

--description TEXT           Project description

--author TEXT                Author name and email in format "Name <email>"

--license TEXT               License identifier (default: Apache-2.0)
                             Common: Apache-2.0, MIT, GPL-3.0, CC-BY-4.0

--skip-install               Don't run 'uv sync' after scaffolding

--skip-git                   Don't initialize git repository

--list                       List available templates and exit

--version                    Show version and exit

--help                       Show help message and exit
```

## What It Does

1. **Validates Input**: Checks project name, directory, template, and email format
2. **Copies Template Files**: From `examples/<template>/` with smart exclusions
3. **Customizes Metadata**: Updates `vigil.yaml`, `pyproject.toml`, and `README.md`
4. **Generates workspace.spec.json**: Using `vigil.tools.workspace_spec`
5. **Initializes Git**: Creates initial commit with template metadata
6. **Installs Dependencies**: Runs `uv sync` to set up the environment

## Available Templates

### minimal-starter

The simplest viable Vigil template for getting started quickly.

**Features:**
- Single data handle with offline CSV fallback
- One processing step (threshold filter)
- Minimal Snakemake pipeline
- Basic receipt promotion
- Health checks

**Best for:** Learning Vigil basics or starting a simple analysis

### imaging-starter

Full-featured microscopy analysis pipeline with GPU support.

**Features:**
- GPU-accelerated processing
- MCP server integration
- Interactive UI components
- Advanced metrics collection
- Comprehensive testing

**Best for:** Production microscopy workflows

## Template Structure

Each template includes:

- `README.md` - Experiment Card with front matter
- `vigil.yaml` - Project manifest
- `pyproject.toml` - Python project configuration
- `app/code/pipelines/Snakefile` - Pipeline definition
- `app/data/handles/*.dhandle.json` - Data handles
- `app/data/samples/` - Offline sample data
- `capsule/Dockerfile` - Container recipe
- `.gitignore` - Standard Python/Vigil ignores

## Customization

Templates use placeholders that get replaced during scaffolding:

- `__PROJECT__` - Project name
- `__DESCRIPTION__` - Project description
- `__AUTHOR_NAME__` - Author name
- `__AUTHOR_EMAIL__` - Author email
- `__LICENSE__` - License identifier
- `__ORG__` - Organization (derived from email domain)
- `__CREATED__` - ISO-8601 timestamp

## Development

```bash
# Clone the repo
git clone https://github.com/science-abundance/vigil.git
cd vigil/packages/create-vigil-app

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run ruff format .
```

## Requirements

- Python 3.11+
- `uv` package manager (for dependency installation)
- `git` (for repository initialization)

## License

Apache-2.0

## Contributing

Contributions welcome! Please see the main Vigil repository for contribution guidelines.

## Support

- Documentation: https://docs.vigil.science
- Issues: https://github.com/science-abundance/vigil/issues
- Discussions: https://github.com/science-abundance/vigil/discussions