Feature/first cut

.github/workflows/push.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          cache: true
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Run vet
+        run: go vet ./...
+
+      - name: Run tests
+        run: go test ./... -v
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          cache: true
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v6
+        with:
+          version: v2.5.0
+
+  vulncheck:
+    name: Vulnerability Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          cache: true
+
+      - name: Run govulncheck
+        uses: golang/govulncheck-action@v1

.gitignore

@@ -0,0 +1,34 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Code coverage profiles and other test artifacts
+*.out
+coverage.*
+*.coverprofile
+profile.cov
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# Editor/IDE
+# .idea/
+# .vscode/
+.DS_Store
+*.db

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Wooltorton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,21 @@
+
+.PHONY: generate-mocks
+
+generate-mocks:
+	@echo "Generating mocks..."
+	mockgen -source=internal/plugins/plugin.go -destination=internal/plugins/mocks/plugin_mocks.go -package=mocks
+	mockgen -source internal/connectors/main.go -destination internal/connectors/mocks/mock_interfaces.go -package mocks
+	mockgen -source internal/subscription_manager/main.go -destination internal/subscription_manager/mocks/mock_interfaces.go -package mocks
+	mockgen -source internal/processor/main.go -destination internal/processor/mocks/mock_interfaces.go -package mocks
+	mockgen -source internal/storage_manager/main.go -destination internal/storage_manager/mocks/mock_interfaces.go -package mocks
+	mockgen -package=mocks -destination=internal/processor/mocks/mock_connector.go github.com/kvatch-hub/kvatch-runtime/internal/connectors Connector
+	mockgen -package=mocks -destination=internal/processor/mocks/mock_plugin.go github.com/kvatch-hub/kvatch-runtime/internal/plugins Plugin
+
+	@echo "Mocks generated successfully"
+
+lint:
+	golangci-lint version && golangci-lint run --verbose  -E  misspell    
+
+test:
+	go test -short ./...
+

README.md

@@ -1 +1,142 @@
-# kvatch-runtime
+# 🚀 Kvatch Runtime
+
+![Go Version](https://img.shields.io/badge/go-1.21+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![Status](https://img.shields.io/badge/status-alpha-orange.svg)
+
+A lightweight runtime for executing federated data plans.
+
+> ⚠️ This project is in early development. APIs may change.
+
+------------------------------------------------------------------------
+
+## 📦 Installation
+
+``` bash
+go get github.com/kvatch-hub/kvatch-runtime
+```
+
+------------------------------------------------------------------------
+
+## 🚀 Quick Start
+
+``` go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/kvatch-hub/kvatch-runtime/entities"
+    "github.com/kvatch-hub/kvatch-runtime/runtime"
+)
+
+func main() {
+    rt, err := runtime.NewDefault()
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    plan := entities.Plan{
+        Datasets: []entities.Dataset{
+            {
+                Name: "example",
+                Type: "static",
+                Data: []map[string]interface{}{
+                    {"id": 1, "name": "Alice"},
+                    {"id": 2, "name": "Bob"},
+                },
+            },
+        },
+        Output: entities.PlanOutput{
+            DatasetName: "example",
+        },
+    }
+
+    resp, err := rt.ExecutePlan(context.Background(), entities.ExecutePlanRequest{
+        Plan: plan,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Columns:", resp.Columns)
+    fmt.Println("Data:", resp.Data)
+}
+```
+
+------------------------------------------------------------------------
+
+## 🧠 What's happening
+
+-   `runtime.NewDefault()` sets up the engine, storage, and processor
+-   You define a `Plan`
+-   `ExecutePlan` runs it and returns structured results
+
+------------------------------------------------------------------------
+
+## ⚙️ Configuration
+
+### Default (recommended)
+
+``` go
+rt, _ := runtime.NewDefault()
+```
+
+Uses a local SQLite database:
+
+    ./kvatch.db
+
+------------------------------------------------------------------------
+
+### Custom SQLite
+
+``` go
+rt, _ := runtime.NewWithSQLite("file:my.db")
+```
+
+------------------------------------------------------------------------
+
+### Full configuration
+
+``` go
+cfg := configs.Config{
+    Storage: configs.StorageConfig{
+        Driver: "sqlite",
+        DSN:    "file:custom.db",
+    },
+}
+
+rt, _ := runtime.New(cfg)
+```
+
+------------------------------------------------------------------------
+
+## 📦 Output Format
+
+``` go
+type ExecutePlanResponse struct {
+    Columns []DataColumn
+    Data    []map[string]interface{}
+}
+```
+
+-   `Columns` defines order and metadata\
+-   `Data` contains row values
+
+------------------------------------------------------------------------
+
+## 🎯 Philosophy
+
+Kvatch Runtime is designed to be:
+
+-   **Simple to start** → one function call\
+-   **Composable internally** → clean engine architecture\
+-   **Extensible** → connectors, processors, and plugins
+
+------------------------------------------------------------------------
+
+## 📄 License
+
+MIT License © 2026 James Wooltorton