chore: initial project setup

Author: miohansen

.github/workflows/cd.yml

@@ -0,0 +1,48 @@
+name: CD
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g. v0.2.0)'
+        required: true
+
+env:
+  RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.4"
+
+      - name: Run tests
+        run: go test ./...
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [test]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release view ${{ env.RELEASE_TAG }} --repo ${{ github.repository }} \
+            && echo "Release already exists, skipping" \
+            || gh release create ${{ env.RELEASE_TAG }} \
+                --title "${{ env.RELEASE_TAG }}" \
+                --generate-notes \
+                --repo ${{ github.repository }}

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.4"
+
+      - name: Run tests
+        run: go test ./...

capabilityclient/client.go

@@ -0,0 +1,103 @@
+// Package capabilityclient provides a typed client for calling ctx capabilities
+// from within extension containers.
+//
+// The client calls the capability server sidecar via HTTP. The server URL and
+// bearer token are injected by ctx into the container environment as
+// CTX_CAPABILITY_URL and CTX_CAPABILITY_TOKEN.
+package capabilityclient
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+)
+
+const (
+	envCapabilityURL   = "CTX_CAPABILITY_URL"
+	envCapabilityToken = "CTX_CAPABILITY_TOKEN"
+)
+
+// Client calls ctx capabilities via the capability server sidecar.
+type Client struct {
+	httpC *http.Client
+}
+
+// New returns a Client. The client requires CTX_CAPABILITY_URL to be set in
+// the environment (injected by ctx when starting the container).
+func New() *Client {
+	return &Client{httpC: &http.Client{}}
+}
+
+// Run executes a named capability with the given input (marshalled to JSON)
+// and returns the raw JSON output bytes.
+//
+// Returns an error if CTX_CAPABILITY_URL is not set or the server returns
+// a non-2xx status.
+func (c *Client) Run(ctx context.Context, capability string, input any) ([]byte, error) {
+	url := os.Getenv(envCapabilityURL)
+	if url == "" {
+		return nil, fmt.Errorf("capability-client: CTX_CAPABILITY_URL is not set; capabilities require a ctx-managed container")
+	}
+
+	inputJSON, err := json.Marshal(input)
+	if err != nil {
+		return nil, fmt.Errorf("capability-client: marshal input for %q: %w", capability, err)
+	}
+	envelope := struct {
+		Input json.RawMessage `json:"input"`
+	}{Input: inputJSON}
+	body, err := json.Marshal(envelope)
+	if err != nil {
+		return nil, fmt.Errorf("capability-client: marshal envelope for %q: %w", capability, err)
+	}
+
+	reqURL := strings.TrimRight(url, "/") + "/run/" + capability
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, reqURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("capability-client: build request for %q: %w", capability, err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if token := os.Getenv(envCapabilityToken); token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+
+	resp, err := c.httpC.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("capability-client: http request for %q: %w", capability, err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("capability-client: read response for %q: %w", capability, err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, &RunError{
+			Capability: capability,
+			Cause:      fmt.Errorf("http status %d", resp.StatusCode),
+			Stderr:     strings.TrimSpace(string(respBody)),
+		}
+	}
+	return respBody, nil
+}
+
+// RunError is returned when the capability call fails (non-2xx HTTP status).
+type RunError struct {
+	Capability string
+	Cause      error
+	Stderr     string
+}
+
+func (e *RunError) Error() string {
+	if e.Stderr != "" {
+		return fmt.Sprintf("capability-client: %s: %v\n%s", e.Capability, e.Cause, e.Stderr)
+	}
+	return fmt.Sprintf("capability-client: %s: %v", e.Capability, e.Cause)
+}
+
+func (e *RunError) Unwrap() error { return e.Cause }

capabilityclient/client_test.go

@@ -0,0 +1,159 @@
+package capabilityclient_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/delegateas/ctx-sdk/capabilityclient"
+)
+
+func TestClient_New(t *testing.T) {
+	if capabilityclient.New() == nil {
+		t.Fatal("New() returned nil")
+	}
+}
+
+func TestClient_Run_NoURL_Error(t *testing.T) {
+	t.Setenv("CTX_CAPABILITY_URL", "")
+	c := capabilityclient.New()
+	_, err := c.Run(context.Background(), "ai.generate", map[string]string{"prompt": "hi"})
+	if err == nil {
+		t.Fatal("expected error when CTX_CAPABILITY_URL is not set")
+	}
+	if !strings.Contains(err.Error(), "CTX_CAPABILITY_URL") {
+		t.Errorf("error should mention CTX_CAPABILITY_URL, got: %v", err)
+	}
+}
+
+func TestClient_Run_Success(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"output":"hello"}`)) //nolint:errcheck
+	}))
+	defer srv.Close()
+	t.Setenv("CTX_CAPABILITY_URL", srv.URL)
+
+	c := capabilityclient.New()
+	out, err := c.Run(context.Background(), "ai.generate", map[string]string{"prompt": "hello"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var result map[string]string
+	if err := json.Unmarshal(out, &result); err != nil {
+		t.Fatalf("unmarshal output: %v", err)
+	}
+	if result["output"] != "hello" {
+		t.Errorf("output = %q; want %q", result["output"], "hello")
+	}
+}
+
+func TestClient_Run_NonOK(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "something went wrong", http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+	t.Setenv("CTX_CAPABILITY_URL", srv.URL)
+
+	c := capabilityclient.New()
+	_, err := c.Run(context.Background(), "ai.generate", map[string]string{"prompt": "hello"})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var runErr *capabilityclient.RunError
+	if !errors.As(err, &runErr) {
+		t.Fatalf("error type = %T; want *RunError", err)
+	}
+	if runErr.Capability != "ai.generate" {
+		t.Errorf("Capability = %q; want %q", runErr.Capability, "ai.generate")
+	}
+	if !strings.Contains(runErr.Stderr, "something went wrong") {
+		t.Errorf("Stderr = %q; want to contain 'something went wrong'", runErr.Stderr)
+	}
+}
+
+func TestClient_Run_SendsToken(t *testing.T) {
+	const token = "secret-token"
+	var gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{}`)) //nolint:errcheck
+	}))
+	defer srv.Close()
+	t.Setenv("CTX_CAPABILITY_URL", srv.URL)
+	t.Setenv("CTX_CAPABILITY_TOKEN", token)
+
+	capabilityclient.New().Run(context.Background(), "ai.generate", nil) //nolint:errcheck
+	if gotAuth != "Bearer "+token {
+		t.Errorf("Authorization = %q; want %q", gotAuth, "Bearer "+token)
+	}
+}
+
+func TestClient_Run_MarshalInput(t *testing.T) {
+	var gotBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"output":"ok"}`)) //nolint:errcheck
+	}))
+	defer srv.Close()
+	t.Setenv("CTX_CAPABILITY_URL", srv.URL)
+
+	type myInput struct {
+		Prompt string `json:"prompt"`
+		Count  int    `json:"count"`
+	}
+	capabilityclient.New().Run(context.Background(), "test.cap", myInput{Prompt: "test", Count: 42}) //nolint:errcheck
+
+	var envelope struct {
+		Input struct {
+			Prompt string `json:"prompt"`
+			Count  int    `json:"count"`
+		} `json:"input"`
+	}
+	if err := json.Unmarshal(gotBody, &envelope); err != nil {
+		t.Fatalf("unmarshal request body: %v", err)
+	}
+	if envelope.Input.Prompt != "test" || envelope.Input.Count != 42 {
+		t.Errorf("input = %+v; want {Prompt:test Count:42}", envelope.Input)
+	}
+}
+
+func TestRunError_Error_WithStderr(t *testing.T) {
+	err := &capabilityclient.RunError{
+		Capability: "ai.generate",
+		Cause:      errors.New("exit status 1"),
+		Stderr:     "something failed",
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "ai.generate") {
+		t.Errorf("Error() missing capability name: %q", msg)
+	}
+	if !strings.Contains(msg, "something failed") {
+		t.Errorf("Error() missing stderr: %q", msg)
+	}
+}
+
+func TestRunError_Error_WithoutStderr(t *testing.T) {
+	err := &capabilityclient.RunError{
+		Capability: "ai.generate",
+		Cause:      errors.New("exit status 1"),
+	}
+	if !strings.Contains(err.Error(), "ai.generate") {
+		t.Errorf("Error() missing capability name: %q", err.Error())
+	}
+}
+
+func TestRunError_Unwrap(t *testing.T) {
+	cause := errors.New("root cause")
+	runErr := &capabilityclient.RunError{Capability: "ai.generate", Cause: cause}
+	if !errors.Is(runErr, cause) {
+		t.Error("errors.Is failed — Unwrap not working")
+	}
+}

capabilityclient/generate.go

@@ -0,0 +1,37 @@
+package capabilityclient
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+type generateInput struct {
+	Prompt string `json:"prompt"`
+}
+
+type generateOutput struct {
+	Output string `json:"output"`
+}
+
+// Generate calls the built-in ai.generate capability with the given prompt and
+// returns the trimmed text output.
+//
+// This is the typed equivalent of:
+//
+//	ctx run ai.generate --input '{"prompt":"..."}'
+func (c *Client) Generate(ctx context.Context, prompt string) (string, error) {
+	if prompt == "" {
+		return "", fmt.Errorf("capability-client: Generate: prompt must not be empty")
+	}
+	raw, err := c.Run(ctx, "ai.generate", generateInput{Prompt: prompt})
+	if err != nil {
+		return "", err
+	}
+	var out generateOutput
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return "", fmt.Errorf("capability-client: Generate: decode response: %w", err)
+	}
+	return strings.TrimSpace(out.Output), nil
+}