Merge pull request #131 from copilot-community-sdk/copilot/create-cookbooks-dotnet-go

Add cookbook with 5 practical recipes for common SDK usage patterns

Author: brunoborges

.github/workflows/publish-maven.yml

@@ -116,8 +116,13 @@ jobs:
                   # Update version in jbang-example.java
                   sed -i "s|copilot-sdk:[0-9]*\.[0-9]*\.[0-9]*|copilot-sdk:${VERSION}|g" jbang-example.java
                   
+                  # Update version in cookbook files (Maven will filter ${project.version} during site generation,
+                  # but we also need the actual version for direct JBang usage)
+                  find src/site/markdown/cookbook -name "*.md" -type f -exec \
+                    sed -i "s|\${project.version}|${VERSION}|g" {} \;
+                  
                   # Commit the documentation changes before release:prepare (requires clean working directory)
-                  git add CHANGELOG.md README.md jbang-example.java
+                  git add CHANGELOG.md README.md jbang-example.java src/site/markdown/cookbook/
                   git commit -m "docs: update version references to ${VERSION}"
                   
                   # Save the commit SHA for potential rollback

CHANGELOG.md

@@ -12,6 +12,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+#### Cookbook with Practical Recipes
+
+Added a comprehensive cookbook with 5 practical recipes demonstrating common SDK usage patterns. All examples are JBang-compatible and can be run directly without a full Maven project setup.
+
+**Recipes:**
+- **Error Handling** - Connection failures, timeouts, cleanup patterns, tool errors
+- **Multiple Sessions** - Parallel conversations, custom session IDs, lifecycle management  
+- **Managing Local Files** - AI-powered file organization with grouping strategies
+- **PR Visualization** - Interactive CLI tool for analyzing PR age distribution via GitHub MCP Server
+- **Persisting Sessions** - Save and resume conversations across restarts
+
+**Location:** `src/site/markdown/cookbook/`
+
+**Usage:**
+```bash
+jbang BasicErrorHandling.java
+jbang MultipleSessions.java
+jbang PRVisualization.java github/copilot-sdk
+```
+
+Each recipe includes JBang prerequisites, usage instructions, and best practices.
+
 #### Session Context and Filtering
 
 Added session context tracking and filtering capabilities to help manage multiple Copilot sessions across different repositories and working directories.

README.md

@@ -105,6 +105,7 @@ jbang https://github.com/copilot-community-sdk/copilot-sdk-java/blob/latest/jban
 - [Getting Started](https://copilot-community-sdk.github.io/copilot-sdk-java/documentation.html)
 - [Javadoc API Reference](https://copilot-community-sdk.github.io/copilot-sdk-java/apidocs/)
 - [MCP Servers Integration](https://copilot-community-sdk.github.io/copilot-sdk-java/mcp.html)
+- [Cookbook](src/site/markdown/cookbook/) — Practical recipes for common use cases
 
 ## Projects Using This SDK
 

src/site/markdown/cookbook/README.md

@@ -0,0 +1,38 @@
+# GitHub Copilot SDK Cookbook — Java
+
+This folder hosts short, practical recipes for using the GitHub Copilot SDK with Java. Each recipe is concise, copy‑pasteable, and points to fuller examples and tests.
+
+## Prerequisites
+
+All cookbook examples can be run directly using [JBang](https://www.jbang.dev/), which allows you to run Java code without a full project setup.
+
+**Install JBang:**
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+For other installation methods, see the [JBang installation guide](https://www.jbang.dev/download/).
+
+## Recipes
+
+- [Error Handling](error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](persisting-sessions.md): Save and resume sessions across restarts.
+
+## Contributing
+
+Add a new recipe by creating a markdown file in this folder and linking it above. Follow repository guidance in the [main README](https://github.com/github/copilot-sdk-java#contributing).
+
+## Status
+
+These recipes are complete, practical examples and can be used directly or adapted for your own projects.

src/site/markdown/cookbook/error-handling.md

@@ -0,0 +1,278 @@
+# Error Handling Patterns
+
+Handle errors gracefully in your Copilot SDK applications.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run these examples:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You need to handle various error conditions like connection failures, timeouts, and invalid responses.
+
+## Basic error handling
+
+**Usage:**
+```bash
+jbang BasicErrorHandling.java
+```
+
+**Code:**
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+public class BasicErrorHandling {
+    public static void main(String[] args) {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setModel("gpt-5")).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Hello!")).get();
+
+            session.close();
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Handling specific error types
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.concurrent.ExecutionException;
+
+public class SpecificErrorHandling {
+    public static void startClient() {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            // ... use client ...
+        } catch (ExecutionException ex) {
+            Throwable cause = ex.getCause();
+            if (cause instanceof java.io.IOException) {
+                System.err.println("Copilot CLI not found. Please install it first.");
+                System.err.println("Details: " + cause.getMessage());
+            } else if (cause instanceof java.util.concurrent.TimeoutException) {
+                System.err.println("Could not connect to Copilot CLI server.");
+                System.err.println("Details: " + cause.getMessage());
+            } else {
+                System.err.println("Unexpected error: " + cause.getMessage());
+                cause.printStackTrace();
+            }
+        } catch (InterruptedException ex) {
+            Thread.currentThread().interrupt();
+            System.err.println("Operation interrupted: " + ex.getMessage());
+        } catch (Exception ex) {
+            System.err.println("Unexpected error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Timeout handling
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+public class TimeoutHandling {
+    public static void sendWithTimeout(CopilotSession session) {
+        try {
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            // Wait up to 30 seconds for response
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Complex question..."))
+                .get(30, TimeUnit.SECONDS);
+
+        } catch (TimeoutException ex) {
+            System.err.println("Request timed out");
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+        }
+    }
+}
+```
+
+## Aborting a request
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+public class AbortRequest {
+    public static void abortAfterDelay(CopilotSession session) {
+        // Start a request (non-blocking)
+        session.send(new MessageOptions()
+            .setPrompt("Write a very long story..."));
+
+        // Schedule abort after 5 seconds
+        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
+        scheduler.schedule(() -> {
+            try {
+                session.abort().get();
+                System.out.println("Request aborted");
+            } catch (Exception ex) {
+                System.err.println("Failed to abort: " + ex.getMessage());
+            } finally {
+                scheduler.shutdown();
+            }
+        }, 5, TimeUnit.SECONDS);
+    }
+}
+```
+
+## Graceful shutdown
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+public class GracefulShutdown {
+    public static void main(String[] args) {
+        var client = new CopilotClient();
+
+        // Set up shutdown hook
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            System.out.println("\nShutting down...");
+            try {
+                client.close();
+            } catch (Exception ex) {
+                System.err.println("Error during shutdown: " + ex.getMessage());
+            }
+        }));
+
+        try {
+            client.start().get();
+            // ... do work ...
+        } catch (Exception ex) {
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Try-with-resources pattern
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+public class TryWithResources {
+    public static void doWork() throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            try (var session = client.createSession(
+                    new SessionConfig().setModel("gpt-5")).get()) {
+
+                session.on(AssistantMessageEvent.class, msg -> {
+                    System.out.println(msg.getData().getContent());
+                });
+
+                session.sendAndWait(new MessageOptions()
+                    .setPrompt("Hello!")).get();
+
+                // Session and client are automatically closed
+            }
+        }
+    }
+}
+```
+
+## Handling tool errors
+
+```java
+//DEPS io.github.copilot-community-sdk:copilot-sdk:${project.version}
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.Map;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+public class ToolErrorHandling {
+    public static void handleToolErrors() throws Exception {
+        var errorTool = ToolDefinition.create(
+            "get_user_location",
+            "Gets the user's location",
+            Map.of("type", "object", "properties", Map.of()),
+            invocation -> {
+                // Return an error result
+                return CompletableFuture.completedFuture(
+                    ToolResultObject.error("Location service unavailable")
+                );
+            }
+        );
+
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setTools(List.of(errorTool))).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            // Session continues even when tool fails
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("What is my location? If you can't find out, just say 'unknown'."))
+                .get();
+
+            session.close();
+        }
+    }
+}
+```
+
+## Best practices
+
+1. **Always clean up**: Use try-with-resources to ensure `close()` is called
+2. **Handle connection errors**: The CLI might not be installed or running
+3. **Set appropriate timeouts**: Use `get(timeout, TimeUnit)` for long-running requests
+4. **Log errors**: Capture error details for debugging
+5. **Wrap operations**: Consider wrapping SDK operations in methods that handle common errors
+6. **Check error causes**: Use `ExecutionException.getCause()` to get the actual error from `CompletableFuture`