v4: conforming example provider + package + conformance CI

.github/workflows/conformance.yml

@@ -0,0 +1,30 @@
+name: Conformance
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  plugin-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # eve is not published to PyPI yet — clone the repo for its conformance
+      # harness + schema. Once eve ships, replace this step with `pip install eve`
+      # and the runs below with `eve plugin test providers/example-provider`.
+      - uses: actions/checkout@v5
+        with:
+          repository: fruwehq/eve
+          path: eve
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - run: pip install jsonschema pyyaml
+
+      - run: eve/scripts/plugin-test providers/example-provider
+      - run: eve/scripts/plugin-test packages/example-package

README.md

@@ -1,19 +1,42 @@
 # eve-plugin-template
 
-Authoring template for **eve** plugins — copy this to start a new **provider** and/or **package**.
+Authoring template for **eve** plugins — copy this repo to start a new
+**provider** and/or **package**.
 
-> **Status: scaffold.** The full skeleton (manifest, a provision step, and a CI
-> workflow running `eve plugin test`) lands with the eve v4.0 plugin contract
-> (Phase 0). See the v4.0 roadmap in the `eve` repo.
+## What's inside
 
-Every first-party eve plugin is scaffolded from this template (dogfooding): if the
-template can't express a built-in, the template — and likely the contract — is wrong.
-
-## Intended layout
 ```
-providers/<id>/eve-plugin.yaml   # example provider
-packages/<id>/eve-plugin.yaml    # example package
-.github/workflows/               # eve plugin test conformance CI
+providers/example-provider/   # example provider plugin (template stub)
+  eve-plugin.yaml             # manifest: access, bring-up commands, supports
+  commands/                   # stub exec scripts for every provider command
+packages/example-package/     # example package plugin (template stub)
+  eve-plugin.yaml             # manifest: install/status/down, supports
+  commands/                   # stub exec scripts for every package command
+.github/workflows/            # CI running `eve plugin test` conformance checks
 ```
 
+## Scaffolding a plugin from this template
+
+1. Copy the directory for the kind you need (`providers/` or `packages/`).
+2. Rename it to your plugin id (must match `[a-z][a-z0-9-]*`).
+3. Edit `eve-plugin.yaml`: change `id`, `display_name`, and adapt the fields.
+4. Replace the stub scripts in `commands/` with real implementations.
+5. Run `eve plugin test <your-plugin-dir>` to verify conformance.
+
+For a **provider**, you must declare all bring-up commands (`resolve`, `init`,
+`plan`, `up`, `down`, `start`, `stop`, `status`, `ip`, `ssh`, `validate`) and
+`access` rules (bootstrap/provision/human users).
+
+For a **package**, you declare only post-SSH commands (`install`, `status`,
+`down`). Packages must **not** declare `access`, `catalog.inits`, provider
+capabilities, or bring-up commands — they assume an already-reachable host.
+
+## CI
+
+[`.github/workflows/conformance.yml`](.github/workflows/conformance.yml) runs
+eve's `plugin-test` conformance harness against both example plugins on every
+push and pull request. It validates each manifest against the plugin contract
+schema and enforces the SSH-readiness boundary (provider owns bring-up + access;
+package is post-SSH only).
+
 MIT licensed.

packages/example-package/commands/down

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-package: down not implemented (template stub)"
+exit 0

packages/example-package/commands/install

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-package: install not implemented (template stub)"
+exit 0

packages/example-package/commands/status

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-package: status not implemented (template stub)"
+exit 0

packages/example-package/eve-plugin.yaml

@@ -0,0 +1,11 @@
+api_version: eve.plugin/v1
+kind: package
+id: example-package
+display_name: Example Package
+commands:
+  install: {exec: commands/install}
+  status: {exec: commands/status}
+  down: {exec: commands/down}
+supports:
+  os_families: [ubuntu]
+env: []

providers/example-provider/commands/down

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: down not implemented (template stub)"
+exit 0

providers/example-provider/commands/init

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: init not implemented (template stub)"
+exit 0

providers/example-provider/commands/ip

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: ip not implemented (template stub)"
+exit 0

providers/example-provider/commands/plan

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: plan not implemented (template stub)"
+exit 0

providers/example-provider/commands/resolve

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: resolve not implemented (template stub)"
+exit 0

providers/example-provider/commands/ssh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: ssh not implemented (template stub)"
+exit 0

providers/example-provider/commands/start

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: start not implemented (template stub)"
+exit 0

providers/example-provider/commands/status

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: status not implemented (template stub)"
+exit 0

providers/example-provider/commands/stop

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: stop not implemented (template stub)"
+exit 0

providers/example-provider/commands/up

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: up not implemented (template stub)"
+exit 0

providers/example-provider/commands/validate

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+echo "example-provider: validate not implemented (template stub)"
+exit 0

providers/example-provider/eve-plugin.yaml

@@ -0,0 +1,25 @@
+api_version: eve.plugin/v1
+kind: provider
+id: example-provider
+display_name: Example Provider
+commands:
+  resolve: {exec: commands/resolve}
+  init: {exec: commands/init}
+  plan: {exec: commands/plan}
+  up: {exec: commands/up}
+  down: {exec: commands/down}
+  start: {exec: commands/start}
+  stop: {exec: commands/stop}
+  status: {exec: commands/status}
+  ip: {exec: commands/ip}
+  ssh: {exec: commands/ssh}
+  validate: {exec: commands/validate}
+access:
+  ubuntu:
+    bootstrap_user: {env: VM_USER_NAME, value: ubuntu}
+    provision_user: {env: VM_USER_NAME, value: ubuntu}
+    human_user: {env: VM_USER_NAME, fallback: provision_user}
+supports:
+  engines: [terraform]
+  kinds: [vm]
+env: []