@opensoha/contracts 0.1.4

package/resource/models_test.go

@@ -0,0 +1,72 @@
+package resource
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestNetworkTopologyViewJSONOmitsAggregateInputs(t *testing.T) {
+	raw, err := json.Marshal(NetworkTopologyView{
+		ClusterID:   "cluster-a",
+		Source:      "backend-aggregate",
+		GeneratedAt: "2026-07-18T00:00:00Z",
+	})
+	if err != nil {
+		t.Fatalf("marshal topology: %v", err)
+	}
+
+	var payload map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("unmarshal topology: %v", err)
+	}
+	for _, key := range []string{"services", "ingresses", "httpRoutes", "gateways", "pods"} {
+		if _, ok := payload[key]; ok {
+			t.Errorf("topology response contains aggregate input %q: %s", key, raw)
+		}
+	}
+}
+
+func TestLightweightListViewsOmitDetailOnlyFields(t *testing.T) {
+	views := []struct {
+		name    string
+		value   any
+		omitted []string
+	}{
+		{"configmap", ConfigMapView{}, []string{"binaryEntries", "immutable"}},
+		{"serviceaccount", ServiceAccountView{}, []string{"secrets", "imagePullSecrets", "automountServiceAccountToken"}},
+		{"role", RoleView{}, []string{"rules"}},
+		{"rolebinding", RoleBindingView{}, []string{"subjects"}},
+		{"clusterrole", ClusterRoleView{}, []string{"rules", "aggregationRules"}},
+		{"clusterrolebinding", ClusterRoleBindingView{}, []string{"subjects"}},
+		{"storageclass", StorageClassView{}, []string{"parameters"}},
+	}
+	for _, view := range views {
+		t.Run(view.name, func(t *testing.T) {
+			raw, err := json.Marshal(view.value)
+			if err != nil {
+				t.Fatalf("marshal %s: %v", view.name, err)
+			}
+			var payload map[string]json.RawMessage
+			if err := json.Unmarshal(raw, &payload); err != nil {
+				t.Fatalf("unmarshal %s: %v", view.name, err)
+			}
+			for _, key := range view.omitted {
+				if _, ok := payload[key]; ok {
+					t.Errorf("%s list response contains detail-only field %q", view.name, key)
+				}
+			}
+		})
+	}
+}
+
+func TestAdmissionWebhookDetailDoesNotExposeCABundle(t *testing.T) {
+	raw, err := json.Marshal(AdmissionWebhookConfigurationDetailView{
+		Webhooks: []AdmissionWebhookView{{Name: "hook.example", CABundleConfigured: true}},
+	})
+	if err != nil {
+		t.Fatalf("marshal webhook detail: %v", err)
+	}
+	if string(raw) != `{"name":"","ageSeconds":0,"webhooks":[{"name":"hook.example","clientTarget":"","caBundleConfigured":true}]}` {
+		t.Fatalf("unexpected webhook detail JSON: %s", raw)
+	}
+}

package/runner/operation-lifecycle.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/runner/operation-lifecycle.schema.json",
+  "title": "OpenSoha Runner Operation Lifecycle",
+  "description": "Shared lifecycle event contract for long-running delivery, Docker, VM, AI provider, and agent runner operations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operationId", "operationKind", "runnerId", "state", "occurredAt"],
+  "properties": {
+    "operationId": { "type": "string", "minLength": 1 },
+    "operationKind": {
+      "type": "string",
+      "enum": ["delivery", "docker", "vm", "ai_provider", "agent_run", "connector_action"]
+    },
+    "runnerId": { "type": "string", "minLength": 1 },
+    "agentId": { "type": "string", "minLength": 1 },
+    "tenantId": { "type": "string", "minLength": 1 },
+    "workspaceId": { "type": "string", "minLength": 1 },
+    "state": {
+      "type": "string",
+      "enum": [
+        "claimed",
+        "heartbeat",
+        "cancel_requested",
+        "cancelled",
+        "timed_out",
+        "succeeded",
+        "failed",
+        "late_callback_ignored"
+      ]
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic event sequence per operation when available."
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "deadlineAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "heartbeat": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "intervalSeconds": { "type": "integer", "minimum": 1 },
+        "nextDueAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/OperationEvidence" }
+    },
+    "finalState": {
+      "$ref": "#/$defs/FinalOperationState"
+    },
+    "callback": {
+      "$ref": "#/$defs/CallbackContext"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "OperationEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "message"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["log", "event", "artifact", "callback_payload", "approval", "user_action"]
+        },
+        "message": { "type": "string", "minLength": 1 },
+        "uri": { "type": "string", "format": "uri" },
+        "redacted": { "type": "boolean" },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "FinalOperationState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["succeeded", "failed", "cancelled", "timed_out"]
+        },
+        "reason": { "type": "string" },
+        "message": { "type": "string" },
+        "completedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "CallbackContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "callbackId": { "type": "string", "minLength": 1 },
+        "accepted": { "type": "boolean" },
+        "late": { "type": "boolean" },
+        "dedupeKey": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/skills/skill-manifest.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/skills/skill-manifest.schema.json",
+  "title": "Soha Skill Manifest",
+  "description": "Structured front matter extracted from official Soha skill markdown files.",
+  "type": "object",
+  "required": ["id", "name", "category"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "version": { "type": "string" },
+    "category": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "capabilityRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "permissionKeys": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "requiredScopes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "providerSkillRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["providerKind", "ref"],
+        "properties": {
+          "providerKind": { "type": "string" },
+          "ref": { "type": "string" },
+          "arguments": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}
+

package/streamlimit/limited_buffer.go

@@ -0,0 +1,58 @@
+package streamlimit
+
+import (
+	"bytes"
+	"io"
+)
+
+type LimitedBuffer struct {
+	limit      int
+	buffer     bytes.Buffer
+	totalBytes int64
+	truncated  bool
+}
+
+func NewLimitedBuffer(limit int) *LimitedBuffer {
+	if limit <= 0 {
+		limit = 1
+	}
+	return &LimitedBuffer{limit: limit}
+}
+
+func (b *LimitedBuffer) Write(p []byte) (int, error) {
+	b.totalBytes += int64(len(p))
+	remaining := b.limit - b.buffer.Len()
+	if remaining > 0 {
+		chunk := p
+		if len(chunk) > remaining {
+			chunk = chunk[:remaining]
+		}
+		if _, err := b.buffer.Write(chunk); err != nil {
+			return 0, err
+		}
+	}
+	if len(p) > remaining {
+		b.truncated = true
+	}
+	return len(p), nil
+}
+
+func (b *LimitedBuffer) String() string {
+	return b.buffer.String()
+}
+
+func (b *LimitedBuffer) TotalBytes() int64 {
+	return b.totalBytes
+}
+
+func (b *LimitedBuffer) Truncated() bool {
+	return b.truncated
+}
+
+func ReadString(reader io.Reader, limit int) (string, int64, bool, error) {
+	buffer := NewLimitedBuffer(limit)
+	if _, err := io.Copy(buffer, reader); err != nil {
+		return "", 0, false, err
+	}
+	return buffer.String(), buffer.TotalBytes(), buffer.Truncated(), nil
+}

package/streamlimit/limited_buffer_test.go

@@ -0,0 +1,38 @@
+package streamlimit
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLimitedBufferTruncatesAtLimit(t *testing.T) {
+	buffer := NewLimitedBuffer(5)
+	if _, err := buffer.Write([]byte("hello world")); err != nil {
+		t.Fatalf("Write() error = %v", err)
+	}
+	if got := buffer.String(); got != "hello" {
+		t.Fatalf("String() = %q, want hello", got)
+	}
+	if got := buffer.TotalBytes(); got != 11 {
+		t.Fatalf("TotalBytes() = %d, want 11", got)
+	}
+	if !buffer.Truncated() {
+		t.Fatalf("Truncated() = false, want true")
+	}
+}
+
+func TestReadStringReturnsFullContentWhenWithinLimit(t *testing.T) {
+	content, totalBytes, truncated, err := ReadString(strings.NewReader("hello"), 16)
+	if err != nil {
+		t.Fatalf("ReadString() error = %v", err)
+	}
+	if content != "hello" {
+		t.Fatalf("content = %q, want hello", content)
+	}
+	if totalBytes != 5 {
+		t.Fatalf("totalBytes = %d, want 5", totalBytes)
+	}
+	if truncated {
+		t.Fatalf("truncated = true, want false")
+	}
+}