docs: restructure for VitePress with flat layout and examples
- Remove mkdocs files (requirements.txt, CNAME) - Add CLI documentation: build.md, release.md, php.md, run.md - Add configuration.md with full reference - Add examples/ directory with sample configurations: - go-cli-release.yaml - wails-desktop-release.yaml - php-laravel-release.yaml - linuxkit-server.yml - linuxkit-docker-format.yml - full-release.yaml - minimal-release.yaml - official-repos.yaml - Flatten existing framework docs into framework/ - Update index.md as CLI entry point Ready for VitePress integration with core-php/docs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
02d0167d91
commit
a57fb4273d
41 changed files with 1221 additions and 537 deletions
|
|
@ -1 +0,0 @@
|
|||
core.help
|
||||
113
docs/build.md
Normal file
113
docs/build.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
# core build
|
||||
|
||||
Build Go, Wails, Docker, and LinuxKit projects with automatic project detection.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
core build [flags]
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--type` | Project type: `go`, `wails`, `docker`, `linuxkit` (auto-detected) |
|
||||
| `--targets` | Build targets: `linux/amd64,darwin/arm64,windows/amd64` |
|
||||
| `--output` | Output directory (default: `dist`) |
|
||||
| `--ci` | CI mode - non-interactive, fail fast |
|
||||
| `--image` | Docker image name (for docker builds) |
|
||||
|
||||
## Examples
|
||||
|
||||
### Go Project
|
||||
|
||||
```bash
|
||||
# Auto-detect and build
|
||||
core build
|
||||
|
||||
# Build for specific platforms
|
||||
core build --targets linux/amd64,linux/arm64,darwin/arm64
|
||||
|
||||
# CI mode
|
||||
core build --ci
|
||||
```
|
||||
|
||||
### Wails Project
|
||||
|
||||
```bash
|
||||
# Build Wails desktop app
|
||||
core build --type wails
|
||||
|
||||
# Build for all desktop platforms
|
||||
core build --type wails --targets darwin/amd64,darwin/arm64,windows/amd64,linux/amd64
|
||||
```
|
||||
|
||||
### Docker Image
|
||||
|
||||
```bash
|
||||
# Build Docker image
|
||||
core build --type docker
|
||||
|
||||
# With custom image name
|
||||
core build --type docker --image ghcr.io/myorg/myapp
|
||||
```
|
||||
|
||||
### LinuxKit Image
|
||||
|
||||
```bash
|
||||
# Build LinuxKit ISO
|
||||
core build --type linuxkit
|
||||
```
|
||||
|
||||
## Project Detection
|
||||
|
||||
Core automatically detects project type based on files:
|
||||
|
||||
| Files | Type |
|
||||
|-------|------|
|
||||
| `wails.json` | Wails |
|
||||
| `go.mod` | Go |
|
||||
| `Dockerfile` | Docker |
|
||||
| `composer.json` | PHP |
|
||||
| `package.json` | Node |
|
||||
|
||||
## Output
|
||||
|
||||
Build artifacts are placed in `dist/` by default:
|
||||
|
||||
```
|
||||
dist/
|
||||
├── myapp-linux-amd64.tar.gz
|
||||
├── myapp-linux-arm64.tar.gz
|
||||
├── myapp-darwin-amd64.tar.gz
|
||||
├── myapp-darwin-arm64.tar.gz
|
||||
├── myapp-windows-amd64.zip
|
||||
└── CHECKSUMS.txt
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Optional `.core/build.yaml`:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
binary: myapp
|
||||
|
||||
build:
|
||||
main: ./cmd/myapp
|
||||
ldflags:
|
||||
- -s -w
|
||||
- -X main.version={{.Version}}
|
||||
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: linux
|
||||
arch: arm64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
```
|
||||
223
docs/configuration.md
Normal file
223
docs/configuration.md
Normal file
|
|
@ -0,0 +1,223 @@
|
|||
# Configuration
|
||||
|
||||
Core uses `.core/` directory for project configuration.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.core/
|
||||
├── release.yaml # Release configuration
|
||||
├── build.yaml # Build configuration (optional)
|
||||
├── php.yaml # PHP configuration (optional)
|
||||
└── linuxkit/ # LinuxKit templates
|
||||
├── server.yml
|
||||
└── dev.yml
|
||||
```
|
||||
|
||||
## release.yaml
|
||||
|
||||
Full release configuration reference:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
repository: myorg/myapp
|
||||
|
||||
build:
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: linux
|
||||
arch: arm64
|
||||
- os: darwin
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
- os: windows
|
||||
arch: amd64
|
||||
|
||||
publishers:
|
||||
# GitHub Releases (required - others reference these artifacts)
|
||||
- type: github
|
||||
prerelease: false
|
||||
draft: false
|
||||
|
||||
# npm binary wrapper
|
||||
- type: npm
|
||||
package: "@myorg/myapp"
|
||||
access: public # or "restricted"
|
||||
|
||||
# Homebrew formula
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap
|
||||
formula: myapp
|
||||
official:
|
||||
enabled: false
|
||||
output: dist/homebrew
|
||||
|
||||
# Scoop manifest (Windows)
|
||||
- type: scoop
|
||||
bucket: myorg/scoop-bucket
|
||||
official:
|
||||
enabled: false
|
||||
output: dist/scoop
|
||||
|
||||
# AUR (Arch Linux)
|
||||
- type: aur
|
||||
maintainer: "Name <email>"
|
||||
|
||||
# Chocolatey (Windows)
|
||||
- type: chocolatey
|
||||
push: false # true to publish
|
||||
|
||||
# Docker multi-arch
|
||||
- type: docker
|
||||
registry: ghcr.io
|
||||
image: myorg/myapp
|
||||
dockerfile: Dockerfile
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
tags:
|
||||
- latest
|
||||
- "{{.Version}}"
|
||||
build_args:
|
||||
VERSION: "{{.Version}}"
|
||||
|
||||
# LinuxKit images
|
||||
- type: linuxkit
|
||||
config: .core/linuxkit/server.yml
|
||||
formats:
|
||||
- iso
|
||||
- qcow2
|
||||
- docker
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
|
||||
changelog:
|
||||
include:
|
||||
- feat
|
||||
- fix
|
||||
- perf
|
||||
- refactor
|
||||
exclude:
|
||||
- chore
|
||||
- docs
|
||||
- style
|
||||
- test
|
||||
- ci
|
||||
```
|
||||
|
||||
## build.yaml
|
||||
|
||||
Optional build configuration:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
binary: myapp
|
||||
|
||||
build:
|
||||
main: ./cmd/myapp
|
||||
env:
|
||||
CGO_ENABLED: "0"
|
||||
flags:
|
||||
- -trimpath
|
||||
ldflags:
|
||||
- -s -w
|
||||
- -X main.version={{.Version}}
|
||||
- -X main.commit={{.Commit}}
|
||||
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
```
|
||||
|
||||
## php.yaml
|
||||
|
||||
PHP/Laravel configuration:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
dev:
|
||||
domain: myapp.test
|
||||
ssl: true
|
||||
port: 8000
|
||||
services:
|
||||
- frankenphp
|
||||
- vite
|
||||
- horizon
|
||||
- reverb
|
||||
- redis
|
||||
|
||||
test:
|
||||
parallel: true
|
||||
coverage: false
|
||||
|
||||
deploy:
|
||||
coolify:
|
||||
server: https://coolify.example.com
|
||||
project: my-project
|
||||
environment: production
|
||||
```
|
||||
|
||||
## LinuxKit Templates
|
||||
|
||||
LinuxKit YAML configuration:
|
||||
|
||||
```yaml
|
||||
kernel:
|
||||
image: linuxkit/kernel:6.6
|
||||
cmdline: "console=tty0 console=ttyS0"
|
||||
|
||||
init:
|
||||
- linuxkit/init:latest
|
||||
- linuxkit/runc:latest
|
||||
- linuxkit/containerd:latest
|
||||
- linuxkit/ca-certificates:latest
|
||||
|
||||
onboot:
|
||||
- name: sysctl
|
||||
image: linuxkit/sysctl:latest
|
||||
|
||||
services:
|
||||
- name: dhcpcd
|
||||
image: linuxkit/dhcpcd:latest
|
||||
- name: sshd
|
||||
image: linuxkit/sshd:latest
|
||||
- name: myapp
|
||||
image: myorg/myapp:latest
|
||||
capabilities:
|
||||
- CAP_NET_BIND_SERVICE
|
||||
|
||||
files:
|
||||
- path: /etc/myapp/config.yaml
|
||||
contents: |
|
||||
server:
|
||||
port: 8080
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `GITHUB_TOKEN` | GitHub authentication (via gh CLI) |
|
||||
| `NPM_TOKEN` | npm publish token |
|
||||
| `CHOCOLATEY_API_KEY` | Chocolatey publish key |
|
||||
| `COOLIFY_TOKEN` | Coolify deployment token |
|
||||
|
||||
## Defaults
|
||||
|
||||
If no configuration exists, sensible defaults are used:
|
||||
|
||||
- **Targets**: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64
|
||||
- **Publishers**: GitHub only
|
||||
- **Changelog**: feat, fix, perf, refactor included
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Core Framework Overview
|
||||
|
||||
The Core package (`pkg/core`) is the foundation of the framework, providing service management, lifecycle handling, and inter-service communication.
|
||||
|
||||
## Creating a Core Instance
|
||||
|
||||
```go
|
||||
import "github.com/Snider/Core/pkg/core"
|
||||
|
||||
c, err := core.New(
|
||||
core.WithAssets(assets), // Embed frontend assets
|
||||
core.WithService(myServiceFactory), // Register services
|
||||
core.WithServiceLock(), // Prevent late registration
|
||||
)
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `WithService(factory)` | Register a service with auto-discovered name |
|
||||
| `WithName(name, factory)` | Register a service with explicit name |
|
||||
| `WithAssets(fs)` | Embed filesystem for frontend assets |
|
||||
| `WithServiceLock()` | Lock service registration after init |
|
||||
|
||||
## Service Factory Pattern
|
||||
|
||||
Services use factory functions for dependency injection:
|
||||
|
||||
```go
|
||||
func NewMyService(c *core.Core) (any, error) {
|
||||
// Get dependencies
|
||||
config := core.MustServiceFor[*config.Service](c, "config")
|
||||
|
||||
return &MyService{
|
||||
config: config,
|
||||
}, nil
|
||||
}
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
Core includes a feature flag system:
|
||||
|
||||
```go
|
||||
// Check if feature is enabled
|
||||
if c.Features.IsEnabled("experimental") {
|
||||
// Use experimental feature
|
||||
}
|
||||
|
||||
// Enable a feature
|
||||
c.Features.Enable("experimental")
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Use the `E()` helper for contextual errors:
|
||||
|
||||
```go
|
||||
import "github.com/Snider/Core/pkg/core"
|
||||
|
||||
func (s *Service) DoSomething() error {
|
||||
if err := someOperation(); err != nil {
|
||||
return core.E("Service.DoSomething", "operation failed", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Register all services before starting** - Use `WithServiceLock()` to catch mistakes
|
||||
2. **Use factory functions** - Enables proper dependency injection
|
||||
3. **Implement lifecycle interfaces** - For proper startup/shutdown
|
||||
4. **Use typed service retrieval** - Catches type mismatches at compile time
|
||||
98
docs/examples/full-release.yaml
Normal file
98
docs/examples/full-release.yaml
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
# Example: Full Release Configuration
|
||||
# Complete configuration with all publishers
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: core
|
||||
repository: host-uk/core
|
||||
|
||||
build:
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: linux
|
||||
arch: arm64
|
||||
- os: darwin
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
- os: windows
|
||||
arch: amd64
|
||||
- os: windows
|
||||
arch: arm64
|
||||
|
||||
publishers:
|
||||
# 1. GitHub Releases - always first, others reference these
|
||||
- type: github
|
||||
prerelease: false
|
||||
draft: false
|
||||
|
||||
# 2. npm - JavaScript ecosystem
|
||||
- type: npm
|
||||
package: "@host-uk/core"
|
||||
access: public
|
||||
|
||||
# 3. Homebrew - macOS/Linux
|
||||
- type: homebrew
|
||||
tap: host-uk/homebrew-tap
|
||||
formula: core
|
||||
# Generate files for official homebrew-core PR
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/homebrew
|
||||
|
||||
# 4. Scoop - Windows
|
||||
- type: scoop
|
||||
bucket: host-uk/scoop-bucket
|
||||
# Generate files for official scoop-main PR
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/scoop
|
||||
|
||||
# 5. AUR - Arch Linux
|
||||
- type: aur
|
||||
maintainer: "Host UK <dev@host.uk.com>"
|
||||
|
||||
# 6. Chocolatey - Windows enterprise
|
||||
- type: chocolatey
|
||||
push: false # Manual review before push
|
||||
|
||||
# 7. Docker - Container deployment
|
||||
- type: docker
|
||||
registry: ghcr.io
|
||||
image: host-uk/core
|
||||
dockerfile: Dockerfile
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
tags:
|
||||
- latest
|
||||
- "{{.Version}}"
|
||||
- "{{.Version}}-alpine"
|
||||
|
||||
# 8. LinuxKit - Immutable infrastructure
|
||||
- type: linuxkit
|
||||
config: .core/linuxkit/core-server.yml
|
||||
formats:
|
||||
- iso # Bootable ISO for bare metal
|
||||
- qcow2 # QEMU/KVM/Proxmox
|
||||
- docker # Immutable container
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
|
||||
changelog:
|
||||
include:
|
||||
- feat # New features
|
||||
- fix # Bug fixes
|
||||
- perf # Performance improvements
|
||||
- refactor # Code refactoring
|
||||
- security # Security fixes
|
||||
exclude:
|
||||
- chore
|
||||
- docs
|
||||
- style
|
||||
- test
|
||||
- ci
|
||||
- build
|
||||
59
docs/examples/go-cli-release.yaml
Normal file
59
docs/examples/go-cli-release.yaml
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Example: Go CLI Release Configuration
|
||||
# Publishes to GitHub, npm, Homebrew, Scoop, AUR, and Chocolatey
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: mycli
|
||||
repository: myorg/mycli
|
||||
|
||||
build:
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: linux
|
||||
arch: arm64
|
||||
- os: darwin
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
- os: windows
|
||||
arch: amd64
|
||||
|
||||
publishers:
|
||||
# GitHub Releases - foundation for all other publishers
|
||||
- type: github
|
||||
prerelease: false
|
||||
draft: false
|
||||
|
||||
# npm - binary wrapper pattern
|
||||
# Users install via: npm install -g @myorg/mycli
|
||||
- type: npm
|
||||
package: "@myorg/mycli"
|
||||
access: public
|
||||
|
||||
# Homebrew - tap repository
|
||||
# Users install via: brew install myorg/tap/mycli
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap
|
||||
|
||||
# Scoop - Windows package manager
|
||||
# Users install via: scoop bucket add myorg https://github.com/myorg/scoop-bucket && scoop install mycli
|
||||
- type: scoop
|
||||
bucket: myorg/scoop-bucket
|
||||
|
||||
# AUR - Arch Linux User Repository
|
||||
# Users install via: yay -S mycli-bin
|
||||
- type: aur
|
||||
maintainer: "Your Name <your@email.com>"
|
||||
|
||||
# Chocolatey - Windows enterprise
|
||||
# Users install via: choco install mycli
|
||||
- type: chocolatey
|
||||
push: false # Set true to auto-publish
|
||||
|
||||
changelog:
|
||||
include:
|
||||
- feat
|
||||
- fix
|
||||
- perf
|
||||
29
docs/examples/linuxkit-docker-format.yml
Normal file
29
docs/examples/linuxkit-docker-format.yml
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Example: LinuxKit Docker Format
|
||||
# Build immutable container that loads with `docker load`
|
||||
|
||||
kernel:
|
||||
image: linuxkit/kernel:6.6
|
||||
cmdline: "console=tty0"
|
||||
|
||||
init:
|
||||
- linuxkit/init:latest
|
||||
- linuxkit/runc:latest
|
||||
- linuxkit/containerd:latest
|
||||
|
||||
services:
|
||||
- name: myservice
|
||||
image: ghcr.io/myorg/myservice:latest
|
||||
|
||||
# Use in release.yaml:
|
||||
#
|
||||
# publishers:
|
||||
# - type: linuxkit
|
||||
# config: .core/linuxkit/docker-format.yml
|
||||
# formats:
|
||||
# - docker # Outputs .docker.tar
|
||||
# platforms:
|
||||
# - linux/amd64
|
||||
# - linux/arm64
|
||||
#
|
||||
# Load the image:
|
||||
# docker load < linuxkit-v1.0.0-amd64.docker.tar
|
||||
51
docs/examples/linuxkit-server.yml
Normal file
51
docs/examples/linuxkit-server.yml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# Example: LinuxKit Server Configuration
|
||||
# Minimal immutable Linux server with your application
|
||||
|
||||
kernel:
|
||||
image: linuxkit/kernel:6.6
|
||||
cmdline: "console=tty0 console=ttyS0"
|
||||
|
||||
init:
|
||||
- linuxkit/init:latest
|
||||
- linuxkit/runc:latest
|
||||
- linuxkit/containerd:latest
|
||||
- linuxkit/ca-certificates:latest
|
||||
|
||||
onboot:
|
||||
- name: sysctl
|
||||
image: linuxkit/sysctl:latest
|
||||
- name: dhcpcd
|
||||
image: linuxkit/dhcpcd:latest
|
||||
|
||||
services:
|
||||
# SSH for management
|
||||
- name: sshd
|
||||
image: linuxkit/sshd:latest
|
||||
binds:
|
||||
- /etc/ssh/authorized_keys:/root/.ssh/authorized_keys
|
||||
|
||||
# Your application
|
||||
- name: myapp
|
||||
image: ghcr.io/myorg/myapp:latest
|
||||
capabilities:
|
||||
- CAP_NET_BIND_SERVICE
|
||||
binds:
|
||||
- /etc/myapp:/etc/myapp:ro
|
||||
|
||||
files:
|
||||
# SSH authorized keys
|
||||
- path: /etc/ssh/authorized_keys
|
||||
mode: "0600"
|
||||
contents: |
|
||||
ssh-ed25519 AAAA... your-key
|
||||
|
||||
# Application config
|
||||
- path: /etc/myapp/config.yaml
|
||||
mode: "0644"
|
||||
contents: |
|
||||
server:
|
||||
host: 0.0.0.0
|
||||
port: 8080
|
||||
database:
|
||||
host: ${DB_HOST:-localhost}
|
||||
port: ${DB_PORT:-5432}
|
||||
11
docs/examples/minimal-release.yaml
Normal file
11
docs/examples/minimal-release.yaml
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# Example: Minimal Release Configuration
|
||||
# Just GitHub releases with defaults
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
repository: myorg/myapp
|
||||
|
||||
publishers:
|
||||
- type: github
|
||||
51
docs/examples/official-repos.yaml
Normal file
51
docs/examples/official-repos.yaml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# Example: Generate Files for Official Repository PRs
|
||||
# Creates files for PRs to homebrew-core, scoop-main, etc.
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
repository: myorg/myapp
|
||||
|
||||
publishers:
|
||||
- type: github
|
||||
|
||||
# Generate formula for homebrew-core PR
|
||||
# Output: dist/homebrew/myapp.rb
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap # Also push to own tap
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/homebrew
|
||||
|
||||
# Generate manifest for scoop-main PR
|
||||
# Output: dist/scoop/myapp.json
|
||||
- type: scoop
|
||||
bucket: myorg/scoop-bucket # Also push to own bucket
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/scoop
|
||||
|
||||
# Generate files for AUR
|
||||
# Output: dist/aur/PKGBUILD, dist/aur/.SRCINFO
|
||||
- type: aur
|
||||
maintainer: "Your Name <email>"
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/aur
|
||||
|
||||
# After release, submit PRs:
|
||||
#
|
||||
# Homebrew:
|
||||
# cd homebrew-core
|
||||
# cp ../myapp/dist/homebrew/myapp.rb Formula/m/myapp.rb
|
||||
# git checkout -b myapp-1.0.0
|
||||
# git add . && git commit -m "myapp 1.0.0 (new formula)"
|
||||
# gh pr create
|
||||
#
|
||||
# Scoop:
|
||||
# cd Main
|
||||
# cp ../myapp/dist/scoop/myapp.json bucket/myapp.json
|
||||
# git checkout -b myapp-1.0.0
|
||||
# git add . && git commit -m "myapp: Add version 1.0.0"
|
||||
# gh pr create
|
||||
42
docs/examples/php-laravel-release.yaml
Normal file
42
docs/examples/php-laravel-release.yaml
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# Example: PHP/Laravel Release Configuration
|
||||
# Builds Docker container and LinuxKit image
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: mylaravel
|
||||
repository: myorg/mylaravel
|
||||
|
||||
publishers:
|
||||
- type: github
|
||||
prerelease: false
|
||||
|
||||
# Docker container for deployment
|
||||
- type: docker
|
||||
registry: ghcr.io
|
||||
image: myorg/mylaravel
|
||||
dockerfile: Dockerfile
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
tags:
|
||||
- latest
|
||||
- "{{.Version}}"
|
||||
build_args:
|
||||
PHP_VERSION: "8.4"
|
||||
APP_ENV: production
|
||||
|
||||
# LinuxKit for immutable server deployment
|
||||
- type: linuxkit
|
||||
config: .core/linuxkit/server-php.yml
|
||||
formats:
|
||||
- iso
|
||||
- qcow2
|
||||
platforms:
|
||||
- linux/amd64
|
||||
|
||||
changelog:
|
||||
include:
|
||||
- feat
|
||||
- fix
|
||||
- security
|
||||
36
docs/examples/wails-desktop-release.yaml
Normal file
36
docs/examples/wails-desktop-release.yaml
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Example: Wails Desktop App Release Configuration
|
||||
# Builds cross-platform desktop app and publishes to GitHub
|
||||
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: myapp
|
||||
repository: myorg/myapp
|
||||
|
||||
build:
|
||||
targets:
|
||||
- os: darwin
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
- os: windows
|
||||
arch: amd64
|
||||
- os: linux
|
||||
arch: amd64
|
||||
|
||||
publishers:
|
||||
- type: github
|
||||
prerelease: false
|
||||
draft: true # Review before publishing
|
||||
|
||||
# Homebrew cask for macOS
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap
|
||||
formula: myapp
|
||||
|
||||
changelog:
|
||||
include:
|
||||
- feat
|
||||
- fix
|
||||
- perf
|
||||
- ui # Custom type for UI changes
|
||||
129
docs/index.md
129
docs/index.md
|
|
@ -1,76 +1,77 @@
|
|||
# Core Framework
|
||||
# Core CLI
|
||||
|
||||
Core is a Web3 Framework for building production-grade Go desktop applications using [Wails v3](https://wails.io/). It replaces Electron with a native Go backend while providing a modern, service-based architecture.
|
||||
Core is a unified CLI for the host-uk ecosystem - build, release, and deploy Go, Wails, PHP, and container workloads.
|
||||
|
||||
## Why Core?
|
||||
## Installation
|
||||
|
||||
- **Native Performance**: Go backend with native webview, no Chromium bloat
|
||||
- **Service Architecture**: Modular, testable services with dependency injection
|
||||
- **MCP Integration**: Built-in Model Context Protocol support for AI tooling
|
||||
- **Cross-Platform**: macOS, Windows, and Linux from a single codebase
|
||||
- **TypeScript Bindings**: Auto-generated bindings for frontend integration
|
||||
```bash
|
||||
# Go install
|
||||
go install github.com/host-uk/core/cmd/core@latest
|
||||
|
||||
## Quick Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"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() {
|
||||
// Create the Core with services
|
||||
c, err := core.New(
|
||||
core.WithAssets(assets),
|
||||
core.WithService(display.NewService),
|
||||
core.WithServiceLock(),
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Create Wails app
|
||||
app := application.New(application.Options{
|
||||
Name: "MyApp",
|
||||
})
|
||||
|
||||
// Run
|
||||
if err := app.Run(); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
# Or download from releases
|
||||
curl -fsSL https://github.com/host-uk/core/releases/latest/download/core-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/').tar.gz | tar -xzf - -C /usr/local/bin
|
||||
```
|
||||
|
||||
## Core Services
|
||||
## Commands
|
||||
|
||||
| Service | Description |
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| **Core** | Central service container and lifecycle management |
|
||||
| **Display** | Window management, dialogs, tray, clipboard |
|
||||
| **WebView** | JavaScript execution, DOM interaction, screenshots |
|
||||
| **MCP** | Model Context Protocol server for AI tool integration |
|
||||
| **Config** | Application configuration and state persistence |
|
||||
| **Crypt** | Encryption, signing, key management |
|
||||
| **I18n** | Internationalization and localization |
|
||||
| **IO** | File system operations |
|
||||
| **Workspace** | Project and path management |
|
||||
| `core build` | Build Go, Wails, Docker, and LinuxKit projects |
|
||||
| `core release` | Build and publish to GitHub, npm, Homebrew, etc. |
|
||||
| `core run` | Run LinuxKit images with qemu/hyperkit |
|
||||
| `core php` | Laravel/PHP development environment |
|
||||
| `core ps` | List running containers |
|
||||
| `core stop` | Stop running containers |
|
||||
| `core logs` | View container logs |
|
||||
| `core exec` | Execute commands in containers |
|
||||
|
||||
## Getting Started
|
||||
## Quick Start
|
||||
|
||||
1. [Installation](getting-started/installation.md) - Install Go, Wails, and Core
|
||||
2. [Quick Start](getting-started/quickstart.md) - Build your first app
|
||||
3. [Architecture](getting-started/architecture.md) - Understand the design
|
||||
```bash
|
||||
# Build a Go project
|
||||
core build
|
||||
|
||||
## Links
|
||||
# Build for specific targets
|
||||
core build --targets linux/amd64,darwin/arm64
|
||||
|
||||
- **Repository**: [github.com/Snider/Core](https://github.com/Snider/Core)
|
||||
- **Issues**: [GitHub Issues](https://github.com/Snider/Core/issues)
|
||||
# Release to GitHub
|
||||
core release
|
||||
|
||||
# Release to multiple package managers
|
||||
core release # Publishes to all configured targets
|
||||
|
||||
# Start PHP dev environment
|
||||
core php dev
|
||||
|
||||
# Run a LinuxKit image
|
||||
core run server.iso
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Core uses `.core/` directory for project configuration:
|
||||
|
||||
```
|
||||
.core/
|
||||
├── release.yaml # Release targets and settings
|
||||
├── build.yaml # Build configuration (optional)
|
||||
└── linuxkit/ # LinuxKit templates
|
||||
└── server.yml
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Build Command](build.md) - Cross-platform builds
|
||||
- [Release Command](release.md) - Publishing to package managers
|
||||
- [PHP Commands](php.md) - Laravel development
|
||||
- [Run Command](run.md) - Container management
|
||||
- [Configuration](configuration.md) - All config options
|
||||
- [Examples](examples/) - Sample configurations
|
||||
|
||||
## Framework
|
||||
|
||||
Core also provides a Go framework for building desktop applications:
|
||||
|
||||
- [Framework Overview](framework/overview.md)
|
||||
- [Services](framework/services.md)
|
||||
- [Lifecycle](framework/lifecycle.md)
|
||||
|
|
|
|||
138
docs/php.md
Normal file
138
docs/php.md
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
# core php
|
||||
|
||||
Laravel/PHP development environment with FrankenPHP, Vite, Horizon, Reverb, and Redis.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `core php dev` | Start development environment |
|
||||
| `core php test` | Run PHPUnit/Pest tests |
|
||||
| `core php fmt` | Format with Laravel Pint |
|
||||
| `core php analyse` | Static analysis with PHPStan |
|
||||
| `core php build` | Build production container |
|
||||
| `core php deploy` | Deploy to Coolify |
|
||||
|
||||
## Development Environment
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
core php dev
|
||||
```
|
||||
|
||||
This starts:
|
||||
- FrankenPHP/Octane (HTTP server)
|
||||
- Vite dev server (frontend)
|
||||
- Laravel Horizon (queues)
|
||||
- Laravel Reverb (WebSockets)
|
||||
- Redis
|
||||
|
||||
```bash
|
||||
# View unified logs
|
||||
core php logs
|
||||
|
||||
# Stop all services
|
||||
core php stop
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
core php test
|
||||
|
||||
# Parallel testing
|
||||
core php test --parallel
|
||||
|
||||
# With coverage
|
||||
core php test --coverage
|
||||
```
|
||||
|
||||
## Code Quality
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
core php fmt
|
||||
|
||||
# Static analysis
|
||||
core php analyse
|
||||
|
||||
# Run both
|
||||
core php fmt && core php analyse
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
# Build Docker container
|
||||
core php build
|
||||
|
||||
# Build LinuxKit image
|
||||
core php build --type linuxkit
|
||||
|
||||
# Run production locally
|
||||
core php serve --production
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
```bash
|
||||
# Deploy to Coolify
|
||||
core php deploy
|
||||
|
||||
# Deploy to staging
|
||||
core php deploy --staging
|
||||
|
||||
# Check deployment status
|
||||
core php deploy:status
|
||||
|
||||
# Rollback
|
||||
core php deploy:rollback
|
||||
```
|
||||
|
||||
## Package Management
|
||||
|
||||
Link local packages for development:
|
||||
|
||||
```bash
|
||||
# Link a local package
|
||||
core php packages link ../my-package
|
||||
|
||||
# Update linked packages
|
||||
core php packages update
|
||||
|
||||
# Unlink
|
||||
core php packages unlink my-package
|
||||
```
|
||||
|
||||
## SSL/HTTPS
|
||||
|
||||
Local SSL with mkcert:
|
||||
|
||||
```bash
|
||||
# Auto-configured with core php dev
|
||||
# Uses mkcert for trusted local certificates
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Optional `.core/php.yaml`:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
dev:
|
||||
domain: myapp.test
|
||||
ssl: true
|
||||
services:
|
||||
- frankenphp
|
||||
- vite
|
||||
- horizon
|
||||
- reverb
|
||||
- redis
|
||||
|
||||
deploy:
|
||||
coolify:
|
||||
server: https://coolify.example.com
|
||||
project: my-project
|
||||
```
|
||||
173
docs/release.md
Normal file
173
docs/release.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
# core release
|
||||
|
||||
Build and publish releases to GitHub, npm, Homebrew, Scoop, AUR, Chocolatey, Docker, and LinuxKit.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
core release [flags]
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--dry-run` | Preview what would be published |
|
||||
| `--version` | Override version (default: git tag) |
|
||||
| `--skip-build` | Skip build, use existing artifacts |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize release config
|
||||
core release init
|
||||
|
||||
# Preview release
|
||||
core release --dry-run
|
||||
|
||||
# Release
|
||||
core release
|
||||
```
|
||||
|
||||
## Publishers
|
||||
|
||||
### GitHub Releases
|
||||
|
||||
Uploads artifacts and changelog to GitHub Releases.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: github
|
||||
prerelease: false
|
||||
draft: false
|
||||
```
|
||||
|
||||
### npm
|
||||
|
||||
Publishes binary wrapper that downloads correct platform binary.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: npm
|
||||
package: "@myorg/myapp"
|
||||
access: public
|
||||
```
|
||||
|
||||
Requires `NPM_TOKEN` environment variable.
|
||||
|
||||
### Homebrew
|
||||
|
||||
Generates formula and commits to tap repository.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap
|
||||
formula: myapp # optional, defaults to project name
|
||||
```
|
||||
|
||||
For official Homebrew PR:
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: homebrew
|
||||
tap: myorg/homebrew-tap
|
||||
official:
|
||||
enabled: true
|
||||
output: dist/homebrew
|
||||
```
|
||||
|
||||
### Scoop
|
||||
|
||||
Generates manifest and commits to bucket repository.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: scoop
|
||||
bucket: myorg/scoop-bucket
|
||||
```
|
||||
|
||||
### AUR
|
||||
|
||||
Generates PKGBUILD and pushes to AUR.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: aur
|
||||
maintainer: "Your Name <email@example.com>"
|
||||
```
|
||||
|
||||
### Chocolatey
|
||||
|
||||
Generates NuSpec and optionally pushes to Chocolatey.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: chocolatey
|
||||
push: false # generate only
|
||||
```
|
||||
|
||||
Set `push: true` and `CHOCOLATEY_API_KEY` to publish.
|
||||
|
||||
### Docker
|
||||
|
||||
Builds and pushes multi-arch Docker images.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: docker
|
||||
registry: ghcr.io
|
||||
image: myorg/myapp
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
tags:
|
||||
- latest
|
||||
- "{{.Version}}"
|
||||
```
|
||||
|
||||
### LinuxKit
|
||||
|
||||
Builds immutable LinuxKit images.
|
||||
|
||||
```yaml
|
||||
publishers:
|
||||
- type: linuxkit
|
||||
config: .core/linuxkit/server.yml
|
||||
formats:
|
||||
- iso
|
||||
- qcow2
|
||||
- docker # Immutable container
|
||||
platforms:
|
||||
- linux/amd64
|
||||
- linux/arm64
|
||||
```
|
||||
|
||||
## Full Example
|
||||
|
||||
See [examples/full-release.yaml](examples/full-release.yaml) for a complete configuration.
|
||||
|
||||
## Changelog
|
||||
|
||||
Changelog is auto-generated from conventional commits:
|
||||
|
||||
```
|
||||
feat: Add new feature → Features
|
||||
fix: Fix bug → Bug Fixes
|
||||
perf: Improve performance → Performance
|
||||
refactor: Refactor code → Refactoring
|
||||
```
|
||||
|
||||
Configure in `.core/release.yaml`:
|
||||
|
||||
```yaml
|
||||
changelog:
|
||||
include:
|
||||
- feat
|
||||
- fix
|
||||
- perf
|
||||
exclude:
|
||||
- chore
|
||||
- docs
|
||||
- test
|
||||
```
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
mkdocs>=1.6.0
|
||||
mkdocs-material>=9.5.0
|
||||
mkdocs-material-extensions>=1.3
|
||||
pymdown-extensions>=10.8
|
||||
132
docs/run.md
Normal file
132
docs/run.md
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
# core run
|
||||
|
||||
Run LinuxKit images with qemu or hyperkit.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
core run <image> [flags]
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-d, --detach` | Run in background |
|
||||
| `--cpus` | Number of CPUs (default: 1) |
|
||||
| `--mem` | Memory in MB (default: 1024) |
|
||||
| `--disk` | Disk size (default: none) |
|
||||
| `--template` | Use built-in template |
|
||||
|
||||
## Examples
|
||||
|
||||
### Run ISO Image
|
||||
|
||||
```bash
|
||||
# Run LinuxKit ISO
|
||||
core run server.iso
|
||||
|
||||
# With more resources
|
||||
core run server.iso --cpus 2 --mem 2048
|
||||
|
||||
# Detached mode
|
||||
core run server.iso -d
|
||||
```
|
||||
|
||||
### Run from Template
|
||||
|
||||
```bash
|
||||
# List available templates
|
||||
core templates
|
||||
|
||||
# Run template
|
||||
core run --template core-dev
|
||||
```
|
||||
|
||||
### Formats
|
||||
|
||||
Supported image formats:
|
||||
- `.iso` - Bootable ISO
|
||||
- `.qcow2` - QEMU disk image
|
||||
- `.raw` - Raw disk image
|
||||
- `.vmdk` - VMware disk
|
||||
|
||||
## Container Management
|
||||
|
||||
```bash
|
||||
# List running containers
|
||||
core ps
|
||||
|
||||
# View logs
|
||||
core logs <id>
|
||||
|
||||
# Follow logs
|
||||
core logs -f <id>
|
||||
|
||||
# Execute command
|
||||
core exec <id> <command>
|
||||
|
||||
# Stop container
|
||||
core stop <id>
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
Built-in templates in `.core/linuxkit/`:
|
||||
|
||||
| Template | Description |
|
||||
|----------|-------------|
|
||||
| `core-dev` | Development environment |
|
||||
| `server-php` | FrankenPHP server |
|
||||
|
||||
### Custom Templates
|
||||
|
||||
Create `.core/linuxkit/mytemplate.yml`:
|
||||
|
||||
```yaml
|
||||
kernel:
|
||||
image: linuxkit/kernel:6.6
|
||||
cmdline: "console=tty0"
|
||||
|
||||
init:
|
||||
- linuxkit/init:latest
|
||||
- linuxkit/runc:latest
|
||||
- linuxkit/containerd:latest
|
||||
|
||||
services:
|
||||
- name: myservice
|
||||
image: myorg/myservice:latest
|
||||
|
||||
files:
|
||||
- path: /etc/myconfig
|
||||
contents: |
|
||||
key: value
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
core run --template mytemplate
|
||||
```
|
||||
|
||||
## Networking
|
||||
|
||||
LinuxKit VMs get their own network namespace. Port forwarding:
|
||||
|
||||
```bash
|
||||
# Forward port 8080
|
||||
core run server.iso -p 8080:80
|
||||
|
||||
# Multiple ports
|
||||
core run server.iso -p 8080:80 -p 8443:443
|
||||
```
|
||||
|
||||
## Disk Persistence
|
||||
|
||||
```bash
|
||||
# Create persistent disk
|
||||
core run server.iso --disk 10G
|
||||
|
||||
# Attach existing disk
|
||||
core run server.iso --disk /path/to/disk.qcow2
|
||||
```
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
---
|
||||
title: core
|
||||
---
|
||||
# Service: `core`
|
||||
|
||||
The `core` service is the foundation of the application. It serves as a central hub for managing service lifecycles, dependency injection, asset handling, and inter-process communication (IPC).
|
||||
|
||||
## Types
|
||||
|
||||
### `type Core`
|
||||
|
||||
`Core` is the central application object. It holds references to the Wails application instance, configuration, and registered services.
|
||||
|
||||
```go
|
||||
type Core struct {
|
||||
// App is the Wails application instance
|
||||
App *application.App
|
||||
// Features manages feature flags
|
||||
Features *Features
|
||||
// ... internal fields
|
||||
}
|
||||
```
|
||||
|
||||
### `type Option`
|
||||
|
||||
`Option` is a function type used to configure the `Core` during initialization.
|
||||
|
||||
```go
|
||||
type Option func(*Core) error
|
||||
```
|
||||
|
||||
### `type Startable`
|
||||
|
||||
`Startable` is an interface for services that require initialization logic when the application starts.
|
||||
|
||||
```go
|
||||
type Startable interface {
|
||||
OnStartup(ctx context.Context) error
|
||||
}
|
||||
```
|
||||
|
||||
### `type Stoppable`
|
||||
|
||||
`Stoppable` is an interface for services that require cleanup logic when the application shuts down.
|
||||
|
||||
```go
|
||||
type Stoppable interface {
|
||||
OnShutdown(ctx context.Context) error
|
||||
}
|
||||
```
|
||||
|
||||
### `type Message`
|
||||
|
||||
`Message` is a marker interface for structs that can be sent via the Core's IPC system.
|
||||
|
||||
```go
|
||||
type Message interface{}
|
||||
```
|
||||
|
||||
### `type ActionServiceStartup`
|
||||
|
||||
`ActionServiceStartup` is a message dispatched when the application services are starting up.
|
||||
|
||||
```go
|
||||
type ActionServiceStartup struct{}
|
||||
```
|
||||
|
||||
### `type ActionServiceShutdown`
|
||||
|
||||
`ActionServiceShutdown` is a message dispatched when the application services are shutting down.
|
||||
|
||||
```go
|
||||
type ActionServiceShutdown struct{}
|
||||
```
|
||||
|
||||
## Functions
|
||||
|
||||
### `func New(opts ...Option) (*Core, error)`
|
||||
|
||||
`New` initializes a new `Core` instance with the provided options. It sets up the internal service registry and feature flags.
|
||||
|
||||
### `func WithService(factory func(*Core) (any, error)) Option`
|
||||
|
||||
`WithService` registers a service using a factory function. It automatically discovers the service name from the package path and registers any IPC handlers if the service implements `HandleIPCEvents`.
|
||||
|
||||
### `func WithName(name string, factory func(*Core) (any, error)) Option`
|
||||
|
||||
`WithName` registers a service with a specific name using a factory function. Unlike `WithService`, it does not automatically discover IPC handlers.
|
||||
|
||||
### `func WithWails(app *application.App) Option`
|
||||
|
||||
`WithWails` injects the Wails application instance into the `Core`. This is required for services that need to interact with the Wails runtime.
|
||||
|
||||
### `func WithAssets(fs embed.FS) Option`
|
||||
|
||||
`WithAssets` registers the application's embedded assets (filesystem).
|
||||
|
||||
### `func WithServiceLock() Option`
|
||||
|
||||
`WithServiceLock` locks the service registry after initialization, preventing further service registration.
|
||||
|
||||
### `func ServiceFor[T any](c *Core, name string) (T, error)`
|
||||
|
||||
`ServiceFor` retrieves a registered service by its name and asserts that it is of type `T`. Returns an error if the service is not found or the type assertion fails.
|
||||
|
||||
### `func MustServiceFor[T any](c *Core, name string) T`
|
||||
|
||||
`MustServiceFor` is a helper that wraps `ServiceFor` and panics if the service is not found or the type is incorrect.
|
||||
|
||||
### `func App() *application.App`
|
||||
|
||||
`App` returns the global Wails application instance. It panics if the Core has not been initialized.
|
||||
|
||||
## Methods
|
||||
|
||||
### `func (c *Core) Config() Config`
|
||||
|
||||
`Config` returns the registered `Config` service. This is a convenience method for accessing application configuration.
|
||||
|
||||
### `func (c *Core) Assets() embed.FS`
|
||||
|
||||
`Assets` returns the embedded filesystem containing the application's assets.
|
||||
|
||||
### `func (c *Core) ServiceStartup(ctx context.Context, options application.ServiceOptions) error`
|
||||
|
||||
`ServiceStartup` is the entry point for the Core's startup lifecycle. It initializes all registered `Startable` services and dispatches the `ActionServiceStartup` message.
|
||||
|
||||
### `func (c *Core) ServiceShutdown(ctx context.Context) error`
|
||||
|
||||
`ServiceShutdown` is the entry point for the Core's shutdown lifecycle. It dispatches the `ActionServiceShutdown` message and calls `OnShutdown` on all `Stoppable` services in reverse registration order.
|
||||
|
||||
### `func (c *Core) RegisterAction(handler func(*Core, Message) error)`
|
||||
|
||||
`RegisterAction` registers a new IPC message handler.
|
||||
|
||||
### `func (c *Core) RegisterActions(handlers ...func(*Core, Message) error)`
|
||||
|
||||
`RegisterActions` registers multiple IPC message handlers at once.
|
||||
|
||||
### `func (c *Core) ACTION(msg Message) error`
|
||||
|
||||
`ACTION` dispatches a message to all registered IPC handlers. It aggregates errors from all handlers.
|
||||
|
||||
### `func (c *Core) RegisterService(name string, api any) error`
|
||||
|
||||
`RegisterService` adds a new service to the Core. It detects if the service implements `Startable` or `Stoppable` and registers it for lifecycle events.
|
||||
|
||||
### `func (c *Core) Service(name string) any`
|
||||
|
||||
`Service` retrieves a registered service instance by name as an `any` type. Returns `nil` if not found.
|
||||
|
|
@ -1,243 +0,0 @@
|
|||
# Display Service
|
||||
|
||||
The Display service (`pkg/display`) provides comprehensive window management, dialogs, system tray, clipboard, and notification functionality.
|
||||
|
||||
## Features
|
||||
|
||||
- Window creation, positioning, and lifecycle
|
||||
- System tray with menus
|
||||
- Native dialogs (open, save, confirm)
|
||||
- Clipboard operations
|
||||
- System notifications
|
||||
- Multi-monitor support
|
||||
- Layout management
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```go
|
||||
import "github.com/Snider/Core/pkg/display"
|
||||
|
||||
// Register with Core
|
||||
c, _ := core.New(
|
||||
core.WithService(display.NewService),
|
||||
)
|
||||
|
||||
// Get service
|
||||
svc := core.MustServiceFor[*display.Service](c, "display")
|
||||
```
|
||||
|
||||
## Window Management
|
||||
|
||||
### Create Window
|
||||
|
||||
```go
|
||||
info, err := svc.CreateWindow(display.CreateWindowOptions{
|
||||
Name: "settings",
|
||||
Title: "Settings",
|
||||
URL: "/settings",
|
||||
Width: 800,
|
||||
Height: 600,
|
||||
X: 100,
|
||||
Y: 100,
|
||||
})
|
||||
```
|
||||
|
||||
### Position & Size
|
||||
|
||||
```go
|
||||
// Move window
|
||||
svc.SetWindowPosition("main", 100, 100)
|
||||
|
||||
// Resize window
|
||||
svc.SetWindowSize("main", 1200, 800)
|
||||
|
||||
// Both at once
|
||||
svc.SetWindowBounds("main", 100, 100, 1200, 800)
|
||||
```
|
||||
|
||||
### Window State
|
||||
|
||||
```go
|
||||
svc.MaximizeWindow("main")
|
||||
svc.MinimizeWindow("main")
|
||||
svc.RestoreWindow("main")
|
||||
svc.FocusWindow("main")
|
||||
svc.SetWindowFullscreen("main", true)
|
||||
svc.SetWindowAlwaysOnTop("main", true)
|
||||
```
|
||||
|
||||
### List Windows
|
||||
|
||||
```go
|
||||
windows := svc.ListWindowInfos()
|
||||
for _, w := range windows {
|
||||
fmt.Printf("%s: %dx%d at (%d,%d)\n",
|
||||
w.Name, w.Width, w.Height, w.X, w.Y)
|
||||
}
|
||||
```
|
||||
|
||||
## Dialogs
|
||||
|
||||
### File Dialogs
|
||||
|
||||
```go
|
||||
// Open file
|
||||
path, err := svc.OpenSingleFileDialog(display.OpenFileOptions{
|
||||
Title: "Select File",
|
||||
Filters: []display.FileFilter{
|
||||
{DisplayName: "Images", Pattern: "*.png;*.jpg"},
|
||||
},
|
||||
})
|
||||
|
||||
// Open multiple files
|
||||
paths, err := svc.OpenFileDialog(display.OpenFileOptions{
|
||||
Title: "Select Files",
|
||||
AllowMultiple: true,
|
||||
})
|
||||
|
||||
// Save file
|
||||
path, err := svc.SaveFileDialog(display.SaveFileOptions{
|
||||
Title: "Save As",
|
||||
DefaultFilename: "document.txt",
|
||||
})
|
||||
|
||||
// Select directory
|
||||
dir, err := svc.OpenDirectoryDialog(display.OpenDirectoryOptions{
|
||||
Title: "Select Folder",
|
||||
})
|
||||
```
|
||||
|
||||
### Confirm Dialog
|
||||
|
||||
```go
|
||||
confirmed, err := svc.ConfirmDialog("Delete File", "Are you sure?")
|
||||
if confirmed {
|
||||
// User clicked Yes
|
||||
}
|
||||
```
|
||||
|
||||
## System Tray
|
||||
|
||||
```go
|
||||
// Set tooltip
|
||||
svc.SetTrayTooltip("My Application")
|
||||
|
||||
// Set label
|
||||
svc.SetTrayLabel("Running")
|
||||
|
||||
// Set icon (PNG bytes)
|
||||
iconData, _ := os.ReadFile("icon.png")
|
||||
svc.SetTrayIcon(iconData)
|
||||
|
||||
// Set menu
|
||||
svc.SetTrayMenu([]display.TrayMenuItem{
|
||||
{Label: "Open", ActionID: "open"},
|
||||
{Label: "Settings", ActionID: "settings"},
|
||||
{IsSeparator: true},
|
||||
{Label: "Quit", ActionID: "quit"},
|
||||
})
|
||||
```
|
||||
|
||||
## Clipboard
|
||||
|
||||
```go
|
||||
// Write to clipboard
|
||||
svc.WriteClipboard("Hello, World!")
|
||||
|
||||
// Read from clipboard
|
||||
text, err := svc.ReadClipboard()
|
||||
|
||||
// Check if has content
|
||||
hasContent := svc.HasClipboard()
|
||||
|
||||
// Clear clipboard
|
||||
svc.ClearClipboard()
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
```go
|
||||
// Basic notification
|
||||
svc.ShowNotification(display.NotificationOptions{
|
||||
Title: "Download Complete",
|
||||
Message: "Your file has been downloaded.",
|
||||
})
|
||||
|
||||
// Convenience methods
|
||||
svc.ShowInfoNotification("Info", "Operation completed")
|
||||
svc.ShowWarningNotification("Warning", "Low disk space")
|
||||
svc.ShowErrorNotification("Error", "Connection failed")
|
||||
```
|
||||
|
||||
## Multi-Monitor Support
|
||||
|
||||
```go
|
||||
// List all screens
|
||||
screens := svc.GetScreens()
|
||||
|
||||
// Get primary screen
|
||||
primary, _ := svc.GetPrimaryScreen()
|
||||
|
||||
// Get screen at point
|
||||
screen, _ := svc.GetScreenAtPoint(500, 300)
|
||||
|
||||
// Get screen for window
|
||||
screen, _ := svc.GetScreenForWindow("main")
|
||||
|
||||
// Get work areas (excluding dock/taskbar)
|
||||
workAreas := svc.GetWorkAreas()
|
||||
```
|
||||
|
||||
## Layout Management
|
||||
|
||||
```go
|
||||
// Save current layout
|
||||
svc.SaveLayout("coding")
|
||||
|
||||
// Restore layout
|
||||
svc.RestoreLayout("coding")
|
||||
|
||||
// List saved layouts
|
||||
layouts := svc.ListLayouts()
|
||||
|
||||
// Tile windows
|
||||
svc.TileWindows(display.TileModeGrid, nil)
|
||||
|
||||
// Snap to edge
|
||||
svc.SnapWindow("main", display.SnapPositionLeft)
|
||||
|
||||
// Apply workflow preset
|
||||
svc.ApplyWorkflowLayout(display.WorkflowCoding)
|
||||
```
|
||||
|
||||
## Theme
|
||||
|
||||
```go
|
||||
theme := svc.GetTheme()
|
||||
fmt.Println(theme.IsDark)
|
||||
```
|
||||
|
||||
## Frontend Usage (TypeScript)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
CreateWindow,
|
||||
SetWindowPosition,
|
||||
ShowNotification,
|
||||
OpenFileDialog
|
||||
} from '@bindings/display/service';
|
||||
|
||||
// Create window
|
||||
await CreateWindow({
|
||||
name: "settings",
|
||||
title: "Settings",
|
||||
width: 800,
|
||||
height: 600
|
||||
});
|
||||
|
||||
// Show notification
|
||||
await ShowNotification({
|
||||
title: "Success",
|
||||
message: "Settings saved!"
|
||||
});
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue