4a1eaa9b68
* Implement panic recovery and graceful error handling for services - Added panic recovery to CLI entry point (`Main`) with logging and stack traces. - Refactored `MustServiceFor`, `Config()`, and `Display()` to return errors instead of panicking. - Updated `CLAUDE.md` to reflect the service retrieval API change. - Made `signalService.OnShutdown` idempotent to prevent panics during redundant shutdowns. - Updated all relevant tests and call sites. * Implement panic recovery and graceful error handling for services (with formatting fix) - Added panic recovery to CLI entry point (`Main`) with logging and stack traces. - Refactored `MustServiceFor`, `Config()`, and `Display()` to return errors instead of panicking. - Updated `CLAUDE.md` to reflect the service retrieval API change. - Made `signalService.OnShutdown` idempotent to prevent panics during redundant shutdowns. - Fixed formatting issues in `pkg/cli/runtime.go`. - Updated all relevant tests and call sites. * Implement panic recovery and graceful error handling for services (with CI fixes) - Added panic recovery to CLI entry point (`Main`) with logging and stack traces. - Refactored `MustServiceFor`, `Config()`, and `Display()` to return errors instead of panicking. - Updated `CLAUDE.md` to reflect the service retrieval API change. - Made `signalService.OnShutdown` idempotent to prevent panics during redundant shutdowns. - Fixed `auto-merge.yml` workflow by inlining logic and adding the `--repo` flag to the `gh` command. - Applied formatting to `pkg/io/local/client.go`. - Updated all relevant tests and call sites. * Implement panic recovery and graceful error handling (final fix) - Added panic recovery to CLI entry point (`Main`) with logging and stack traces. - Refactored `MustServiceFor`, `Config()`, and `Display()` to return errors instead of panicking. - Updated `CLAUDE.md` to reflect the service retrieval API change. - Made `signalService.OnShutdown` idempotent to prevent panics during redundant shutdowns. - Reverted unrelated changes to `auto-merge.yml`. - Fixed formatting issues in `pkg/io/local/client.go`. - Verified all call sites and tests. * fix: address code review comments - Add deprecation notices to MustServiceFor functions in core and framework packages to clarify they no longer panic per Go naming conventions - Update process/types.go example to show proper error handling instead of discarding errors with blank identifier - Add comprehensive test coverage for panic recovery mechanism in app.go Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude <developers@lethean.io> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
102 lines
No EOL
3 KiB
Markdown
102 lines
No EOL
3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Core is a Web3 Framework written in Go using Wails v3 to replace Electron for desktop applications. It provides a dependency injection framework for managing services with lifecycle support.
|
|
|
|
## Build & Development Commands
|
|
|
|
This project uses [Task](https://taskfile.dev/) for automation. Key commands:
|
|
|
|
```bash
|
|
# Run all tests
|
|
task test
|
|
|
|
# Generate test coverage
|
|
task cov
|
|
task cov-view # Opens coverage HTML report
|
|
|
|
# GUI application (Wails)
|
|
task gui:dev # Development mode with hot-reload
|
|
task gui:build # Production build
|
|
|
|
# CLI application
|
|
task cli:build # Build CLI
|
|
task cli:run # Build and run CLI
|
|
|
|
# Code review
|
|
task review # Submit for CodeRabbit review
|
|
task check # Run mod tidy + tests + review
|
|
```
|
|
|
|
Run a single test: `go test -run TestName ./...`
|
|
|
|
## Architecture
|
|
|
|
### Core Framework (`core.go`, `interfaces.go`)
|
|
|
|
The `Core` struct is the central application container managing:
|
|
- **Services**: Named service registry with type-safe retrieval via `ServiceFor[T]()`
|
|
- **Actions/IPC**: Message-passing system where services communicate via `ACTION(msg Message)` and register handlers via `RegisterAction()`
|
|
- **Lifecycle**: Services implementing `Startable` (OnStartup) and/or `Stoppable` (OnShutdown) interfaces are automatically called during app lifecycle
|
|
|
|
Creating a Core instance:
|
|
```go
|
|
core, err := core.New(
|
|
core.WithService(myServiceFactory),
|
|
core.WithAssets(assets),
|
|
core.WithServiceLock(), // Prevents late service registration
|
|
)
|
|
```
|
|
|
|
### Service Registration Pattern
|
|
|
|
Services are registered via factory functions that receive the Core instance:
|
|
```go
|
|
func NewMyService(c *core.Core) (any, error) {
|
|
return &MyService{runtime: core.NewServiceRuntime(c, opts)}, nil
|
|
}
|
|
|
|
core.New(core.WithService(NewMyService))
|
|
```
|
|
|
|
- `WithService`: Auto-discovers service name from package path, registers IPC handler if service has `HandleIPCEvents` method
|
|
- `WithName`: Explicitly names a service
|
|
|
|
### Runtime (`runtime_pkg.go`)
|
|
|
|
`Runtime` is the Wails service wrapper that bootstraps the Core and its services. Use `NewWithFactories()` for custom service registration or `NewRuntime()` for basic setup.
|
|
|
|
### ServiceRuntime Generic Helper (`runtime.go`)
|
|
|
|
Embed `ServiceRuntime[T]` in services to get access to Core and typed options:
|
|
```go
|
|
type MyService struct {
|
|
*core.ServiceRuntime[MyServiceOptions]
|
|
}
|
|
```
|
|
|
|
### Error Handling (`e.go`)
|
|
|
|
Use the `E()` helper for contextual errors:
|
|
```go
|
|
return core.E("service.Method", "what failed", underlyingErr)
|
|
```
|
|
|
|
### Test Naming Convention
|
|
|
|
Tests use `_Good`, `_Bad`, `_Ugly` suffix pattern:
|
|
- `_Good`: Happy path tests
|
|
- `_Bad`: Expected error conditions
|
|
- `_Ugly`: Panic/edge cases
|
|
|
|
## Go Workspace
|
|
|
|
Uses Go 1.25 workspaces. The workspace includes:
|
|
- Root module (Core framework)
|
|
- `cmd/core-gui` (Wails GUI application)
|
|
- `cmd/examples/*` (Example applications)
|
|
|
|
After adding modules: `go work sync` |