cli

README

Core

Core is a Web3 Framework, written in Go using Wails.io to replace Electron and the bloat of browsers that, at their core, still live in their mum's basement.

• Repo: https://forge.lthn.ai/core/cli

Vision

Core is an opinionated Web3 desktop application framework providing:

1. Service-Oriented Architecture - Pluggable services with dependency injection
2. Encrypted Workspaces - Each workspace gets its own PGP keypair, files are obfuscated
3. Cross-Platform Storage - Abstract storage backends (local, SFTP, WebDAV) behind a Medium interface
4. Multi-Brand Support - Same codebase powers different "hub" apps (AdminHub, ServerHub, GatewayHub, DeveloperHub, ClientHub)
5. Built-in Crypto - PGP encryption/signing, hashing, checksums as first-class citizens

Mental model: A secure, encrypted workspace manager where each "workspace" is a cryptographically isolated environment. The framework handles windows, menus, trays, config, and i18n.

CLI Quick Start

# 1. Install Core
go install forge.lthn.ai/core/cli/cmd/core@latest

# 2. Verify environment
core doctor

# 3. Run tests in any Go/PHP project
core go test   # or core php test

# 4. Build and preview release
core build
core ci

For more details, see the User Guide.

Framework Quick Start (Go)

import core "forge.lthn.ai/core/cli/pkg/framework/core"

app, err := core.New(
  core.WithServiceLock(),
)

Prerequisites

• Go 1.25+
• Node.js
• Wails v3
• Task

Development Workflow (TDD)

task test-gen    # 1. Generate test stubs
task test        # 2. Run tests (watch them fail)
# 3. Implement your feature
task test        # 4. Run tests (watch them pass)
task review      # 5. CodeRabbit review

Building & Running

# GUI (Wails)
task gui:dev      # Development with hot-reload
task gui:build    # Production build

# CLI
task cli:build    # Build to cmd/core/bin/core
task cli:run      # Build and run

Configuration

Core uses a layered configuration system where values are resolved in the following priority:

1. Command-line flags (if applicable)
2. Environment variables
3. Configuration file
4. Default values

Configuration File

The default configuration file is located at ~/.core/config.yaml.

Format

The file uses YAML format and supports nested structures.

# ~/.core/config.yaml
dev:
  editor: vim
  debug: true

log:
  level: info

Environment Variables

Layered Configuration Mapping

Any configuration value can be overridden using environment variables with the CORE_CONFIG_ prefix. After stripping the CORE_CONFIG_ prefix, the remaining variable name is converted to lowercase and underscores are replaced with dots to map to the configuration hierarchy.

Examples:

• CORE_CONFIG_DEV_EDITOR=nano maps to dev.editor: nano
• CORE_CONFIG_LOG_LEVEL=debug maps to log.level: debug

Common Environment Variables

Variable	Description
CORE_DAEMON	Set to 1 to run the application in daemon mode.
NO_COLOR	If set (to any value), disables ANSI color output.
MCP_ADDR	Address for the MCP TCP server (e.g., localhost:9100). If not set, MCP uses Stdio.
COOLIFY_TOKEN	API token for Coolify deployments.
AGENTIC_TOKEN	API token for Agentic services.
UNIFI_URL	URL of the UniFi controller (e.g., https://192.168.1.1).
UNIFI_INSECURE	Set to 1 or true to skip UniFi TLS verification.

All Tasks

Task	Description
task test	Run all Go tests
task test-gen	Generate test stubs for public API
task check	go mod tidy + tests + review
task review	CodeRabbit review
task cov	Run tests with coverage report
task cov-view	Open HTML coverage report
task sync	Update public API Go files

---

Architecture

Project Structure

.
├── main.go              # CLI application entry point
├── pkg/
│   ├── framework/core/  # Service container, DI, Runtime[T]
│   ├── crypt/           # Hashing, checksums, PGP
│   ├── io/              # Medium interface + backends
│   ├── help/            # In-app documentation
│   ├── i18n/            # Internationalization
│   ├── repos/           # Multi-repo registry & management
│   ├── agentic/         # AI agent task management
│   └── mcp/             # Model Context Protocol service
├── internal/
│   ├── cmd/             # CLI command implementations
│   └── variants/        # Build variants (full, minimal, etc.)
└── go.mod               # Go module definition

Service Pattern (Dual-Constructor DI)

Every service follows this pattern:

// Static DI - standalone use/testing (no core.Runtime)
func New() (*Service, error)

// Dynamic DI - for core.WithService() registration
func Register(c *core.Core) (any, error)

Services embed *core.Runtime[Options] for access to Core() and Config().

IPC/Action System

Services implement HandleIPCEvents(c *core.Core, msg core.Message) error - auto-discovered via reflection. Handles typed actions like core.ActionServiceStartup.

---

Wails v3 Frontend Bindings

Core uses Wails v3 to expose Go methods to a WebView2 browser runtime. Wails automatically generates TypeScript bindings for registered services.

Documentation: Wails v3 Method Bindings

How It Works

1. Go services with exported methods are registered with Wails
2. Run wails3 generate bindings (or wails3 dev / wails3 build)
3. TypeScript SDK is generated in frontend/bindings/
4. Frontend calls Go methods with full type safety, no HTTP overhead

Current Binding Architecture

// cmd/core-gui/main.go
app.RegisterService(application.NewService(coreService))  // Only Core is registered

Problem: Only Core is registered with Wails. Sub-services (crypt, workspace, display, etc.) are internal to Core's service map - their methods aren't directly exposed to JS.

Currently exposed (see cmd/core-gui/public/bindings/):

// From frontend:
import { ACTION, Config, Service } from './bindings/forge.lthn.ai/core/cli/pkg/core'

ACTION(msg)              // Broadcast IPC message
Config()                 // Get config service reference
Service("workspace")     // Get service by name (returns any)

NOT exposed: Direct calls like workspace.CreateWorkspace() or crypt.Hash().

Configuration Management

Core uses a centralized configuration service implemented in pkg/config, with YAML-based persistence and layered overrides.

The pkg/config package provides:

• YAML-backed persistence at ~/.core/config.yaml
• Dot-notation key access (for example: cfg.Set("dev.editor", "vim"), cfg.GetString("dev.editor"))
• Environment variable overlay support (env vars can override persisted values)
• Thread-safe operations for concurrent reads/writes

Application code should treat pkg/config as the primary configuration mechanism. Direct reads/writes to YAML files should generally be avoided from application logic in favour of using this centralized service.

Project and Service Configuration Files

In addition to the centralized configuration service, Core uses several YAML files for project-specific build/CI and service configuration. These live alongside (but are distinct from) the centralized configuration:

• Project Configuration (in the .core/ directory of the project root):
  • build.yaml: Build targets, flags, and project metadata.
  • release.yaml: Release automation, changelog settings, and publishing targets.
  • ci.yaml: CI pipeline configuration.
• Global Configuration (in the ~/.core/ directory):
  • config.yaml: Centralized user/framework settings and defaults, managed via pkg/config.
  • agentic.yaml: Configuration for agentic services (BaseURL, Token, etc.).
• Registry Configuration (repos.yaml, auto-discovered):
  • Multi-repo registry definition.
  • Searched in the current directory and its parent directories (walking up).
  • Then in ~/Code/host-uk/repos.yaml.
  • Finally in ~/.config/core/repos.yaml.

Format

All persisted configuration files described above use YAML format for readability and nested structure support.

The IPC Bridge Pattern (Chosen Architecture)

Sub-services are accessed via Core's IPC/ACTION system, not direct Wails bindings:

// Frontend calls Core.ACTION() with typed messages
import { ACTION } from './bindings/forge.lthn.ai/core/cli/pkg/core'

// Open a window
ACTION({ action: "display.open_window", name: "settings", options: { Title: "Settings", Width: 800 } })

// Switch workspace
ACTION({ action: "workspace.switch_workspace", name: "myworkspace" })

Each service implements HandleIPCEvents(c *core.Core, msg core.Message) to process these messages:

// pkg/display/display.go
func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
    switch m := msg.(type) {
    case map[string]any:
        if action, ok := m["action"].(string); ok && action == "display.open_window" {
            return s.handleOpenWindowAction(m)
        }
    }
    return nil
}

Why this pattern:

• Single Wails service (Core) = simpler binding generation
• Services remain decoupled from Wails
• Centralized message routing via ACTION()
• Services can communicate internally using same pattern

Current gap: Not all service methods have IPC handlers yet. See HandleIPCEvents in each service to understand what's wired up.

Generating Bindings

Wails v3 bindings are typically generated in the GUI repository (e.g., core-gui).

wails3 generate bindings    # Regenerate after Go changes

---

Service Interfaces (pkg/framework/core/interfaces.go)

type Config interface {
    Get(key string, out any) error
    Set(key string, v any) error
}

type Display interface {
    OpenWindow(opts ...WindowOption) error
}

type Workspace interface {
    CreateWorkspace(identifier, password string) (string, error)
    SwitchWorkspace(name string) error
    WorkspaceFileGet(filename string) (string, error)
    WorkspaceFileSet(filename, content string) error
}

type Crypt interface {
    EncryptPGP(writer io.Writer, recipientPath, data string, ...) (string, error)
    DecryptPGP(recipientPath, message, passphrase string, ...) (string, error)
}

---

Current State (Prototype)

Working

Package	Notes
pkg/framework/core	Service container, DI, thread-safe - solid
pkg/config	Layered YAML configuration, XDG paths - solid
pkg/crypt	Hashing, checksums, symmetric/asymmetric - solid, well-tested
pkg/help	Embedded docs, full-text search - solid
pkg/i18n	Multi-language with go-i18n - solid
pkg/io	Medium interface + local backend - solid
pkg/repos	Multi-repo registry & management - solid
pkg/agentic	AI agent task management - solid
pkg/mcp	Model Context Protocol service - solid

---

Package Deep Dives

pkg/crypt

The crypt package provides a comprehensive suite of cryptographic primitives:

• Hashing & Checksums: SHA-256, SHA-512, and CRC32 support.
• Symmetric Encryption: AES-GCM and ChaCha20-Poly1305 for secure data at rest.
• Key Derivation: Argon2id for secure password hashing.
• Asymmetric Encryption: PGP implementation in the pkg/crypt/openpgp subpackage using github.com/ProtonMail/go-crypto.

pkg/io - Storage Abstraction

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
}

Implementations: local/, sftp/, webdav/

---

Future Work

Phase 1: Core Stability

• Fix workspace medium injection (critical blocker)
• Initialize io.Local global
• Clean up dead code (orphaned vars, broken wrappers)
• Wire up IPC handlers for all services (config, crypt, display, help, i18n, workspace)
• Complete display menu handlers (New/List workspace)
• Tray icon setup with asset embedding
• Test coverage for io packages
• System tray brand-specific menus

Phase 2: Multi-Brand Support

• Define brand configuration system (config? build flags?)
• Implement brand-specific tray menus (AdminHub, ServerHub, GatewayHub, DeveloperHub, ClientHub)
• Brand-specific theming/assets
• Per-brand default workspace configurations

Phase 3: Remote Storage

• Complete SFTP backend (pkg/io/sftp/)
• Complete WebDAV backend (pkg/io/webdav/)
• Workspace sync across storage backends
• Conflict resolution for multi-device access

Phase 4: Enhanced Crypto

• Key management UI (import/export, key rotation)
• Multi-recipient encryption
• Hardware key support (YubiKey, etc.)
• Encrypted workspace backup/restore

Phase 5: Developer Experience

• TypeScript types for IPC messages (codegen from Go structs)
• Hot-reload for service registration
• Plugin system for third-party services
• CLI tooling for workspace management

Phase 6: Distribution

• Auto-update mechanism
• Platform installers (DMG, MSI, AppImage)
• Signing and notarization
• Crash reporting integration

---

Getting Help

• User Guide: Detailed usage and concepts.
• FAQ: Frequently asked questions.
• Workflows: Common task sequences.
• Troubleshooting: Solving common issues.
• Configuration: Config file reference.

# Check environment
core doctor

# Command help
core <command> --help

---

For New Contributors

1. Run task test to verify all tests pass
2. Follow TDD: task test-gen creates stubs, implement to pass
3. The dual-constructor pattern is intentional: New(deps) for tests, Register() for runtime
4. IPC handlers in each service's HandleIPCEvents() are the frontend bridge