diff --git a/.github/workflows/.gitkeep b/.github/workflows/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml new file mode 100644 index 0000000..25a7681 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index e4c9562..b1e0194 100644 --- a/README.md +++ b/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//eve-plugin.yaml # example provider -packages//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 ` 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. diff --git a/packages/example-package/.gitkeep b/packages/example-package/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/packages/example-package/commands/down b/packages/example-package/commands/down new file mode 100755 index 0000000..095ad4b --- /dev/null +++ b/packages/example-package/commands/down @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-package: down not implemented (template stub)" +exit 0 diff --git a/packages/example-package/commands/install b/packages/example-package/commands/install new file mode 100755 index 0000000..327a54d --- /dev/null +++ b/packages/example-package/commands/install @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-package: install not implemented (template stub)" +exit 0 diff --git a/packages/example-package/commands/status b/packages/example-package/commands/status new file mode 100755 index 0000000..d837449 --- /dev/null +++ b/packages/example-package/commands/status @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-package: status not implemented (template stub)" +exit 0 diff --git a/packages/example-package/eve-plugin.yaml b/packages/example-package/eve-plugin.yaml new file mode 100644 index 0000000..3e0b15b --- /dev/null +++ b/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: [] diff --git a/providers/example-provider/.gitkeep b/providers/example-provider/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/providers/example-provider/commands/down b/providers/example-provider/commands/down new file mode 100755 index 0000000..283cb2a --- /dev/null +++ b/providers/example-provider/commands/down @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: down not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/init b/providers/example-provider/commands/init new file mode 100755 index 0000000..1210e63 --- /dev/null +++ b/providers/example-provider/commands/init @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: init not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/ip b/providers/example-provider/commands/ip new file mode 100755 index 0000000..3fc3cd1 --- /dev/null +++ b/providers/example-provider/commands/ip @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: ip not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/plan b/providers/example-provider/commands/plan new file mode 100755 index 0000000..bad5dba --- /dev/null +++ b/providers/example-provider/commands/plan @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: plan not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/resolve b/providers/example-provider/commands/resolve new file mode 100755 index 0000000..2bfcacd --- /dev/null +++ b/providers/example-provider/commands/resolve @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: resolve not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/ssh b/providers/example-provider/commands/ssh new file mode 100755 index 0000000..2f59e0b --- /dev/null +++ b/providers/example-provider/commands/ssh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: ssh not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/start b/providers/example-provider/commands/start new file mode 100755 index 0000000..75539b5 --- /dev/null +++ b/providers/example-provider/commands/start @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: start not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/status b/providers/example-provider/commands/status new file mode 100755 index 0000000..cd79089 --- /dev/null +++ b/providers/example-provider/commands/status @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: status not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/stop b/providers/example-provider/commands/stop new file mode 100755 index 0000000..07d13dc --- /dev/null +++ b/providers/example-provider/commands/stop @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: stop not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/up b/providers/example-provider/commands/up new file mode 100755 index 0000000..82a3652 --- /dev/null +++ b/providers/example-provider/commands/up @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: up not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/commands/validate b/providers/example-provider/commands/validate new file mode 100755 index 0000000..bafcb93 --- /dev/null +++ b/providers/example-provider/commands/validate @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +echo "example-provider: validate not implemented (template stub)" +exit 0 diff --git a/providers/example-provider/eve-plugin.yaml b/providers/example-provider/eve-plugin.yaml new file mode 100644 index 0000000..76de104 --- /dev/null +++ b/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: []