core/cli
8
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions 1

refactor: move plans to tasks/, framework docs to core-gui

Browse source 
- plans/ → tasks/plans/ (planning documents)
- framework/ → core-gui/docs/framework/ (GUI framework docs)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 15:01:46 +00:00
parent 8601e5b355
commit 77a7237d71
31 changed files with 0 additions and 3529 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
docs/framework/architecture.md
View file

@ -1,134 +0,0 @@
# Architecture
Core follows a modular, service-based architecture designed for maintainability and testability.
## Overview
```
┌─────────────────────────────────────────────────────────┐
│ Wails Application │
├─────────────────────────────────────────────────────────┤
│ Core │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Display │ │ WebView │ │ MCP │ │ Config │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Crypt │ │ I18n │ │ IO │ │Workspace │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────┤
│ Plugin System │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Plugin A │ │ Plugin B │ │ Plugin C │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────┘
```
## Core Container
The `Core` struct is the central service container:
```go
type Core struct {
services map[string]any // Service registry
actions []ActionHandler // IPC handlers
Features *Features // Feature flags
servicesLocked bool // Prevent late registration
}
```
### Service Registration
Services are registered using factory functions:
```go
core.New(
core.WithService(display.NewService), // Auto-discovered name
core.WithName("custom", myFactory), // Explicit name
)
```
### Service Retrieval
Type-safe service retrieval:
```go
// Returns error if not found
svc, err := core.ServiceFor[*display.Service](c, "display")
// Panics if not found (use in init code)
svc := core.MustServiceFor[*display.Service](c, "display")
```
## Service Lifecycle
Services can implement lifecycle interfaces:
```go
// Called when app starts
type Startable interface {
OnStartup(ctx context.Context) error
}
// Called when app shuts down
type Stoppable interface {
OnShutdown(ctx context.Context) error
}
```
## IPC / Actions
Services communicate via the action system:
```go
// Register a handler
c.RegisterAction(func(c *core.Core, msg core.Message) error {
if msg.Type == "my-action" {
// Handle message
}
return nil
})
// Send a message
c.ACTION(core.Message{
Type: "my-action",
Data: map[string]any{"key": "value"},
})
```
## Frontend Bindings
Wails generates TypeScript bindings automatically:
```typescript
// Auto-generated from Go service
import { ShowNotification } from '@bindings/display/service';
await ShowNotification({
title: "Hello",
message: "From TypeScript!"
});
```
## Package Structure
```
pkg/
├── core/ # Core container and interfaces
├── display/ # Window, tray, dialogs, clipboard
├── webview/ # JS execution, DOM, screenshots
├── mcp/ # Model Context Protocol server
├── config/ # Configuration persistence
├── crypt/ # Encryption and signing
├── i18n/ # Internationalization
├── io/ # File system helpers
├── workspace/ # Project management
├── plugin/ # Plugin system
└── module/ # Module system
```
## Design Principles
1. **Dependency Injection**: Services receive dependencies via constructor
2. **Interface Segregation**: Small, focused interfaces
3. **Testability**: All services are mockable
4. **No Globals**: State contained in Core instance

122
docs/framework/config.md
View file

@ -1,122 +0,0 @@
# Config Service
The Config service (`pkg/config`) provides unified configuration management with automatic persistence, feature flags, and XDG-compliant directory paths.
## Features
- JSON configuration with auto-save
- Feature flag management
- XDG Base Directory support
- Struct serialization helpers
- Type-safe get/set operations
## Basic Usage
```go
import "github.com/Snider/Core/pkg/config"
// Standalone usage
cfg, err := config.New()
if err != nil {
log.Fatal(err)
}
// With Core framework
c, _ := core.New(
core.WithService(config.Register),
)
cfg := core.MustServiceFor[*config.Service](c, "config")
```
## Get & Set Values
```go
// Set a value (auto-saves)
err := cfg.Set("language", "fr")
// Get a value
var lang string
err := cfg.Get("language", &lang)
```
Available configuration keys:
| Key | Type | Description |
|-----|------|-------------|
| `language` | string | UI language code |
| `default_route` | string | Default navigation route |
| `configDir` | string | Config files directory |
| `dataDir` | string | Data files directory |
| `cacheDir` | string | Cache directory |
| `workspaceDir` | string | Workspaces directory |
## Feature Flags
```go
// Enable a feature
cfg.EnableFeature("dark_mode")
// Check if enabled
if cfg.IsFeatureEnabled("dark_mode") {
// Apply dark theme
}
// Disable a feature
cfg.DisableFeature("dark_mode")
```
## Struct Serialization
Store complex data structures in separate JSON files:
```go
type UserPrefs struct {
Theme string `json:"theme"`
Notifications bool `json:"notifications"`
}
// Save struct to config/user_prefs.json
prefs := UserPrefs{Theme: "dark", Notifications: true}
err := cfg.SaveStruct("user_prefs", prefs)
// Load struct from file
var loaded UserPrefs
err := cfg.LoadStruct("user_prefs", &loaded)
```
## Directory Paths
The service automatically creates XDG-compliant directories:
```go
// Access directory paths
fmt.Println(cfg.ConfigDir) // ~/.config/lethean or ~/lethean/config
fmt.Println(cfg.DataDir) // Data storage
fmt.Println(cfg.CacheDir) // Cache files
fmt.Println(cfg.WorkspaceDir) // User workspaces
```
## Manual Save
Changes are auto-saved, but you can save explicitly:
```go
err := cfg.Save()
```
## Frontend Usage (TypeScript)
```typescript
import { Get, Set, IsFeatureEnabled } from '@bindings/config/service';
// Get configuration
const lang = await Get("language");
// Set configuration
await Set("default_route", "/dashboard");
// Check feature flag
if (await IsFeatureEnabled("dark_mode")) {
applyDarkTheme();
}
```

312
docs/framework/core.md
View file

@ -1,312 +0,0 @@
# Core API Reference
Complete API reference for the Core framework (`pkg/core`).
## Core Struct
The central application container.
### Creation
```go
func New(opts ...Option) (*Core, error)
```
Creates a new Core instance with the specified options.
### Methods
#### Service Access
```go
func ServiceFor[T any](c *Core, name string) (T, error)
```
Retrieves a service by name with type safety.
```go
func MustServiceFor[T any](c *Core, name string) T
```
Retrieves a service by name, panics if not found or wrong type.
#### Actions
```go
func (c *Core) ACTION(msg Message) error
```
Broadcasts a message to all registered action handlers.
```go
func (c *Core) RegisterAction(handler func(*Core, Message) error)
```
Registers an action handler.
#### Service Registration
```go
func (c *Core) AddService(name string, svc any) error
```
Manually adds a service to the registry.
#### Config Access
```go
func (c *Core) Config() *config.Service
```
Returns the config service if registered.
## Options
### WithService
```go
func WithService(factory ServiceFactory) Option
```
Registers a service using its factory function.
```go
c, _ := core.New(
core.WithService(config.Register),
core.WithService(display.NewService),
)
```
### WithName
```go
func WithName(name string, factory ServiceFactory) Option
```
Registers a service with an explicit name.
```go
c, _ := core.New(
core.WithName("mydb", database.NewService),
)
```
### WithAssets
```go
func WithAssets(assets embed.FS) Option
```
Sets embedded assets for the application.
### WithServiceLock
```go
func WithServiceLock() Option
```
Prevents late service registration after initialization.
## ServiceFactory
```go
type ServiceFactory func(c *Core) (any, error)
```
Factory function signature for service creation.
## Message
```go
type Message interface{}
```
Messages can be any type. Common patterns:
```go
// Map-based message
c.ACTION(map[string]any{
"action": "user.created",
"id": "123",
})
// Typed message
type UserCreated struct {
ID string
Email string
}
c.ACTION(UserCreated{ID: "123", Email: "user@example.com"})
```
## ServiceRuntime
Generic helper for services that need Core access.
```go
type ServiceRuntime[T any] struct {
core *Core
options T
}
```
### Creation
```go
func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T]
```
### Methods
```go
func (r *ServiceRuntime[T]) Core() *Core
func (r *ServiceRuntime[T]) Options() T
func (r *ServiceRuntime[T]) Config() *config.Service
```
### Usage
```go
type MyOptions struct {
Timeout time.Duration
}
type MyService struct {
*core.ServiceRuntime[MyOptions]
}
func NewMyService(c *core.Core) (any, error) {
opts := MyOptions{Timeout: 30 * time.Second}
return &MyService{
ServiceRuntime: core.NewServiceRuntime(c, opts),
}, nil
}
func (s *MyService) DoSomething() {
timeout := s.Options().Timeout
cfg := s.Config()
// ...
}
```
## Lifecycle Interfaces
### Startable
```go
type Startable interface {
OnStartup(ctx context.Context) error
}
```
Implement for initialization on app start.
### Stoppable
```go
type Stoppable interface {
OnShutdown(ctx context.Context) error
}
```
Implement for cleanup on app shutdown.
### IPC Handler
```go
type IPCHandler interface {
HandleIPCEvents(c *Core, msg Message) error
}
```
Automatically registered when using `WithService`.
## Built-in Actions
### ActionServiceStartup
```go
type ActionServiceStartup struct{}
```
Sent to all services when application starts.
### ActionServiceShutdown
```go
type ActionServiceShutdown struct{}
```
Sent to all services when application shuts down.
## Error Helpers
```go
func E(service, operation string, err error) error
```
Creates a contextual error with service and operation info.
```go
if err != nil {
return core.E("myservice", "Connect", err)
}
// Error: myservice.Connect: connection refused
```
## Complete Example
```go
package main
import (
"context"
"github.com/Snider/Core/pkg/core"
"github.com/Snider/Core/pkg/config"
)
type MyService struct {
*core.ServiceRuntime[struct{}]
data string
}
func NewMyService(c *core.Core) (any, error) {
return &MyService{
ServiceRuntime: core.NewServiceRuntime(c, struct{}{}),
data: "initialized",
}, nil
}
func (s *MyService) OnStartup(ctx context.Context) error {
// Startup logic
return nil
}
func (s *MyService) OnShutdown(ctx context.Context) error {
// Cleanup logic
return nil
}
func (s *MyService) HandleIPCEvents(c *core.Core, msg core.Message) error {
switch m := msg.(type) {
case map[string]any:
if m["action"] == "myservice.update" {
s.data = m["data"].(string)
}
}
return nil
}
func main() {
c, err := core.New(
core.WithService(config.Register),
core.WithService(NewMyService),
core.WithServiceLock(),
)
if err != nil {
panic(err)
}
svc := core.MustServiceFor[*MyService](c, "main")
_ = svc
}
```

133
docs/framework/crypt.md
View file

@ -1,133 +0,0 @@
# Crypt Service
The Crypt service (`pkg/crypt`) provides cryptographic utilities including hashing, checksums, RSA encryption, and PGP operations.
## Features
- Multiple hash algorithms (SHA512, SHA256, SHA1, MD5)
- Checksum functions (Fletcher, Luhn)
- RSA key generation and encryption
- PGP encryption, signing, and verification
- Symmetric PGP encryption
## Basic Usage
```go
import "github.com/Snider/Core/pkg/crypt"
// Standalone usage
crypto, err := crypt.New()
// With Core framework
c, _ := core.New(
core.WithService(crypt.Register),
)
crypto := core.MustServiceFor[*crypt.Service](c, "crypt")
```
## Hashing
```go
// Available algorithms: SHA512, SHA256, SHA1, MD5, LTHN
hash := crypto.Hash(crypt.SHA256, "hello world")
// Check if string is valid hash algorithm
isValid := crypto.IsHashAlgo("sha256")
```
## Checksums
```go
// Luhn validation (credit card numbers)
isValid := crypto.Luhn("4532015112830366")
// Fletcher checksums
f16 := crypto.Fletcher16("data")
f32 := crypto.Fletcher32("data")
f64 := crypto.Fletcher64("data")
```
## RSA Encryption
```go
// Generate key pair (2048 or 4096 bits recommended)
publicKey, privateKey, err := crypto.GenerateRSAKeyPair(2048)
// Encrypt with public key
ciphertext, err := crypto.EncryptRSA(publicKey, "secret message")
// Decrypt with private key
plaintext, err := crypto.DecryptRSA(privateKey, ciphertext)
```
## PGP Encryption
### Key Generation
```go
// Generate PGP key pair
publicKey, privateKey, err := crypto.GeneratePGPKeyPair(
"User Name",
"user@example.com",
"Key comment",
)
```
### Asymmetric Encryption
```go
// Encrypt for recipient
ciphertext, err := crypto.EncryptPGPToString(recipientPublicKey, "secret data")
// Decrypt with private key
plaintext, err := crypto.DecryptPGP(privateKey, ciphertext)
```
### Symmetric Encryption
```go
var buf bytes.Buffer
err := crypto.SymmetricallyEncryptPGP(&buf, "data", "passphrase")
```
### Signing & Verification
```go
// Sign data
signature, err := crypto.SignPGP(privateKey, "data to sign")
// Verify signature
err := crypto.VerifyPGP(publicKey, "data to sign", signature)
if err != nil {
// Signature invalid
}
```
## Hash Types
| Constant | Algorithm |
|----------|-----------|
| `crypt.SHA512` | SHA-512 |
| `crypt.SHA256` | SHA-256 |
| `crypt.SHA1` | SHA-1 |
| `crypt.MD5` | MD5 |
| `crypt.LTHN` | Custom LTHN hash |
## Frontend Usage (TypeScript)
```typescript
import {
Hash,
GenerateRSAKeyPair,
EncryptRSA,
DecryptRSA
} from '@bindings/crypt/service';
// Hash data
const hash = await Hash("SHA256", "hello world");
// RSA encryption
const { publicKey, privateKey } = await GenerateRSAKeyPair(2048);
const encrypted = await EncryptRSA(publicKey, "secret");
const decrypted = await DecryptRSA(privateKey, encrypted);
```

352
docs/framework/display.md
View file

@ -1,352 +0,0 @@
# Display API Reference
Complete API reference for the Display service (`pkg/display`).
## Service Creation
```go
func NewService(c *core.Core) (any, error)
```
## Window Management
### CreateWindow
```go
func (s *Service) CreateWindow(opts CreateWindowOptions) (*WindowInfo, error)
```
Creates a new window with the specified options.
```go
type CreateWindowOptions struct {
Name string
Title string
URL string
X int
Y int
Width int
Height int
}
```
### CloseWindow
```go
func (s *Service) CloseWindow(name string) error
```
### GetWindowInfo
```go
func (s *Service) GetWindowInfo(name string) (*WindowInfo, error)
```
Returns:
```go
type WindowInfo struct {
Name string
Title string
X int
Y int
Width int
Height int
IsVisible bool
IsFocused bool
IsMaximized bool
IsMinimized bool
}
```
### ListWindowInfos
```go
func (s *Service) ListWindowInfos() []*WindowInfo
```
### Window Position & Size
```go
func (s *Service) SetWindowPosition(name string, x, y int) error
func (s *Service) SetWindowSize(name string, width, height int) error
func (s *Service) SetWindowBounds(name string, x, y, width, height int) error
```
### Window State
```go
func (s *Service) MaximizeWindow(name string) error
func (s *Service) MinimizeWindow(name string) error
func (s *Service) RestoreWindow(name string) error
func (s *Service) FocusWindow(name string) error
func (s *Service) SetWindowFullscreen(name string, fullscreen bool) error
func (s *Service) SetWindowAlwaysOnTop(name string, onTop bool) error
func (s *Service) SetWindowVisibility(name string, visible bool) error
```
### Window Title
```go
func (s *Service) SetWindowTitle(name, title string) error
func (s *Service) GetWindowTitle(name string) (string, error)
```
### Window Background
```go
func (s *Service) SetWindowBackgroundColour(name string, r, g, b, a uint8) error
```
### Focus
```go
func (s *Service) GetFocusedWindow() string
```
## Screen Management
### GetScreens
```go
func (s *Service) GetScreens() []*Screen
```
Returns:
```go
type Screen struct {
ID string
Name string
X int
Y int
Width int
Height int
ScaleFactor float64
IsPrimary bool
}
```
### GetScreen
```go
func (s *Service) GetScreen(id string) (*Screen, error)
```
### GetPrimaryScreen
```go
func (s *Service) GetPrimaryScreen() (*Screen, error)
```
### GetScreenAtPoint
```go
func (s *Service) GetScreenAtPoint(x, y int) (*Screen, error)
```
### GetScreenForWindow
```go
func (s *Service) GetScreenForWindow(name string) (*Screen, error)
```
### GetWorkAreas
```go
func (s *Service) GetWorkAreas() []*WorkArea
```
Returns usable screen space (excluding dock/taskbar).
## Layout Management
### SaveLayout / RestoreLayout
```go
func (s *Service) SaveLayout(name string) error
func (s *Service) RestoreLayout(name string) error
func (s *Service) ListLayouts() []string
func (s *Service) DeleteLayout(name string) error
func (s *Service) GetLayout(name string) *Layout
```
### TileWindows
```go
func (s *Service) TileWindows(mode TileMode, windows []string) error
```
Tile modes:
```go
const (
TileModeLeft TileMode = "left"
TileModeRight TileMode = "right"
TileModeGrid TileMode = "grid"
TileModeQuadrants TileMode = "quadrants"
)
```
### SnapWindow
```go
func (s *Service) SnapWindow(name string, position SnapPosition) error
```
Snap positions:
```go
const (
SnapPositionLeft SnapPosition = "left"
SnapPositionRight SnapPosition = "right"
SnapPositionTop SnapPosition = "top"
SnapPositionBottom SnapPosition = "bottom"
SnapPositionTopLeft SnapPosition = "top-left"
SnapPositionTopRight SnapPosition = "top-right"
SnapPositionBottomLeft SnapPosition = "bottom-left"
SnapPositionBottomRight SnapPosition = "bottom-right"
)
```
### StackWindows
```go
func (s *Service) StackWindows(windows []string, offsetX, offsetY int) error
```
### ApplyWorkflowLayout
```go
func (s *Service) ApplyWorkflowLayout(workflow WorkflowType) error
```
Workflow types:
```go
const (
WorkflowCoding WorkflowType = "coding"
WorkflowDebugging WorkflowType = "debugging"
WorkflowPresenting WorkflowType = "presenting"
)
```
## Dialogs
### File Dialogs
```go
func (s *Service) OpenSingleFileDialog(opts OpenFileOptions) (string, error)
func (s *Service) OpenFileDialog(opts OpenFileOptions) ([]string, error)
func (s *Service) SaveFileDialog(opts SaveFileOptions) (string, error)
func (s *Service) OpenDirectoryDialog(opts OpenDirectoryOptions) (string, error)
```
Options:
```go
type OpenFileOptions struct {
Title string
DefaultDirectory string
AllowMultiple bool
Filters []FileFilter
}
type SaveFileOptions struct {
Title string
DefaultDirectory string
DefaultFilename string
Filters []FileFilter
}
type FileFilter struct {
DisplayName string
Pattern string // e.g., "*.png;*.jpg"
}
```
### ConfirmDialog
```go
func (s *Service) ConfirmDialog(title, message string) (bool, error)
```
### PromptDialog
```go
func (s *Service) PromptDialog(title, message string) (string, bool, error)
```
## System Tray
```go
func (s *Service) SetTrayIcon(icon []byte) error
func (s *Service) SetTrayTooltip(tooltip string) error
func (s *Service) SetTrayLabel(label string) error
func (s *Service) SetTrayMenu(items []TrayMenuItem) error
func (s *Service) GetTrayInfo() map[string]any
```
Menu item:
```go
type TrayMenuItem struct {
Label string
ActionID string
IsSeparator bool
}
```
## Clipboard
```go
func (s *Service) ReadClipboard() (string, error)
func (s *Service) WriteClipboard(text string) error
func (s *Service) HasClipboard() bool
func (s *Service) ClearClipboard() error
```
## Notifications
```go
func (s *Service) ShowNotification(opts NotificationOptions) error
func (s *Service) ShowInfoNotification(title, message string) error
func (s *Service) ShowWarningNotification(title, message string) error
func (s *Service) ShowErrorNotification(title, message string) error
func (s *Service) RequestNotificationPermission() (bool, error)
func (s *Service) CheckNotificationPermission() (bool, error)
```
Options:
```go
type NotificationOptions struct {
ID string
Title string
Message string
Subtitle string
}
```
## Theme
```go
func (s *Service) GetTheme() *Theme
func (s *Service) GetSystemTheme() string
```
Returns:
```go
type Theme struct {
IsDark bool
}
```
## Events
```go
func (s *Service) GetEventManager() *EventManager
```
The EventManager handles WebSocket connections for real-time events.

54
docs/framework/e.md
View file

@ -1,54 +0,0 @@
---
title: e
---
# Service: `e`
Package e provides a standardized error handling mechanism for the Core library.
It allows for wrapping errors with contextual information, making it easier to
trace the origin of an error and provide meaningful feedback.
The design of this package is influenced by the need for a simple, yet powerful
way to handle errors that can occur in different layers of the application,
from low-level file operations to high-level service interactions.
The key features of this package are:
- Error wrapping: The Op and an optional Msg field provide context about
where and why an error occurred.
- Stack traces: By wrapping errors, we can build a logical stack trace
that is more informative than a raw stack trace.
- Consistent error handling: Encourages a uniform approach to error
handling across the entire codebase.
## Types
### `type Error`
`Error` represents a standardized error with operational context.
```go
type Error struct {
// Op is the operation being performed, e.g., "config.Load".
Op string
// Msg is a human-readable message explaining the error.
Msg string
// Err is the underlying error that was wrapped.
Err error
}
```
#### Methods
- `Error() string`: Error returns the string representation of the error.
- `Unwrap() error`: Unwrap provides compatibility for Go's errors.Is and errors.As functions.
## Functions
- `E(op, msg string, err error) error`: E is a helper function to create a new Error.
This is the primary way to create errors that will be consumed by the system. For example:
```go
return e.E("config.Load", "failed to load config file", err)
```
The `op` parameter should be in the format of `package.function` or `service.method`. The `msg` parameter should be a human-readable message that can be displayed to the user. The `err` parameter is the underlying error that is being wrapped.

152
docs/framework/help.md
View file

@ -1,152 +0,0 @@
# Help Service
The Help service (`pkg/help`) provides an embeddable documentation system that displays MkDocs-based help content in a dedicated window.
## Features
- Embedded help content (MkDocs static site)
- Context-sensitive help navigation
- Works with or without Display service
- Multiple content sources (embedded, filesystem, custom)
## Basic Usage
```go
import "github.com/Snider/Core/pkg/help"
// Create with default embedded content
helpService, err := help.New(help.Options{})
// Initialize with core dependencies
helpService.Init(coreInstance, displayService)
```
## Showing Help
```go
// Show main help window
err := helpService.Show()
// Show specific section
err := helpService.ShowAt("getting-started")
err := helpService.ShowAt("api/config")
```
## Options
```go
type Options struct {
Source string // Path to help content directory
Assets fs.FS // Custom filesystem for assets
}
```
### Default Embedded Content
```go
// Uses embedded MkDocs site
helpService, _ := help.New(help.Options{})
```
### Custom Directory
```go
// Use local directory
helpService, _ := help.New(help.Options{
Source: "/path/to/docs/site",
})
```
### Custom Filesystem
```go
//go:embed docs/*
var docsFS embed.FS
helpService, _ := help.New(help.Options{
Assets: docsFS,
})
```
## Integration with Core
The help service can work standalone or integrated with Core:
### With Display Service
When Display service is available, help opens through the IPC action system:
```go
// Automatically uses display.open_window action
helpService.Init(core, displayService)
helpService.Show()
```
### Without Display Service
Falls back to direct Wails window creation:
```go
// Creates window directly via Wails
helpService.Init(core, nil)
helpService.Show()
```
## Lifecycle
```go
// Called on application startup
err := helpService.ServiceStartup(ctx)
```
## Building Help Content
Help content is a static MkDocs site. To update:
1. Edit documentation in `docs/` directory
2. Build with MkDocs:
```bash
mkdocs build
```
3. The built site goes to `pkg/help/public/`
4. Content is embedded at compile time
## Frontend Usage (TypeScript)
```typescript
import { Show, ShowAt } from '@bindings/help/service';
// Open help window
await Show();
// Open specific section
await ShowAt("configuration");
await ShowAt("api/display");
```
## Help Window Options
The help window opens with default settings:
| Property | Value |
|----------|-------|
| Title | "Help" |
| Width | 800px |
| Height | 600px |
## IPC Action
When using Display service, help triggers this action:
```go
{
"action": "display.open_window",
"name": "help",
"options": {
"Title": "Help",
"Width": 800,
"Height": 600,
"URL": "/#anchor", // When using ShowAt
},
}
```

130
docs/framework/i18n.md
View file

@ -1,130 +0,0 @@
# I18n Service
The I18n service (`pkg/i18n`) provides internationalization and localization support with automatic language detection and template-based translations.
## Features
- JSON-based locale files
- Embedded locale bundles
- Automatic language detection from environment
- Template variable interpolation
- BCP 47 language tag support
## Basic Usage
```go
import "github.com/Snider/Core/pkg/i18n"
// Create service (defaults to English)
i18n, err := i18n.New()
if err != nil {
log.Fatal(err)
}
```
## Setting Language
```go
// Set language using BCP 47 tag
err := i18n.SetLanguage("fr")
err := i18n.SetLanguage("en-US")
err := i18n.SetLanguage("zh-Hans")
```
## Translating Messages
```go
// Simple translation
msg := i18n.Translate("welcome_message")
// With template data
msg := i18n.Translate("greeting", map[string]string{
"Name": "John",
})
// Template: "Hello, {{.Name}}!"
// Result: "Hello, John!"
```
## Available Languages
```go
// Get list of available language codes
langs := i18n.AvailableLanguages()
// Returns: ["en", "es", "fr", "de", ...]
```
## Get All Messages
```go
// Get all translations for a language
messages, err := i18n.GetAllMessages("en")
for key, value := range messages {
fmt.Printf("%s: %s\n", key, value)
}
```
## Locale File Format
Locale files are JSON stored in `locales/` directory:
```json
// locales/en.json
{
"welcome": "Welcome to the application",
"greeting": "Hello, {{.Name}}!",
"items_count": {
"one": "{{.Count}} item",
"other": "{{.Count}} items"
}
}
```
## Adding New Languages
1. Create a new JSON file in `pkg/i18n/locales/`:
```
locales/es.json
```
2. Add translations:
```json
{
"welcome": "Bienvenido a la aplicación",
"greeting": "¡Hola, {{.Name}}!"
}
```
3. The service automatically loads embedded locales at startup.
## Language Detection
The service can detect system language from the `LANG` environment variable:
```go
// Automatic detection happens internally
// LANG=fr_FR.UTF-8 -> French
// LANG=de_DE.UTF-8 -> German
```
## Frontend Usage (TypeScript)
```typescript
import {
SetLanguage,
Translate,
AvailableLanguages,
GetAllMessages
} from '@bindings/i18n/service';
// Set language
await SetLanguage("fr");
// Translate
const welcome = await Translate("welcome_message");
// Get available languages for a selector
const languages = await AvailableLanguages();
// Load all messages for client-side caching
const messages = await GetAllMessages("en");
```

76
docs/framework/installation.md
View file

@ -1,76 +0,0 @@
# Installation
## Prerequisites
### Go 1.22+
```bash
# macOS
brew install go
# Linux
sudo apt install golang-go
# Windows - download from https://go.dev/dl/
```
### Wails v3
```bash
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
```
### Task (Build Automation)
```bash
# macOS
brew install go-task
# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
# Windows
choco install go-task
```
## Install Core
```bash
go get github.com/Snider/Core@latest
```
## Verify Installation
```bash
# Check Go
go version
# Check Wails
wails3 version
# Check Task
task --version
```
## IDE Setup
### VS Code
Install the Go extension and configure:
```json
{
"go.useLanguageServer": true,
"gopls": {
"ui.semanticTokens": true
}
}
```
### GoLand / IntelliJ
Go support is built-in. Enable the Wails plugin for additional features.
## Next Steps
Continue to [Quick Start](quickstart.md) to create your first application.

165
docs/framework/io.md
View file

@ -1,165 +0,0 @@
# IO Service
The IO package (`pkg/io`) provides a unified interface for file operations across different storage backends (local filesystem, S3, SFTP, etc.).
## Features
- Abstract `Medium` interface for storage backends
- Local filesystem implementation
- Copy between different mediums
- Mock implementation for testing
## Medium Interface
All storage backends implement the `Medium` interface:
```go
type Medium interface {
Read(path string) (string, error)
Write(path, content string) error
EnsureDir(path string) error
IsFile(path string) bool
FileGet(path string) (string, error)
FileSet(path, content string) error
}
```
## Local Filesystem
```go
import (
"github.com/Snider/Core/pkg/io"
"github.com/Snider/Core/pkg/io/local"
)
// Pre-initialized global medium (root = "/")
content, err := io.Local.Read("/etc/hosts")
// Create sandboxed medium
medium, err := local.New("/app/data")
content, err := medium.Read("config.json") // Reads /app/data/config.json
```
## Basic Operations
```go
// Read file
content, err := medium.Read("path/to/file.txt")
// Write file
err := medium.Write("path/to/file.txt", "content")
// Check if file exists
if medium.IsFile("config.json") {
// File exists
}
// Ensure directory exists
err := medium.EnsureDir("path/to/dir")
// Convenience methods
content, err := medium.FileGet("file.txt")
err := medium.FileSet("file.txt", "content")
```
## Helper Functions
Package-level functions that work with any Medium:
```go
// Read from medium
content, err := io.Read(medium, "file.txt")
// Write to medium
err := io.Write(medium, "file.txt", "content")
// Ensure directory
err := io.EnsureDir(medium, "path/to/dir")
// Check if file
exists := io.IsFile(medium, "file.txt")
```
## Copy Between Mediums
```go
localMedium, _ := local.New("/local/path")
remoteMedium := s3.New(bucket, region) // hypothetical S3 implementation
// Copy from local to remote
err := io.Copy(localMedium, "data.json", remoteMedium, "backup/data.json")
```
## Mock Medium for Testing
```go
import "github.com/Snider/Core/pkg/io"
func TestMyFunction(t *testing.T) {
mock := io.NewMockMedium()
// Pre-populate files
mock.Files["config.json"] = `{"key": "value"}`
mock.Dirs["data"] = true
// Use in tests
myService := NewService(mock)
// Verify writes
err := myService.SaveData("test")
if mock.Files["data/test.json"] != expectedContent {
t.Error("unexpected content")
}
}
```
## Creating Custom Backends
Implement the `Medium` interface for custom storage:
```go
type S3Medium struct {
bucket string
client *s3.Client
}
func (m *S3Medium) Read(path string) (string, error) {
// Implement S3 read
}
func (m *S3Medium) Write(path, content string) error {
// Implement S3 write
}
// ... implement remaining methods
```
## Error Handling
```go
content, err := medium.Read("missing.txt")
if err != nil {
// File not found or read error
log.Printf("Read failed: %v", err)
}
```
## Frontend Usage
The IO package is primarily used server-side. Frontend file operations should use the Display service dialogs or direct API calls:
```typescript
import { OpenFileDialog, SaveFileDialog } from '@bindings/display/service';
// Open file picker
const path = await OpenFileDialog({
title: "Select File",
filters: [{ displayName: "Text", pattern: "*.txt" }]
});
// Save file picker
const savePath = await SaveFileDialog({
title: "Save As",
defaultFilename: "document.txt"
});
```

119
docs/framework/ipc.md
View file

@ -1,119 +0,0 @@
# IPC & Actions
Core provides an inter-process communication system for services to communicate without tight coupling.
## Message Structure
```go
type Message struct {
Type string // Message type identifier
Data map[string]any // Message payload
Source string // Originating service (optional)
Timestamp time.Time // When message was created
}
```
## Sending Messages
```go
c.ACTION(core.Message{
Type: "user.created",
Data: map[string]any{
"id": "123",
"email": "user@example.com",
},
})
```
## Handling Messages
Register action handlers during service initialization:
```go
func NewNotificationService(c *core.Core) (any, error) {
svc := &NotificationService{}
// Register handler
c.RegisterAction(func(c *core.Core, msg core.Message) error {
return svc.handleAction(msg)
})
return svc, nil
}
func (s *NotificationService) handleAction(msg core.Message) error {
switch msg.Type {
case "user.created":
email := msg.Data["email"].(string)
return s.sendWelcomeEmail(email)
}
return nil
}
```
## Auto-Discovery
Services implementing `HandleIPCEvents` are automatically registered:
```go
type MyService struct{}
// Automatically registered when using WithService
func (s *MyService) HandleIPCEvents(c *core.Core, msg core.Message) error {
// Handle messages
return nil
}
```
## Common Patterns
### Request/Response
```go
// Sender
responseChan := make(chan any)
c.ACTION(core.Message{
Type: "data.request",
Data: map[string]any{
"query": "SELECT * FROM users",
"response": responseChan,
},
})
result := <-responseChan
// Handler
func (s *DataService) handleAction(msg core.Message) error {
if msg.Type == "data.request" {
query := msg.Data["query"].(string)
respChan := msg.Data["response"].(chan any)
result, err := s.execute(query)
if err != nil {
return err
}
respChan <- result
}
return nil
}
```
### Event Broadcasting
```go
// Broadcast to all listeners
c.ACTION(core.Message{
Type: "system.config.changed",
Data: map[string]any{
"key": "theme",
"value": "dark",
},
})
```
## Best Practices
1. **Use namespaced types** - `service.action` format
2. **Keep payloads simple** - Use primitive types when possible
3. **Handle errors** - Return errors from handlers
4. **Document message types** - Create constants for message types

101
docs/framework/lifecycle.md
View file

@ -1,101 +0,0 @@
# Service Lifecycle
Core provides lifecycle hooks for services to initialize and clean up resources.
## Lifecycle Interfaces
### Startable
Called when the application starts:
```go
type Startable interface {
OnStartup(ctx context.Context) error
}
```
### Stoppable
Called when the application shuts down:
```go
type Stoppable interface {
OnShutdown(ctx context.Context) error
}
```
## Implementation Example
```go
type DatabaseService struct {
db *sql.DB
}
func (s *DatabaseService) OnStartup(ctx context.Context) error {
db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
if err != nil {
return err
}
// Verify connection
if err := db.PingContext(ctx); err != nil {
return err
}
s.db = db
return nil
}
func (s *DatabaseService) OnShutdown(ctx context.Context) error {
if s.db != nil {
return s.db.Close()
}
return nil
}
```
## Lifecycle Order
1. **Registration**: Services registered via `core.New()`
2. **Wails Binding**: Services bound to Wails app
3. **Startup**: `OnStartup()` called for each Startable service
4. **Running**: Application runs
5. **Shutdown**: `OnShutdown()` called for each Stoppable service
## Context Usage
The context passed to lifecycle methods includes:
- Cancellation signal for graceful shutdown
- Deadline for timeout handling
```go
func (s *Service) OnStartup(ctx context.Context) error {
select {
case <-ctx.Done():
return ctx.Err()
case <-s.initialize():
return nil
}
}
```
## Error Handling
If `OnStartup` returns an error, the application will fail to start:
```go
func (s *Service) OnStartup(ctx context.Context) error {
if err := s.validate(); err != nil {
return fmt.Errorf("validation failed: %w", err)
}
return nil
}
```
## Best Practices
1. **Keep startup fast** - Defer heavy initialization
2. **Handle context cancellation** - Support graceful shutdown
3. **Clean up resources** - Always implement OnShutdown for services with resources
4. **Log lifecycle events** - Helps with debugging

220
docs/framework/mcp-bridge.md
View file

@ -1,220 +0,0 @@
# MCP Bridge
The MCP Bridge (`cmd/core-gui/mcp_bridge.go`) connects the Model Context Protocol server with Display, WebView, and WebSocket services.
## Overview
The MCP Bridge provides an HTTP API for AI assistants to interact with the desktop application, enabling:
- Window and screen management
- JavaScript execution in webviews
- DOM interaction (click, type, select)
- Screenshot capture
- File and process management
- Real-time events via WebSocket
## HTTP Endpoints
| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check |
| `GET /mcp` | Server capabilities |
| `GET /mcp/tools` | List available tools |
| `POST /mcp/call` | Execute a tool |
| `WS /ws` | WebSocket for GUI clients |
| `WS /events` | WebSocket for display events |
## Server Capabilities
```bash
curl http://localhost:9877/mcp
```
Response:
```json
{
"name": "core",
"version": "0.1.0",
"capabilities": {
"webview": true,
"display": true,
"windowControl": true,
"screenControl": true,
"websocket": "ws://localhost:9877/ws",
"events": "ws://localhost:9877/events"
}
}
```
## Tool Categories
### File Operations
| Tool | Description |
|------|-------------|
| `file_read` | Read file contents |
| `file_write` | Write content to file |
| `file_edit` | Edit file by replacing text |
| `file_delete` | Delete a file |
| `file_exists` | Check if file exists |
| `dir_list` | List directory contents |
| `dir_create` | Create directory |
### Window Control
| Tool | Description |
|------|-------------|
| `window_list` | List all windows |
| `window_create` | Create new window |
| `window_close` | Close window |
| `window_position` | Move window |
| `window_size` | Resize window |
| `window_maximize` | Maximize window |
| `window_minimize` | Minimize window |
| `window_focus` | Bring window to front |
### WebView Interaction
| Tool | Description |
|------|-------------|
| `webview_eval` | Execute JavaScript |
| `webview_click` | Click element |
| `webview_type` | Type into element |
| `webview_screenshot` | Capture page |
| `webview_navigate` | Navigate to URL |
| `webview_console` | Get console messages |
### Screen Management
| Tool | Description |
|------|-------------|
| `screen_list` | List all monitors |
| `screen_primary` | Get primary screen |
| `screen_at_point` | Get screen at coordinates |
| `screen_work_areas` | Get usable screen space |
### Layout Management
| Tool | Description |
|------|-------------|
| `layout_save` | Save window arrangement |
| `layout_restore` | Restore saved layout |
| `layout_tile` | Auto-tile windows |
| `layout_snap` | Snap window to edge |
## Calling Tools
```bash
# List windows
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{"tool": "window_list", "params": {}}'
# Move window
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{
"tool": "window_position",
"params": {"name": "main", "x": 100, "y": 100}
}'
# Execute JavaScript
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{
"tool": "webview_eval",
"params": {
"window": "main",
"code": "document.title"
}
}'
# Click element
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{
"tool": "webview_click",
"params": {
"window": "main",
"selector": "#submit-button"
}
}'
# Take screenshot
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{
"tool": "webview_screenshot",
"params": {"window": "main"}
}'
```
## WebSocket Events
Connect to `/events` for real-time display events:
```javascript
const ws = new WebSocket('ws://localhost:9877/events');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
switch (data.type) {
case 'window.focus':
console.log('Window focused:', data.name);
break;
case 'window.move':
console.log('Window moved:', data.name, data.x, data.y);
break;
case 'theme.change':
console.log('Theme changed:', data.isDark);
break;
}
};
```
Event types:
- `window.focus` - Window received focus
- `window.blur` - Window lost focus
- `window.move` - Window position changed
- `window.resize` - Window size changed
- `window.close` - Window was closed
- `window.create` - New window created
- `theme.change` - System theme changed
- `screen.change` - Screen configuration changed
## Go Integration
```go
import "github.com/Snider/Core/cmd/core-gui"
// Create bridge
bridge := NewMCPBridge(9877, displayService)
// Access services
mcpSvc := bridge.GetMCPService()
webview := bridge.GetWebView()
display := bridge.GetDisplay()
```
## Configuration
The bridge starts automatically on Wails app startup via the `ServiceStartup` lifecycle hook:
```go
func (b *MCPBridge) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
b.app = application.Get()
b.webview.SetApp(b.app)
go b.startHTTPServer()
return nil
}
```
## Security
The MCP server binds to localhost only by default. For production:
- Consider firewall rules
- Add authentication if needed
- Limit exposed tools

151
docs/framework/mcp.md
View file

@ -1,151 +0,0 @@
# MCP Service
The MCP service (`pkg/mcp`) implements the [Model Context Protocol](https://modelcontextprotocol.io/), enabling AI assistants like Claude to interact with your application.
## Overview
MCP provides a standardized way for AI tools to:
- Execute operations in your application
- Query application state
- Interact with the UI
- Manage files and processes
## Basic Setup
```go
import "github.com/Snider/Core/pkg/mcp"
// Create standalone MCP server
mcpService := mcp.NewStandaloneWithPort(9877)
// Or integrate with Core
c, _ := core.New(
core.WithService(mcp.NewService),
)
```
## Available Tools
The MCP service exposes numerous tools organized by category:
### File Operations
| Tool | Description |
|------|-------------|
| `file_read` | Read file contents |
| `file_write` | Write content to file |
| `file_edit` | Replace text in file |
| `file_delete` | Delete a file |
| `file_exists` | Check if file exists |
| `dir_list` | List directory contents |
| `dir_create` | Create directory |
### Window Control
| Tool | Description |
|------|-------------|
| `window_list` | List all windows |
| `window_create` | Create new window |
| `window_close` | Close window |
| `window_position` | Move window |
| `window_size` | Resize window |
| `window_maximize` | Maximize window |
| `window_minimize` | Minimize window |
| `window_focus` | Bring to front |
### WebView Interaction
| Tool | Description |
|------|-------------|
| `webview_eval` | Execute JavaScript |
| `webview_click` | Click element |
| `webview_type` | Type into element |
| `webview_screenshot` | Capture page |
| `webview_navigate` | Navigate to URL |
| `webview_console` | Get console logs |
### Process Management
| Tool | Description |
|------|-------------|
| `process_start` | Start a process |
| `process_stop` | Stop a process |
| `process_list` | List running processes |
| `process_output` | Get process output |
## HTTP API
The MCP service exposes an HTTP API:
```bash
# Health check
curl http://localhost:9877/health
# List available tools
curl http://localhost:9877/mcp/tools
# Call a tool
curl -X POST http://localhost:9877/mcp/call \
-H "Content-Type: application/json" \
-d '{"tool": "window_list", "params": {}}'
```
## WebSocket Events
Connect to `/events` for real-time updates:
```javascript
const ws = new WebSocket('ws://localhost:9877/events');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Event:', data.type, data.data);
};
```
## Integration with Display Service
```go
mcpService := mcp.NewStandaloneWithPort(9877)
mcpService.SetDisplay(displayService)
mcpService.SetWebView(webviewService)
```
## Example: Claude Integration
When Claude connects via MCP, it can:
```
User: "Move the settings window to the left side of the screen"
Claude uses: window_position("settings", 0, 100)
```
```
User: "Take a screenshot of the app"
Claude uses: webview_screenshot("main")
```
```
User: "Click the submit button"
Claude uses: webview_click("main", "#submit-btn")
```
## Security Considerations
- MCP server binds to localhost by default
- No authentication (designed for local AI assistants)
- Consider firewall rules for production
## Configuration
```go
// Custom port
mcp.NewStandaloneWithPort(8080)
// With all services
bridge := NewMCPBridge(9877, displayService)
bridge.SetWebView(webviewService)
```

271
docs/framework/modules.md
View file

@ -1,271 +0,0 @@
# Module System
The Module system (`pkg/module`) provides a declarative way to register UI menus, routes, and API endpoints using the `.itw3.json` configuration format.
## Features
- Declarative module configuration
- UI menu contributions
- Frontend route registration
- API endpoint declarations
- Multi-context support (developer, retail, miner)
- Binary/daemon management
- Module dependencies
## Module Config Format
Modules are defined using `.itw3.json` files:
```json
{
"code": "wallet",
"type": "core",
"name": "Wallet Manager",
"version": "1.0.0",
"namespace": "finance",
"description": "Cryptocurrency wallet management",
"author": "Your Name",
"contexts": ["default", "retail"],
"menu": [...],
"routes": [...],
"api": [...],
"config": {...}
}
```
## Module Types
| Type | Description |
|------|-------------|
| `core` | Built-in core functionality |
| `app` | External web application |
| `bin` | Binary/daemon wrapper |
## UI Contexts
Modules can target specific UI contexts:
| Context | Description |
|---------|-------------|
| `default` | Standard user interface |
| `developer` | Developer tools and debugging |
| `retail` | Point-of-sale interface |
| `miner` | Mining operations interface |
## Menu Contributions
Add items to the application menu:
```json
{
"menu": [
{
"id": "wallet-send",
"label": "Send Funds",
"icon": "send",
"route": "/wallet/send",
"accelerator": "CmdOrCtrl+Shift+S",
"contexts": ["default", "retail"],
"order": 10
},
{
"id": "wallet-receive",
"label": "Receive",
"icon": "receive",
"route": "/wallet/receive",
"order": 20
},
{
"separator": true
},
{
"id": "wallet-settings",
"label": "Settings",
"action": "wallet.open_settings",
"children": [
{"id": "wallet-backup", "label": "Backup", "action": "wallet.backup"},
{"id": "wallet-restore", "label": "Restore", "action": "wallet.restore"}
]
}
]
}
```
## Route Contributions
Register frontend routes:
```json
{
"routes": [
{
"path": "/wallet",
"component": "wallet-dashboard",
"title": "Wallet",
"icon": "wallet",
"contexts": ["default"]
},
{
"path": "/wallet/send",
"component": "wallet-send-form",
"title": "Send Funds"
}
]
}
```
## API Declarations
Declare API endpoints the module provides:
```json
{
"api": [
{
"method": "GET",
"path": "/balance",
"description": "Get wallet balance"
},
{
"method": "POST",
"path": "/send",
"description": "Send transaction"
}
]
}
```
## Binary Downloads
For `bin` type modules, specify platform binaries:
```json
{
"downloads": {
"app": "https://example.com/wallet-ui.tar.gz",
"x86_64": {
"darwin": {
"url": "https://example.com/wallet-darwin-x64",
"checksum": "sha256:abc123..."
},
"linux": {
"url": "https://example.com/wallet-linux-x64",
"checksum": "sha256:def456..."
},
"windows": {
"url": "https://example.com/wallet-win-x64.exe",
"checksum": "sha256:ghi789..."
}
},
"aarch64": {
"darwin": {
"url": "https://example.com/wallet-darwin-arm64"
}
}
}
}
```
## Web App Configuration
For `app` type modules:
```json
{
"app": {
"url": "https://example.com/wallet-app.tar.gz",
"type": "spa",
"hooks": [
{
"type": "rename",
"from": "dist",
"to": "wallet"
}
]
}
}
```
## Dependencies
Declare module dependencies:
```json
{
"depends": ["core", "crypto"]
}
```
## Using in Go
### Module Registration
```go
import "github.com/Snider/Core/pkg/module"
// Create from config
cfg := module.Config{
Code: "wallet",
Type: module.TypeCore,
Name: "Wallet",
Namespace: "finance",
}
mod := module.Module{
Config: cfg,
Handler: myHandler,
}
```
### Gin Router Integration
```go
type WalletModule struct{}
func (m *WalletModule) RegisterRoutes(group *gin.RouterGroup) {
group.GET("/balance", m.getBalance)
group.POST("/send", m.sendTransaction)
}
// Register with Gin
router := gin.Default()
apiGroup := router.Group("/api/finance/wallet")
walletModule.RegisterRoutes(apiGroup)
```
## Registry Service
The registry manages all modules:
```go
import "github.com/Snider/Core/pkg/module"
registry := module.NewRegistry()
// Register module
registry.Register(walletModule)
// Get module by code
mod := registry.Get("wallet")
// List all modules
modules := registry.List()
// Get modules for context
devModules := registry.ForContext(module.ContextDeveloper)
```
## Built-in Modules
Core provides several built-in modules:
- System information
- Configuration management
- Process management
- File operations
Access via:
```go
builtins := module.BuiltinModules()
```

175
docs/framework/overview.md
View file

@ -1,175 +0,0 @@
# GUI Application
The Core GUI (`cmd/core-gui`) is a Wails v3 desktop application that demonstrates the Core framework capabilities with integrated MCP support.
## Features
- Angular frontend with Wails bindings
- MCP HTTP server for AI tool integration
- WebView automation capabilities
- Real-time WebSocket communication
- System tray support
- Multi-window management
## Architecture
```
┌─────────────────────────────────────────┐
│ Angular Frontend │
│ (TypeScript + Wails Bindings) │
└─────────────────┬───────────────────────┘
│ IPC
┌─────────────────┴───────────────────────┐
│ Wails Runtime │
│ (Window, Events, Bindings) │
└─────────────────┬───────────────────────┘
│
┌─────────────────┴───────────────────────┐
│ MCP Bridge │
│ ┌─────────┬──────────┬─────────────┐ │
│ │ Display │ WebView │ WebSocket │ │
│ │ Service │ Service │ Hub │ │
│ └─────────┴──────────┴─────────────┘ │
└─────────────────────────────────────────┘
```
## Running the GUI
### Development Mode
```bash
# From project root
task gui:dev
# Or directly
cd cmd/core-gui
wails3 dev
```
### Production Build
```bash
task gui:build
```
## Directory Structure
```
cmd/core-gui/
├── main.go # Application entry point
├── mcp_bridge.go # MCP HTTP server and tool handler
├── claude_bridge.go # Claude MCP client (optional)
├── frontend/ # Angular application
│ ├── src/
│ │ ├── app/ # Angular components
│ │ └── lib/ # Shared utilities
│ └── bindings/ # Generated Wails bindings
└── public/ # Static assets
```
## Services Integrated
The GUI integrates several Core services:
| Service | Purpose |
|---------|---------|
| Display | Window management, dialogs, tray |
| WebView | JavaScript execution, DOM interaction |
| MCP | AI tool protocol server |
| WebSocket | Real-time communication |
## Configuration
The application uses the Config service for settings:
```go
// Default settings
DefaultRoute: "/"
Language: "en"
Features: []
```
## Frontend Bindings
Wails generates TypeScript bindings for Go services:
```typescript
import { CreateWindow, ShowNotification } from '@bindings/display/service';
import { Translate, SetLanguage } from '@bindings/i18n/service';
// Create a new window
await CreateWindow({
name: "settings",
title: "Settings",
width: 800,
height: 600
});
// Show notification
await ShowNotification({
title: "Success",
message: "Operation completed!"
});
```
## WebSocket Communication
Connect to the WebSocket endpoint for real-time updates:
```typescript
const ws = new WebSocket('ws://localhost:9877/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
ws.send(JSON.stringify({
type: 'ping',
data: {}
}));
```
## System Tray
The application includes system tray support:
```go
// Set tray menu
display.SetTrayMenu([]display.TrayMenuItem{
{Label: "Open", ActionID: "open"},
{Label: "Settings", ActionID: "settings"},
{IsSeparator: true},
{Label: "Quit", ActionID: "quit"},
})
```
## Building for Distribution
### macOS
```bash
task gui:build
# Creates: build/bin/core-gui.app
```
### Windows
```bash
task gui:build
# Creates: build/bin/core-gui.exe
```
### Linux
```bash
task gui:build
# Creates: build/bin/core-gui
```
## Environment Variables
| Variable | Description |
|----------|-------------|
| `MCP_PORT` | MCP server port (default: 9877) |
| `DEBUG` | Enable debug logging |

172
docs/framework/plugins.md
View file

@ -1,172 +0,0 @@
# Plugin System
The Plugin system (`pkg/plugin`) allows you to extend Core applications with HTTP-based plugins that register routes under `/api/{namespace}/{name}/`.
## Features
- Namespace-based organization
- HTTP handler registration
- Lifecycle hooks (OnRegister, OnUnregister)
- Wails service integration
## Plugin Interface
All plugins implement the `Plugin` interface:
```go
type Plugin interface {
// Name returns the unique identifier for this plugin
Name() string
// Namespace returns the plugin's namespace (e.g., "core", "mining")
Namespace() string
// ServeHTTP handles HTTP requests routed to this plugin
http.Handler
// OnRegister is called when the plugin is registered
OnRegister(ctx context.Context) error
// OnUnregister is called when the plugin is being removed
OnUnregister(ctx context.Context) error
}
```
## Using BasePlugin
For simple plugins, embed `BasePlugin`:
```go
import "github.com/Snider/Core/pkg/plugin"
func NewMyPlugin() *plugin.BasePlugin {
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello from plugin!"))
})
return plugin.NewBasePlugin("myapp", "greeting", handler).
WithDescription("A simple greeting plugin").
WithVersion("1.0.0")
}
```
## Custom Plugin Implementation
For more control, implement the full interface:
```go
type DataPlugin struct {
db *sql.DB
}
func (p *DataPlugin) Name() string { return "data" }
func (p *DataPlugin) Namespace() string { return "myapp" }
func (p *DataPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/users":
p.handleUsers(w, r)
case "/items":
p.handleItems(w, r)
default:
http.NotFound(w, r)
}
}
func (p *DataPlugin) OnRegister(ctx context.Context) error {
// Initialize database connection
db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
if err != nil {
return err
}
p.db = db
return nil
}
func (p *DataPlugin) OnUnregister(ctx context.Context) error {
if p.db != nil {
return p.db.Close()
}
return nil
}
```
## Plugin Info
Access plugin metadata:
```go
info := myPlugin.Info()
fmt.Println(info.Name) // "greeting"
fmt.Println(info.Namespace) // "myapp"
fmt.Println(info.Description) // "A simple greeting plugin"
fmt.Println(info.Version) // "1.0.0"
```
## Wails Integration
Register plugins as Wails services:
```go
app := application.New(application.Options{
Services: []application.Service{
application.NewServiceWithOptions(
myPlugin,
plugin.ServiceOptionsForPlugin(myPlugin),
),
},
})
```
## URL Routing
Plugins receive requests at:
```
/api/{namespace}/{name}/{path}
```
Examples:
- `/api/myapp/greeting/` → GreetingPlugin
- `/api/myapp/data/users` → DataPlugin (path: "/users")
- `/api/core/system/health` → SystemPlugin (path: "/health")
## Built-in Plugins
### System Plugin
Located at `pkg/plugin/builtin/system`:
```go
// Provides system information endpoints
/api/core/system/info - Application info
/api/core/system/health - Health check
```
## Plugin Router
The Router manages plugin registration:
```go
import "github.com/Snider/Core/pkg/plugin"
router := plugin.NewRouter()
// Register plugins
router.Register(ctx, myPlugin)
router.Register(ctx, dataPlugin)
// Get all registered plugins
plugins := router.List()
// Unregister a plugin
router.Unregister(ctx, "myapp", "greeting")
```
## Best Practices
1. **Use namespaces** to group related plugins
2. **Implement OnRegister** for initialization that can fail
3. **Implement OnUnregister** to clean up resources
4. **Return meaningful errors** from lifecycle hooks
5. **Use standard HTTP patterns** in ServeHTTP

128
docs/framework/quickstart.md
View file

@ -1,128 +0,0 @@
# Quick Start
Build a simple Core application in 5 minutes.
## Create Project
```bash
mkdir myapp && cd myapp
go mod init myapp
```
## Install Dependencies
```bash
go get github.com/Snider/Core@latest
go get github.com/wailsapp/wails/v3@latest
```
## Create Main File
Create `main.go`:
```go
package main
import (
"context"
"embed"
"log"
"github.com/Snider/Core/pkg/core"
"github.com/Snider/Core/pkg/display"
"github.com/wailsapp/wails/v3/pkg/application"
)
//go:embed all:frontend/dist
var assets embed.FS
func main() {
// Initialize Core with display service
c, err := core.New(
core.WithAssets(assets),
core.WithService(display.NewService),
)
if err != nil {
log.Fatal(err)
}
// Get display service for window creation
displaySvc := core.MustServiceFor[*display.Service](c, "display")
// Create Wails application
app := application.New(application.Options{
Name: "My App",
Assets: application.AssetOptions{
FS: assets,
},
})
// Create main window
app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
Title: "My App",
Width: 1200,
Height: 800,
URL: "/",
})
// Register display service with Wails
app.RegisterService(displaySvc)
// Run application
if err := app.Run(); err != nil {
log.Fatal(err)
}
}
```
## Create Frontend
Create a minimal frontend:
```bash
mkdir -p frontend/dist
```
Create `frontend/dist/index.html`:
```html
<!DOCTYPE html>
<html>
<head>
<title>My App</title>
<style>
body {
font-family: system-ui, sans-serif;
display: flex;
justify-content: center;
align-items: center;
height: 100vh;
margin: 0;
background: #1a1a2e;
color: #eee;
}
</style>
</head>
<body>
<h1>Hello from Core!</h1>
</body>
</html>
```
## Run Development Mode
```bash
wails3 dev
```
## Build for Production
```bash
wails3 build
```
## Next Steps
- [Architecture](architecture.md) - Understand how Core works
- [Display Service](../services/display.md) - Window and dialog management
- [MCP Integration](../services/mcp.md) - AI tool support

76
docs/framework/runtime.md
View file

@ -1,76 +0,0 @@
---
title: runtime
---
# Service: `runtime`
The `runtime` service provides the main entry point for the application and a helper structure for services to interact with the `Core`.
## Types
### `type Runtime`
`Runtime` is the top-level container that holds the `Core` instance and the Wails application. It serves as the bridge between Wails and the Core framework.
```go
type Runtime struct {
// Core is the central service manager
Core *Core
// app is the Wails application instance
app *application.App
}
```
### `type ServiceRuntime[T any]`
`ServiceRuntime` is a generic helper struct designed to be embedded in service implementations. It provides easy access to the `Core` and service-specific options.
```go
type ServiceRuntime[T any] struct {
core *Core
opts T
}
```
### `type ServiceFactory`
`ServiceFactory` is a function type that creates a service instance.
```go
type ServiceFactory func() (any, error)
```
## Functions
### `func NewRuntime(app *application.App) (*Runtime, error)`
`NewRuntime` creates and wires together all application services using default settings. It is the standard way to initialize the runtime.
### `func NewWithFactories(app *application.App, factories map[string]ServiceFactory) (*Runtime, error)`
`NewWithFactories` creates a new `Runtime` instance using a provided map of service factories. This allows for flexible, dynamic service registration.
### `func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T]`
`NewServiceRuntime` creates a new `ServiceRuntime` instance. This is typically used in a service's factory or constructor.
## Methods
### `func (r *Runtime) ServiceName() string`
`ServiceName` returns the name of the service ("Core"). This is used by Wails for service identification.
### `func (r *Runtime) ServiceStartup(ctx context.Context, options application.ServiceOptions)`
`ServiceStartup` delegates the startup lifecycle event to the underlying `Core`, which in turn initializes all registered services.
### `func (r *Runtime) ServiceShutdown(ctx context.Context)`
`ServiceShutdown` delegates the shutdown lifecycle event to the underlying `Core`.
### `func (r *ServiceRuntime[T]) Core() *Core`
`Core` returns the central `Core` instance, giving the service access to other services and features.
### `func (r *ServiceRuntime[T]) Config() Config`
`Config` returns the registered `Config` service from the `Core`. It is a convenience method for accessing configuration.

119
docs/framework/services.md
View file

@ -1,119 +0,0 @@
# Services
Services are the building blocks of a Core application. Each service encapsulates a specific domain of functionality.
## Creating a Service
```go
package myservice
import (
"context"
"github.com/Snider/Core/pkg/core"
)
type Service struct {
core *core.Core
}
// Factory function for registration
func NewService(c *core.Core) (any, error) {
return &Service{core: c}, nil
}
// Implement Startable for startup logic
func (s *Service) OnStartup(ctx context.Context) error {
// Initialize resources
return nil
}
// Implement Stoppable for cleanup
func (s *Service) OnShutdown(ctx context.Context) error {
// Release resources
return nil
}
```
## Registering Services
```go
c, err := core.New(
// Auto-discover name from package path
core.WithService(myservice.NewService),
// Explicit name
core.WithName("custom", func(c *core.Core) (any, error) {
return &CustomService{}, nil
}),
)
```
## Retrieving Services
```go
// Safe retrieval with error
svc, err := core.ServiceFor[*myservice.Service](c, "myservice")
if err != nil {
log.Printf("Service not found: %v", err)
}
// Must retrieval (panics if not found)
svc := core.MustServiceFor[*myservice.Service](c, "myservice")
```
## Service Dependencies
Services can depend on other services:
```go
func NewOrderService(c *core.Core) (any, error) {
// Get required dependencies
userSvc := core.MustServiceFor[*user.Service](c, "user")
paymentSvc := core.MustServiceFor[*payment.Service](c, "payment")
return &OrderService{
users: userSvc,
payments: paymentSvc,
}, nil
}
```
!!! warning "Dependency Order"
Register dependencies before services that use them. Core does not automatically resolve dependency order.
## Exposing to Frontend
Services are automatically exposed to the frontend via Wails bindings:
```go
// Go service method
func (s *Service) GetUser(id string) (*User, error) {
return s.db.FindUser(id)
}
```
```typescript
// TypeScript (auto-generated)
import { GetUser } from '@bindings/myservice/service';
const user = await GetUser("123");
```
## Testing Services
```go
func TestMyService(t *testing.T) {
// Create mock core
c, _ := core.New()
// Create service
svc, err := NewService(c)
if err != nil {
t.Fatal(err)
}
// Test methods
result := svc.(*Service).DoSomething()
assert.Equal(t, expected, result)
}
```

215
docs/framework/webview.md
View file

@ -1,215 +0,0 @@
# WebView Service
The WebView service (`pkg/webview`) provides programmatic interaction with web content in your application windows.
## Features
- JavaScript execution
- DOM manipulation
- Element interaction (click, type, select)
- Console message capture
- Screenshots
- Network request monitoring
- Performance metrics
## Basic Usage
```go
import "github.com/Snider/Core/pkg/webview"
// Create service
wv := webview.New()
// Set Wails app reference
wv.SetApp(app)
```
## JavaScript Execution
```go
// Execute JavaScript and get result
result, err := wv.ExecJS("main", `
document.title
`)
// Execute complex scripts
result, err := wv.ExecJS("main", `
const items = document.querySelectorAll('.item');
Array.from(items).map(el => el.textContent);
`)
```
## DOM Interaction
### Click Element
```go
err := wv.Click("main", "#submit-button")
err := wv.Click("main", ".nav-link:first-child")
```
### Type Text
```go
err := wv.Type("main", "#search-input", "hello world")
```
### Select Option
```go
err := wv.Select("main", "#country-select", "US")
```
### Check/Uncheck
```go
err := wv.Check("main", "#agree-checkbox", true)
```
### Hover
```go
err := wv.Hover("main", ".dropdown-trigger")
```
### Scroll
```go
// Scroll to element
err := wv.Scroll("main", "#section-3", 0, 0)
// Scroll by coordinates
err := wv.Scroll("main", "", 0, 500)
```
## Element Information
### Query Selector
```go
elements, err := wv.QuerySelector("main", ".list-item")
```
### Element Info
```go
info, err := wv.GetElementInfo("main", "#user-card")
// Returns: tag, id, classes, text, attributes, bounds
```
### Computed Styles
```go
styles, err := wv.GetComputedStyle("main", ".button",
[]string{"color", "background-color", "font-size"})
```
### DOM Tree
```go
tree, err := wv.GetDOMTree("main", 5) // max depth 5
```
## Console Messages
```go
// Setup console listener
wv.SetupConsoleListener()
// Inject capture script
wv.InjectConsoleCapture("main")
// Get messages
messages := wv.GetConsoleMessages("all", 100)
messages := wv.GetConsoleMessages("error", 50)
// Clear buffer
wv.ClearConsole()
// Get errors only
errors := wv.GetErrors(50)
```
## Screenshots
```go
// Full page screenshot (base64 PNG)
data, err := wv.Screenshot("main")
// Element screenshot
data, err := wv.ScreenshotElement("main", "#chart")
// Export as PDF
pdfData, err := wv.ExportToPDF("main", map[string]any{
"margin": 20,
})
```
## Page Information
```go
// Get current URL
url, err := wv.GetURL("main")
// Get page title
title, err := wv.GetTitle("main")
// Get page source
source, err := wv.GetPageSource("main")
// Navigate
err := wv.Navigate("main", "https://example.com")
```
## Network Monitoring
```go
// Inject network interceptor
wv.InjectNetworkInterceptor("main")
// Get captured requests
requests, err := wv.GetNetworkRequests("main", 100)
// Clear request log
wv.ClearNetworkRequests("main")
```
## Performance Metrics
```go
metrics, err := wv.GetPerformance("main")
// Returns: loadTime, domContentLoaded, firstPaint, etc.
```
## Resource Listing
```go
resources, err := wv.GetResources("main")
// Returns: scripts, stylesheets, images, fonts, etc.
```
## Visual Debugging
```go
// Highlight element temporarily
err := wv.Highlight("main", "#target-element", 2000) // 2 seconds
```
## Window Listing
```go
windows := wv.ListWindows()
for _, w := range windows {
fmt.Println(w.Name)
}
```
## Frontend Usage
The WebView service is primarily used server-side for:
- Automated testing
- AI assistant interactions (via MCP)
- Scripted UI interactions
For normal frontend development, use standard DOM APIs directly.

152
docs/framework/workspace.md
View file

@ -1,152 +0,0 @@
# Workspace Service
The Workspace service (`pkg/workspace`) manages isolated user workspaces with encrypted storage and PGP key pairs.
## Features
- Isolated workspace environments
- PGP key pair generation per workspace
- Encrypted workspace identification
- File operations within workspace context
- Multiple workspace support
## Basic Usage
```go
import "github.com/Snider/Core/pkg/workspace"
// With IO medium (standalone)
medium, _ := local.New("/app/workspaces")
ws, err := workspace.New(medium)
// With Core framework (recommended)
c, _ := core.New(
core.WithService(workspace.Register),
)
ws := core.MustServiceFor[*workspace.Service](c, "workspace")
```
## Creating Workspaces
```go
// Create a new encrypted workspace
workspaceID, err := ws.CreateWorkspace("my-project", "secure-password")
// Returns obfuscated workspace ID
// Workspace structure created:
// workspaces/
// <workspace-id>/
// config/
// log/
// data/
// files/
// keys/
// key.pub (PGP public key)
// key.priv (PGP private key)
```
## Switching Workspaces
```go
// Switch to a workspace
err := ws.SwitchWorkspace(workspaceID)
// Switch to default workspace
err := ws.SwitchWorkspace("default")
```
## Workspace File Operations
```go
// Write file to active workspace
err := ws.WorkspaceFileSet("config/settings.json", jsonData)
// Read file from active workspace
content, err := ws.WorkspaceFileGet("config/settings.json")
```
## Listing Workspaces
```go
// Get all workspace IDs
workspaces := ws.ListWorkspaces()
for _, id := range workspaces {
fmt.Println(id)
}
```
## Active Workspace
```go
// Get current workspace info
active := ws.ActiveWorkspace()
if active != nil {
fmt.Println("Name:", active.Name)
fmt.Println("Path:", active.Path)
}
```
## Workspace Structure
Each workspace contains:
| Directory | Purpose |
|-----------|---------|
| `config/` | Workspace configuration files |
| `log/` | Workspace logs |
| `data/` | Application data |
| `files/` | User files |
| `keys/` | PGP key pair |
## Security Model
Workspaces use a two-level hashing scheme:
1. **Real Name**: Hash of the identifier
2. **Workspace ID**: Hash of `workspace/{real_name}`
This prevents workspace enumeration while allowing consistent access.
## IPC Events
The workspace service responds to IPC messages:
```go
// Switch workspace via IPC
c.ACTION(core.Message{
Type: "workspace.switch_workspace",
Data: map[string]any{
"name": workspaceID,
},
})
```
## Frontend Usage (TypeScript)
```typescript
import {
CreateWorkspace,
SwitchWorkspace,
WorkspaceFileGet,
WorkspaceFileSet,
ListWorkspaces,
ActiveWorkspace
} from '@bindings/workspace/service';
// Create workspace
const wsId = await CreateWorkspace("my-project", "password");
// Switch workspace
await SwitchWorkspace(wsId);
// Read/write files
const config = await WorkspaceFileGet("config/app.json");
await WorkspaceFileSet("config/app.json", JSON.stringify(newConfig));
// List all workspaces
const workspaces = await ListWorkspaces();
// Get active workspace
const active = await ActiveWorkspace();
console.log(`Current: ${active.Name} at ${active.Path}`);
```

0
docs/plans/2026-01-29-code-signing-design.md → tasks/plans/2026-01-29-code-signing-design.md
View file

0
docs/plans/2026-01-29-code-signing-impl.md → tasks/plans/2026-01-29-code-signing-impl.md
View file

0
docs/plans/2026-01-29-core-devops-design.md → tasks/plans/2026-01-29-core-devops-design.md
View file

0
docs/plans/2026-01-29-core-devops-impl.md → tasks/plans/2026-01-29-core-devops-impl.md
View file

0
docs/plans/2026-01-29-sdk-generation-design.md → tasks/plans/2026-01-29-sdk-generation-design.md
View file

0
docs/plans/2026-01-29-sdk-generation-impl.md → tasks/plans/2026-01-29-sdk-generation-impl.md
View file

0
docs/plans/2026-01-29-sdk-release-design.md → tasks/plans/2026-01-29-sdk-release-design.md
View file

0
docs/plans/2026-01-29-sdk-release-impl.md → tasks/plans/2026-01-29-sdk-release-impl.md
View file

0
docs/plans/docs-sync-next-steps.md → tasks/plans/docs-sync-next-steps.md
View file