@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/golang-pro/references/testing.md

@@ -0,0 +1,451 @@
+# Testing and Benchmarking
+
+## Table-Driven Tests
+
+```go
+package math
+
+import "testing"
+
+func Add(a, b int) int {
+    return a + b
+}
+
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -2, -3, -5},
+        {"mixed signs", -2, 3, 1},
+        {"zeros", 0, 0, 0},
+        {"large numbers", 1000000, 2000000, 3000000},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d; want %d", tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+## Subtests and Parallel Execution
+
+```go
+func TestParallel(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+        want  string
+    }{
+        {"lowercase", "hello", "HELLO"},
+        {"uppercase", "WORLD", "WORLD"},
+        {"mixed", "HeLLo", "HELLO"},
+    }
+
+    for _, tt := range tests {
+        tt := tt // Capture range variable for parallel tests
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel() // Run subtests in parallel
+
+            result := strings.ToUpper(tt.input)
+            if result != tt.want {
+                t.Errorf("got %q, want %q", result, tt.want)
+            }
+        })
+    }
+}
+```
+
+## Test Helpers and Setup/Teardown
+
+```go
+func TestWithSetup(t *testing.T) {
+    // Setup
+    db := setupTestDB(t)
+    defer cleanupTestDB(t, db)
+
+    tests := []struct {
+        name string
+        user User
+    }{
+        {"valid user", User{Name: "John", Email: "john@example.com"}},
+        {"empty name", User{Name: "", Email: "test@example.com"}},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := db.SaveUser(tt.user)
+            if err != nil {
+                t.Fatalf("SaveUser failed: %v", err)
+            }
+        })
+    }
+}
+
+// Helper function (doesn't show in stack trace)
+func setupTestDB(t *testing.T) *DB {
+    t.Helper()
+
+    db, err := NewDB(":memory:")
+    if err != nil {
+        t.Fatalf("failed to create test DB: %v", err)
+    }
+    return db
+}
+
+func cleanupTestDB(t *testing.T, db *DB) {
+    t.Helper()
+
+    if err := db.Close(); err != nil {
+        t.Errorf("failed to close DB: %v", err)
+    }
+}
+```
+
+## Mocking with Interfaces
+
+```go
+// Interface to mock
+type EmailSender interface {
+    Send(to, subject, body string) error
+}
+
+// Mock implementation
+type MockEmailSender struct {
+    SentEmails []Email
+    ShouldFail bool
+}
+
+type Email struct {
+    To, Subject, Body string
+}
+
+func (m *MockEmailSender) Send(to, subject, body string) error {
+    if m.ShouldFail {
+        return fmt.Errorf("failed to send email")
+    }
+    m.SentEmails = append(m.SentEmails, Email{to, subject, body})
+    return nil
+}
+
+// Test using mock
+func TestUserService_Register(t *testing.T) {
+    mockSender := &MockEmailSender{}
+    service := NewUserService(mockSender)
+
+    err := service.Register("user@example.com")
+    if err != nil {
+        t.Fatalf("Register failed: %v", err)
+    }
+
+    if len(mockSender.SentEmails) != 1 {
+        t.Errorf("expected 1 email sent, got %d", len(mockSender.SentEmails))
+    }
+
+    email := mockSender.SentEmails[0]
+    if email.To != "user@example.com" {
+        t.Errorf("expected email to user@example.com, got %s", email.To)
+    }
+}
+```
+
+## Benchmarking
+
+```go
+func BenchmarkAdd(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        Add(100, 200)
+    }
+}
+
+// Benchmark with subtests
+func BenchmarkStringOperations(b *testing.B) {
+    benchmarks := []struct {
+        name  string
+        input string
+    }{
+        {"short", "hello"},
+        {"medium", strings.Repeat("hello", 10)},
+        {"long", strings.Repeat("hello", 100)},
+    }
+
+    for _, bm := range benchmarks {
+        b.Run(bm.name, func(b *testing.B) {
+            for i := 0; i < b.N; i++ {
+                _ = strings.ToUpper(bm.input)
+            }
+        })
+    }
+}
+
+// Benchmark with setup
+func BenchmarkMapOperations(b *testing.B) {
+    m := make(map[string]int)
+    for i := 0; i < 1000; i++ {
+        m[fmt.Sprintf("key%d", i)] = i
+    }
+
+    b.ResetTimer() // Don't count setup time
+
+    for i := 0; i < b.N; i++ {
+        _ = m["key500"]
+    }
+}
+
+// Parallel benchmark
+func BenchmarkConcurrentAccess(b *testing.B) {
+    var counter int64
+
+    b.RunParallel(func(pb *testing.PB) {
+        for pb.Next() {
+            atomic.AddInt64(&counter, 1)
+        }
+    })
+}
+
+// Memory allocation benchmark
+func BenchmarkAllocation(b *testing.B) {
+    b.ReportAllocs() // Report allocations
+
+    for i := 0; i < b.N; i++ {
+        s := make([]int, 1000)
+        _ = s
+    }
+}
+```
+
+## Fuzzing (Go 1.18+)
+
+```go
+func FuzzReverse(f *testing.F) {
+    // Seed corpus
+    testcases := []string{"hello", "world", "123", ""}
+    for _, tc := range testcases {
+        f.Add(tc)
+    }
+
+    f.Fuzz(func(t *testing.T, input string) {
+        reversed := Reverse(input)
+        doubleReversed := Reverse(reversed)
+
+        if input != doubleReversed {
+            t.Errorf("Reverse(Reverse(%q)) = %q, want %q", input, doubleReversed, input)
+        }
+    })
+}
+
+// Fuzz with multiple parameters
+func FuzzAdd(f *testing.F) {
+    f.Add(1, 2)
+    f.Add(0, 0)
+    f.Add(-1, 1)
+
+    f.Fuzz(func(t *testing.T, a, b int) {
+        result := Add(a, b)
+
+        // Properties that should always hold
+        if result < a && b >= 0 {
+            t.Errorf("Add(%d, %d) = %d; result should be >= a when b >= 0", a, b, result)
+        }
+    })
+}
+```
+
+## Test Coverage
+
+```go
+// Run tests with coverage:
+// go test -cover
+// go test -coverprofile=coverage.out
+// go tool cover -html=coverage.out
+
+func TestCalculate(t *testing.T) {
+    tests := []struct {
+        name     string
+        input    int
+        expected int
+    }{
+        {"zero", 0, 0},
+        {"positive", 5, 25},
+        {"negative", -3, 9},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Calculate(tt.input)
+            if result != tt.expected {
+                t.Errorf("Calculate(%d) = %d; want %d", tt.input, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+## Race Detector
+
+```go
+// Run with: go test -race
+
+func TestConcurrentAccess(t *testing.T) {
+    var counter int
+    var wg sync.WaitGroup
+
+    // This will fail with -race if not synchronized
+    for i := 0; i < 10; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            counter++ // Data race!
+        }()
+    }
+
+    wg.Wait()
+}
+
+// Fixed version with mutex
+func TestConcurrentAccessSafe(t *testing.T) {
+    var counter int
+    var mu sync.Mutex
+    var wg sync.WaitGroup
+
+    for i := 0; i < 10; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            mu.Lock()
+            counter++
+            mu.Unlock()
+        }()
+    }
+
+    wg.Wait()
+
+    if counter != 10 {
+        t.Errorf("expected 10, got %d", counter)
+    }
+}
+```
+
+## Golden Files
+
+```go
+import (
+    "os"
+    "path/filepath"
+    "testing"
+)
+
+func TestRenderHTML(t *testing.T) {
+    data := Data{Title: "Test", Content: "Hello"}
+    result := RenderHTML(data)
+
+    goldenFile := filepath.Join("testdata", "expected.html")
+
+    if *update {
+        // Update golden file: go test -update
+        os.WriteFile(goldenFile, []byte(result), 0644)
+    }
+
+    expected, err := os.ReadFile(goldenFile)
+    if err != nil {
+        t.Fatalf("failed to read golden file: %v", err)
+    }
+
+    if result != string(expected) {
+        t.Errorf("output doesn't match golden file\ngot:\n%s\nwant:\n%s", result, expected)
+    }
+}
+
+var update = flag.Bool("update", false, "update golden files")
+```
+
+## Integration Tests
+
+```go
+// integration_test.go
+// +build integration
+
+package myapp
+
+import (
+    "testing"
+    "time"
+)
+
+func TestIntegration(t *testing.T) {
+    if testing.Short() {
+        t.Skip("skipping integration test in short mode")
+    }
+
+    // Long-running integration test
+    server := startTestServer(t)
+    defer server.Stop()
+
+    time.Sleep(100 * time.Millisecond) // Wait for server
+
+    client := NewClient(server.URL)
+    resp, err := client.Get("/health")
+    if err != nil {
+        t.Fatalf("health check failed: %v", err)
+    }
+
+    if resp.Status != "ok" {
+        t.Errorf("expected status ok, got %s", resp.Status)
+    }
+}
+
+// Run: go test -tags=integration
+// Run short tests only: go test -short
+```
+
+## Testable Examples
+
+```go
+// Example tests that appear in godoc
+func ExampleAdd() {
+    result := Add(2, 3)
+    fmt.Println(result)
+    // Output: 5
+}
+
+func ExampleAdd_negative() {
+    result := Add(-2, -3)
+    fmt.Println(result)
+    // Output: -5
+}
+
+// Unordered output
+func ExampleKeys() {
+    m := map[string]int{"a": 1, "b": 2, "c": 3}
+    keys := Keys(m)
+    for _, k := range keys {
+        fmt.Println(k)
+    }
+    // Unordered output:
+    // a
+    // b
+    // c
+}
+```
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `go test` | Run tests |
+| `go test -v` | Verbose output |
+| `go test -run TestName` | Run specific test |
+| `go test -bench .` | Run benchmarks |
+| `go test -cover` | Show coverage |
+| `go test -race` | Run race detector |
+| `go test -short` | Skip long tests |
+| `go test -fuzz FuzzName` | Run fuzzing |
+| `go test -cpuprofile cpu.prof` | CPU profiling |
+| `go test -memprofile mem.prof` | Memory profiling |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/gorouter-restoration/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: "gorouter-restoration"
+displayName: "GoRouter & State Restoration"
+description: "GoRouter guard patterns, deep links, redirect safety, tab preservation, and restoration best practices"
+keywords:
+  [
+    "gorouter",
+    "routing",
+    "navigation",
+    "guards",
+    "deep links",
+    "state restoration",
+    "statefulshellroute",
+  ]
+---
+
+# GoRouter & State Restoration
+
+## Overview
+
+Use this skill for safe routing architecture with GoRouter.
+Focus: guard correctness, redirect loop prevention, deep-link safety, shell navigation preservation, and restoration.
+
+## When to Use
+
+- Adding/modifying routes
+- Implementing authentication/authorization guards
+- Handling deep links
+- Preserving tab stacks with `StatefulShellRoute`
+- Fixing redirect loops or bad back-stack behavior
+
+## Core Rules
+
+1. Keep `onEnter`/`redirect` pure and fast (no async side effects).
+2. Avoid redirect loops by checking current matched location.
+3. Use `redirectLimit` intentionally for complex guard trees.
+4. Preserve user intent with `from=` query on auth redirects.
+5. Prefer IDs/path params over large objects in `extra`.
+
+## Guard Execution Model
+
+- `onEnter` runs first.
+- If allowed, top-level `redirect` runs.
+- Route-level `GoRoute.redirect` runs last.
+
+Design guards so each stage is deterministic and idempotent.
+
+## Quick Reference
+
+### Safe redirect logic
+
+```dart
+String? redirectLogic({
+  required bool isAuthenticated,
+  required bool activationDone,
+  required String matchedLocation,
+}) {
+  final isLogin = matchedLocation == '/login';
+  final isActivation = matchedLocation == '/activation';
+
+  if (!activationDone && !isActivation) return '/activation';
+  if (activationDone && !isAuthenticated && !isLogin) {
+    return '/login?from=${Uri.encodeComponent(matchedLocation)}';
+  }
+  if (isAuthenticated && (isLogin || isActivation)) return '/home';
+
+  return null;
+}
+```
+
+### Tab/state preservation
+
+```dart
+StatefulShellRoute.indexedStack(
+  branches: [
+    StatefulShellBranch(navigatorKey: _homeKey, routes: [...]),
+    StatefulShellBranch(navigatorKey: _salesKey, routes: [...]),
+    StatefulShellBranch(navigatorKey: _settingsKey, routes: [...]),
+  ],
+  builder: (context, state, shell) => AppShell(shell: shell),
+)
+```
+
+### Restoration
+
+```dart
+final router = GoRouter(
+  restorationScopeId: 'router',
+  routes: [...],
+);
+
+MaterialApp.router(
+  restorationScopeId: 'app',
+  routerConfig: router,
+)
+```
+
+## Routing Checklist
+
+- Routes use constants and typed parameter extraction.
+- Guards do not mutate app state.
+- Redirect logic handles both anonymous and authenticated states.
+- Deep links are validated for invalid/missing IDs.
+- Logout clears sensitive stack/history as intended.
+- Tab branch stacks remain independent.
+
+## Output Format
+
+1. Route plan (paths, params, names)
+2. Guard plan (stage, conditions, outcomes)
+3. Restoration plan (what is preserved)
+4. Edge cases (deep links, logout, back-nav)
+5. Tests (guard behavior, tab preservation, invalid params)
+
+## Steering Files
+
+| File | Load when |
+| --- | --- |
+| `references/guard_patterns.md` | Designing guard logic, redirect rules, or anti-loop checks. |
+| `references/tab_preservation.md` | Preserving `StatefulShellRoute` branches and restoration state. |
+
+## Templates
+
+| File | Load when |
+| --- | --- |
+| `templates/guard_redirect.md` | Starting a redirect/guard function skeleton. |
+| `templates/stateful_shell_skeleton.md` | Starting a shell/tab restoration scaffold. |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/gorouter-restoration/references/guard_patterns.md

@@ -0,0 +1,37 @@
+# Guard patterns (safe redirects)
+
+## Hard rules
+
+- Keep guard logic synchronous, pure, and deterministic.
+- Do not trigger side effects in `onEnter`/`redirect`.
+- Ensure guards are idempotent for repeated router reevaluation.
+- Always protect against redirect loops.
+
+## Evaluation order
+
+1. `onEnter`
+2. Top-level `GoRouter.redirect`
+3. Route-level `GoRoute.redirect`
+
+Each stage should either:
+- return `null` (allow), or
+- return one stable target path.
+
+## Baseline decision set
+
+- If activation is incomplete, redirect to activation route (allow activation route).
+- If unauthenticated on protected route, redirect to login with `from=` query.
+- If authenticated user visits login/activation, redirect to app home.
+- If maintenance mode is enabled, redirect to maintenance except allowlisted routes.
+
+## Loop prevention checks
+
+- Compare target against current `matchedLocation` before redirecting.
+- Keep route allowlists explicit.
+- Set and monitor `redirectLimit` for complex chains.
+
+## Deep-link safety
+
+- Preserve original destination via encoded `from`.
+- Validate required params (path/query) before entering protected detail routes.
+- Redirect invalid params to a safe fallback (`/not-found` or list route).

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/gorouter-restoration/references/tab_preservation.md

@@ -0,0 +1,26 @@
+# Tab preservation & state restoration
+
+## Recommended architecture
+
+- Use `StatefulShellRoute.indexedStack` for bottom tabs.
+- Give each branch its own `navigatorKey`.
+- Keep shell widget stable so tab switch does not rebuild branch roots.
+
+## What to preserve
+
+- active tab index,
+- each tab's navigation stack,
+- long lists scroll position where needed,
+- in-progress form drafts when required.
+
+## Restoration guidance
+
+- Enable app restoration via both `GoRouter(restorationScopeId: 'router', ...)` and `MaterialApp.router(restorationScopeId: 'app', ...)`.
+- Use `RestorationMixin` for page-local restorable state.
+- Keep critical unsaved drafts in explicit state (provider/local DB) instead of only widget memory.
+
+## Anti-patterns
+
+- Single navigator for all tabs when independent stacks are required.
+- Recreating shell/router on every auth or theme change.
+- Storing heavy objects in route extras when ID lookup is sufficient.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/gorouter-restoration/steering/guard_patterns.md

@@ -0,0 +1,37 @@
+# Guard patterns (safe redirects)
+
+## Hard rules
+
+- Keep guard logic synchronous, pure, and deterministic.
+- Do not trigger side effects in `onEnter`/`redirect`.
+- Ensure guards are idempotent for repeated router reevaluation.
+- Always protect against redirect loops.
+
+## Evaluation order
+
+1. `onEnter`
+2. Top-level `GoRouter.redirect`
+3. Route-level `GoRoute.redirect`
+
+Each stage should either:
+- return `null` (allow), or
+- return one stable target path.
+
+## Baseline decision set
+
+- If activation is incomplete, redirect to activation route (allow activation route).
+- If unauthenticated on protected route, redirect to login with `from=` query.
+- If authenticated user visits login/activation, redirect to app home.
+- If maintenance mode is enabled, redirect to maintenance except allowlisted routes.
+
+## Loop prevention checks
+
+- Compare target against current `matchedLocation` before redirecting.
+- Keep route allowlists explicit.
+- Set and monitor `redirectLimit` for complex chains.
+
+## Deep-link safety
+
+- Preserve original destination via encoded `from`.
+- Validate required params (path/query) before entering protected detail routes.
+- Redirect invalid params to a safe fallback (`/not-found` or list route).

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/gorouter-restoration/steering/tab_preservation.md

@@ -0,0 +1,26 @@
+# Tab preservation & state restoration
+
+## Recommended architecture
+
+- Use `StatefulShellRoute.indexedStack` for bottom tabs.
+- Give each branch its own `navigatorKey`.
+- Keep shell widget stable so tab switch does not rebuild branch roots.
+
+## What to preserve
+
+- active tab index,
+- each tab's navigation stack,
+- long lists scroll position where needed,
+- in-progress form drafts when required.
+
+## Restoration guidance
+
+- Enable app restoration via both `GoRouter(restorationScopeId: 'router', ...)` and `MaterialApp.router(restorationScopeId: 'app', ...)`.
+- Use `RestorationMixin` for page-local restorable state.
+- Keep critical unsaved drafts in explicit state (provider/local DB) instead of only widget memory.
+
+## Anti-patterns
+
+- Single navigator for all tabs when independent stacks are required.
+- Recreating shell/router on every auth or theme change.
+- Storing heavy objects in route extras when ID lookup is sufficient.