diff --git a/docs/cmd/ci/changelog/index.md b/docs/cmd/ci/changelog/index.md new file mode 100644 index 00000000..7b66a5f1 --- /dev/null +++ b/docs/cmd/ci/changelog/index.md @@ -0,0 +1,28 @@ +# core ci changelog + +Generate changelog from conventional commits. + +## Usage + +```bash +core ci changelog +``` + +## Output + +Generates markdown changelog from git commits since last tag: + +```markdown +## v1.2.0 + +### Features +- Add user authentication (#123) +- Support dark mode (#124) + +### Bug Fixes +- Fix memory leak in worker (#125) +``` + +## Configuration + +See [config.md](../config.md) for changelog configuration options. diff --git a/docs/cmd/ci/example.md b/docs/cmd/ci/example.md new file mode 100644 index 00000000..5c43806b --- /dev/null +++ b/docs/cmd/ci/example.md @@ -0,0 +1,90 @@ +# CI Examples + +## Quick Start + +```bash +# Build first +core build + +# Preview release +core ci + +# Publish +core ci --were-go-for-launch +``` + +## Configuration + +`.core/release.yaml`: + +```yaml +version: 1 + +project: + name: myapp + repository: host-uk/myapp + +publishers: + - type: github +``` + +## Publisher Examples + +### GitHub + Docker + +```yaml +publishers: + - type: github + + - type: docker + registry: ghcr.io + image: host-uk/myapp + platforms: + - linux/amd64 + - linux/arm64 + tags: + - latest + - "{{.Version}}" +``` + +### Full Stack (GitHub + npm + Homebrew) + +```yaml +publishers: + - type: github + + - type: npm + package: "@host-uk/myapp" + access: public + + - type: homebrew + tap: host-uk/homebrew-tap +``` + +### LinuxKit Image + +```yaml +publishers: + - type: linuxkit + config: .core/linuxkit/server.yml + formats: + - iso + - qcow2 + platforms: + - linux/amd64 + - linux/arm64 +``` + +## Changelog Configuration + +```yaml +changelog: + include: + - feat + - fix + - perf + exclude: + - chore + - docs + - test +``` diff --git a/docs/cmd/ci/index.md b/docs/cmd/ci/index.md index 0c5217b6..e9e7cf44 100644 --- a/docs/cmd/ci/index.md +++ b/docs/cmd/ci/index.md @@ -1,201 +1,79 @@ -# core release +# core ci -Build and publish releases to GitHub, npm, Homebrew, Scoop, AUR, Chocolatey, Docker, and LinuxKit. +Publish releases to GitHub, Docker, npm, Homebrew, and more. + +**Safety:** Dry-run by default. Use `--were-go-for-launch` to actually publish. + +## Subcommands + +| Command | Description | +|---------|-------------| +| [init](init/) | Initialize release config | +| [changelog](changelog/) | Generate changelog | +| [version](version/) | Show determined version | ## Usage ```bash -core release [flags] +core ci [flags] ``` ## Flags | Flag | Description | |------|-------------| -| `--dry-run` | Preview what would be published | -| `--version` | Override version (default: git tag) | -| `--target` | Release target: `sdk` for SDK-only release | -| `--draft` | Create release as draft | -| `--prerelease` | Mark release as prerelease | +| `--were-go-for-launch` | Actually publish (default is dry-run) | +| `--version` | Override version | +| `--draft` | Create as draft release | +| `--prerelease` | Mark as prerelease | -## Quick Start +## Examples ```bash -# Initialize release config -core release init +# Preview what would be published (safe) +core ci -# Preview release -core release --dry-run +# Actually publish +core ci --were-go-for-launch -# Release -core release +# Publish as draft +core ci --were-go-for-launch --draft -# SDK-only release -core release --target sdk +# Publish as prerelease +core ci --were-go-for-launch --prerelease ``` -## SDK Release +## Workflow -Generate SDKs without building binaries: +Build and publish are **separated** to prevent accidents: ```bash -# Generate SDKs with version from git tag -core release --target sdk +# Step 1: Build artifacts +core build +core build sdk -# Explicit version -core release --target sdk --version v1.2.3 +# Step 2: Preview (dry-run by default) +core ci -# Preview -core release --target sdk --dry-run +# Step 3: Publish (explicit flag required) +core ci --were-go-for-launch ``` -This will: -1. Determine version from git tags (or `--version` flag) -2. Run breaking change detection if configured -3. Generate SDKs for all configured languages -4. Output to `sdk/` directory - -See [SDK commands](sdk.md) for more details. - ## Publishers -### GitHub Releases +See [example.md](example.md) for publisher configuration. -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 " -``` - -### 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. +| Type | Target | +|------|--------| +| `github` | GitHub Releases | +| `docker` | Container registries | +| `linuxkit` | LinuxKit images | +| `npm` | npm registry | +| `homebrew` | Homebrew tap | +| `scoop` | Scoop bucket | +| `aur` | Arch User Repository | +| `chocolatey` | Chocolatey | ## 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 -``` +Auto-generated from conventional commits. See [example.md](example.md) for configuration. diff --git a/docs/cmd/ci/init/index.md b/docs/cmd/ci/init/index.md new file mode 100644 index 00000000..07be027a --- /dev/null +++ b/docs/cmd/ci/init/index.md @@ -0,0 +1,25 @@ +# core ci init + +Initialize release configuration. + +## Usage + +```bash +core ci init +``` + +Creates `.core/release.yaml` with default configuration. + +## Example Output + +```yaml +version: 1 + +project: + name: myapp + +publishers: + - type: github +``` + +See [config.md](../config.md) for full configuration options. diff --git a/docs/cmd/ci/version/index.md b/docs/cmd/ci/version/index.md new file mode 100644 index 00000000..7014a347 --- /dev/null +++ b/docs/cmd/ci/version/index.md @@ -0,0 +1,21 @@ +# core ci version + +Show the determined release version. + +## Usage + +```bash +core ci version +``` + +## Output + +``` +v1.2.0 +``` + +Version is determined from: +1. `--version` flag (if provided) +2. Git tag on HEAD +3. Latest git tag + increment +4. `v0.0.1` (if no tags exist) diff --git a/docs/cmd/dev/example.md b/docs/cmd/dev/example.md new file mode 100644 index 00000000..1fd1b4d1 --- /dev/null +++ b/docs/cmd/dev/example.md @@ -0,0 +1,87 @@ +# Dev Examples + +## Multi-Repo Workflow + +```bash +# Quick status +core dev health + +# Full workflow +core dev work + +# Status only +core dev work --status + +# Commit dirty repos +core dev commit + +# Push unpushed +core dev push + +# Pull behind +core dev pull +``` + +## GitHub Integration + +```bash +# Open issues +core dev issues + +# Include closed +core dev issues --all + +# PRs needing review +core dev reviews + +# CI status +core dev ci +``` + +## Dependency Analysis + +```bash +# What depends on core-php? +core dev impact core-php +``` + +## Dev Environment + +```bash +# First time setup +core dev install +core dev boot + +# Open shell +core dev shell + +# Mount and serve +core dev serve + +# Run tests +core dev test + +# Sandboxed Claude +core dev claude +``` + +## Configuration + +`repos.yaml`: +```yaml +org: host-uk +repos: + core-php: + type: package + description: Foundation framework + core-tenant: + type: package + depends: [core-php] +``` + +`~/.core/config.yaml`: +```yaml +version: 1 +images: + source: auto +``` diff --git a/docs/cmd/go/example.md b/docs/cmd/go/example.md new file mode 100644 index 00000000..51ad71a5 --- /dev/null +++ b/docs/cmd/go/example.md @@ -0,0 +1,89 @@ +# Go Examples + +## Testing + +```bash +# Run 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 +``` + +## Coverage + +```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 +``` + +## Formatting + +```bash +# Check +core go fmt + +# Fix +core go fmt --fix + +# Show diff +core go fmt --diff +``` + +## Linting + +```bash +# Check +core go lint + +# Auto-fix +core go lint --fix +``` + +## Installing + +```bash +# Auto-detect cmd/ +core go install + +# Specific path +core go install ./cmd/myapp + +# Pure Go (no CGO) +core go install --no-cgo +``` + +## Module Management + +```bash +core go mod tidy +core go mod download +core go mod verify +core go mod graph +``` + +## Workspace + +```bash +core go work sync +core go work init +core go work use ./pkg/mymodule +``` diff --git a/docs/cmd/php/example.md b/docs/cmd/php/example.md new file mode 100644 index 00000000..508163ce --- /dev/null +++ b/docs/cmd/php/example.md @@ -0,0 +1,89 @@ +# PHP Examples + +## Development + +```bash +# Start all services +core php dev + +# With HTTPS +core php dev --https + +# Skip services +core php dev --no-vite --no-horizon +``` + +## Testing + +```bash +# Run all +core php test + +# Parallel +core php test --parallel + +# With coverage +core php test --coverage + +# Filter +core php test --filter UserTest +``` + +## Code Quality + +```bash +# Format +core php fmt --fix + +# Static analysis +core php analyse --level 9 +``` + +## Deployment + +```bash +# Production +core php deploy + +# Staging +core php deploy --staging + +# Wait for completion +core php deploy --wait + +# Check status +core php deploy:status + +# Rollback +core php deploy:rollback +``` + +## Configuration + +`.env`: +```env +COOLIFY_URL=https://coolify.example.com +COOLIFY_TOKEN=your-api-token +COOLIFY_APP_ID=production-app-id +COOLIFY_STAGING_APP_ID=staging-app-id +``` + +## Package Linking + +```bash +# Link local packages +core php packages link ../my-package + +# Update linked +core php packages update + +# Unlink +core php packages unlink my-package +``` + +## SSL Setup + +```bash +core php ssl +core php ssl --domain myapp.test +``` diff --git a/docs/cmd/vm/example.md b/docs/cmd/vm/example.md new file mode 100644 index 00000000..f31f97eb --- /dev/null +++ b/docs/cmd/vm/example.md @@ -0,0 +1,52 @@ +# VM Examples + +## Running VMs + +```bash +# Run image +core vm run server.iso + +# Detached with resources +core vm run -d --memory 4096 --cpus 4 server.iso + +# From template +core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..." +``` + +## Management + +```bash +# List running +core vm ps + +# Include stopped +core vm ps -a + +# Stop +core vm stop abc123 + +# View logs +core vm logs abc123 + +# Follow logs +core vm logs -f abc123 + +# Execute command +core vm exec abc123 ls -la + +# Shell +core vm exec abc123 /bin/sh +``` + +## Templates + +```bash +# List +core vm templates + +# Show content +core vm templates show core-dev + +# Show variables +core vm templates vars core-dev +```