diff --git a/.gitignore b/.gitignore index 41e12bac..1bc44414 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ wails3 build/ !pkg/build !cmd/core-gui/build +!docs/cmd/build cmd/core-gui/build/bin .task vendor/ diff --git a/docs/cmd/build/example.md b/docs/cmd/build/example.md new file mode 100644 index 00000000..da2f3b45 --- /dev/null +++ b/docs/cmd/build/example.md @@ -0,0 +1,83 @@ +# Build Examples + +## Quick Start + +```bash +# Auto-detect and build +core build + +# Build for specific platforms +core build --targets linux/amd64,darwin/arm64 + +# CI mode +core build --ci +``` + +## Configuration + +`.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 +``` + +## Cross-Platform Build + +```bash +core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64 +``` + +Output: +``` +dist/ +├── myapp-linux-amd64.tar.gz +├── myapp-linux-arm64.tar.gz +├── myapp-darwin-arm64.tar.gz +├── myapp-windows-amd64.zip +└── CHECKSUMS.txt +``` + +## Code Signing + +```yaml +sign: + enabled: true + gpg: + key: $GPG_KEY_ID + macos: + identity: "Developer ID Application: Your Name (TEAM_ID)" + notarize: true + apple_id: $APPLE_ID + team_id: $APPLE_TEAM_ID + app_password: $APPLE_APP_PASSWORD +``` + +## Docker Build + +```bash +core build --type docker --image ghcr.io/myorg/myapp +``` + +## Wails Desktop App + +```bash +core build --type wails --targets darwin/arm64,windows/amd64 +``` diff --git a/docs/cmd/build/index.md b/docs/cmd/build/index.md new file mode 100644 index 00000000..e121bcd2 --- /dev/null +++ b/docs/cmd/build/index.md @@ -0,0 +1,177 @@ +# core build + +Build Go, Wails, Docker, and LinuxKit projects with automatic project detection. + +## Subcommands + +| Command | Description | +|---------|-------------| +| [sdk](sdk/) | Generate API SDKs from OpenAPI | + +## 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) | +| `--no-sign` | Skip code signing | +| `--notarize` | Enable macOS notarization (requires Apple credentials) | + +## 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 + +sign: + enabled: true + gpg: + key: $GPG_KEY_ID + macos: + identity: "Developer ID Application: Your Name (TEAM_ID)" + notarize: false + apple_id: $APPLE_ID + team_id: $APPLE_TEAM_ID + app_password: $APPLE_APP_PASSWORD +``` + +## Code Signing + +Core supports GPG signing for checksums and native code signing for macOS. + +### GPG Signing + +Signs `CHECKSUMS.txt` with a detached ASCII signature (`.asc`): + +```bash +# Build with GPG signing (default if key configured) +core build + +# Skip signing +core build --no-sign +``` + +Users can verify: + +```bash +gpg --verify CHECKSUMS.txt.asc CHECKSUMS.txt +sha256sum -c CHECKSUMS.txt +``` + +### macOS Code Signing + +Signs Darwin binaries with your Developer ID and optionally notarizes with Apple: + +```bash +# Build with codesign (automatic if identity configured) +core build + +# Build with notarization (takes 1-5 minutes) +core build --notarize +``` + +### Environment Variables + +| Variable | Purpose | +|----------|---------| +| `GPG_KEY_ID` | GPG key ID or fingerprint | +| `CODESIGN_IDENTITY` | macOS Developer ID (fallback) | +| `APPLE_ID` | Apple account email | +| `APPLE_TEAM_ID` | Apple Developer Team ID | +| `APPLE_APP_PASSWORD` | App-specific password for notarization | diff --git a/docs/cmd/build/sdk/example.md b/docs/cmd/build/sdk/example.md new file mode 100644 index 00000000..e8323087 --- /dev/null +++ b/docs/cmd/build/sdk/example.md @@ -0,0 +1,56 @@ +# SDK Build Examples + +## Generate All SDKs + +```bash +core build sdk +``` + +## Specific Language + +```bash +core build sdk --lang typescript +core build sdk --lang php +core build sdk --lang go +``` + +## Custom Spec + +```bash +core build sdk --spec ./api/openapi.yaml +``` + +## With Version + +```bash +core build sdk --version v2.0.0 +``` + +## Preview + +```bash +core build sdk --dry-run +``` + +## Configuration + +`.core/sdk.yaml`: + +```yaml +version: 1 + +spec: ./api/openapi.yaml + +languages: + - name: typescript + output: sdk/typescript + package: "@myorg/api-client" + + - name: php + output: sdk/php + namespace: MyOrg\ApiClient + + - name: go + output: sdk/go + module: github.com/myorg/api-client-go +``` diff --git a/docs/cmd/build/sdk/index.md b/docs/cmd/build/sdk/index.md new file mode 100644 index 00000000..d89f485e --- /dev/null +++ b/docs/cmd/build/sdk/index.md @@ -0,0 +1,27 @@ +# core build sdk + +Generate API SDKs from OpenAPI specifications. + +## Usage + +```bash +core build sdk [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--spec` | Path to OpenAPI spec file | +| `--lang` | Generate only this language | +| `--version` | Version to embed | +| `--dry-run` | Preview without generating | + +## Examples + +```bash +core build sdk # Generate all +core build sdk --lang typescript # TypeScript only +core build sdk --spec ./api.yaml # Custom spec +core build sdk --dry-run # Preview +``` diff --git a/docs/cmd/ci/changelog/example.md b/docs/cmd/ci/changelog/example.md new file mode 100644 index 00000000..101cad76 --- /dev/null +++ b/docs/cmd/ci/changelog/example.md @@ -0,0 +1,36 @@ +# CI Changelog Examples + +```bash +core ci changelog +``` + +## Output + +```markdown +## v1.2.0 + +### Features +- Add user authentication (#123) +- Support dark mode (#124) + +### Bug Fixes +- Fix memory leak in worker (#125) + +### Performance +- Optimize database queries (#126) +``` + +## Configuration + +`.core/release.yaml`: + +```yaml +changelog: + include: + - feat + - fix + - perf + exclude: + - chore + - docs +``` diff --git a/docs/cmd/ci/init/example.md b/docs/cmd/ci/init/example.md new file mode 100644 index 00000000..8f76ab98 --- /dev/null +++ b/docs/cmd/ci/init/example.md @@ -0,0 +1,17 @@ +# CI Init Examples + +```bash +core ci init +``` + +Creates `.core/release.yaml`: + +```yaml +version: 1 + +project: + name: myapp + +publishers: + - type: github +``` diff --git a/docs/cmd/ci/version/example.md b/docs/cmd/ci/version/example.md new file mode 100644 index 00000000..e669d656 --- /dev/null +++ b/docs/cmd/ci/version/example.md @@ -0,0 +1,18 @@ +# CI Version Examples + +```bash +core ci version +``` + +## Output + +``` +v1.2.0 +``` + +## Version Resolution + +1. `--version` flag (if provided) +2. Git tag on HEAD +3. Latest git tag + increment +4. `v0.0.1` (no tags) diff --git a/docs/cmd/dev/work/example.md b/docs/cmd/dev/work/example.md new file mode 100644 index 00000000..f62b5145 --- /dev/null +++ b/docs/cmd/dev/work/example.md @@ -0,0 +1,21 @@ +# Dev Work Examples + +```bash +# Full workflow: status → commit → push +core dev work + +# Status only +core dev work --status +``` + +## Output + +``` +┌─────────────┬────────┬──────────┬─────────┐ +│ Repo │ Branch │ Status │ Behind │ +├─────────────┼────────┼──────────┼─────────┤ +│ core-php │ main │ clean │ 0 │ +│ core-tenant │ main │ 2 files │ 0 │ +│ core-admin │ dev │ clean │ 3 │ +└─────────────┴────────┴──────────┴─────────┘ +``` diff --git a/docs/cmd/docs/example.md b/docs/cmd/docs/example.md new file mode 100644 index 00000000..706615ba --- /dev/null +++ b/docs/cmd/docs/example.md @@ -0,0 +1,14 @@ +# Docs Examples + +## List + +```bash +core docs list +``` + +## Sync + +```bash +core docs sync +core docs sync --target ./docs +``` diff --git a/docs/cmd/doctor/example.md b/docs/cmd/doctor/example.md new file mode 100644 index 00000000..ba94d71c --- /dev/null +++ b/docs/cmd/doctor/example.md @@ -0,0 +1,20 @@ +# Doctor Examples + +```bash +core doctor +``` + +## Output + +``` +✓ go 1.25.0 +✓ git 2.43.0 +✓ gh 2.40.0 +✓ docker 24.0.7 +✓ task 3.30.0 +✓ golangci-lint 1.55.0 +✗ wails (not installed) +✓ php 8.3.0 +✓ composer 2.6.0 +✓ node 20.10.0 +``` diff --git a/docs/cmd/go/cov/example.md b/docs/cmd/go/cov/example.md new file mode 100644 index 00000000..4fdc6c28 --- /dev/null +++ b/docs/cmd/go/cov/example.md @@ -0,0 +1,18 @@ +# Go Coverage Examples + +```bash +# Summary +core go cov + +# HTML report +core go cov --html + +# Open in browser +core go cov --open + +# Fail if below threshold +core go cov --threshold 80 + +# Specific package +core go cov --pkg ./pkg/release +``` diff --git a/docs/cmd/go/fmt/example.md b/docs/cmd/go/fmt/example.md new file mode 100644 index 00000000..40233e06 --- /dev/null +++ b/docs/cmd/go/fmt/example.md @@ -0,0 +1,12 @@ +# Go Format Examples + +```bash +# Check only +core go fmt + +# Apply fixes +core go fmt --fix + +# Show diff +core go fmt --diff +``` diff --git a/docs/cmd/go/install/example.md b/docs/cmd/go/install/example.md new file mode 100644 index 00000000..bba88cdd --- /dev/null +++ b/docs/cmd/go/install/example.md @@ -0,0 +1,15 @@ +# Go Install Examples + +```bash +# Auto-detect cmd/ +core go install + +# Specific path +core go install ./cmd/myapp + +# Pure Go (no CGO) +core go install --no-cgo + +# Verbose +core go install -v +``` diff --git a/docs/cmd/go/lint/example.md b/docs/cmd/go/lint/example.md new file mode 100644 index 00000000..56b46d4f --- /dev/null +++ b/docs/cmd/go/lint/example.md @@ -0,0 +1,22 @@ +# Go Lint Examples + +```bash +# Check +core go lint + +# Auto-fix +core go lint --fix +``` + +## Configuration + +`.golangci.yml`: + +```yaml +linters: + enable: + - gofmt + - govet + - errcheck + - staticcheck +``` diff --git a/docs/cmd/go/mod/example.md b/docs/cmd/go/mod/example.md new file mode 100644 index 00000000..57d2e667 --- /dev/null +++ b/docs/cmd/go/mod/example.md @@ -0,0 +1,15 @@ +# Go Module Examples + +```bash +# Tidy +core go mod tidy + +# Download +core go mod download + +# Verify +core go mod verify + +# Graph +core go mod graph +``` diff --git a/docs/cmd/go/test/example.md b/docs/cmd/go/test/example.md new file mode 100644 index 00000000..85ff1b5e --- /dev/null +++ b/docs/cmd/go/test/example.md @@ -0,0 +1,27 @@ +# Go Test Examples + +```bash +# All tests +core go test + +# Specific package +core go test --pkg ./pkg/core + +# Specific test +core go test --run TestHash + +# With coverage +core go test --coverage + +# Race detection +core go test --race + +# Short tests only +core go test --short + +# Verbose +core go test -v + +# JSON output (CI) +core go test --json +``` diff --git a/docs/cmd/pkg/example.md b/docs/cmd/pkg/example.md new file mode 100644 index 00000000..7904aaef --- /dev/null +++ b/docs/cmd/pkg/example.md @@ -0,0 +1,36 @@ +# Package Examples + +## Search + +```bash +core pkg search core- +core pkg search api +core pkg search --org myorg +``` + +## Install + +```bash +core pkg install core-api +core pkg install host-uk/core-api +``` + +## List + +```bash +core pkg list +core pkg list --format json +``` + +## Update + +```bash +core pkg update +core pkg update core-api +``` + +## Outdated + +```bash +core pkg outdated +``` diff --git a/docs/cmd/pkg/search/example.md b/docs/cmd/pkg/search/example.md new file mode 100644 index 00000000..fbcaa6f4 --- /dev/null +++ b/docs/cmd/pkg/search/example.md @@ -0,0 +1,23 @@ +# Package Search Examples + +```bash +# Find all core-* packages +core pkg search core- + +# Search term +core pkg search api + +# Different org +core pkg search --org myorg query +``` + +## Output + +``` +┌──────────────┬─────────────────────────────┐ +│ Package │ Description │ +├──────────────┼─────────────────────────────┤ +│ core-api │ REST API framework │ +│ core-auth │ Authentication utilities │ +└──────────────┴─────────────────────────────┘ +``` diff --git a/docs/cmd/sdk/example.md b/docs/cmd/sdk/example.md new file mode 100644 index 00000000..2fada8c4 --- /dev/null +++ b/docs/cmd/sdk/example.md @@ -0,0 +1,35 @@ +# SDK Examples + +## Validate + +```bash +core sdk validate +core sdk validate --spec ./api.yaml +``` + +## Diff + +```bash +# Compare with tag +core sdk diff --base v1.0.0 + +# Compare files +core sdk diff --base ./old-api.yaml --spec ./new-api.yaml +``` + +## Output + +``` +Breaking changes detected: + +- DELETE /users/{id}/profile + Endpoint removed + +- PATCH /users/{id} + Required field 'email' added + +Non-breaking changes: + ++ POST /users/{id}/avatar + New endpoint added +``` diff --git a/docs/cmd/setup/example.md b/docs/cmd/setup/example.md new file mode 100644 index 00000000..283c4c88 --- /dev/null +++ b/docs/cmd/setup/example.md @@ -0,0 +1,29 @@ +# Setup Examples + +```bash +# Clone all repos +core setup + +# Specific directory +core setup --dir ~/Code/host-uk + +# Use SSH +core setup --ssh +``` + +## Configuration + +`repos.yaml`: + +```yaml +org: host-uk +repos: + core-php: + type: package + core-tenant: + type: package + depends: [core-php] + core-admin: + type: package + depends: [core-php, core-tenant] +``` diff --git a/docs/cmd/test/example.md b/docs/cmd/test/example.md new file mode 100644 index 00000000..9e2a4a73 --- /dev/null +++ b/docs/cmd/test/example.md @@ -0,0 +1,8 @@ +# Test Examples + +**Note:** Prefer `core go test` or `core php test` instead. + +```bash +core test +core test --coverage +``` diff --git a/docs/cmd/vm/templates/example.md b/docs/cmd/vm/templates/example.md new file mode 100644 index 00000000..ffe73956 --- /dev/null +++ b/docs/cmd/vm/templates/example.md @@ -0,0 +1,34 @@ +# VM Templates Examples + +## List + +```bash +core vm templates +``` + +## Show + +```bash +core vm templates show core-dev +``` + +## Variables + +```bash +core vm templates vars core-dev +``` + +## Output + +``` +Variables for core-dev: + SSH_KEY (required) SSH public key + MEMORY (optional) Memory in MB (default: 4096) + CPUS (optional) CPU count (default: 4) +``` + +## Using Templates + +```bash +core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..." +```