goadesign · raphael · Aug 13, 2025 · Aug 13, 2025 · Aug 13, 2025 · Aug 13, 2025
diff --git a/.cursorrules b/.cursorrules
@@ -0,0 +1,16 @@
+# Goa repository rules for Cursor
+
+- Never edit generated code. Fix the generator/templates instead.
+- Prefer any over interface{} in new code.
+- Transports: HTTP, gRPC, and JSON-RPC 2.0 (HTTP, SSE, WebSocket). JSON-RPC supports batch and notifications; streaming over WS/SSE.
+- Testing:
+  - Run unit tests with `make test`.
+  - JSON-RPC integration tests live in `jsonrpc/integration_tests`; run with `make integration-test` (skips on Windows).
+  - Golden tests use testify; update with `go test -update` or `-u`.
+- Code style:
+  - Small, focused files; one main construct per file when possible.
+  - Public types first, then private types, public constants, private constants, public vars, private vars, public functions/methods, then private.
+  - Use `maps.Copy`/`slices.Contains`, `http.NoBody`, avoid shadowing builtins.
+- Architecture quick map:
+  - `dsl/` (design DSL), `expr/` (expressions), `codegen/` (generation engine & templates), `cmd/goa/` (CLI), `http/`, `grpc/`, `jsonrpc/` (transports), `pkg/`, `middleware/`, `security/`, `eval/`.
+- For deeper guidance, see `CLAUDE.md`.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,7 +2,6 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-<<<<<<< HEAD
 ## About This Project
 
 Goa is a design-first API framework for Go that generates production-ready code
@@ -32,7 +31,7 @@ interfaces, client code, transport adapters, and documentation automatically.
 The Goa project favors short-ish files (ideally no more than 2,000 lines of code
 per file).  Each file should encapsulate one main construct and potentially
 smaller satellite constructs used by the main construct. A construct may consist
-of a strut, an interface and related factory functions and methods.
+of a struct, an interface and related factory functions and methods.
 
 Each file should be organized as follows:
 
@@ -82,6 +81,11 @@ Do not put markers between these sections, this is solely for organization.
   - Client and server stub generation
   - Streaming support
 
+- **`jsonrpc/`** - JSON‑RPC 2.0 transport implementation
+  - HTTP transport with batch requests and notifications
+  - Streaming over WebSocket and Server‑Sent Events (SSE)
+  - Client/server/CLI code generation and helpers in the `jsonrpc` package
+
 ### Supporting Packages
 - **`pkg/`** - Core runtime utilities (endpoint, error handling, validation)
 - **`middleware/`** - Common middleware implementations
@@ -109,6 +113,8 @@ The codebase uses extensive testing:
 - **DSL Testing** - Test files often contain example DSL definitions in `testdata/*_dsls.go`
 - **Cross-Package Testing** - Tests verify integration between DSL, expressions, and code generation
 - **Protocol Buffer Testing** - Special protoc-based tests for gRPC functionality
+ - JSON‑RPC integration tests live under `jsonrpc/integration_tests`; run with
+   `make integration-test` (Linux/macOS; skipped on Windows)
 
 ## Development Workflow
 
@@ -117,6 +123,8 @@ The codebase uses extensive testing:
 3. Run `make test` to verify all tests pass
 4. For template changes, verify golden files are updated correctly
 5. Test with real examples using `goa gen` and `goa example` commands
+6. Never edit generated code; fix the generators/templates instead
+7. Prefer `any` (Go 1.18+) over `interface{}` in new code
 
 ## Branch Naming Conventions
 
@@ -155,137 +163,3 @@ will include whatever change was made to its source code.
 NOTE2: The `goa gen` command will wipe out the `gen` folder but the
 `goa example` command will NOT override pre-existing files (the `cmd` folder and
 the top level service files).
-=======
-## Project Overview
-
-Goa is a design-first framework for building APIs and microservices in Go. It uses a Domain Specific Language (DSL) to define APIs, then generates production-ready code, documentation, and client libraries automatically.
-
-Key value proposition: Instead of writing boilerplate code, developers express their API's intent through a clear DSL, and Goa generates 30-50% of the codebase while ensuring perfect alignment between design, code, and documentation.
-
-## Essential Commands
-
-### Building and Testing
-```bash
-# Install dependencies and setup tooling
-make depend
-
-# Run linter and tests (default target)
-make all
-
-# Run linter only
-make lint
-
-# Run tests with coverage
-make test
-# or directly:
-go test ./... --coverprofile=cover.out
-
-# Build the goa command
-go install ./cmd/goa
-```
-
-### Code Generation Workflow
-```bash
-# Generate service interfaces, endpoints, and transport code from design
-# Takes the design Go package path as argument (NOT the file path)
-goa gen DESIGN_PACKAGE
-# For example
-goa gen goa.design/examples/basic/design
-
-# Generate example server and client implementations
-goa example DESIGN_PACKAGE
-
-# Common flags
-goa gen -o OUTPUT_DIR DESIGN_PACKAGE    # Specify output directory
-goa gen -debug DESIGN_PACKAGE           # Leave temporary files around for debugging
-```
-
-## Code Architecture
-
-### High-Level Structure
-
-**DSL → Expression Tree → Code Generation Pipeline → Generated Files**
-
-The framework follows a clean four-phase architecture:
-
-1. **DSL Phase**: Developers write declarative API designs using Goa's DSL
-2. **Expression Building**: DSL functions create an expression tree stored in a global Root
-3. **Evaluation Pipeline**: Four-phase execution (Prepare → Validate → Finalize → Generate)
-4. **Code Generation**: Specialized generators transform expressions into Go code using templates
-
-### Key Packages and Responsibilities
-
-**`/cmd/goa/`** - Main CLI command
-- `main.go` - Command parsing with three subcommands: `gen`, `example`, `version`
-- `gen.go` - Dynamic generator creation: builds temporary Go program, compiles it, runs it
-
-**`/dsl/`** - Domain Specific Language implementation
-- Defines all DSL functions: `API()`, `Service()`, `Method()`, `Type()`, `HTTP()`, `GRPC()`, etc.
-- Creates expression structs when DSL functions execute
-- Uses dot imports for clean design syntax: `import . "goa.design/goa/v3/dsl"`
-
-**`/eval/`** - DSL execution engine
-- Four-phase execution: Parse → Prepare → Validate → Finalize
-- Error reporting and context management
-- Orchestrates expression evaluation
-
-**`/expr/`** - Expression data structures  
-- All expression types: `APIExpr`, `ServiceExpr`, `MethodExpr`, `HTTPEndpointExpr`, etc.
-- `Root` expression holds entire design tree
-- Type system: primitives, arrays, maps, objects, user types
-
-**`/codegen/`** - Code generation infrastructure
-- `File` and `SectionTemplate` structures for organizing generated code
-- Template rendering with Go code formatting
-- Plugin system for extending generation
-- `/generator/` - Core generators (Service, Transport, OpenAPI, Example)
-- `/service/` - Service-specific code generation (interfaces, endpoints, clients)
-
-**Transport Packages** - Protocol-specific implementations
-- `/http/` - HTTP/REST transport with middleware, routing, encoding
-- `/grpc/` - gRPC transport with protobuf generation  
-- `/jsonrpc/` - JSON-RPC transport (work in progress)
-
-### Code Generation Flow
-
-1. **Dynamic Compilation**: Goa creates temporary Go program importing design + codegen libraries
-2. **Expression Tree**: DSL execution builds complete API expression tree in memory
-3. **Multi-Phase Processing**: Expressions are prepared, validated, and finalized
-4. **Specialized Generators**: Different generators handle services, transports, documentation
-5. **Template Rendering**: Go templates generate actual source code files
-6. **File Writing**: Generated code written to disk with proper formatting
-
-### Design Patterns
-
-**Expression-Based Architecture**: Everything is an expression that implements `Preparer`, `Validator`, `Finalizer` interfaces
-
-**Template-Driven Generation**: All code generated through Go templates in `/templates/` directories
-
-**Transport Abstraction**: Single DSL generates multiple transport implementations (HTTP + gRPC)
-
-**Plugin Architecture**: Extensible through pre/post generation plugins
-
-**Clean Separation**: Business logic stays separate from transport concerns
-
-### Testing Approach
-
-- Extensive golden file testing in `/testdata/` directories
-- DSL definitions in `*_dsls.go` files for test scenarios  
-- Generated code compared against `.golden` files
-- Coverage testing with `go test ./... --coverprofile=cover.out`
-- Use `make` to run both linting and tests
-
-## Thinking Approach
-
-- Be judicious, remember why you are doing what you are doing
-- Do not go for the quick fix / cheat
-
-### Goa Specific
-
-- Always fix the code generator - never edit generated code
-- Note: "goa example" does not override existing files - it only creates files that don't exist
-
-## Tools
-
-Take advantage of the Go language server MCP (mcp-gopls)
->>>>>>> b15f1721 (Add JSON-RPC SSE support and integration tests)
diff --git a/README.md b/README.md
@@ -11,40 +11,15 @@
     <a href="https://goreportcard.com/report/github.com/goadesign/goa"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/goadesign/goa?style=for-the-badge"></a>
     <a href="/LICENSE"><img alt="Software License" src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge"></a>
     <a href="https://gurubase.io/g/goa"><img alt="Gurubase" src="https://img.shields.io/badge/Gurubase-Ask%20Goa%20Guru-006BFF?style=for-the-badge"></a>
+    <a href="https://chat.openai.com/g/g-mLuQDGyro-goa-design-wizard"><img alt="Goa Design Wizard" src="https://img.shields.io/badge/Goa%20Design%20Wizard-ChatGPT-00A67D?logo=openai&logoColor=white&style=for-the-badge"></a>
     </br>
-    <a href="https://gophers.slack.com/messages/goa"><img alt="Slack: Goa" src="https://img.shields.io/badge/Goa-gray.svg?longCache=true&logo=slack&colorB=red&style=for-the-badge"></a>
-    <a href="https://invite.slack.golangbridge.org/"><img alt="Slack: Sign-up" src="https://img.shields.io/badge/Signup-gray.svg?longCache=true&logo=slack&colorB=red&style=for-the-badge"></a>
-    <a href="https://bsky.app/profile/goadesign.bsky.social"><img alt="BSky: Goa" src="https://img.shields.io/badge/Bluesky-0285FF?longCache=true&logo=bluesky&logoColor=fff&style=for-the-badge"></a>
+    <a href="https://goadesign.substack.com/subscribe?params=%5Bobject%20Object%5D"><img alt="Substack: Design First" src="https://img.shields.io/badge/Design%20First-Substack-FF6719?logo=substack&logoColor=white&style=for-the-badge"></a>
+    <a href="https://gophers.slack.com/messages/goa"><img alt="Slack: Goa" src="https://img.shields.io/badge/Goa-Slack-4A154B?logo=slack&logoColor=white&style=for-the-badge"></a>
+    <a href="https://bsky.app/profile/goadesign.bsky.social"><img alt="Bluesky: Goa Design" src="https://img.shields.io/badge/Goa%20Design-Bluesky-0285FF?logo=bluesky&logoColor=white&style=for-the-badge"></a>
   </p>
 </p>
 
-<div align="center">
-<table border="0" cellspacing="0" cellpadding="0">
-    <tr>
-        <td align="center" width="200">
-            <a href="https://chat.openai.com/g/g-mLuQDGyro-goa-design-wizard">
-                <img src="docs/Wizard.png" alt="Wizard Logo" style="width: 100%; height: auto;"/>
-            </a>
-        </td>
-        <td align="center">
-            <div>
-            <h1>Goa Design Wizard</h1>
-            </div>
-            <p>
-            Use the <a href="https://chat.openai.com/g/g-mLuQDGyro-goa-design-wizard">Goa Design Wizard</a> to:
-            </p>
-            <ul>
-                <li>Create Goa designs in seconds</li>
-                <li>Review existing designs</li>
-                <li>Explore the Goa DSL</li>
-            </ul>
-            <p>
-            (requires a <a href="https://openai.com/blog/chatgpt-plus">ChatGPT Plus</a> subscription)<br/><br/>
-            </p>
-        </td>
-    </tr>
-</table>
-</div>
+<!-- Removed card; Wizard is now a badge button above -->
 
 # Goa - Design First, Code With Confidence
 
@@ -243,6 +218,7 @@ The [examples repository](https://github.com/goadesign/examples) contains comple
 - Follow us on [Bluesky](https://goadesign.bsky.social)
 - Report issues on [GitHub](https://github.com/goadesign/goa/issues)
 - Find answers with the [Goa Guru](https://gurubase.io/g/goa) AI assistant
+- Subscribe to our Substack, “Design First”: [Design First](https://goadesign.substack.com/subscribe?params=%5Bobject%20Object%5D)
 
 ## What's New