scaffold: OpenAPI generator plugin skeleton

Generator plugin (not executor) — invoked via `qube generate --from <spec>`.

- contract.go, plugin.go, host.go — shared template
- info.go — generator plugin metadata (no protocols, no fields)
- generator.go — GenerateInput/Output types and generate() skeleton
- exports.go — custom exports: plugin_info, plugin_init, generate, plugin_destroy
  (no execute/validate — this plugin is not a test executor)

Detects CRUD patterns (POST + GET/{id} + PUT/{id} + DELETE/{id}) and
generates scenario files with save/extract chains.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: davidmovas

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  vet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+      - run: go vet ./...
+
+  build-wasm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+      - name: Install TinyGo
+        run: |
+          wget https://github.com/tinygo-org/tinygo/releases/download/v0.33.0/tinygo_0.33.0_amd64.deb
+          sudo dpkg -i tinygo_0.33.0_amd64.deb
+      - name: Build WASM
+        run: tinygo build -o plugin-openapi.wasm -target=wasi ./
+      - name: Check WASM size
+        run: ls -lh plugin-openapi.wasm
+      - uses: actions/upload-artifact@v4
+        with:
+          name: plugin-openapi.wasm
+          path: plugin-openapi.wasm

.gitignore

@@ -0,0 +1,8 @@
+*.wasm
+*.exe
+*.test
+*.out
+vendor/
+.idea/
+.vscode/
+.DS_Store

.golangci.yml

@@ -0,0 +1,11 @@
+version: "2"
+
+linters:
+  default: standard
+  enable:
+    - govet
+    - errcheck
+    - staticcheck
+    - gocritic
+    - ineffassign
+    - misspell

README.md

@@ -0,0 +1,40 @@
+# plugin-openapi
+
+> OpenAPI / Swagger test generator for [ApiQube](https://github.com/apiqube).
+
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![Status](https://img.shields.io/badge/Status-Scaffold-yellow?style=flat-square)]()
+
+Generator plugin (not an executor). Invoked via `qube generate --from openapi.json`
+to produce qube test files from an existing API specification.
+
+Detects CRUD patterns and emits scenario files with proper save/extract chains.
+
+## Usage
+
+```bash
+# From a local file
+qube generate --from ./swagger.json --output ./tests/
+
+# From a URL
+qube generate --from http://localhost:8081/swagger/doc.json --output ./tests/
+```
+
+## What it generates
+
+For each `paths` entry in the spec:
+
+- CRUD groups (POST + GET/{id} + PUT/{id} + DELETE/{id}) → scenario file
+- Schema fields → `fake.*` template values
+- Response codes → `expect.status` assertions
+- Required fields → test bodies
+
+## Build
+
+```bash
+tinygo build -o plugin-openapi.wasm -target=wasi ./
+```
+
+## License
+
+[MIT](LICENSE)

contract.go

@@ -0,0 +1,45 @@
+package main
+
+// These types mirror github.com/apiqube/engine/internal/plugin.
+// They are duplicated here (not imported) because plugins are compiled
+// to WASM independently and communicate with the host via JSON bytes.
+
+// PluginInfo is the metadata returned by plugin_info().
+type PluginInfo struct {
+	Name        string               `json:"name"`
+	Version     string               `json:"version"`
+	Description string               `json:"description"`
+	Protocols   []string             `json:"protocols"`
+	Fields      map[string]FieldSpec `json:"fields"`
+}
+
+// FieldSpec declares one manifest field this plugin adds.
+type FieldSpec struct {
+	Type        string `json:"type"` // string, number, bool, object, array, map, any
+	Required    bool   `json:"required"`
+	Description string `json:"description"`
+}
+
+// TestInput is what the host passes to execute().
+type TestInput struct {
+	Target  string            `json:"target"`
+	Headers map[string]string `json:"headers,omitempty"`
+	Timeout string            `json:"timeout,omitempty"`
+	Fields  map[string]any    `json:"fields"`
+}
+
+// TestOutput is what execute() returns to the host.
+type TestOutput struct {
+	Status     any               `json:"status"`
+	Headers    map[string]string `json:"headers,omitempty"`
+	Body       any               `json:"body,omitempty"`
+	DurationMs int64             `json:"duration_ms"`
+	Error      string            `json:"error,omitempty"`
+	Metadata   map[string]any    `json:"metadata,omitempty"`
+}
+
+// FieldError reports a validation problem on a specific field.
+type FieldError struct {
+	Field   string `json:"field"`
+	Message string `json:"message"`
+}

exports.go

@@ -0,0 +1,51 @@
+package main
+
+import "encoding/json"
+
+// plugin_info returns metadata as JSON.
+//
+//export plugin_info
+func pluginInfo() uint64 {
+	data, _ := json.Marshal(info())
+	return toPointer(data)
+}
+
+// plugin_init runs one-time initialization.
+//
+//export plugin_init
+func pluginInit(cfgPtr uint64) uint64 {
+	// TODO: read cfgPtr, apply any generator settings
+	_ = cfgPtr
+	return 0
+}
+
+// generate produces test files from an OpenAPI spec.
+//
+//export generate
+func generateFromSpec(inputPtr uint64) uint64 {
+	// TODO:
+	// 1. readBytes(inputPtr) → GenerateInput
+	// 2. Call generate(in)
+	// 3. Marshal GenerateOutput to JSON
+	// 4. Return toPointer(data)
+	_ = inputPtr
+	return 0
+}
+
+// plugin_destroy releases generator resources.
+//
+//export plugin_destroy
+func pluginDestroy() {}
+
+// toPointer packs a byte slice into a (ptr << 32) | len uint64.
+func toPointer(data []byte) uint64 {
+	// TODO: WASM implementation via unsafe
+	return uint64(len(data))
+}
+
+// readBytes reads bytes at the given packed location.
+func readBytes(packed uint64) []byte {
+	// TODO: WASM implementation
+	_ = packed
+	return nil
+}

generator.go

@@ -0,0 +1,41 @@
+package main
+
+// GenerateInput is what the host passes to the exported `generate` function.
+type GenerateInput struct {
+	SourceURL  string `json:"source_url,omitempty"`  // http://localhost/swagger.json
+	SourcePath string `json:"source_path,omitempty"` // local file path
+	OutputDir  string `json:"output_dir"`            // where to write generated test files
+	Format     string `json:"format,omitempty"`      // full, compact, oneliner
+}
+
+// GenerateOutput is what `generate` returns.
+type GenerateOutput struct {
+	FilesCreated []string `json:"files_created"`
+	TestsCount   int      `json:"tests_count"`
+	Warnings     []string `json:"warnings,omitempty"`
+	Error        string   `json:"error,omitempty"`
+}
+
+// generate reads an OpenAPI spec and produces qube test files.
+// This is the main function of the generator plugin.
+func generate(in *GenerateInput) *GenerateOutput {
+	// TODO: implementation
+	//
+	// 1. Fetch spec:
+	//    - From URL via host_http_request
+	//    - Or from file via host_read_file
+	// 2. Parse OpenAPI JSON/YAML (use kin-openapi compatible structure)
+	// 3. Walk paths, group by tag (or by resource prefix)
+	// 4. Detect CRUD patterns per resource:
+	//    POST /users  →  creates, extract id from response
+	//    GET /users/{id}  →  uses saved id
+	//    PUT /users/{id}  →  uses saved id, body from schema
+	//    DELETE /users/{id}  →  uses saved id
+	//    → emit as a scenario file
+	// 5. For standalone endpoints: emit as independent tests
+	// 6. For each schema property: use fake.* generator
+	// 7. For each response code: emit expect.status assertion
+	// 8. Write files to OutputDir
+	// 9. Return GenerateOutput with file list and counts
+	return &GenerateOutput{Error: "not implemented"}
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/apiqube/plugin-openapi
+
+go 1.26.0

host.go

@@ -0,0 +1,44 @@
+package main
+
+// Host functions provided by the ApiQube engine to this plugin.
+//
+// When built as a WASM module, these are linked at load time by wazero.
+// The //go:wasmimport directive only takes effect under TinyGo WASI build,
+// so a regular `go build` compiles the stubs below cleanly.
+
+// httpResponse mirrors what the host returns from host_http_request.
+type httpResponse struct {
+	Status     int               `json:"status"`
+	Headers    map[string]string `json:"headers"`
+	Body       []byte            `json:"body"`
+	DurationMs int64             `json:"duration_ms"`
+	Error      string            `json:"error,omitempty"`
+}
+
+// httpRequest is the Go-friendly wrapper around host_http_request.
+func httpRequest(method, url string, headers map[string]string, body []byte) (*httpResponse, error) {
+	// TODO: implementation
+	// 1. Marshal headers to JSON
+	// 2. Pack method/url/headers/body as ptr+len pairs
+	// 3. Call hostHTTPRequestImport (see below)
+	// 4. Read response bytes, unmarshal into httpResponse
+	_ = method
+	_ = url
+	_ = headers
+	_ = body
+	return nil, nil
+}
+
+// logMessage sends a log line to the host for display/storage.
+func logMessage(level, msg string) {
+	// TODO: implementation via host_log import
+	_ = level
+	_ = msg
+}
+
+// now returns the current Unix timestamp in milliseconds from the host.
+// (Plugins don't have direct access to system clock in WASI.)
+func now() int64 {
+	// TODO: implementation via host_now import
+	return 0
+}

info.go

@@ -0,0 +1,17 @@
+package main
+
+// plugin-openapi is a Generator plugin, not an Executor.
+// It has no protocols and no manifest fields — it is invoked via
+// `qube generate --from openapi.json` and produces YAML test files.
+//
+// Generator plugins use a different subset of the plugin contract:
+// plugin_info() + generate(source) instead of plugin_info() + execute(test).
+func info() PluginInfo {
+	return PluginInfo{
+		Name:        "openapi",
+		Version:     "0.1.0",
+		Description: "Generates qube test files from OpenAPI/Swagger specifications.",
+		Protocols:   nil, // generator plugins have no protocols
+		Fields:      nil, // generator plugins do not add manifest fields
+	}
+}