Merge pull request #8 from thedotmack/coderabbitai/docstrings/07f347a

📝 Add docstrings to `copilot/fix-6`

Author: thedotmack

claudia-server/examples/javascript/client.js

@@ -177,7 +177,16 @@ class ClaudiaClient {
 }
 
 /**
- * Example usage
+ * Example entrypoint demonstrating end-to-end usage of ClaudiaClient.
+ *
+ * Performs a health check against the Claudia server, starts a Claude session
+ * for the current working directory, connects to the server WebSocket to stream
+ * real-time responses, and installs a SIGINT handler for graceful shutdown.
+ *
+ * This is an example/demo helper — it performs network I/O, logs status to stdout,
+ * and exits the process on error or when the user interrupts (Ctrl+C).
+ *
+ * @returns {Promise<void>} Resolves when the setup completes; the process may continue running to receive streamed responses.
  */
 async function example() {
   const client = new ClaudiaClient();

claudia-server/examples/python/client.py

@@ -21,23 +21,60 @@
 
 class ClaudiaClient:
     def __init__(self, server_url: str = None):
+        """
+        Initialize a ClaudiaClient.
+        
+        If server_url is not provided, reads CLAUDIA_SERVER_URL from the environment and defaults to "http://localhost:3000".
+        Derives the WebSocket URL by replacing the HTTP scheme with "ws" and appending "/ws", and initializes session and websocket attributes.
+        
+        Parameters:
+            server_url (str, optional): Base URL of the Claudia Server (e.g. "http://localhost:3000"). If omitted, the
+                CLAUDIA_SERVER_URL environment variable is used; if that is unset, "http://localhost:3000" is used.
+        """
         self.server_url = server_url or os.environ.get('CLAUDIA_SERVER_URL', 'http://localhost:3000')
         self.ws_url = self.server_url.replace('http', 'ws') + '/ws'
         self.session = None
         self.websocket = None
 
     async def __aenter__(self):
+        """
+        Enter async context: create an aiohttp ClientSession and return the client instance.
+        
+        Initializes and stores an aiohttp.ClientSession on self.session for use by other methods. Returns self so the class can be used as an asynchronous context manager.
+        """
         self.session = aiohttp.ClientSession()
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """
+        Close the client's HTTP session and WebSocket when exiting the async context manager.
+        
+        If an HTTP session or WebSocket is open, they are closed asynchronously. The method does not suppress exceptions raised in the managed block (it returns None).
+        """
         if self.session:
             await self.session.close()
         if self.websocket:
             await self.websocket.close()
 
     async def start_session(self, project_path: str, prompt: str, model: str = 'claude-3-5-sonnet-20241022') -> str:
-        """Start a new Claude session"""
+        """
+        Start a new Claude session on the configured Claudia Server.
+        
+        Sends a POST to /api/claude/execute with the project path, prompt, and model.
+        On success returns the created session's ID. On non-200 responses raises an
+        Exception with the server-provided error message.
+        
+        Parameters:
+            project_path (str): Filesystem path of the project to run the prompt against.
+            prompt (str): The text prompt to send to Claude.
+            model (str): Model identifier to use for the session (defaults to 'claude-3-5-sonnet-20241022').
+        
+        Returns:
+            str: The newly created session_id.
+        
+        Raises:
+            Exception: If the server responds with a non-200 status; message includes server error.
+        """
         url = f"{self.server_url}/api/claude/execute"
         data = {
             'project_path': project_path,
@@ -54,7 +91,13 @@ async def start_session(self, project_path: str, prompt: str, model: str = 'clau
             return result['data']['session_id']
 
     async def connect_websocket(self, session_id: str):
-        """Connect to WebSocket and subscribe to session"""
+        """
+        Establish a WebSocket connection to the server, subscribe to a session, and stream incoming messages to the message handler.
+        
+        Opens a connection to self.ws_url and stores the WebSocket in self.websocket, sends a JSON subscribe message for the given session, then iterates over incoming text messages, parsing each as JSON and delegating to self.handle_message. JSON parsing errors and handler exceptions are caught and logged; connection errors from establishing the WebSocket may propagate.
+        Parameters:
+            session_id (str): The server session identifier to subscribe to.
+        """
         self.websocket = await websockets.connect(self.ws_url)
         print("📡 Connected to WebSocket")
 
@@ -76,7 +119,18 @@ async def connect_websocket(self, session_id: str):
                 print(f"Error handling message: {e}")
 
     async def handle_message(self, message: dict):
-        """Handle incoming WebSocket messages"""
+        """
+        Dispatch and process a single incoming WebSocket message from the server.
+        
+        Recognizes message types in the `message['type']` field:
+        - "status": prints a short status line from `message['data']['status']`.
+        - "claude_stream": forwards `message['data']` to `handle_claude_stream` for streaming output handling.
+        - "error": prints the error text from `message['data']['error']`.
+        - any other value: prints an "unknown message type" notice.
+        
+        Parameters:
+            message (dict): Parsed JSON message with at least a `type` key and a `data` payload whose structure depends on `type`.
+        """
         message_type = message.get('type')
 
         if message_type == 'status':
@@ -89,7 +143,18 @@ async def handle_message(self, message: dict):
             print(f"📩 Unknown message type: {message_type}")
 
     async def handle_claude_stream(self, data: dict):
-        """Handle Claude streaming messages"""
+        """
+        Handle incoming Claude streaming events and render them to stdout.
+        
+        The `data` payload is a dictionary that must include a 'type' field indicating the stream event:
+        - 'start'    : indicates the model has begun producing a response; prints a start notice.
+        - 'partial'  : contains incremental text under 'content'; prints text without a trailing newline to stream output progressively.
+        - 'complete' : signals the end of the response; prints a newline and a completion notice.
+        - 'error'    : contains an error message under 'content'; prints the error with a leading newline.
+        - other      : prints the provided 'content' (or the full payload) as a generic Claude output.
+        
+        This function has no return value; it side-effects by printing to stdout.
+        """
         stream_type = data.get('type')
 
         if stream_type == 'start':
@@ -107,7 +172,15 @@ async def handle_claude_stream(self, data: dict):
             print(f"\\n📝 Claude output: {data.get('content', data)}")
 
     async def get_running_sessions(self) -> list:
-        """Get list of running sessions"""
+        """
+        Return the list of currently running Claude sessions.
+        
+        Returns:
+            list: Session objects parsed from the server response `data` field.
+        
+        Raises:
+            Exception: If the server responds with a non-200 status; message is taken from the server's `error` field.
+        """
         url = f"{self.server_url}/api/claude/sessions/running"
 
         async with self.session.get(url) as response:
@@ -119,7 +192,20 @@ async def get_running_sessions(self) -> list:
             return result['data']
 
     async def cancel_session(self, session_id: str) -> bool:
-        """Cancel a session"""
+        """
+        Cancel a running Claude session on the server.
+        
+        Sends a POST request to /api/claude/cancel/{session_id} and returns whether the session was successfully cancelled.
+        
+        Parameters:
+            session_id (str): The server-side identifier of the session to cancel.
+        
+        Returns:
+            bool: True if the server reports the session was cancelled, False otherwise.
+        
+        Raises:
+            Exception: If the HTTP response status is not 200; the exception message contains the server-provided error.
+        """
         url = f"{self.server_url}/api/claude/cancel/{session_id}"
 
         async with self.session.post(url) as response:
@@ -131,7 +217,17 @@ async def cancel_session(self, session_id: str) -> bool:
             return result['data']['cancelled']
 
     async def check_health(self) -> dict:
-        """Check server health"""
+        """
+        Check the Claudia Server health status.
+        
+        Performs a GET request to the server's /api/status/health endpoint and returns the parsed JSON health payload on success.
+        
+        Returns:
+            dict: The JSON response body describing server health.
+        
+        Raises:
+            Exception: If the server responds with a non-200 status code.
+        """
         url = f"{self.server_url}/api/status/health"
 
         async with self.session.get(url) as response:
@@ -141,7 +237,18 @@ async def check_health(self) -> dict:
             return await response.json()
 
 async def example():
-    """Example usage"""
+    """
+    Run a self-contained example demonstrating ClaudiaClient usage.
+    
+    This coroutine exercises the end-to-end flow against a Claudia Server:
+    - Opens a ClaudiaClient session context.
+    - Verifies server health.
+    - Uses the current working directory as the project path.
+    - Starts a Claude session with a sample prompt and model, printing the returned session ID.
+    - Connects to the server WebSocket to stream real-time responses until interrupted.
+    
+    Handles KeyboardInterrupt by printing a shutdown message; on other exceptions it prints the error and exits the process with code 1.
+    """
     async with ClaudiaClient() as client:
         try:
             # Check if server is healthy
@@ -174,6 +281,13 @@ async def example():
 if __name__ == "__main__":
     # Handle graceful shutdown
     def signal_handler(sig, frame):
+        """
+        Handle an OS signal by printing a shutdown message and exiting the process with status code 0.
+        
+        Parameters:
+            sig: Signal number received.
+            frame: Current stack frame (unused).
+        """
         print("\\n🛑 Shutting down...")
         sys.exit(0)
 

claudia-server/src/index.ts

@@ -4,7 +4,24 @@ import { ClaudiaServer } from './server.js';
 import type { ServerConfig } from './types/index.js';
 
 /**
- * Parse command line arguments
+ * Parse command-line arguments into a partial ServerConfig.
+ *
+ * Recognized options:
+ * - `--port`, `-p <number>` — sets `port`
+ * - `--host`, `-h <host>` — sets `host`
+ * - `--claude-binary <path>` — sets `claude_binary_path`
+ * - `--claude-home <path>` — sets `claude_home_dir`
+ * - `--help` — prints help and exits (0)
+ * - `--version` — prints the version and exits (0)
+ *
+ * Options that take a value expect the value as the next argument and will
+ * ignore values that start with `-`. Unknown options beginning with `-`
+ * result in an error message and exit(1).
+ *
+ * Note: this function may call `process.exit()` as a side effect for help,
+ * version, or unrecognized option handling.
+ *
+ * @returns A Partial<ServerConfig> populated with any recognized CLI options.
  */
 function parseArgs(): Partial<ServerConfig> {
   const args = process.argv.slice(2);
@@ -61,7 +78,10 @@ function parseArgs(): Partial<ServerConfig> {
 }
 
 /**
- * Print help information
+ * Print the command-line help/usage information for the Claudia Server CLI.
+ *
+ * Outputs usage, supported options, examples, relevant environment variables,
+ * and available API endpoints to the process standard output.
  */
 function printHelp(): void {
   console.log(`
@@ -106,7 +126,14 @@ For more information, visit: https://github.com/getAsterisk/claudia
 }
 
 /**
- * Main function
+ * Start the Claudia server using CLI arguments and environment variables.
+ *
+ * Parses command-line options, merges them with environment variables to construct a partial ServerConfig,
+ * instantiates and starts a ClaudiaServer, and logs the effective runtime configuration (port, host,
+ * CORS origins, max concurrent sessions, and optionally Claude binary/home paths). On startup failure
+ * the function logs the error and exits the process with code 1.
+ *
+ * @returns A promise that resolves when the server has started.
  */
 async function main(): Promise<void> {
   try {

claudia-server/src/routes/claude.ts

@@ -9,6 +9,23 @@ import type {
   ErrorResponse
 } from '../types/index.js';
 
+/**
+ * Creates an Express Router with endpoints for managing and interacting with Claude code executions.
+ *
+ * The router exposes these routes:
+ * - GET  /version                        — check Claude code version/installation status
+ * - POST /execute                        — start a new Claude execution (requires project_path, prompt, model)
+ * - POST /continue                       — continue an existing conversation (requires project_path, prompt, model)
+ * - POST /resume                         — resume a session (requires project_path, session_id, prompt, model)
+ * - POST /cancel/:sessionId              — cancel a running execution
+ * - GET  /sessions/running               — list running Claude sessions
+ * - GET  /sessions/:sessionId            — get session information
+ * - GET  /sessions/:sessionId/history    — load session history/output
+ *
+ * All endpoints return a standardized SuccessResponse or ErrorResponse object with a timestamp and appropriate HTTP status codes for validation, not-found, and internal errors.
+ *
+ * @returns An Express Router configured with the Claude-related routes.
+ */
 export function createClaudeRoutes(
   claudeService: ClaudeService,
   projectService: ProjectService

claudia-server/src/routes/projects.ts

@@ -2,6 +2,19 @@ import { Router } from 'express';
 import type { ProjectService } from '../services/project.js';
 import type { SuccessResponse, ErrorResponse } from '../types/index.js';
 
+/**
+ * Create an Express Router exposing project-related HTTP endpoints.
+ *
+ * The returned router is configured with routes for listing and creating projects,
+ * retrieving project sessions, finding and reading/saving `CLAUDE.md` files, and
+ * listing directory contents. Handlers delegate data operations to the provided
+ * ProjectService and respond with a consistent SuccessResponse or ErrorResponse
+ * shape that includes a timestamp. Validation failures return 400, missing
+ * resources return 404 where appropriate, and unexpected errors return 500 with
+ * route-specific error codes.
+ *
+ * @returns An Express Router wired with project management and CLAUDE file endpoints.
+ */
 export function createProjectRoutes(projectService: ProjectService): Router {
   const router = Router();
 

claudia-server/src/routes/status.ts

@@ -3,6 +3,16 @@ import type { SuccessResponse } from '../types/index.js';
 import { homedir } from 'os';
 import { join } from 'path';
 
+/**
+ * Create an Express Router with status-related endpoints.
+ *
+ * Exposes three GET endpoints:
+ * - GET /health: returns runtime health data (status, uptime, memory usage, Node version) and a timestamp.
+ * - GET /info: returns server metadata (name, version, description) and runtime/environment details (node version, platform, architecture, pid, cwd, claude_home) with a timestamp.
+ * - GET /home: returns the current user's home directory and the server's Claude-specific directory path with a timestamp.
+ *
+ * @returns An Express Router configured with the above endpoints.
+ */
 export function createStatusRoutes(): Router {
   const router = Router();