almost empty

2026-01-30 22:44:32 +01:00
commit b5320bf29a
22 changed files with 1576 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,134 @@
+> **⚠️ Do not clone this repository directly!**
+>
+> Use `formae plugin init` to create your plugin. This command scaffolds a new
+> plugin from this template with proper naming and configuration.
+>
+> ```bash
+> formae plugin init my-plugin
+> ```
+
+---
+
+## Setup Checklist
+
+*Remove this section and the warning above after completing setup.*
+
+After creating your plugin with `formae plugin init`, complete these steps:
+
+- [X] Update `formae-plugin.pkl` with your plugin metadata (name, namespace, description)
+- [X] Define your resource types in `schema/pkl/*.pkl`
+- [ ] Implement CRUD operations in `plugin.go`
+- [ ] Update test fixtures in `testdata/*.pkl` to use your resources
+- [ ] Update this README (replace title, description, resources table, etc.)
+- [ ] Set up local credentials for testing
+- [ ] Run conformance tests locally: `make conformance-test`
+- [ ] Configure CI credentials in `.github/workflows/ci.yml` (optional)
+- [ ] Remove this checklist section and the warning box above
+
+For detailed guidance, see the [Plugin SDK Documentation](https://docs.formae.io/plugin-sdk).
+
+---
+
+# Example Plugin for formae
+
+*TODO: Update title and description for your plugin*
+
+Example Formae plugin template - replace this with a description of what your plugin manages.
+
+## Installation
+
+```bash
+# Install the plugin
+make install
+```
+
+## Supported Resources
+
+*TODO: Document your supported resource types*
+
+| Resource Type                  | Description                                           |
+| ------------------------------ | ----------------------------------------------------- |
+| `PROXMOX::Service::Resource` | Example resource (replace with your actual resources) |
+
+## Configuration
+
+Configure a target in your Forma file:
+
+```pkl
+new formae.Target {
+    label = "my-target"
+    namespace = "PROXMOX"  // TODO: Update with your namespace
+    config = new Mapping {
+        ["region"] = "us-east-1"
+        // TODO: Add your provider-specific configuration
+    }
+}
+```
+
+## Examples
+
+See the [examples/](examples/) directory for usage examples.
+
+```bash
+# Evaluate an example
+formae eval examples/basic/main.pkl
+
+# Apply resources
+formae apply --mode reconcile --watch examples/basic/main.pkl
+```
+
+## Development
+
+### Prerequisites
+
+- Go 1.25+
+- [Pkl CLI](https://pkl-lang.org/main/current/pkl-cli/index.html)
+- Cloud provider credentials (for conformance testing)
+
+### Building
+
+```bash
+make build      # Build plugin binary
+make test       # Run unit tests
+make lint       # Run linter
+make install    # Build + install locally
+```
+
+### Local Testing
+
+```bash
+# Install plugin locally
+make install
+
+# Start formae agent
+formae agent start
+
+# Apply example resources
+formae apply --mode reconcile --watch examples/basic/main.pkl
+```
+
+### Conformance Testing
+
+Conformance tests validate your plugin's CRUD lifecycle using the test fixtures in `testdata/`:
+
+| File                     | Purpose                          |
+| ------------------------ | -------------------------------- |
+| `resource.pkl`         | Initial resource creation        |
+| `resource-update.pkl`  | In-place update (mutable fields) |
+| `resource-replace.pkl` | Replacement (createOnly fields)  |
+
+The test harness sets `FORMAE_TEST_RUN_ID` for unique resource naming between runs.
+
+```bash
+make conformance-test                  # Latest formae version
+make conformance-test VERSION=0.80.0   # Specific version
+```
+
+The `scripts/ci/clean-environment.sh` script cleans up test resources. It runs before and after conformance tests and should be idempotent.
+
+## Licensing
+
+Plugins are independent works and may be licensed under any license of the author’s choosing.
+
+See the formae plugin policy:
+<https://docs.formae.io/plugin-sdk/