# Co-op Cloud Recipe Toolkit

Claude skills and tooling for working with [Co-op Cloud](https://coopcloud.tech) recipes — creating new recipes, updating existing ones, and testing deployments.

## Quickstart

```
git clone ssh://git@git.autonomic.zone:2222/notplants/recipe-maintainer.git
cd recipe-maintainer
claude
```

Then inside Claude, run:

```
/intro
```

This will walk you through the project and how to get started.

## Skills

These Claude Code slash commands automate common recipe maintenance tasks.

### Recipe lifecycle

| Skill | Description |
|-------|-------------|
| `/recipe-overview` | Check all recipes in `maintained-recipes.md` for available upgrades and recommend what to focus on |
| `/recipe-init <name>` | Bootstrap a new recipe — fetch, create test instance, set up `recipe-info/`, deploy |
| `/recipe-check <name>` | Quick status report — check if a recipe has upstream image upgrades available |
| `/recipe-upgrade-plan <name>` | Research release notes and write a detailed upgrade plan to `plans/` |
| `/recipe-upgrade-apply <name>` | Execute a planned upgrade — apply changes, deploy, test, commit and tag |
| `/recipe-new-tag <name>` | Bump the recipe version and create an annotated git tag |
| `/recipe-review <name>` | Audit a recipe against Co-op Cloud best practices |
| `/new-recipe-guide` | Step-by-step guide for developing a new recipe from scratch |

### Deployment and testing

| Skill | Description |
|-------|-------------|
| `/recipe-deploy <name>` | Deploy the local recipe checkout to the test instance with chaos mode |
| `/recipe-test <name>` | Run all Python test scripts from `recipe-info/<recipe>/tests/` |
| `/recipe-test-new <name>` | Test first-time initialization of a recipe from scratch |
| `/recipe-test-update <name>` | Test upgrading a recipe's test instance |
| `/recipe-test-backup <name>` | Test backing up and restoring a recipe's test instance |
| `/recipe-test-all` | Run tests for all maintained recipes, deploying each one at a time |

### Infrastructure and environment

| Skill | Description |
|-------|-------------|
| `/init-instance` | Deploy all maintained recipes to the active test instance from scratch |
| `/switch-default-instance` | Switch the default test instance (b1cc or t1cc) for all operations |
| `/test-setup` | Verify the test environment is configured correctly |
| `/test-context-reset` | Undeploy all apps from the test server except traefik |
| `/sync-secrets` | Sync Docker secrets from the test server into `recipe-info/testsecrets/` |
| `/t1cc-start` | Provision the t1cc DigitalOcean droplet (2 vCPU, 8 GB) and deploy Traefik |
| `/t1cc-stop` | Destroy the t1cc droplet (reserved IP is preserved, DNS unchanged) |

## Recommended workflow

### Daily check-in

```
/recipe-overview
```

Start here. This checks all your maintained recipes at once, shows what's up to date and what has upgrades available, and tells you which recipe to focus on.

### Setting up a new recipe

```
/recipe-init <recipe-name>
```

This creates the test instance, all the `recipe-info/` files, and deploys. After it finishes, verify with `/recipe-test` and add any recipe-specific test scripts to `recipe-info/<recipe>/tests/`.

### Checking for and applying upgrades

1. **Check** what's available:
   ```
   /recipe-check <recipe-name>
   ```
   Quick status report — see what upgrades exist and any breaking changes.

2. **Plan** the upgrade:
   ```
   /recipe-upgrade-plan <recipe-name>
   ```
   Creates a detailed plan file in `plans/`. Review it before proceeding.

3. **Apply** the plan:
   ```
   /recipe-upgrade-apply <recipe-name>
   ```
   Executes the plan — applies changes, deploys, tests, and commits + tags locally if everything passes.

4. **Push** when satisfied:
   ```
   cd ~/.abra/recipes/<recipe-name> && git push && git push --tags
   ```

### Day-to-day development

When making local changes to a recipe (editing compose.yml, tweaking configs):

1. **Deploy** your changes:
   ```
   /recipe-deploy <recipe-name>
   ```

2. **Test** the deployment:
   ```
   /recipe-test <recipe-name>
   ```

## Test Environment Setup

This project is designed to run inside a container that bind-mounts `~/.abra`, creating an isolated environment where `abra` operates normally without access to the host's SSH keys or abra configuration.

### SSH keys and config

The `test-ssh/` folder must contain SSH keys and an SSH config that point to a server (or VM) running Co-op Cloud that is ready to be deployed to. The skills use this SSH config when connecting to the test server to deploy and manage recipe instances.

### Container isolation

Run this project in a container with `~/.abra` bind-mounted from the host or a dedicated volume. This ensures:

- `abra` finds its recipes, servers, and app state in the expected location (`~/.abra/`)
- The host's own SSH keys and abra configs are never exposed to the container
- The test SSH keys in `test-ssh/` are the only credentials available, limiting the blast radius of any deployment operations to the designated test server

## Structure

- **`recipe-info/`** — Per-recipe metadata, setup docs, and Python test scripts (organized by recipe name)
- **`lib/`** — Python library for interacting with `abra`, managing config, secrets, SSH, and recipe operations
- **`scripts/`** — Standalone Python scripts (test runner, context reset, secret sync, tag creation)
- **`utils/`** — SSO integration helpers and test utilities
- **`planned-updates/`** — Upgrade reports and summaries generated by `/recipe-upgrade-plan` and `/recipe-upgrade-apply`
- **`plans/`** — Detailed upgrade and project planning documents
- **`terraform/`** — Terraform config for provisioning a DigitalOcean test droplet
- **`test-ssh/`** — SSH config and keys for the test server
- **`docs.coopcloud.tech/`** — Local copy of the [Co-op Cloud documentation](https://docs.coopcloud.tech); reference for recipes, deployment patterns, and platform conventions
- **`.claude/commands/`** — Skill definitions for the slash commands above
- **`.opencode/`** — Thin wrapper mapping Claude skills to [OpenCode](https://opencode.ai) commands