# Tribes Plugin Template

Template for creating [Tribes](https://github.com/your-org/tribes) plugins.

## Getting Started

1. Click **"Use this template"** on GitHub to create your own repo
2. Clone and rename:

```bash
git clone https://github.com/you/your-plugin.git
cd your-plugin
./scripts/rename.sh your_plugin YourPlugin
```

3. Edit `manifest.json` — set description, capabilities, requirements
4. Implement your plugin in `lib/your_plugin/plugin.ex`
5. Run tests:

```bash
mix deps.get
mix test
```

## Development

For local development alongside a Tribes checkout:

```bash
# Build plugin code once (host loads BEAM from _build/dev/lib/<otp_app>/ebin)
cd /path/to/your-plugin
mix compile

# Symlink into the host plugins directory
cd /path/to/tribes
ln -s /path/to/your-plugin plugins/your_plugin

# Start Tribes dev server
iex --sname dev -S mix phx.server
```

When you change plugin Elixir code, re-run `mix compile` in the plugin repo.

## Project Structure

```
your_plugin/
├── manifest.json           # Plugin metadata (Nix build + runtime)
├── mix.exs                 # Dependencies
├── lib/
│   ├── your_plugin/
│   │   ├── plugin.ex       # Tribes.Plugin entry point
│   │   └── application.ex  # OTP supervision tree (optional)
│   └── your_plugin_web/
│       └── live/            # LiveView pages
├── assets/                 # JS/CSS (one bundle per plugin)
├── priv/
│   ├── static/             # Built assets for release
│   └── repo/migrations/    # Ecto migrations
└── test/
```

## Manifest

`manifest.json` declares your plugin's identity and capabilities:

```json
{
  "name": "your_plugin",
  "entry_module": "Tribes.Plugins.YourPlugin.Plugin",
  "host_api": "1",
  "otp_app": "your_plugin",
  "provides": ["some_capability@1"],
  "requires": ["ecto@1"],
  "enhances_with": ["inference@1"]
}
```

- **entry_module** — must be `Tribes.Plugins.*.Plugin`
- **otp_app** — required and must match `name`
- **provides** — capabilities this plugin makes available
- **requires** — hard dependencies (build fails without them)
- **enhances_with** — optional dependencies (plugin degrades gracefully)

See the [Plugin System docs](https://github.com/your-org/tribes/blob/master/docs/PLUGINS.md) for the full specification.

## Testing

Three test levels:

- **Unit tests** (`test/your_plugin/`) — plugin logic in isolation
- **Manifest tests** (`test/your_plugin/manifest_test.exs`) — manifest schema validation
- **Contract tests** (`test/contract_test.exs`) — runtime spec matches manifest

Run all: `mix test`

For DB setup/migrations in local development, run:

```bash
mix tribes.migrate
```

This runs Tribes + Parrhesia + plugin migrations via `Tribes.Release`.

## Building for Release

```bash
MIX_ENV=prod mix compile

mkdir -p dist/your_plugin
cp -r _build/prod/lib/your_plugin/ebin dist/your_plugin/
cp -r priv dist/your_plugin/
cp manifest.json dist/your_plugin/
```

For Nix-based deployment, add your plugin to the host's `plugins.json`.

## Licence

TODO: Choose a licence.